Modding

Mods are partial world configurations that can be layered onto any world. The creation process is identical to creating a world - same editor, same JSON sections, same schema - with one difference: the Type field in the creation UI is set to Mod instead of World. No section is required; include only what the mod contributes.

#How mods work

A mod is a partial V36 world JSON. Most top-level sections can be included freely - triggers, locations, itemTypes, npcs, abilities, and so on. aiInstructions is the exception (see below). When a world imports a mod, the engine merges each section into the world:

• Content sections (itemTypes, locations, npcs, triggers, etc.) - mod entries are appended to the world's existing entries. itemTypes is directly tested; locations is confirmed by the official description. Behavior of other content sections has not been independently tested.
• Keys the world already defines - the world wins. This holds across sections, not just nameFilterSettings: where a mod and the world define the same key, the world's entry is kept whole and the mod's is discarded. A mod adds what the world lacks; it does not replace what the world has.
• aiInstructions - special case, see What a mod can contain.

The official description: "A mod is just a partial world. Instead of having every section filled, you can just make 1 section, like locations, and then publish it. Anyone who imports your mod will add on all of your locations to their existing world's locations."

#Creating a mod

1. Click Create → Create a World in the Voyage UI
2. Set Type to Mod (instead of World) in the creation form
3. Fill in only the sections the mod should contribute - leave all others empty
4. Publish to receive a shortId

The editor UI, all tabs, and all JSON fields are identical to a world. The Type field is the only distinction.

Mods validate against the full V36 schema. All required top-level fields (configVersion, heroesVersion, storySettings, triggers, itemTypes, npcs, etc.) must be present - even in a mod that only contributes one section. Leave every section you don't need as an empty object {} or empty array []. The default world template is the correct starting point for a new mod.

#Schema

The mods field on a world is the list of installed mods:

"mods": [
  { "shortId": "abc123", "version": null },
  { "shortId": "def456", "version": 2 }
]

#What a mod can contain

Any standard V36 top-level section - triggers, locations, itemTypes, npcs, abilities, nameFilterSettings, and so on. A mod containing only triggers is valid; so is one containing only nameFilterSettings. A mod can also span multiple sections. Include whatever sections the mod contributes.

aiInstructions is a special case. It is a top-level field but requires every default task key to be present whenever it is included - you cannot include only the tasks you want to change. The tasks you leave alone must be present as empty {}.

#Examples

#Name replacement mod (nameFilterSettings only)

{
  "nameFilterSettings": {
    "Marcus": { "replacements": ["Aldric", "Brennan", "Cael", "Dorian", "Emric"] },
    "Elena":  { "replacements": ["Mira", "Sable", "Vesper", "Corrin", "Laith"] }
  }
}

#NPC intent grounding mod (aiInstructions only)

{
  "aiInstructions": {
    "generateStory":             {},
    "generateInitialStart":      {},
    "generateCharacterBackground": {},
    "generateActionInfo":        {},
    "generateNPCIntents": {
      "custom": "Stay grounded in the current scene. Do not invent new threats or emergencies that have not been established. Do not escalate calm scenes without cause. NPC goals should follow from what is actually happening, not from a need to manufacture tension."
    },
    "generateNewNPC":            {},
    "generateNPCDetails":        {},
    "generateLocationDetails":   {},
    "generateRegionDetails":     {},
    "generateEncounters":        {},
    "generateNPCUpdates":          {},
    "generateLearnedAbilities":    {},
    "summarization":               {},
    "ItemGenerationAndUsage":    {}
  }
}

#Multi-section mod (nameFilterSettings + aiInstructions)

{
  "nameFilterSettings": {
    "Mira":   { "replacements": ["Sable", "Vesper", "Corrin", "Laith"] },
    "Elara":  { "replacements": ["Thea", "Cora", "Nova", "Selene"] }
  },
  "aiInstructions": {
    "generateStory":             {},
    "generateInitialStart":      {},
    "generateCharacterBackground": {},
    "generateActionInfo":        {},
    "generateNPCIntents":        {},
    "generateNewNPC": {
      "custom": "Derive names from world context: use the current region, location, and world background as cultural sources. Do not default to generic fantasy or modern name pools."
    },
    "generateNPCDetails":        {},
    "generateLocationDetails":   {},
    "generateRegionDetails":     {},
    "generateEncounters":        {},
    "generateNPCUpdates":          {},
    "generateLearnedAbilities":    {},
    "summarization":               {},
    "ItemGenerationAndUsage":    {}
  }
}

