How It Works
Every interaction in Yumina follows the same cycle:
Player sends a message or interacts with the UI
↓
Engine assembles everything the AI needs to know
↓
AI generates a narrative response + state changes
↓
Engine extracts the changes and updates the game
↓
Player sees the story, updated UI, and hears audioThat's it. Your entire job as a creator is deciding what goes into that loop — what the AI reads, what it tracks, what happens automatically, and how it's presented.
The Building Blocks
1. Entries — What the AI Reads
Entries are pieces of text the AI sees when generating a response. A character description, a world rule, a writing style guide — these are all entries.
Some entries are always included (like your world's background story). Others only appear when relevant — triggered by keywords in the conversation. If the player mentions "the tavern," your tavern lore entry gets pulled in automatically.
2. Variables — What the AI Tracks
Variables are the game state — health, gold, location, relationship scores, inventory. The AI reads the current values every turn and updates them by writing simple directives in its response:
The bandit's blade catches your arm.
[health: -15]
[location: set "dark forest"]The player sees the narrative. The engine quietly extracts those bracket directives and updates the game state. As long as your world has variables, the engine automatically teaches the AI the directive format — you don't need to write any format instructions yourself.
You teach the AI when and how to update each variable by writing AI instructions — plain English guidance like "decrease health by 10-30 on physical damage, never more than 30 in one turn." These are not the same as the automation triggers below.
3. Rules & Behaviors — What Happens Between Turns
Rules handle things the AI would forget or get inconsistent about. They're event-driven triggers that fire automatically, no AI involvement:
- When health drops below 10 → show a "You're dying!" warning
- When affinity crosses 75 → inject a romance directive into the AI's instructions
- Every 5 turns → play an ambient thunder sound effect
The editor calls these Behaviors, but they work the same way — every rule has a WHEN trigger, an optional IF condition, and a THEN action.
Rules are optional. Many great worlds use zero rules — the AI handles everything through well-written entries and AI instructions. But for game-like mechanics with precise thresholds, rules are what make things feel tight and consistent.
→ Learn more about rules & behaviors
4. Visuals & Audio — The Presentation Layer (Optional)
By default, players see a clean chat interface. That's enough for most worlds.
But if you want more, you can add custom UI and audio to shape how your world looks and sounds. Custom UI lets you build anything from styled message bubbles to full game interfaces with health bars, maps, and inventories. Audio adds background music, sound effects, and ambient layers that the AI triggers naturally in its narrative.
You don't need to know code. Studio AI generates custom interfaces from a description. Just describe what you want, and it builds it. Audio works the same way — the AI writes audio directives alongside its story, and the engine plays the right sounds.
Both are purely presentational. They read game state but never change it. All state changes still flow through the AI's directives.
→ Learn more about visuals and audio
What the AI Actually Sees
Here's the exact order of what gets assembled into the AI's prompt each turn. The AI pays the most attention to content at the beginning and end — content in the middle gets less focus. Understanding this helps you place content where it has the most impact:
| Order | What | Where You Configure It |
|---|---|---|
| 1 | Your always-on entries (character, world, narrator instructions) | Entries → System Presets section |
| 2 | The player's active persona (name, appearance, backstory) | Player's settings, not yours |
| 3 | Variable AI instructions + current values | Variables tab |
| 4 | Example dialogue | Entries with "example" role |
| 5 | Conversation history | Automatic |
| 6 | Keyword-triggered entries (injected near relevant messages) | Entries → Keyword-Triggered section |
| 7 | Post-instructions (final emphasis, style enforcement) | Entries → Post Instructions section |
Everything above and below the conversation history stays solid across turns. The conversation history itself will grow over time and is automatically summarized by the memory system as it approaches the context limit — so your framework never gets pushed out.
Two Ways to Build
Use Studio AI (Recommended)
Open the Studio editor, describe what you want, and the built-in AI assistant creates entries, variables, and automation for you. It knows the platform inside out — valid syntax, proven patterns, reference integrity.
"Create a survival horror world with health, sanity, and hunger. The player is trapped in an abandoned hospital. Sanity drops when they see disturbing things. At zero sanity, the AI should describe hallucinations."
Studio AI will generate the entries, variables with AI instructions, and the rules that trigger at zero sanity — all correctly wired together.
Use Your Own AI + the World Spec
If you prefer working in Claude Code, Cursor, or ChatGPT, download the World Spec — a complete technical reference designed to be fed to AI tools. Your AI reads the spec, you describe what you want, and it generates a valid world schema you can import.
Ready to start?
Open the editor and create a new world, or keep reading to learn about each building block in detail.