BandTwine

Appearance

data.json 简介 ​

欢迎来到互动故事开发的世界！common/data.json 是您构建引人入胜、动态变化的叙事体验的核心。对于初学者而言，理解 data.json 的作用和结构是迈向成功的第一步。本指南将从基础概念入手，逐步深入，帮助您快速掌握 data.json 的编写技巧。

1.1 data.json 是什么？ ​

在我们的互动故事框架中，common/data.json 文件扮演着“故事大脑”的角色。它是一个纯粹的 JSON (JavaScript Object Notation) 文件，其中包含了您故事的所有核心数据和逻辑配置，例如：

  • 故事节点 (Nodes)：构成故事的各个场景、段落或事件。
  • 变量 (Variables)：存储游戏状态、玩家选择、角色属性等动态数据。
  • 链接 (Links)：定义玩家在不同节点之间跳转的选项和条件。
  • 动作 (Actions)：在特定事件发生时（如进入新节点、点击选项）触发的逻辑，例如改变变量、显示提示等。
  • 条件 (Conditions)：控制故事流程、选项可用性或文本显示的逻辑判断。
  • 随机事件 (Randoms)：为故事增加随机性和重玩价值的机制。

简而言之，data.json 是一个结构化的数据文件，它告诉游戏引擎“故事是什么”、“故事如何发展”以及“玩家如何与故事互动”。通过修改这个文件，您可以完全控制故事的走向、角色的命运以及玩家的体验。

1.2 为什么使用 data.json？ ​

将故事数据和逻辑配置集中在一个独立的 data.json 文件中，带来了诸多优势：

  • 清晰的分离：将故事内容与游戏引擎的实现逻辑分离，使得故事创作者可以专注于叙事本身，而无需深入了解复杂的编程细节。
  • 易于维护和扩展：当您需要修改故事内容、添加新章节或调整游戏平衡性时，只需编辑 data.json 文件，而无需触碰核心代码。
  • 便于协作：故事作者、设计师和开发者可以并行工作。
  • 数据驱动：游戏行为完全由数据驱动，这意味着您可以轻松地创建多个不同的故事，只需替换 data.json 文件即可。
  • 版本控制友好：data.json 是一个纯文本文件，非常适合使用 Git 等版本控制工具进行管理。

提示: 我们计划在下一代引擎支持将 data.json 拆分成多个 json 文件，这有利于大型项目的维护和协作，并且提升性能，届时我们会提供一个 .py 脚本，开发者可快速迁移。我们仍会保留支持单 data.json 文件的支持

1.3 data.json 的基本结构 ​

data.json 文件是一个标准的 JSON 对象，它以 { 开始，以 } 结束，内部包含 metadata、nodes 和 variables 等顶级属性。以下是一个最基本的 data.json 结构示例：

json
{
  "metadata": {
    "title": "我的第一个互动故事",
    "description": "这是一个示例互动故事",
    "author": "你的名字",
    "version": "1.0.0",
    "versionCode": 1,
    "releaseDate": "2025-09-01",
    "license": "MIT",
    "copyright": "Copyright © 2025 你的名字.",
    "indexNode": "start"
  },
  "nodes": {
    "start": {
      "title": "故事的开端",
      "text": "你醒来发现自己身处一片陌生的森林中。{0}",
      "links": [
        { "text": "继续前进", "target": "forest_path" }
      ],
      "actions": [
        { "type": "set", "target": "var.player.location", "value": "forest" }
      ]
    },
    "forest_path": {
      "title": "森林深处",
      "text": "你走在森林的小径上。"
    }
  },
  "variables": {
    "player": {
      "name": "",
      "health": 100,
      "location": ""
    },
    "world": {
      "time": 480,
      "day": 1
    }
  }
}

重要区别: 与 JavaScript 对象不同，在 JSON 中，所有的键名（key）都必须用双引号 " 包裹，并且不能有注释。

1.4 文件结构和命名约定 ​

为了保持项目的整洁和可维护性，我们建议遵循以下文件结构和命名约定：

  • common/data.json：您的主故事数据文件。
  • 节点ID：建议使用小写字母和下划线组合的描述性名称，例如 start、chapter_1_intro。确保每个节点ID都是唯一的。
  • 变量名：在 JSON 的键名中，同样建议使用驼峰命名法或下划线命名法，并尽量保持描述性，例如 playerHealth 或 player_health。

遵循这些约定将有助于您和您的团队更好地理解和管理故事数据。

注意 不要使用 拼音 作为变量名，这 非常抽象 并且 不利于项目后续维护和协作。