Build a Scenario
A step-by-step walkthrough for creating a complete NPC — from persona to publishable scenario — in the Foil Engine editor.
1. Create a persona
Click Create NPC from the dashboard. Fill in a name, identity prompt (backstory and personality), and a short description that explains who this character is. These fields are injected into every AI call as system-level context.
2. Add a scenario
A scenario defines what the player is trying to accomplish. Set an objective that describes the goal, then configure win and lose conditions so the engine knows when a conversation has reached a conclusion.
3. Add states
States represent phases of the conversation. Every scenario needs at least one initial state (where the conversation starts), one or more intermediate states (the middle of the interaction), and one or more terminal states (win/lose endpoints). Write a system prompt for each state that tells the AI how to behave during that phase.
4. Configure transitions
When you add a state, default transitions (pass, reject, kick_out) are created automatically. Click any transition to edit its decision type and write a condition that describes when the transition should fire.
5. Use AI generation
Foil Engine offers a two-step generation flow. First, generate the identity — the AI will draft a name, backstory, and personality for you. Then generate the scenario — the AI will create states, transitions, and prompts based on the identity you approved. You can edit everything after generation.
6. Polish prompts
Select any text field and click Polish to have the AI refine your wording. This is useful for tightening system prompts, sharpening transition conditions, or improving the persona description. Polish rewrites the field in place — review the result and edit further if needed.
7. Preview with the diagram
Click the Diagram tab to see a read-only visualization of your state machine. The diagram shows all states as nodes and all transitions as edges, laid out automatically. Use it to verify your scenario's structure — check for missing connections, orphaned states, or paths that don't reach a terminal state.
8. Link multiple scenarios
If your persona has two or more scenarios, a Machine Links section appears in the editor. Create links to control which scenario unlocks after another completes. Each link has a condition — unlock based on outcome (ACCEPT, REJECT, KICK_OUT), score threshold, or always. Mark a link as auto-advance to skip the scenario selection screen and move the player directly into the next conversation.
9. Set up cross-machine variables
To carry information between scenarios, expand the Cross-Machine Variables section inside a scenario's editor. Add output variables to extract data when the scenario completes — give each a key and an extraction prompt (e.g. "What item did the player choose?"). On the receiving scenario, add input variables with the same key and an inject_as label that tells the AI how to use the value.
chosen_weapon, extraction prompt = "What weapon did the player buy?" Input on "Arena": key= chosen_weapon, inject_as = "The player is carrying this weapon". The AI in the Arena scenario will know the player has a longsword (or whatever was extracted).