FAQ
Answers to the most common questions you'll run into while creating.
Getting started
Q: Do I need to know how to code?
No. Most creators use the visual editor and Studio AI to build everything. Custom UI is the only feature that involves code, and Studio AI can generate that for you too.
Q: What's the minimum I need to create a world?
Three steps: 1) click Create to make a new world; 2) in Lorebook, create a character entry with the character's profile and turn on Always Send; 3) in First Message, write an opening line. Click Save and you're ready to chat. Variables, rules, and custom UI are all optional.
Q: How long does it take to build a world?
A simple character with a few variables takes 10-15 minutes with Studio AI. A complex world with custom UI, audio, and detailed mechanics can take a few hours to a few days.
Q: Which AI models does Yumina support?
Yumina supports multiple AI providers including Anthropic (Claude), OpenAI (GPT), Google (Gemini), and OpenRouter (which gives access to hundreds of models). You can use Yumina's official API or bring your own API key (BYOK) in Settings → API Keys.
Q: Where is my world data stored?
Your world data is saved on Yumina's server. You can export a world JSON file from the Overview section of the editor as a local backup anytime.
Entries & Lorebook
Q: I have too many entries. How do I organize them?
Use folders. The editor supports creating folders to group entries by logic — by character, by scene, by function. Folders are purely an organizational tool and don't affect runtime behavior. Also make good use of the tags field for filtering and searching. See the "Folder organization" section in Entries & Lorebook.
Q: Keyword triggering isn't working. How do I debug?
Check these common causes: 1) verify the entry's enabled is true; 2) check that lorebookScanDepth is large enough — the default only scans the last 2 messages, so keywords in earlier messages won't be found; 3) if you're using secondary keywords (secondaryKeywords), make sure the logic is set correctly; 4) if matchWholeWords is on, note that Chinese text generally doesn't need whole-word matching. See the "Keyword matching" section in Entries & Lorebook.
Q: What's the difference between alwaysSend entries and keyword-triggered ones?
alwaysSend: true entries are included in every prompt no matter what the player says — good for core character profiles and foundational world rules that need to be in effect at all times. Keyword-triggered entries only activate when matching words appear in recent messages — good for specific scenes, locations, NPCs, and other on-demand content. The fundamental difference is "always-on" vs. "on-demand." Using both strategically can save a huge amount of token budget. See Entries & Lorebook.
Q: How do I write effective example dialogue?
Use <START> to separate different dialogue segments, and {{user}}: and {{char}}: to mark speakers. Each example should demonstrate the character's unique speech style, tone, and reactions — not just information exchange. Two or three high-quality examples are worth far more than ten mediocre ones. Set the entry's role to example and section to examples. See the "Example dialogue format" section in Entries & Lorebook.
Variables & Directives
Q: The AI isn't writing directives in the right format. What do I do?
The engine already automatically tells the AI the directive format, so the problem usually isn't "the AI doesn't know the format" — it's "the AI isn't sure when to use it." A few fixes: 1) make the trigger conditions in behaviorRules more specific — "subtract when the player takes damage; deduct 10–30 per hit" is better than "subtract when hurt"; 2) add a reminder entry in the post-history section telling the AI not to forget to output directives; 3) lower temperature (e.g., 0.5–0.7) to make the AI follow rules more reliably; 4) different models vary significantly in directive compliance — switching models is also worth trying. See AI Directives & Macros and AI Model & Settings.
Q: A variable suddenly has a weird value. How do I debug?
First look at what directives the AI wrote in its raw reply — sometimes the AI writes operations you didn't anticipate. Then check if any rules are quietly modifying this variable in the background (via modify-variable actions). For number variables, confirm you've set reasonable min and max values — the engine auto-clamps out-of-range values. If you still can't find it, check every rule and entry in the editor that references this variable.
Q: How do I use JSON-type variables?
JSON variables can store complex data structures — objects, arrays, nested structures. The most common uses are inventory (JSON array) and character relationship networks (JSON object). Operations include merge (merge object), push (append to array), delete (remove a key or element), and dot-notation for deep nested paths like [relationships.aria.trust: +10]. See the "Nested JSON paths" section in Variables.
Q: How many variables can I have? Is there a limit?
No hard limit at the engine level. But every variable's current value is included in the prompt sent to the AI, so too many variables eat up token budget and shorten the conversation history the AI can "see." In practice, most worlds work fine with 5–20 variables. If you need to store a lot of data, consider packing related data into one JSON variable — more efficient than a pile of individual variables.
Rules engine
Q: A behavior isn't triggering. How do I debug?
Check these in order: 1) is the behavior enabled — was it disabled by another behavior? 2) is the WHEN trigger type correct — e.g., if you chose "variable crosses threshold" but the variable never crossed that threshold; 3) do all the ONLY IF conditions pass (check whether conditionLogic is "all" or "any"); 4) is it in cooldown (cooldownTurns); 5) has it reached max fire count (maxFireCount). See the "Evaluation flow" section in Rules Engine.
Q: When multiple behaviors trigger at once, what order do they execute in?
Sorted by priority from highest to lowest. Behaviors with higher numbers are evaluated and executed first. For example, a "death check" behavior at priority 100 runs before a "low health warning" at priority 50. If two behaviors have the same priority, they execute in their definition order. Give important behaviors higher priority values. See the "Priority" section in Rules Engine.
Q: Can behaviors control each other?
Yes — this is one of the most powerful features of the rules engine. The "enable/disable behavior" action can turn other behaviors on or off. Typical pattern: Behavior A listens for a "enter dungeon" keyword and, when triggered, enables Behavior B (a monster encounter rule that starts disabled). When the player leaves the dungeon, Behavior A disables B again. You can build "dormant until activated" behavior chains. See the "Rule cross-control" section in Rules Engine.
Q: How do cooldownTurns and maxFireCount work together?
cooldownTurns controls the interval — after a behavior fires, it waits this many turns before it can fire again. Good for "shouldn't trigger too often" scenarios, like reminding about hunger no more than once every 5 turns. maxFireCount controls the total — a behavior can fire at most this many times ever, then never again. Good for one-time events like tutorial hints. Both can be used simultaneously: a "hidden plot hint" behavior set to cooldownTurns: 10 + maxFireCount: 3 means it hints at most 3 times, with at least 10 turns between hints.
Components & Rendering
Q: I can't code TSX. Can I still build custom UI?
You can try. A few starting points: 1) use Enter Studio in the editor, and have the AI Assistant generate code for you; 2) describe your desired effect to an external AI (like Claude) and have it generate the TSX code, then paste it into the editor; 3) copy-paste from the template examples in the docs and adjust colors and text. The editor compiles in real time and shows errors at the bottom (Compile Status), so you can adjust as you go. See Custom UI Guide.
Q: What's the Root Component? Do I need one?
The Root Component is the entry point for your world's UI — a file called index.tsx under the Custom UI section in the editor. It's optional: if you don't define one, the engine uses the default (return <Chat />), which gives you the standard chat experience. You define a Root Component when you want to customize anything visual — custom message bubbles (pass renderBubble to <Chat />), side panels (compose <Chat /> with your own divs), or a fully custom layout (use <MessageList /> and <MessageInput /> directly). See Custom UI Guide.
Q: Where do built-in components (stat-bar, inventory, etc.) display?
Built-in components (stat-bar, text-display, image-panel, inventory-grid, etc.) display in a header bar above the chat window. Component order is controlled by the order field — lower numbers appear first. If you need something more flexible — a sidebar, full-screen layout, or a different header entirely — build it in the Root Component instead, where you have full control via TSX. See Custom UI Guide.
Q: My old world has a "Message Renderer." Do I need to change it?
No — legacy worlds keep working. On import, the engine auto-migrates the old messageRenderer field into your Root Component and the editor shows a Legacy badge. The old customUI[] array with surface: "message" | "app" components also still works. When you're ready to modernize, move the renderer code into index.tsx under Custom UI and pass it as <Chat renderBubble={...} />. See Custom UI Guide.
Publishing & sharing
Q: Can I still make changes after publishing?
Yes. After publishing, you can go back to the editor and modify world content at any time — saving takes effect immediately and new players see the latest version. To temporarily take it down, change status to unpublished and active players will see a read-only notice. Note: if you modify variable definitions (like deleting a variable), the engine automatically handles backward compatibility for existing players' saves — new variables get filled with default values, deleted ones are filtered out. Nothing breaks for existing players. See Publishing, Exporting & Bundles.
Q: How do I get more players to discover my world?
Key points: 1) upload an attractive thumbnail — worlds without covers almost never get clicked in Hub; 2) write a compelling description explaining what the world is and what makes it fun; 3) add 3–5 relevant tags — think about what players would search for; 4) write a great opening message (greeting) — first impressions determine whether players keep playing; 5) play through it yourself before publishing to make sure the experience is smooth. See the "Pre-publish checklist" in Publishing, Exporting & Bundles.
Q: What's the difference between a Bundle and a full world export?
A full world export is the complete WorldDefinition JSON — every entry, variable, rule, component, and setting, nothing left out. Good for backups or sharing an entire world with someone. A Bundle is a "component pack" — you cherry-pick a subset of content (like a combat rules system + related variables + components) and package it. Others can install this package into their own worlds. Simply: a full export is "the whole car"; a Bundle is "the engine assembly." See the "Bundle system" section in Publishing, Exporting & Bundles.