NPCs

Optional. The character's true name behind the public-facing name. Use it when an identity is hidden or the NPC goes by a title or alias: players see name ("Inkwell" in the example above) while properName holds who they really are ("Davan Mosse"). Defaults to name when omitted. The identity counts as revealed once the two match: when the story reveals the true name, the NPC's displayed name updates to it automatically.

What the narrator reads during play, so any appearance you want described in play must live here. Also the image generator's source when visualDescription is empty.

What the player has not yet discovered, revealed only through play. Secrets, true motives, and hidden relationships live here so the narrator knows them without narrating them up front.

The NPC's npcTypes key — required (codec-enforced). The value must be a key defined in your world's npcTypes dict, or an empty string ("") for fully unique NPCs that don't share a damage profile with any type. Use a named type when this NPC shares a damage profile (vulnerabilities / resistances / immunities) with a defined species, creature category, or profession — the damage profile is authored on the npcTypes entry, and every NPC of that type inherits it.

Controls intent complexity, health scaling, and damage output. Defaults to average when omitted. See Combat mechanics for the full tier tables.

generateNPCDetails fires for any NPC with detailType: "basic" that the engine has flagged for detail generation — not gated by tier. Tier controls whether characterArchetypes and authorSeeds are consulted within the task (strong / elite / boss / mythic only).

Usually omit (auto-set at runtime). Defaults to "detailed" when omitted, so authored NPCs do not need to set it. "detailed" prevents generateNPCDetails from running for this NPC (authored content is preserved permanently); "basic" allows the engine to flesh out or overwrite NPC detail dynamically, and may reset detail that has not been encountered for an extended period.

