最佳实践与FAQ

恭喜您！您已经学习了 BandTwine 的核心概念和主要功能。现在，让我们总结一些最佳实践，并解答一些您在开发过程中可能会遇到的常见问题。

10.1 最佳实践

10.1.1 规划先行

• 设计故事大纲: 在编写 common/data.json 之前，花时间规划您的故事大纲、主要角色和关键事件。
• 绘制流程图: 对于复杂的剧情分支，使用流程图可以帮助您可视化故事路径，避免逻辑混乱。
• 设计变量结构: 提前设计好您的 "variables" 结构。考虑哪些数据需要持久化，哪些是临时数据。
• 规范节点ID: 使用有意义且唯一的节点ID，例如 chapter1_forest_path。

10.1.2 保持清晰

• 逻辑与数据分离: 让 common/data.json 专注于数据配置。复杂的计算或系统逻辑应在游戏引擎（前端）中实现。
• 利用表达式: 对于简单的计算或逻辑判断，充分利用 $(...) 表达式，这能让数据文件保持简洁。
• 保持格式一致: 遵循一致的代码格式和缩进风格，提高代码的可读性。

10.1.3 调试技巧

• 启用调试模式: 在开发过程中，启用游戏的调试模式以获取更多日志输出。
• 利用侧边栏: 合理配置 variables.show，实时监控关键变量的状态，这对于调试复杂逻辑非常有帮助。
• 逐步测试: 在添加新功能或修改现有逻辑时，逐步测试，确保每个部分都按预期工作。

10.1.4 用户体验

• 清晰的文本: 确保所有文本内容清晰、准确，没有歧义。
• 明确的选项: 链接文本应该清晰地描述玩家选择的后果或目标。
• 及时的反馈: 通过 toast 动作，及时向玩家提供操作反馈、事件通知和状态变化。
• 合理的存档: 在关键节点设置 autosave，防止玩家因意外情况丢失进度。

---

10.2 常见问题解答 (FAQ)

Q1: 为什么我的变量没有按预期更新？

A1: 请检查以下几点：

• 路径是否正确？ 确保动作中 "target" 的变量路径（如 "var.player.gold"）与 "variables" 中的实际路径完全匹配。
• 动作类型是否正确？ 您使用的是 "set"、"add" 还是 "toggle"？
• jump 动作是否在前面？ 如果一个 "actions" 数组中的 jump 动作被执行，其后的所有动作都会被忽略。

Q2: 我的链接为什么没有显示在屏幕上？

A2: 请检查最关键的一点：

• 是否在 "text" 中标记？ 这是 BandTwine 的核心规则。您必须在节点的 "text" 属性中使用 {0}, {1}... 这样的标记来引用 "links" 数组中对应索引的链接，否则它们不会被渲染。

Q3: 我的链接显示了，但为什么是灰色的，无法点击？

A3: 这通常是因为链接的 "condition" 条件没有满足。请检查：

• 条件表达式是否正确？
• 相关的变量值是否符合预期？ 您可以在文本中临时加入 {var.xxx} 标记来直接查看变量的当前值，以帮助调试。

Q4: 如何在文本中显示变量的计算结果？

A4: 您可以使用表达式标记 $(...)。例如，要显示玩家金币数量的两倍，可以这样写： "text": "你身上的金币翻倍后是：$(var.player.gold * 2)！"

Q5: 监听器为什么没有触发？

A5: 请检查以下几点：

• 监听器是否已添加？ 确保您通过 addListener 动作成功添加了监听器。
• "condition" 是否满足？ 监听器的条件表达式必须评估为 true 才能触发。
• "once" 属性？ 如果 "once" 为 true（默认值），监听器在触发一次后就会被移除。

Q6: 如何在 common/data.json 中使用图片？

A6: 您可以使用图片标记 {img.图片ID}。首先，在节点的 "imgs" 属性中定义图片，例如：

"my_node": {
  "text": "这里有一张图片：{img.my_image}",
  "imgs": {
    "my_image": {
      "path": "path/to/your/image.jpg",
      "width": 300
    }
  }
}

Q7: 如何处理多语言支持？

A7: BandTwine 本身不直接提供多语言支持。通常的做法是为每种语言创建单独的 common/data.json 文件（例如 data_en.json, data_zh.json），然后在游戏启动时根据用户选择加载对应的文件。

10.3 结语

通过这份指南，我们希望您已经对 BandTwine 的核心功能有了全面的了解。不断尝试、实践和迭代，您将能够创造出令人惊叹的互动叙事体验！

祝您创作愉快！