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: a mod is processed like a normal world, so the sections it leaves out are backfilled. Include only what the mod contributes. The Mod label only changes how it is listed on the site and how it interacts with other people's worlds once applied.

#How mods work

A mod is a partial V37 world JSON. Most top-level sections can be included freely - triggerDefinitions, locations, itemTypes, npcs, abilities, and so on. aiInstructions works the same way. When a world imports a mod, the engine merges each section into the world:

• Content sections (itemTypes, locations, npcs, triggerDefinitions, etc.) - mod entries are added alongside the world's existing entries.
• 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.

#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.

#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 V37 top-level section - triggerDefinitions, locations, itemTypes, npcs, abilities, nameFilterSettings, and so on. A mod containing only triggerDefinitions is valid; so is one containing only nameFilterSettings. A mod can also span multiple sections. Include whatever sections the mod contributes.

That includes aiInstructions: list only the tasks the mod changes, and Voyage seeds the default entries for the rest.

#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": {
    "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."
    }
  }
}

#Multi-section mod (nameFilterSettings + aiInstructions)

{
  "nameFilterSettings": {
    "Mira":   { "replacements": ["Sable", "Vesper", "Corrin", "Laith"] },
    "Elara":  { "replacements": ["Thea", "Cora", "Nova", "Selene"] }
  },
  "aiInstructions": {
    "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."
    }
  }
}

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 V37 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. A trait the world already defined keeps its own description and starting items, while a trait only the mod defines appears as written; nameFilterSettings behaves the same way.

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 added. A mod adding itemTypes or locations entries has them appear in the merged world alongside the world's existing ones.

#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. The value follows the position, not 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 Mods tab shows a null version as "latest": the world tracks the mod's most recent published version 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 stay in the world's stored sections even after they are 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: content can disappear unexpectedly when merge layers stack, 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.