AI Instructions
aiInstructionsaiInstructions holds per-task guidance for the AI steps Voyage runs in a world, keyed by task. This page covers what applies to every task: how your keys combine with the built-in sections. Each task has its own page in the sidebar.
"Task-specific guidance that changes how individual AI generation steps behave in this world. Defaults work without edits; use these overrides for decisions, tone, and constraints that authored content or Triggers do not already define."
- Editor location
- Files → AI
- Editor type
- Edit in Studio + View JSON
- Size limits
- Each string leaf under a task (
aiInstructions.<task>.<key>) — 5,000 - Per task (
aiInstructions.<task>total, whole task as compact JSON) — 20,000 - Each string leaf under
aiInstructions.generateNPCIntents— 8,000 aiInstructions.generateStorytotal — 30,000aiInstructions.generateNPCIntentstotal — 40,000aiInstructions.generateNPCDetailstotal — 28,964aiInstructions.generateNPCUpdatestotal — 24,000
- Each string leaf under a task (
Schema
{
"aiInstructions": {
"<key>": {
"<key>": "string"
}
}
}Example
{
"aiInstructions": {
"generateStory": {
"Victory and Downtime": "After a win or escape — if the player is resting or celebrating, focus the turn on that. Do not seed the next problem in the same paragraph.",
"Character Behavior": "NPCs act from consistent motivations. They know only what their position provides. They don't melt at flattery.",
"Style Principles": "Third person, present tense. Short sentences, strong verbs. No adverbs.\n\nBanned phrases: suddenly, you realize, it seems, somehow.",
"custom": "## World Rules\n[World-specific instructions: magic behavior, currency values, species norms, etc.]"
},
"generateActionInfo": {
"custom": "## Combat System\nMixed results means the goal is reached at a cost."
},
"generateInitialStart": {
"Opening Structure": "First beat: WHO. Second beat: WHERE. Third beat: one active situation already in progress.",
"custom": "## World Introduction\nIntroduce proper nouns with immediate context on first use."
}
}
}Note (deterministic alternative — triggers): instructions here are guidance the AI interprets. For anything that must happen at a set moment (one-time narration, state gates, key-locked progression) use triggers instead: a
storyeffect injects its instruction into story generation when the trigger fires, and mechanical conditions and effects change state directly. ReserveaiInstructionsfor voice, tone, and flexible guidance.
Default keys, overrides, and custom keys
Every task ships with default keys carrying Voyage's built-in instruction text. A new world keeps normal Voyage behavior by keeping those keys and their text as they are.
The second-level key name decides what an entry does:
- A key that matches a built-in editable section (for example
Victory and DowntimeundergenerateStory) overrides that section's built-in text. - Any other key name is appended as custom prompt text on top of the built-in behavior.
Deleting a default key does not remove its behavior - loading a world backfills missing default keys from the base config, so the deletion does not stick. To switch a built-in section off, set its key to an empty string ""; a missing key keeps the default. Use custom keys for additive behavior, and the exact default key names only when you intentionally want to replace those sections.
The tasks with named editable sections in the base config:
| Task | Built-in editable sections |
|---|---|
generateStory | How to Use the Narrator, Turn Structure, Turn Boundaries and Endings, Player Agency, Combat Narration, Victory and Downtime, Character Behavior, Style Principles |
generateInitialStart | Opening Structure, Style Principles |
generateActionInfo | impact |
generateCharacterBackground | prompt |
generateConversationStarters | Conversation Starter Guidance |
generateDialogue | Style, Tone, and Length |
generateNpcChatSummary | Summary Guidance |
generateNPCIntents | core_principles, when_to_generate, what_is_not_action, description_economy, summary_established_beats, action_format, story_driver, combat_tactics |
generateNPCDetails | character_creator_instructions, personality_archetype_information, style, cliche_avoidance, hidden_info, personality, faction_affiliation, abilities, basic_info |
generateNPCUpdates | relationship_initialization, relationship_change_updates, party_management |
Every task also carries a custom key, and the remaining tasks ship with only custom - for those, any key you add is appended as custom instructions.
Processing order
Concatenation logic
Task names must match the engine's task IDs exactly (see the sidebar for the full list), and each value is a markdown-capable instruction string. A rule placed in the wrong task reaches the AI at the wrong moment.
For every task with editable keys:
- Engine loads its base instructions for the task
- World config overrides are loaded
- For each editable key: the world's value is used if present (an empty string blanks the section), otherwise the engine default
- Any custom keys you add (beyond the editable defaults) are appended after defaults
- All non-empty instructions are combined
A key whose name matches a section the engine writes itself is stripped on save and never reaches the prompt. If a custom key disappears after saving, rename it.
Keys are case-sensitive and must match exactly. Style Principles will not match style principles.
Non-standard task keys
Non-standard task keys: Only the task keys documented on these pages are standard. Any other key under
aiInstructionsgets a validator warning: Voyage accepts the world, but whether the engine reads a non-standard key isn't documented.
authorSeeds for a consistent NPC voice
A single authorSeeds entry anchors one voice.
Because generateNPCDetails selects a seed at random, defining exactly one comprehensive style entry means every seed-consulting run uses that same voice — a simple way to keep strong / elite / boss / mythic-tier NPC prose consistent without repeating style instructions across tasks. Add more entries when you want the generator to vary between several registers; selection is random, so you cannot pin a specific seed to a particular NPC.