# VoyageWiki

Voyage Heroes V33 schema reference for Voyage world authors and the AI agents that help them.

Full API documentation with examples: https://voyagewiki.pages.dev/tools/api

## Machine-readable API

Reference docs (GET, returns JSON or Markdown):
- https://voyagewiki.pages.dev/api/index.json: manifest of all endpoints
- https://voyagewiki.pages.dev/api/sections.json: lightweight index of every documented section
- https://voyagewiki.pages.dev/api/sections/<section>.json: one section's full content + V33 schema fragment
- https://voyagewiki.pages.dev/api/sections/<section>.md: same as above, Markdown-formatted for LLM ingestion
- https://voyagewiki.pages.dev/api/wiki.json: entire wiki aggregated as JSON
- https://voyagewiki.pages.dev/api/wiki.md: entire wiki concatenated as Markdown
- https://voyagewiki.pages.dev/api/schema.json: raw V33 codec

Validation (POST world JSON, returns errors/warnings/recommendations):
- https://voyagewiki.pages.dev/api/validate: same checks as the in-browser validator; returns { counts, errors, warnings, recommendations, validatorVersion }

## Agent guidance

When authoring or editing a Voyage Heroes V33 world JSON:

- Fetch only the sections you need from /api/sections/<section>.md, or pull the whole reference from /api/wiki.md in one request.
- Verify the world by POSTing it to /api/validate. The response groups issues by severity:
  - errors: runtime-affecting problems. Fix these. The Voyage editor publishes worlds with errors intact, but the engine silently drops fields or breaks lookups at runtime.
  - warnings: quality issues. Many are intentional design choices; read the "Safe to ignore when..." line in each message before acting.
  - recommendations: best-practice suggestions, same rule as warnings.
- Validate after each batch of changes. Do not declare work complete until counts.errors is 0.

## Sections

