# VNLE — game integration documentation

Base URL: https://wiki.vnle.app/
The handbook has ten languages; English is available under /en/.

Editor guides:
- en/resources.html: items, quest objectives, locations and the editor/game boundary.
- en/testing.html: editor preview, test positions, values and history.
- en/everyday.html: search/replace, saving, settings and organization.
- examples/harbour/location-practice.story.json: separate executable location exercise.

Read in order:
- en/integration.html: shared learning path and engine entries.
- en/files.html: editable project versus game export, real fields and IDs.
- en/flow.html: complete node semantics, conditions, effects, commands, call/return, text and saved state.
- en/format.html and story.schema.json: field reference and machine-readable schema.
- examples/harbour/story.json: actual export used by every new example.
- examples/harbour/story-index.json: entry index from the same editable project.
- examples/harbour/guide-map.json: tutorial-only IDs; not universal export metadata.
- en/godot.html, en/phaser.html, en/unity.html, en/unreal.html, en/gamemaker.html,
  en/gdevelop.html, en/rpgmaker.html, en/defold.html, en/cocos.html, en/monogame.html:
  specific engine loading/display paths with official API references.

Scope: small integration examples, no required VNLE player, handler, plugin or paid adapter.
Existing historical browser/Godot/Phaser demos are optional illustrations, not a required API.
Ask the user for engine version, target platform, actual export and existing game systems.
Do not invent JSON fields or engine API calls. Do not present documentation review as a native test.

format=vnle.story; containerVersion=1; sample execution.contractVersion=1.1.
Validate versions, capabilities, references and types before starting the full story.
Use IDs to join tables. Names and translated text are not stable lookup keys.
Load a chosen flowRef/entryRef; entries[entryRef].nodeRef selects the initial node.
Follow continuations, not object iteration order.
Node kinds: dialogue, choice, branch, action, command, jump, call, return, end.
Call pushes continuation; Return pops it. Return without Call is a fault.
Jump enters its target without adding a return point. It does not load an engine map.
End (node or continuation) ends the entire conversation and clears the return stack.
It does not quit the game. Hide the dialogue UI and restore the game's controls.
Commands request an explicitly supported game function, wait, validate a declared outcome,
apply resultBindings and follow that outcome's continuation. Never execute arbitrary JSON code.
Open shop is a possible user-defined action, not a built-in VNLE command.
The sample uses give_item. Inventory rejection follows the authored refund path.
Technical failures are not automatically narrative cancellation outcomes.
Use execution.variables for initial defaults only for a new context, never over a restored save.
Respect automatic transition, condition depth/term and call depth limits.

Resolve content.translations[locale][textRef].message when present, else sourceMessage.
Texts consist of segments; resolve typed placeholders through their definitions and node bindings.
Intentionally empty translations remain empty. Do not re-run effects on language changes.
Speaker names use characters[speakerRef].nameTextRef and the same localization rules.
The full project export includes image files and content.assets relativePath references.
Generic exports can omit portrait paths: the game can map character/emotion IDs to its own assets.
Images have no language-dependent mapping in this format.
Save game systems and dialogue state consistently; never replay a completed command on redraw/load.

Harbour acceptance cases: Gold=10 purchase succeeds with 5 remaining; Gold=2 refuses;
inventory rejection refunds; call/return resumes; end closes; language preserves progress;
missing translation falls back; intentional blank stays blank; package contains JSON/fonts/images.