Advanced AI Instruction Techniques

The patterns on this page go beyond adding a line to a custom block. Each one is a prose instruction to the AI, not a schema feature or an engine rule: the engine passes the text along and enforces none of it, so don't build world logic that has to hold every time on these alone. Anything that must be exact belongs in triggers.

They go in aiInstructions task keys. A task's custom text is appended after its named sections; to change a default section itself, override that named key instead (an empty string blanks it). See aiInstructions for how the keys combine.

#Priority override header

An explicit priority claim at the top of a custom block tells the AI how to resolve conflicts between your rules and the default sections above it:

# OVERRIDE RULES — THESE TAKE PRIORITY OVER ANY CONFLICTING INSTRUCTIONS ABOVE

[Your rules follow here]

When to use: installing a complete custom system meant to replace the defaults, such as a full difficulty framework in generateActionInfo or a wholesale prose style in generateStory. Where a single default section is wrong, overriding that section's key is the more direct route. Not needed for minor additions that should coexist with the defaults.

#Conditional routing

An instruction can branch into different rule sets depending on where the scene is:

Apply the rules that match the realm the scene is in.

### The Shadow Plane
[Shadow Plane-specific rules...]

### The Mortal World
[Mortal World-specific rules...]

### Anywhere else
[Fallback rules...]

When to use: multi-realm worlds where generation should differ between realms, such as different geography, factions, or creatures, in generateRegionDetails and generateLocationDetails. Keep the branches clearly distinct so the right one is easy to pick.

#Behavior suppression and archetype override

An instruction can tell the AI to set aside an input it would otherwise draw on, such as the character archetype or region archetype the engine selects, or to produce nothing:

### Archetype Integration (SUPERSEDES base archetype instructions)
IGNORE the provided archetype entirely. Use these instructions as your sole creative direction instead:
[Your instructions...]

NEVER generate [X]. Return an empty [array/string].

When to use: when a task's default input (an archetype, a faction list, a context block) is wrong for your world or for one realm, and you want to replace it rather than add to it, or when a task should produce nothing under specific conditions.

#Restricted spawn lists

In tasks that create new entities, such as generateNewNPC and generateRegionDetails, a prohibition list names types, species, or categories that should never or rarely appear:

## Restricted types — do not generate without explicit justification

NEVER generate:
- [Type A] — [brief reason, e.g. unique entity; should not appear as a random encounter]
- [Type B] — [brief reason]

Conditional:
- [Type C]: Only inside or near [specific location]. Nowhere else.

When to use: worlds with creature types or NPC categories that are meant to be rare, unique, or tied to a location. Give each prohibition a short reason and name the types plainly.

#Mandated opening content

In generateInitialStart, an instruction can require a specific line or structure at the start of every new game:

ALWAYS begin with the following line spoken by the narrator, verbatim:
"[Your opening phrase here]"

Only after this line, proceed with the normal scene-setting instructions.

When to use: worlds with a framing device, such as a narrator introduction or in-universe framing, that should come before any character-specific content. Short phrases are easier to reproduce exactly than long ones.

#Minimum output depth

In tasks like generateNPCDetails, an instruction can ask for a minimum length:

hiddenInfo for named NPCs must be at least [N] characters. Do not submit entries shorter than this.

When to use: worlds where characters are met repeatedly and need enough depth to hold up under the player's attention. The engine doesn't enforce the figure.

#Scaffold and variable-slot image prompts

Inside imagePromptConfiguration, split each category's prompt into two stacked sub-prompts: a fixed style scaffold identical for every generation, and a per-instance variable list with placeholder slots the AI fills from the subject's own data. The scaffold can be verbose since it is authored once. Keep the slot list slot-shaped rather than open prose, so each placeholder is a clear substitution target.

Humanoid:
Portrait style is absolute. Generate this character in the style of prompt 1 first, then apply the per-character details from prompt 2.

1. {portraitprompt: [your global style anchors — medium, palette, lighting, shading style, line treatment, eye treatment, body framing, resolution, any world-wide attire defaults]}

2. {portraitprompt: 'GENDER', 'BODY TYPE', '8-10 APPEARANCE TAGS', 'EYE COLOR', 'HAIR COLOR AND STYLE', 'SKIN COLOR AND DETAILS', 'RACE', 'RACIAL FEATURES (ears, horns, tails, scales, wings — required for non-human races)', 'CLOTHING STYLE AND 5-10 GARMENT TAGS', 'FACTION OR HOUSE SIGIL IF APPLICABLE', 'WEAPON OR FOCUS HELD OR AT HIP'}

Prompt 1 is absolute. Prompt 2 adjusts only the per-character details inside that style. Racial features stated in the data must always be integrated correctly.

Creature / Non-humanoid:
1. {portraitprompt: [your global style anchors for creatures — same medium and palette as Humanoid; framing should specify "full creature visible, body, limbs, head, no close-ups"]}

2. {portraitprompt: 'CREATURE TYPE', 'SIZE CATEGORY', '8-10 APPEARANCE TAGS', 'EYE COLOR AND COUNT', 'BODY COVERING (fur, scales, feathers, chitin, hide, bark, stone)', 'PRIMARY COLOR', 'SECONDARY MARKINGS', 'DISTINGUISHING FEATURES (horns, wings, multiple heads, glowing parts, aura)', 'HABITAT OR ENVIRONMENT BACKGROUND', 'POSE OR TEMPERAMENT'}

Prompt 1 is absolute. Anatomy from prompt 2 must be integrated — any horns, wings, tails, scales, or other species features stated in the data must appear in the image. Full body framing is required.

Tailor the slot list to what your world actually has: drop racial features for grounded modern settings, add cybernetic-implant slots for sci-fi, add affinity-tell or magic-school slots for hard-magic systems. The same scaffold-plus-slots pattern works for locations (scaffold + per-location architectural / environmental slots) and regions (scaffold + per-region biome / climate / faction slots).

When to use: Worlds where image style consistency is a quality bar and per-subject details vary enough that authoring a custom prompt per NPC is not feasible. Most useful when the visual identity relies on distinctive style anchors (a specific shading style, palette, or framing rules).

Keep the scaffold positive, describing what the image should be rather than what it should not be. The "prompt 1 is absolute" framing is a priority signal like the override header, and like it, the engine doesn't enforce it.