- [Story Instructions](https://voyagewiki.pages.dev/ai/aiInstructions): `aiInstructions` is where you write the rules the narrator follows during play, organized into tasks each firing at a specific moment. This page covers the cross-task mechanics: processing logic and the two internal non-authorable tasks. Each individual task has its own page in the sidebar.
- [Action Info](https://voyagewiki.pages.dev/ai/generateActionInfo): Fires on action resolution and combat. High priority: governs all mechanically-weighted actions — combat, spells, skill checks, and social rolls. Missing rules create inconsistent outcomes.
- [Character Background](https://voyagewiki.pages.dev/ai/generateCharacterBackground): Fires on demand when a player inspects a character's detailed profile. Generates biographical history — distinct from basicInfo/hiddenInfo. Because it fires on demand rather than continuously, it suits detailed backstory constraints that would waste budget in `generateStory`.
- [Encounters](https://voyagewiki.pages.dev/ai/generateEncounters): Fires when framing an encounter. Low priority: `encounterElements` in Other provides the source palette. Use custom to set difficulty mix, creature behavior rules, and non-combat resolution conditions.
- [Faction Details](https://voyagewiki.pages.dev/ai/generateFactionDetails): Generates faction details — hidden agendas, operating methods, and the gap between stated purpose and actual practice. Use custom to shape how `factions` are portrayed beneath their public face.
- [Initial Start](https://voyagewiki.pages.dev/ai/generateInitialStart): Fires on the first scene of a new game only. Controls how the opening scene is constructed: structure, pacing, and first impressions.
- [Item Generation/Usage](https://voyagewiki.pages.dev/ai/generateItemGenerationAndUsage): Provides context to generateItemDefinitions (newly created `items`) and generateItemUpdates (inventory changes). Not included for `generateActionInfo` or `generateStory`. The JSON key is `ItemGenerationAndUsage` — non-standard casing.
- [Learned Abilities](https://voyagewiki.pages.dev/ai/generateLearnedAbilities): Evaluates story events for opportunities to grant new `abilities`. Low priority: most turns produce no output. Use custom to define the world's learnable ability families and acquisition methods.
- [Location Details](https://voyagewiki.pages.dev/ai/generateLocationDetails): Generates location descriptions, areas, and paths. Low priority: a well-written basicInfo carries most of the load. Use custom to add sensory layers, archetype integration rules, and atmosphere guidance.
- [New NPC](https://voyagewiki.pages.dev/ai/generateNewNPC): Fires for first-pass creation of AI-improvised NPCs only. Does not apply to authored NPCs or quest-spawned NPCs. `generateNPCDetails` still runs on all NPC types on first encounter.
- [NPC Details](https://voyagewiki.pages.dev/ai/generateNPCDetails): Fires once when an AI-created NPC first appears in scene with only minimal first-pass data. Generates the full basicInfo, hiddenInfo, personality, and `abilities` record. Distinct from `generateCharacterBackground`, which is on-demand biographical lore.
- [NPC Intents](https://voyagewiki.pages.dev/ai/generateNPCIntents): Fires when the AI chooses NPC goals for a turn. Medium priority: near-constant in NPC-heavy play. Controls quality gates, escalation pacing, and per-scene-type intent logic. Supports multiple named keys for scene-type-specific behavior.
- [NPC Updates](https://voyagewiki.pages.dev/ai/generateNPCUpdates): Fires when an existing NPC's state changes during play — location, mood, status, or relationship updates. Controls continuity: which fields can change, how quickly, and what in-scene evidence is required.
- [Region Details](https://voyagewiki.pages.dev/ai/generateRegionDetails): Generates region descriptions, `factions`, and `locations`. A content-generation task — not narration. Use custom to shape geographic identity, faction character, and location types for generated `regions`.
- [Story](https://voyagewiki.pages.dev/ai/generateStory): The primary narration task. Fires most frequently during active play — keep instructions tight and protect this budget first.
- [Image Prompt Configuration](https://voyagewiki.pages.dev/ai/imagePromptConfiguration): Custom prompt templates for AI image generation per content category. Author-provided strings layered on top of Voyage's default image prompts for NPC portraits, location art, and region art.
- [Story Memory](https://voyagewiki.pages.dev/ai/summarization): Custom guidance for how the AI summarizes recent and past story context. Use it to name the world-specific details summaries should preserve for long-term continuity, so key facts are not forgotten or garbled. Newly author-editable.
- [Advanced AI Instruction Techniques](https://voyagewiki.pages.dev/appendix/ai-advanced-techniques): Instruction patterns observed in authored worlds that go beyond standard custom block usage — priority overrides, conditional routing, behavior suppression, and spawn guards. These are prose instructions to an AI model. The AI interprets and applies them; compliance is high but not guaranteed.
- [Narrative & AI Authoring](https://voyagewiki.pages.dev/appendix/narrative-and-ai): Cross-cutting authoring guidance for the narrator AI.
- [Narrator Chat Tools](https://voyagewiki.pages.dev/appendix/narrator-chat-tools): Read and modify tools the narrator can call through the in-game chat. Listing of every tool and what it returns or changes.
- [Scripting Patterns](https://voyagewiki.pages.dev/appendix/scripting-patterns): Mechanics that go beyond the schema. Trigger scripts, persistent state, and worked recipes.
- [Validation & Size Limits](https://voyagewiki.pages.dev/appendix/validation-and-size-limits): How the io-ts codec validates JSON, the hard size caps the editor enforces, and what the local validator script checks beyond the codec.
- [Voice Catalog](https://voyagewiki.pages.dev/appendix/voice-catalog): Every NPC can be given a `voiceTag` string that maps to a specific TTS voice. The gender prefix is part of the tag string and must be included (e.g. `"female posh british"`, `"male baritone warm"`). See the catalog below for all valid values.
- [Abilities](https://voyagewiki.pages.dev/mechanics/abilities): Abilities are named actions characters can attempt - magical powers, combat techniques, special manoeuvres. Each ability is gated by skill or trait `requirements` and modifies how the engine resolves the resulting roll.
- [Attributes](https://voyagewiki.pages.dev/mechanics/attributeSettings): Attributes are the core stats of your system - strength, dexterity, intelligence, or whatever names fit your world. They drive skill-roll modifiers and optionally scale resource pools.
- [Combat Settings (Advanced)](https://voyagewiki.pages.dev/mechanics/combatSettings): Numeric tuning for the combat system: XP rewards for defeating enemies, ability recharge timing, ability effectiveness bonus, NPC daily healing, and the canonical list of valid damage types for your world.
- [Death Rules](https://voyagewiki.pages.dev/mechanics/death): Defines what happens when a character's health hits zero. `permadeath` controls whether `death` is permanent; `instructions` is prose fed directly to the narrator describing the downing and recovery process.
- [Item Settings](https://voyagewiki.pages.dev/mechanics/itemSettings): Defines the equipment system: the name of your currency, the item categories that exist, the equipment slots characters have, and the `items` given to every player at the start of every game regardless of trait or story start.
- [Resources](https://voyagewiki.pages.dev/mechanics/resourceSettings): Resources are the tracked bars in your game - `health` is required, everything else (mana, stamina, corruption, etc.) is optional. Each resource defines a current/max value, UI bar color, recharge rate, and usage instructions for the narrator.
- [Skills](https://voyagewiki.pages.dev/mechanics/skills): Skills are the rolled actions characters attempt. Each skill connects to one attribute (which contributes to the check total), has a `type` string for difficulty bonuses, and a description that defines what it covers.
- [Skill Settings (Advanced)](https://voyagewiki.pages.dev/mechanics/skillSettings): Global skill mechanics — XP costs for leveling, skill learning chance, maximum skill level, and the difficulty check thresholds that translate difficulty labels (Easy/Hard/etc.) into numeric bonuses.
- [Trait Categories](https://voyagewiki.pages.dev/mechanics/traitCategories): Categories group `traits` together and control how many the player can pick from each group. Each category must be defined before `traits` can be assigned to it - the `traits` array lists which trait names belong to this category.
- [Traits](https://voyagewiki.pages.dev/mechanics/traits): Traits are the character creation choices - race, class, background, and any other categories you define. Each trait is a bucket of `skills`, attributes, resources, `items`, and `abilities` the chosen character receives.
- [Triggers](https://voyagewiki.pages.dev/mechanics/triggers): Conditional automations that fire effects when their conditions all pass. The primary mechanism for quest activation, state flags, world-mutation, and one-time narrator instructions. Triggers are deterministic where narrator instructions are probabilistic -- use `triggers` for anything that must mechanically happen.
- [Modding](https://voyagewiki.pages.dev/mods/modding): How to create and use `mods` in Voyage Heroes. Layered partial world JSON: same editor, same schema, no required sections.
- [NPC Author Seeds](https://voyagewiki.pages.dev/other/authorSeeds): Named NPC-writing-tone presets. Each key is a display label; the value is a multi-line directive injected into `generateNPCDetails` when that seed is selected.
- [NPC Archetypes (Advanced)](https://voyagewiki.pages.dev/other/characterArchetypes): Keyed personality scaffolds for character background generation. Each archetype is a structured prompt block with **Drives, Traits, Morality, and Relationships** sections.
- [Character Creation Music](https://voyagewiki.pages.dev/other/characterCreationMusic): Selects which background music track Voyage plays during the character creation flow. Top-level enum field accepting `fantasy` or `nonfantasy`. Omit the field to play no music during character creation.
- [Encounter Elements (Advanced)](https://voyagewiki.pages.dev/other/encounterElements): These define the encounter palette - a curated menu of possible scenarios the AI draws from when generating random encounters. Short entries work; longer entries are more specific.
- [Game Modes](https://voyagewiki.pages.dev/other/gameModes): Player-selectable modes chosen during character creation. Each mode is a named bundle of story instructions, with an optional difficulty preset and an optional opening narrator message.
- [Location Archetypes (Advanced)](https://voyagewiki.pages.dev/other/locationArchetypes): These strings go to the AI when it needs to describe or expand a location. Write them as tone directions, not encyclopedia entries - the AI doesn't need a lore summary, it needs to know what makes this type of place feel distinct.
- [Location Settings (Advanced)](https://voyagewiki.pages.dev/other/locationSettings): Controls the map and travel system parameters: region size, location radii, travel distances, how many `factions` the engine places in AI-generated `regions`, and whether new `regions` and encounters can be created during play.
- [Name Filter Settings](https://voyagewiki.pages.dev/other/nameFilterSettings): Keyed map of name replacement rules. Each key is a name (or name fragment); its value provides a list of allowed replacements. When a generated name matches a key, the AI substitutes one from the replacements array.
- [Narrator Style](https://voyagewiki.pages.dev/other/narratorStyle): A dedicated prose style field separate from `aiInstructions`. It shapes sentence rhythm, tense, person, vocabulary register, and sensory detail level. Leave the value as `""` to use default narration.
- [Other Settings (Advanced)](https://voyagewiki.pages.dev/other/otherSettings): XP thresholds, level cap, and NPC health scaling for your scenario.
- [Random Character Names (Advanced)](https://voyagewiki.pages.dev/other/randomNames): Name pools the engine draws from when generating character names. Used by the randomize button in character creation and by AI-generated NPC names.
- [Region Archetypes (Advanced)](https://voyagewiki.pages.dev/other/regionArchetypes): These strings go to the AI when it needs to describe or expand a region. Write them as tone directions - what makes this type of terrain or territory feel distinct politically, physically, and atmospherically.
- [Tip Settings (Advanced)](https://voyagewiki.pages.dev/other/tipSettings): Tips are player-facing messages shown periodically during play - the only section of the scenario that speaks directly to a human player rather than to the AI. Use them to surface mechanical rules the player might forget or set tonal expectations.
- [Factions](https://voyagewiki.pages.dev/world/factions): Factions are the named organizations in your world - governing bodies, guilds, cults, criminal networks, or any group with shared goals. Each has a public face (`basicInfo`), a hidden agenda (`hiddenInfo`), and a type (major or minor).
- [Items](https://voyagewiki.pages.dev/world/items): Items are the objects players can carry, equip, and use. During play all `items` are AI-generated, but every item that can appear in a `startingItems` list - on a trait, story start, or `itemSettings` - must be defined here first.
- [Locations](https://voyagewiki.pages.dev/world/locations): Locations are the named places on the map - cities, ruins, dungeons, waypoints. Each has a `basicInfo` description for the narrator, optional `hiddenInfo`, named `areas` inside it with their own descriptions, and `paths` to adjacent `locations`.
- [Map Editor](https://voyagewiki.pages.dev/world/map-editor): The Map Editor is a visual canvas accessible from the **Regions** and **Locations** sidebar items. It's the fastest way to build the world map - you don't have to touch JSON for placement at all.
- [NPCs](https://voyagewiki.pages.dev/world/npcs): `basicInfo` is what the narrator reads during play, so any appearance you want described in play must live here; it is also the image generator's source when `visualDescription` is empty. `hiddenInfo` is what the player has not yet discovered (revealed only through play). `visualDescription` is read only by the image generator (never the narrator) and takes priority over `basicInfo` for portraits, so use it alongside `basicInfo` only for image-specific appearance the narrator should not describe.
- [NPC Types (Advanced)](https://voyagewiki.pages.dev/world/npcTypes): NPC types define behavior templates for categories of NPCs. Each type lists `vulnerabilities`, `resistances`, and `immunities` to `skills` and damage types.
- [Premade Characters](https://voyagewiki.pages.dev/world/premadeCharacters): Pre-built character templates a player can select at session start instead of building one from scratch. JSON-only field with no dedicated editor panel - edit it via the full-world JSON tab.
- [Quests (Advanced)](https://voyagewiki.pages.dev/world/quests): Quests are pre-authored story objectives that start hidden and become visible only when a trigger fires `quest-init`. Every quest needs at least one trigger pointing to it - `quests` with no trigger are permanently unreachable.
- [Realms (Advanced)](https://voyagewiki.pages.dev/world/realms): A realm is the top-level container for your `regions` - the world, country, or dimension the story takes place in. Most scenarios need exactly one. Use multiple `realms` only for true planar or dimensional scenarios.
- [Regions](https://voyagewiki.pages.dev/world/regions): Regions are the geographic map units - the named zones that appear as cells on the player's interactive map. A realm contains all `regions`; `locations` are the specific points of interest inside a region.
- [Story Overview](https://voyagewiki.pages.dev/world/storySettings): `storySettings` contains the world background and quest generation guidance for your scenario. `worldBackground` is the canonical world description; `questGenerationGuidance` is a targeted brief for dynamically-generated `quests`.
- [Story Starts](https://voyagewiki.pages.dev/world/storyStarts): Story starts are the selectable opening scenarios players choose from at the start of a game. Each defines the initial scene, what the player has, and the first narration. A scenario needs at least one start; most have two or three.
- [World Lore](https://voyagewiki.pages.dev/world/worldLore): `worldLore` is ambient context the AI draws on when generating narration and NPCs. It is not player-visible - players never read these entries directly. Think of it as the set of facts the narrator considers true about the world.