type: "story" conditions are well-suited for trigger mods - they let conditions be expressed as plain-language AI-evaluated descriptions rather than structured boolean checks, which is useful when the trigger fires on contextual cues with no discrete state to query.

#Referencing a mod in a world

The mods field is managed through the Mods tab in the world editor. The tab shows active mods in numbered order, with arrows to reorder them and an × to remove. Each mod entry displays its ID (the shortId) directly in the UI - no need to find it elsewhere. A Total Mod Rating badge reflects the aggregated content rating of all active mods. A separate Bookmarked Mods section holds saved mods that are not currently active.

Changes do not take effect until you click Apply. The Apply button merges the active mod stack into the world configuration. This is also when validation errors from the merged result surface - if a mod pushes the world over a limit, the error appears on apply.

#Limits and collisions

Mods merge additively into the world, so the combined result must still satisfy all V36 size and count limits. A mod that pushes a near-full world over any limit will fail to apply - the engine returns a generic "Failed to build mods" error with no indication of which limit was hit or which mod caused it.

Array sections accumulate across world + all active mods and the combined total must stay within section limits. When the error occurs, remove mods one at a time to isolate the culprit.

⚠️

Warning (shared keys can produce a world that will not save): When a mod and the world define the same entry, the write-back can emit that entry carrying only the fields whose values differed, leaving the rest absent. The result fails validation on the missing required fields, and the save is refused with a list of them. Keeping mod keys distinct from the world's own keys avoids it.

#The world wins a collision

The world's entry is kept. Where the world and a mod both define the same key, the world's value survives and the mod's is discarded; keys the world does not define are added from the mod. Tested on traits and on nameFilterSettings, with the same result: a trait the world already defined kept its own description and starting items, while a trait only the mod defined appeared as written.

This is worth setting against the Mods tab, which describes mods as overriding the base world. They do not. A mod is additive, and the world has the last word on anything it already says.

#Content section merge

Mod entries are appended. A mod adding itemTypes entries will have those entries appear in the merged world alongside the base world's existing items. locations follows the same pattern per the official description. Behavior of other content sections has not been independently tested.

#Between two mods, the later one wins

The mod further down the order takes the key. With two mods defining the same key and nothing in the world defining it, the mod at the higher order number supplies the value. Tested both ways round on a fresh world each time, and the answer followed the position rather than the mod.

#The full order

Each layer overwrites the one before it, and the world is applied last:

mod (order 1)  <  mod (order 2)  <  ...  <  world

So a later mod beats an earlier mod, and the world beats every mod.

#version: null means always latest

The Voyage mod list displays null version as "latest", confirming it tracks the most recent published version of the mod rather than a pinned one.

#Applying a mod writes into the world, and the write stays

Applying is not an overlay. The merged result is written into the world's own saved sections, and it remains there afterwards: entries a mod contributed have been observed still present in a world's stored traits after they were taken out of the mod that supplied them. A world that has applied a mod is not the world it was before.

Treat applying a mod to a world you care about as an edit to that world rather than something you can switch off, and try mods against a copy first.

#Remix is the top merge layer

A remix is the engine's mechanism for cloning a published world into your own editable personal copy. Mechanically, a remix is implemented like a mod — but it always sits at the top of the merge stack. The full priority order is Remix > Mod 1 > Mod 2 > ... so the remix layer always wins conflicts, then mods apply in their listed order.

⚠️

Warning: the merge rules above are based on testing, but many users have reported inconsistencies — content occasionally disappears unexpectedly. This shows up most often on remixed worlds with mods applied on top, where the stacked merge layers (Remix + Mods) compound the chance of a collision dropping content. If you cannot afford content loss, the safer pattern is to strip the remix layer before adding mods:

1. Remix the world you want to start from.
2. Open the remix in the editor and copy the full world JSON.
3. Create a fresh new world (not a remix).
4. Paste the JSON into the new world. You now have the same content with no remix layer underneath.
5. Apply your mods on top of the new world.

The merge stack is now just World > Mod 1 > Mod 2 > ..., with no remix layer to compound collisions.