Understand files and JSON

The editable project and the game export serve different purposes. Edit content in VNLE, then export again. The following excerpts come from the included project.

Export folders

story.json                  Game data: flow + text + catalogs
assets/files/…png           Images used by the game
story-index.json            Entry points for starting conversations
export-info.json            Export result
project/
  project.vnle.json          Project name, languages, catalog references
  chapters/                 Chapter structure
  flows/                    Scene nodes and entry points
  layout/                   Node positions in the editor
  characters/               Characters and portrait references
  variables/                Variable definitions and initial values
  commands/                 Game actions, inputs and outcomes
  items/, quests/, locations/ Resources
  localization/             Source texts and translations
  assets/                   Asset catalog and image files

The teaching example adds guide-map.json to associate IDs with readable names. It belongs to this example and is not generated for every project. In a normal export, find entry points in story-index.json and catalogs in story.json.

Start a conversation

An entry point consists of flowRef and entryRef. Both are IDs, not display names. Pass this object to start. These are the real IDs used by the example:

{
  "flowRef": "1f69a7b6-1bdc-4dff-b8ee-9b2819b35168",
  "entryRef": "5e6b2e12-1ac1-4c46-8221-1a051e87370a"
}

Read a dialogue

{
  "continuation": {
    "kind": "node",
    "nodeRef": "85b3aadf-2b95-4150-bc44-c0c796337874"
  },
  "flowRef": "1f69a7b6-1bdc-4dff-b8ee-9b2819b35168",
  "id": "ffa7141b-97ed-44c1-a346-8bba7e26d94f",
  "kind": "dialogue",
  "speakerRef": "807b2957-7bab-4a28-83a4-1f3d1589bbc2",
  "text": {
    "bindings": {},
    "textRef": "fd7b61a3-8233-4ba7-8f77-b88b119a91bf"
  }
}

kind identifies the node type. speakerRef refers to a character in content.characters. text.textRef refers to content.texts. continuation describes what Continue does.

Resolve text and language

{
  "id": "fd7b61a3-8233-4ba7-8f77-b88b119a91bf",
  "category": "dialogue",
  "sourceMessage": {
    "kind": "segments",
    "segments": [
      {
        "kind": "text",
        "text": "Welcome to the harbour. I am Mira."
      }
    ]
  },
  "placeholders": {},
  "externalUse": false
}

Use content.translations[language][text ID].message when present. Otherwise use sourceMessage. Text segments supply visible words; placeholder segments receive values from node bindings. Language belongs to the game settings: changing it does not change progress.

Show name and portrait

{
  "id": "807b2957-7bab-4a28-83a4-1f3d1589bbc2",
  "name": "Mira",
  "key": "character_2fbfc3b256cb4ecf94a89965ef8e4549",
  "nameTextRef": "ff2cf3d4-08d3-47d8-b41a-86f1a801e1b7",
  "color": "#82d5e6",
  "defaultPortraitRef": "eacb484c-0663-4ffd-876d-401664b980db",
  "emotions": {}
}

Resolve nameTextRef like any other text. For the image, use the chosen emotion’s portrait or defaultPortraitRef. Find the file in content.assets[portrait ID].relativePath. Copy assets alongside story.json.

Look up every field

Complete field reference · JSON Schema · story.json