This page describes the .json file of a Formamorph world: the file Export World writes and Import World reads. Use it when you edit a world file by hand or write a tool for one.

💡 The World Editor writes this format for you. Edit the file by hand only for a change the editor can't make, or for a bulk change.

📄 This page covers world files only. It does not describe save files.

1. In the main menu, select the world. In its world dialog, select Export World.
2. Open the .json file in a text editor. Make your changes.
3. In the main menu, open the Worlds tab and select Import World. Pick the file.

💡 The World Editor's Overview tab has Export World too.

The import adds a new world. It never replaces the world you exported. Import skips a file that fails to load, and the menu tells you.

1. Add an object to the top-level stats list.
2. Give it a new id and a name. Scripts and the AI find a stat by its name, so keep names unique.
3. Set type to "number", or to "percentage" for a 0–100 stat.
4. Set min, max, value (the Base Value) and regen.
5. Write a description, and set descriptors to [] or to a list of descriptors.

{ "id": "stamina", "name": "Stamina", "type": "number", "description": "Energy for hard work",
  "min": 0, "max": 100, "value": 80, "regen": 2, "descriptors": [] }

1. Add an object to the top-level traits list. For a trait that one entity owns, add it to that entity's traits list.
2. Give it a new id and a name. Trait ids must be unique across the world and every entity.
3. Write playerDescription and aiDescription.
4. Set statChanges to [] or to a list of stat changes.
5. To put it in a group, set groupId to the group's id.

{ "id": "strong", "name": "Strong", "playerDescription": "Above-average strength",
  "aiDescription": "This person is unusually strong.", "groupId": "physical",
  "statChanges": [{ "statId": "stamina", "value": 10, "type": "max" }] }

1. Add an object to the top-level entities list.
2. Give it a new id and a name.
3. Write playerDescription, aiDescription and, for a long description, aiSummary.
4. Set locations to the ids of the locations where the entity is. Leave it out for an entity with no fixed place.
5. To make the entity playable, set persona to true. See Persona Marks.

{ "id": "smith", "name": "Mara", "aliases": ["the smith"], "pronouns": "she/her",
  "playerDescription": "The village blacksmith.", "aiDescription": "Mara is a gruff, fair blacksmith.",
  "locations": ["town"] }

Editor-only fields organize the World Editor. The AI never reads them.

A stored world also has an id. Export leaves it out, and import gives the world a new one.

⚠️ Import refuses a world without worldOverview, stats, locations, entities, traits and statUpdates. An empty list is enough.

Import runs every world through a migration. The migration changes an older shape into the current one, so a file from any version loads. These older forms still load:

⚠️ The last six rows run only when version is not the app's version. A file stamped with the current version keeps those older forms as written.

Write new files in the current shape. A file with scripts loads in an older version of the app, but its scripts don't run there.

See Persona Rules for how the last two fields behave.

promptOverrides replaces some of the player's prompts while they play this world:

Each stat is a number the player has. The AI reads it, and a script can calculate it.

A script is one box of code with a timing. A stat, a trait and the world each hold a scripts list.

When two scripts write the same field, the later one wins. A world script has no self. A trait's script runs only while the trait is active. The Scripts Guide lists what each timing reads.

A descriptor gives the AI a word or phrase for a band of values.

The lowest band that holds the value wins, in any list order. A value above every threshold has no descriptor.

A trait changes a stat with a list of these.

A statToggles entry takes the same target.

🔁 Older files write "target": "player". The app reads it as "global", and new files write "global" only. Apps older than this change don't read "global", so they apply these rows to the entity's own stat until updated.

A trait describes the player or an entity. The player picks traits before play. An entity can own traits too.

See World Editor: Traits for how modes, requirements and pick counts behave during the game.

requires is a list of rows. Each row is { "all": [ … ] }: a list of requirements. A row holds when every requirement in it holds. A row is never empty.