Set explicitly for any NPC who should be stronger than the party — an explicit value is used as-is. If omitted or 0, the engine rolls a level near the party average at the moment the NPC first becomes visible (so it tracks the party's level at that point), then clamps it into the npcLevelRange of the NPC's location, or the region's range if the location defines none. Each NPC level adds +2 to the NPC's base damage.

Per-NPC scalar on the NPC's calculated maximum HP -- the value derived from level and tier. Default 1.0; 0.5 halves the pool, 2.0 doubles it, with values clamped to the 0.1–100 range. Affects the HP pool only, not damage output. Ignored when hpMax is set explicitly -- use one or the other, not both.

Must be an Array<string>, not a single string. The editor textarea auto-converts to an array on save, but JSON authored directly must already be an array or validation fails. Keep entries behavioral ("calculates every conversation for leverage") not adjectival ("smart, ruthless, charming").

Narrative context for the AI, not references to the top-level abilities section. They are not validated against that section and cannot be used by the player. Each entry is a prose capability description; the final entry is a fighting-style summary. See abilities format under Authoring tips for the writing conventions.

📋

Note (exposure and per-turn sampling): abilities (along with basicInfo and hiddenInfo) reach the AI only when the NPC is detailType: "detailed". They feed the combat-intent and detail-generation tasks but are not sent to the story narration. When generating combat intents the engine samples about 3 of the NPC's abilities at random each turn, re-sampling every turn — so a long ability list surfaces variety over a fight rather than all at once.

Read only by the image generator, never by the story narrator. The generator uses visualDescription when it is set and falls back to basicInfo when it is empty. Because the narrator never reads visualDescription, any appearance you want described in play must live in basicInfo regardless — the narrator has nothing else to draw from. So basicInfo always carries the narrated appearance, and visualDescription is an optional companion for portrait-only details: leave it empty and the portrait falls back to basicInfo (the simple default), or set both when you want the image to show specifics the narrator should not lock in.

There is one legitimate reason to populate visualDescription: when you want appearance prose fed only to the image model and explicitly not to the story narrator. Example: the story AI describes a character as "dressed plainly" without locking in colors or patterns every scene, but the image generator sees "faded blue tunic with patched sleeves, leather belt, scuffed boots" so portraits come out consistent across regenerations. In that case the split is the point. Outside that narrow case, leave the field empty.

Whether the NPC starts in the player's journal. Set to false for NPCs the player must discover, and use a known-entity trigger effect to reveal them at the right story moment. During play the party keeps its own record of which NPCs it knows.

Key of the location the NPC is in; matching ignores case and whitespace. Required. A key that names no location raises a warning. A blank "" keeps the NPC off-stage until something places it, such as an npc-placement trigger effect.

Area inside currentLocation. Required. A blank "" means somewhere in the location: the NPC can appear in any of its areas, so set an area only to pin the NPC to it. In a location with no areas ("areas": {}), leave it blank; a non-empty name there points at nothing and raises a warning. If the NPC should stand somewhere specific, add the area to the location first.

Optional starting relationship score toward the players, a number from -100 to 100; an explicit 0 is neutral. Omit it to let the AI choose a starting score using the generateNPCUpdates relationship initialization guidance. A value outside -100 to 100 is a validation error. The engine keeps the score as it moves during play separately, so this field only ever sets where an NPC starts.

Display name of the NPC, shown to players. Required; see Keys and name and properName for a hidden true name behind it. Don't name an NPC (key, name, or properName) allSceneNPCs, anySceneNPC, allPartyNPCs, anyPartyNPC, or satisfyingNPCs: an NPC answering to one takes over that trigger selector, and Voyage warns.

"male", "female", or "non-binary".

Key of the NPC's faction in factions, or "" for none.

Portrait image URL for this NPC, used as-is (skips AI portrait generation when set; the engine generates one when it is empty). Portraits are portrait-orientation: Voyage's own generator produces 896×1200, and the minimum is 600×600. The in-game card crops the image, so keep the face clear of the edges. In the editor you can upload your own or generate one from a prompt — both set this URL.

Optional map of named portraits for the NPC, keyed by portrait name. A trigger's npc-portrait effect switches the NPC to one of them by giving its key as the value, see trigger effects.

Positions the visible window over the source image along the horizontal axis, as a percentage: 0 holds the left edge, 50 centres it, 100 holds the right edge. Defaults to 50. Saved by the crop control rather than typed by hand; applies to an authored portrait, and generated portraits ignore it.

Positions the visible window over the source image along the vertical axis, as a percentage: 0 holds the top edge, 50 centres it, 100 holds the bottom edge. Defaults to 0 (the top). Saved by the crop control rather than typed by hand; applies to an authored portrait, and generated portraits ignore it.

Scales the image inside its frame, as a percentage of the unzoomed fit: 100 fills the frame with no magnification, 150 shows it at one and a half times, cropping to the area picked by the focus fields. Ranges from 100 to 300, default 100. Saved by the crop control rather than typed by hand; applies to an authored portrait, and generated portraits ignore it.

Previous portrait image URLs for this NPC, shown as Previous portraits in its details window so a player can restore one. Voyage adds to it when the portrait is replaced.

Maximum HP. An authored hpMax is used exactly as written: the game's difficulty never modifies it and healthMultiplier is ignored. Omit it to let the engine derive HP live from (npcHealthPerLevel * level + npcMinHealth) * tier modifier * healthMultiplier * difficulty modifier (see Other Settings for the per-level values). hpMax: 0 with hpCurrent: 0 spawns the NPC dead or dying.

Current HP; defaults to hpMax when omitted, and is clamped to the final hpMax.

The TTS voice for this NPC. See the Voice Catalog for the voices available to name. An NPC left without one is given a voice during play, matched from its gender and traits, so set it to pin a specific voice rather than take whichever fits. A tag outside the catalog is replaced with a catalog voice.

Points at a worldVoices entry by its key, giving this character that voice. It overrides the stock voiceTag pick for this NPC, whether or not the voice is offered in character creation. Use it when the voice is one the world defines and more than one character may share.

These union with the NPC's npcType arrays; the engine merges both. Use only when this specific NPC needs a damage profile beyond what its type provides.

These union with the NPC's npcType arrays; the engine merges both. Use only when this specific NPC needs a damage profile beyond what its type provides.

These union with the NPC's npcType arrays; the engine merges both. Use only when this specific NPC needs a damage profile beyond what its type provides.

Only for NPCs that should roll better or worse than normal: 25 points shifts every roll one success tier; a negative value lets an NPC fumble. Optional. Setting it at all, 0 included, also hands the narrator that NPC's rolled outcome, so its successes and fumbles show up in the prose; an NPC without the field, on itself or its type, rolls the same ladder unnarrated. An NPC that leaves it unset uses its npcType's successBonus, if the type has one. The editor's control accepts -1000 to 1000.

Percent change to outgoing damage (100 doubles it, -100 removes it). Only for NPCs whose hits should land harder or softer than level and tier imply. Optional, and an exception: an NPC without it behaves exactly as its level and tier describe. Set on npcs entries only. The editor's control accepts -100 to 10000.

Percent reduction to incoming damage (100 is true immunity). Only for unusually tough or untouchable NPCs. Optional, and an exception: an NPC without it behaves exactly as its level and tier describe. Set on npcs entries only. The editor's control accepts 0 to 100.