常见问题
创作过程中最常遇到的问题解答。
入门
Q：我需要会写代码吗？
不需要。大多数创作者使用可视化编辑器和 Studio AI 来构建一切。自定义 UI 是唯一涉及代码的功能，而 Studio AI 也可以帮你生成。
Q：创建一个世界最少需要什么？
三步：1) 点击创建新建世界；2) 在知识库中，创建一个 character 条目写入角色档案并开启 Always Send；3) 在第一条消息中写一句开场白。点击保存就可以开始聊天了。变量、规则和自定义 UI 都是可选的。
Q：构建一个世界需要多长时间？
一个带几个变量的简单角色用 Studio AI 大约 10-15 分钟。一个有自定义 UI、音频和详细机制的复杂世界可能需要几小时到几天。
Q：Yumina 支持哪些 AI 模型？
Yumina 支持多家 AI 提供商，包括 Anthropic（Claude）、OpenAI（GPT）、Google（Gemini）和 OpenRouter（可访问数百种模型）。你可以使用 Yumina 的官方 API 或在设置 → API Keys 中自带 API 密钥（BYOK）。
Q：我的世界数据存在哪里？
你的世界数据保存在 Yumina 的服务器上。你可以随时从编辑器的概览部分导出世界 JSON 文件作为本地备份。
条目与知识库
Q：条目太多了，怎么整理？
使用文件夹。编辑器支持创建文件夹按逻辑分组——按角色、按场景、按功能。文件夹纯粹是组织工具，不影响运行时行为。同时善用 tags 字段进行过滤和搜索。参见写好条目的技巧中的「文件夹组织」部分。
Q：关键词触发不生效，怎么调试？
检查这些常见原因：1) 确认条目的 enabled 为 true；2) 检查 lorebookScanDepth 是否足够——默认只扫描最近 2 条消息，更早消息中的关键词不会被找到；3) 如果你使用了二级关键词（secondaryKeywords），确认逻辑设置正确；4) 如果 matchWholeWords 开启，注意中文一般不需要全词匹配。参见写好条目的技巧中的关键词匹配部分。
Q：alwaysSend 条目和关键词触发的条目有什么区别？
alwaysSend: true 的条目无论玩家说什么都会包含在每次 prompt 中——适合核心角色档案和基础世界规则等需要始终生效的内容。关键词触发的条目只在最近消息中出现匹配词时才激活——适合特定场景、地点、NPC 和其他按需内容。根本区别是「始终在线」vs.「按需触发」。策略性地组合使用两者可以大幅节省 token 预算。参见写好条目的技巧。
Q：怎么写有效的示例对话？
用 <START> 分隔不同的对话段落，用 {{user}}: 和 {{char}}: 标记说话者。每个示例应该展示角色独特的说话风格、语气和反应——不只是信息交换。两三个高质量的示例远比十个平庸的有价值。将条目的角色设为 example，分区设为 examples。参见写好条目的技巧中的示例对话格式部分。
变量与指令
Q：AI 没有按正确格式写指令，怎么办？
引擎已经自动告诉 AI 指令格式了，所以问题通常不是「AI 不知道格式」而是「AI 不确定什么时候该用」。几个解决方法：1) 让 behaviorRules 中的触发条件更具体——「受到伤害时减少；每次命中扣 10-30」比「受伤时减少」好；2) 在 post-history 分区添加一个提醒条目告诉 AI 别忘了输出指令；3) 降低 temperature（如 0.5-0.7）让 AI 更可靠地遵守规则；4) 不同模型在指令遵从方面差异很大——换模型也值得尝试。参见 AI 指令与宏。
Q：变量突然出现了奇怪的值，怎么调试？
先看 AI 在原始回复中写了什么指令——有时 AI 会写出你没预料到的操作。然后检查是否有规则在后台悄悄修改这个变量（通过 modify-variable 动作）。对于数值变量，确认你设了合理的 min 和 max 值——引擎自动把超出范围的值限制回来。如果还找不到，在编辑器中检查每个引用了这个变量的规则和条目。
Q：怎么使用 JSON 类型的变量？
JSON 变量可以存储复杂数据结构——对象、数组、嵌套结构。最常见的用途是道具栏（JSON 数组）和角色关系网络（JSON 对象）。操作包括 merge（合并对象）、push（追加到数组）、delete（删除键或元素），以及用点表示法访问深层嵌套路径，如 [relationships.aria.trust: +10]。参见设计游戏状态。
Q：我可以有多少个变量？有限制吗？
引擎层面没有硬性限制。但每个变量的当前值都会包含在发送给 AI 的 prompt 中，所以变量太多会消耗 token 预算并缩短 AI 能「看到」的对话历史。实际使用中，大多数世界 5-20 个变量就能运转良好。如果你需要存储大量数据，考虑把相关数据打包进一个 JSON 变量——比一堆独立变量更高效。
规则引擎
Q：行为没有触发，怎么调试？
按顺序检查：1) 行为是否已启用——是否被其他行为禁用了？2) WHEN 触发器类型是否正确——比如你选了「变量越过阈值」但变量从未越过该阈值；3) 所有 ONLY IF 条件是否通过（检查 conditionLogic 是 "all" 还是 "any"）；4) 是否在冷却中（cooldownTurns）；5) 是否达到最大触发次数（maxFireCount）。参见行为与自动化中的评估流程部分。
Q：多个行为同时触发时，执行顺序是什么？
按 priority 从高到低排序。数字越大的行为越先被评估和执行。例如，priority 100 的「死亡检查」行为在 priority 50 的「低血量警告」之前运行。如果两个行为 priority 相同，按定义顺序执行。给重要行为设置更高的 priority 值。参见行为与自动化中的优先级部分。
Q：行为可以互相控制吗？
可以——这是规则引擎最强大的特性之一。「启用/禁用行为」动作可以开关其他行为。典型模式：行为 A 监听「进入地牢」关键词，触发时启用行为 B（一个初始禁用的怪物遭遇规则）。当玩家离开地牢时，行为 A 关闭 B。你可以构建「休眠直到被激活」的行为链。参见行为与自动化中的规则交叉控制部分。
Q：cooldownTurns 和 maxFireCount 怎么配合使用？
cooldownTurns 控制间隔——行为触发后等待这么多回合才能再次触发。适合「不应该太频繁触发」的场景，比如每 5 回合最多提醒一次饥饿。maxFireCount 控制总次数——行为最多触发这么多次就不再触发了。适合一次性事件如教程提示。两者可以同时使用：一个「隐藏剧情提示」行为设置 cooldownTurns: 10 + maxFireCount: 3 意味着最多提示 3 次，每次之间至少间隔 10 个回合。
组件与渲染
Q：我不会写 TSX，还能做自定义 UI 吗？
可以试试。几个入手方式：1) 在编辑器中使用进入 Studio，让 AI 助手帮你生成代码；2) 向外部 AI（如 Claude）描述你想要的效果让它生成 TSX 代码，然后粘贴到编辑器中；3) 从文档中的模板示例复制粘贴并调整颜色和文字。编辑器实时编译并在底部显示错误（Compile Status），你可以边调边看。参见自定义 UI 指南。
Q：Root Component 是什么？我需要吗？
Root Component 是你世界 UI 的入口点——编辑器自定义 UI部分下的一个 index.tsx 文件。它是可选的：如果你不定义，引擎使用默认的（return <Chat />），给你标准的聊天体验。当你想自定义任何视觉效果时才定义 Root Component——自定义消息气泡（将 renderBubble 传给 <Chat />）、侧边面板（将 <Chat /> 与你的 div 组合）、或完全自定义的布局（直接使用 <MessageList /> 和 <MessageInput />）。参见自定义 UI 指南。
Q：内置组件（stat-bar、inventory 等）显示在哪里？
内置组件（stat-bar、text-display、image-panel、inventory-grid 等）显示在聊天窗口上方的头部栏中。组件顺序由 order 字段控制——数字越小越靠前。如果你需要更灵活的东西——侧边栏、全屏布局或完全不同的头部——在 Root Component 中构建，你可以通过 TSX 完全控制。参见自定义 UI 指南。
Q：我的旧世界有「Message Renderer」，需要改吗？
不需要——旧世界继续工作。导入时引擎自动将旧的 messageRenderer 字段迁移到你的 Root Component 中，编辑器会显示 Legacy 标识。旧的 customUI[] 数组及其 surface: "message" | "app" 组件也仍然有效。当你准备好现代化时，把渲染器代码移到自定义 UI 下的 index.tsx 中，以 <Chat renderBubble={...} /> 的形式传入。参见自定义 UI 指南。
发布与分享
Q：发布后还能修改吗？
可以。发布后你随时可以回到编辑器修改世界内容——保存即时生效，新玩家看到最新版本。要临时下架，将状态改为 unpublished，活跃玩家会看到只读提示。注意：如果你修改了变量定义（比如删除一个变量），引擎会自动处理对现有玩家存档的向后兼容——新变量填入默认值，删除的变量被过滤掉。现有玩家不会受影响。参见发布、导出与 Bundle。
Q：怎么让更多玩家发现我的世界？
要点：1) 上传一个吸引人的封面图——Hub 中没有封面的世界几乎不会被点击；2) 写一段引人入胜的描述，解释世界是什么以及为什么好玩；3) 添加 3-5 个相关标签——想想玩家会搜什么；4) 写好开场消息（问候语）——第一印象决定玩家是否继续玩下去；5) 发布前自己完整玩一遍确保体验流畅。参见发布、导出与 Bundle中的「发布前检查清单」。
Q：Bundle 和完整世界导出有什么区别？
完整世界导出是完整的 WorldDefinition JSON——每个条目、变量、规则、组件和设置一个不漏。适合备份或将整个世界分享给别人。Bundle 是一个「组件包」——你挑选一部分内容（比如一套战斗规则系统 + 相关变量 + 组件）打包。别人可以将这个包安装到自己的世界里。简单来说：完整导出是「整辆车」；Bundle 是「发动机总成」。参见发布、导出与 Bundle中的「Bundle 系统」部分。