"requires": [
  { "all": [{ "kind": "trait", "id": "knight" }, { "kind": "trait", "id": "heavy-build" }] },
  { "all": [{ "kind": "trait", "id": "mercenary" }] }
]

🔁 Older files store requires as a flat list of requirements. The app reads each one as a row of its own.

Each requirement has a kind:

• name is optional. It holds the target's name, so a requirement still reads when the target is gone.
• A "stat" requirement's operator is one of ">", "<", ">=", "<=", "=" or "≠". Its unit is "raw" for the stat's own units or "percent" for a share of the stat's min→max span. { "kind": "stat", "id": "health", "operator": "<", "value": 20, "unit": "percent" } holds while Health is under 20% of its range.
• owner is optional, and it applies only to a trait, group or stat an entity owns. A requirement that names a global item (a root trait, a root group or a global stat) reads the global scope, and the app drops any owner stored with it. Absent = the trait's own owner. { "kind": "you" } checks the entity the player plays, and never holds when the player plays none. { "kind": "entity", "id": "<entity id>", "name": "…" } checks that entity.
• not is optional. true flips the requirement: it holds while its target is off. { "kind": "trait", "id": "paladin", "not": true } holds while the owner doesn't have Paladin.
• A requirement whose target is gone never holds, with or without not.

🔁 Older files name the owner under bearer. The app reads it as owner, and new files write owner only. Apps from v3.1 and v3.2 don't read owner, so they misread these requirements until updated.

A group holds traits and other groups. Both the world and each entity have a traitGroups list.

The world group with system: "blueprints", and every group below it, holds Blueprints items. The player never picks a Blueprints trait. It reaches play only through an entity's link. Only a Blueprints trait or group can be linked.

A connection is a travel link between two locations. A connection between two locations replaces the travel that nesting gives them. Its legs are then the only travel between the two.

A connection needs at least one leg. Both legs = two-way. A leg has one optional field, hint: how the trip is made, such as "through the old gate". The AI reads it after the destination's name.

Only the player has stats. So statChanges and statToggles on an entity's own traits apply only on a playable, persona-only or Custom Persona entity. A playable or persona-only entity's apply while the player plays it. The Custom Persona entity's apply while the player has no world persona.

The Persona control on the entity's Profile tab writes three fields:

One entity at most has customPersona, at the top level of the Traits tree. In a library entity, persona: true makes it one of the player's personas. See Personas for Authors for the rules.

A link gives a Blueprints trait or group to an entity. The entity does not get its own trait. The link reads its original live, except for the fields it overrides.

Each override map can hold isDefault, requires, placeholderPins, playerToggle, statChanges and mode. mode takes "optional", "alwaysOn" or "hidden". Each field holds { "value": …, "blueprint": … }: your value, and the original's value when you set it. The app uses blueprint to tell you when the original changed.

An entity links each original one time.

Editor-only groups for entities.

An entity file, or an entity in the library, can also carry these fields. The app clears them when the entity joins a world, so a world file does not need them.

An opening is one way a game can start. The world, each location and each entity have an openings list.

See World Editor: Openings for which openings draw.

A placeholder is a named value that a chip shows in text. The world's placeholders are shared. An entity's or a book's placeholders belong to it.

Each value:

See World Editor: Placeholders for kinds, parts and weights.

A pin sets one placeholder to one value while its source is active. Traits, locations, stat descriptors and placeholder values carry pins.

A world shared placeholder in the Blueprints group, or a group below it, is a blueprint. An entity holds a copy of each blueprint its traits need, in its own placeholders, with blueprintId set. The app makes copies when it loads the world.

A copy reads its blueprint's values live. Its own values hold only the values it adds. Its valueOverrides map a blueprint value id to changes:

Editor-only groups for the world's shared placeholders.

A chip is a token in a text field. The editor inserts chips. To write one by hand, use this form:

{{ph:<placeholder id>:<world|unique>:<placement id>}}

The editor can add two more parts after the placement id: a path to a part of the placeholder, and a label after :=. Copy those from a chip the editor wrote.

Two chips need no placeholder. {{user}} is the Player Name chip. {{char}} is the Character Name chip.

dictionaries is a list of books. Each book holds lore entries. An entry goes into the AI's prompt when one of its keywords is in the scanned text. See What Gets Scanned.

Each book:

Book order sets the order in the prompt.

An entity or a book in a world can follow a library item. Its link object records that. Let the app write it. See Linked Content.

statUpdates is an older list. No screen edits it, and play does not read it. Write []. An older file can hold records with id, name, prompt, stats (stat names) and messageHistory.

Images (thumbnail, location backgroundImage, a gallery image's data, book thumbnail) hold one string:

• A base64 data URL, such as data:image/png;base64,…
• Or an http or https URL. The app loads the image from that address

Gallery images (entity images) are objects:

Background music (bgm) is a base64 data URL.

Uploaded audio and models (customPlayerVRM, location ambientSound, entity sound and model) are a MediaAsset:

{ "data": "data:model/vrm;base64,...", "type": "model/vrm", "name": "hero.vrm" }

A short world. ... replaces the media data.

{
  "formamorphKind": "world",
  "version": "3.1.2",
  "worldOverview": {
    "name": "Example World",
    "description": "A small town at the edge of the woods.",
    "author": "Docs",
    "thumbnail": "data:image/png;base64,...",
    "bgm": null,
    "systemPrompt": "A quiet fantasy town. Magic is rare and feared.",
    "use3DModel": false,
    "tags": ["fantasy"],
    "readme": "# Welcome\nYou arrive at dusk.",
    "openings": [
      { "id": "op-1", "text": "{{user}} reaches the town gate as the bell rings.", "kind": "narration" }
    ]
  },
  "stats": [
    {
      "id": "health",
      "name": "Health",
      "type": "number",
      "description": "How hurt you are",
      "min": 0,
      "max": 100,
      "value": 100,
      "regen": 1,
      "descriptors": [
        { "id": "hp-low", "threshold": 30, "description": "badly hurt" },
        { "id": "hp-high", "threshold": 100, "description": "healthy" }
      ]
    }
  ],
  "locations": [
    { "id": "town", "name": "Town Square", "playerDescription": "The center of town.", "isStarting": true },
    { "id": "forge", "name": "Forge", "playerDescription": "Heat and noise.", "parentId": "town" }
  ],
  "connections": [],
  "entities": [
    {
      "id": "smith",
      "name": "Mara",
      "pronouns": "she/her",
      "playerDescription": "The town blacksmith.",
      "aiDescription": "Mara is gruff and fair. She wears a {{ph:garb:world:p-1}}.",
      "locations": ["forge"]
    }
  ],
  "traits": [
    {
      "id": "strong",
      "name": "Strong",
      "playerDescription": "Above-average strength",
      "aiDescription": "This person is unusually strong.",
      "groupId": "body",
      "statChanges": [{ "statId": "health", "value": 20, "type": "max" }]
    }
  ],
  "traitGroups": [
    { "id": "body", "name": "Body", "parentId": null, "order": 0, "maxPicks": 1 }
  ],
  "placeholders": [
    {
      "id": "garb",
      "name": "Garb",
      "values": [
        { "id": "v-1", "text": "leather apron" },
        { "id": "v-2", "text": "soot-black smock" }
      ]
    }
  ],
  "dictionaries": [
    {
      "id": "book-1",
      "name": "Default",
      "enabled": true,
      "entries": [
        { "id": "lore-1", "name": "The War", "key": ["war", "old war"], "value": "A war ended here 40 years ago." }
      ]
    }
  ],
  "statUpdates": []
}

• 🛠️ World Editor: the editor that writes this format
• 🧮 Scripts Guide: what a script's code can do
• 🪪 Personas for Authors: persona marks and rules
• 🔗 Linked Content: linked copies and world files