BandTwine

Appearance

API 参考 (API Reference) ​

欢迎来到 BandTwine 的 API 参考。本章节是为希望深入了解引擎工作原理、进行高级定制或二次开发的开发者准备的。

这里详细列出了构成一个 BandTwine 故事（common/data.json）的所有可配置项，并解释了它们在引擎内部的作用和行为。

故事结构 (Story Structure) ​

节点内部结构 (Node Internals) ​

核心概念 (Core Concepts) ​

metadata (元数据) ​

metadata 对象包含了故事的全局信息和配置。

键名类型描述
titleString故事的标题。
authorString故事的作者。
versionString故事的版本号。
indexNodeString(必需) 故事开始的第一个节点的ID。引擎将从这个节点开始加载。

示例:

json
"metadata": {
  "title": "迷雾森林的秘密",
  "author": "Manus AI",
  "version": "1.0.0",
  "indexNode": "start"
}

variables (变量) ​

variables 对象用于初始化游戏世界的所有状态和数据。

顶级键名描述
player(推荐) 用于存放玩家相关的变量，如属性、物品等。
world(推荐) 用于存放世界相关的变量，如时间、天气等。
show(特殊) 用于在游戏侧边栏显示状态。
temp(特殊) 用于存放临时变量，不会被存档。
(自定义)您可以定义任何其他顶级对象来组织您的变量。

variables.world (世界变量) ​

引擎会自动处理 world 对象下的特定变量：

键名类型描述
timeNumber(核心) 游戏的核心时间，单位为分钟 (0-1439)。
dayNumber(核心) 游戏的天数。
formattedTimeString(需预定义) 引擎会自动更新此变量为 "HH:MM" 格式的时间。
timePeriodString(需预定义) 引擎会自动更新此变量为 "早晨"、"夜晚" 等时间段。

variables.show (侧边栏变量) ​

show 对象下的每个子对象都会被渲染到游戏侧边栏，用于实时显示状态。

键名类型描述
descString在侧边栏显示的描述文本（标签）。
valueAny该状态的初始值。

示例:

json
"variables": {
  "world": {
    "time": 480,
    "day": 1,
    "formattedTime": "08:00",
    "timePeriod": "早晨"
  },
  "show": {
    "player_health": { "desc": "生命值", "value": 100 }
  }
}

nodes (节点) ​

nodes 对象是所有故事场景的集合。它的每个键都是一个唯一的节点ID，值是描述该节点内容的节点对象。

键名类型描述
titleString(可选) 节点的标题，会显示在游戏界面顶部。
textString(必需) 节点的主要文本内容，支持文本标记。
linksArray(可选) 定义从该节点出发的链接（选项）。
actionsArray(可选) 定义进入该节点时自动执行的动作。
condsObject(可选) 定义该节点可用的条件文本组。
randomsObject(可选) 定义该节点可用的随机事件组。
imgsObject(可选) 定义该节点可用的图片资源。

links 是一个对象数组，定义了玩家可以做出的选择。所有链接都必须在节点的 text 中通过 {数字} 标记引用才能显示。

键名类型描述
textString(必需) 链接显示的文本。
targetString(必须) 点击后跳转的目标节点ID。
conditionString(可选) 一个条件表达式。若不满足，链接将变灰且不可点击。
actionsArray(可选) 点击链接后、跳转前执行的动作数组。
variantsArray(可选) “变体链接”数组，可根据不同条件显示不同文本或跳转到不同目标。
randomArray(可选) “随机链接”数组，点击后会从数组中随机选择一个结果执行。

actions (动作) ​

actions 是一个对象数组，是驱动故事状态变化的核心指令。

type 类型描述主要参数
set设置变量的值。target, value
add对数值型变量进行加法。target, value
toggle切换布尔变量的值。target
random执行一个在 randoms 中定义的随机动作组。id
vibrate触发设备振动。mode ("long" / "short")
autosave自动存档到存档位 0。-
addListener添加一个监听器。id, condition, actions, once
removeListener移除一个监听器。id ("all" 为全部)
advanceTime推进游戏时间。minutes
toast显示一个短暂的提示信息。message, duration
jump强制跳转到指定节点。target, condition, beforeActions, afterActions

conds (条件文本) ​

conds 对象用于定义条件文本组，与 {cond.ID} 标记配合使用。

结构:

json
"conds": {
  "组ID": [
    { "condition": "条件1", "text": "文本1" },
    { "condition": "条件2", "text": "文本2" },
    { "text": "默认文本" }
  ]
}

引擎会从上到下检查，并使用第一个满足 condition 的 text。

randoms (随机事件) ​

randoms 对象用于定义随机事件组，与 {random.ID} 标记或 random 动作配合使用。

结构:

json
"randoms": {
  "组ID": [
    { "text": "结果A", "weight": 70, "actions": [...] },
    { "text": "结果B", "weight": 30, "condition": "var.player.hasItem" }
  ]
}

引擎会根据 weight (权重) 和 condition (条件) 进行加权随机选择。

imgs (图片) ​

imgs 对象用于定义图片资源，与 {img.ID} 标记配合使用。

键名类型描述
pathString(必需) 图片的路径。相对路径会自动添加 /common/images/ 前缀。
widthNumber(可选) 图片显示的宽度。

条件表达式 (Condition Strings) ​

条件表达式是一个强大的字符串，用于所有需要逻辑判断的地方 (condition 字段)。

语法示例描述
比较"var.player.gold >= 100"支持 ==, !=, >, <, >=, <=。
逻辑"var.player.hasKey && !var.door.isLocked"支持 && (与), `
表达式"$(var.player.str + var.player.agi > 20)"执行括号内的 JavaScript 表达式。
状态"hourChanged", "dayChanged"引擎内置的特殊状态。

文本标记 (Text Markers) ​

文本标记是在节点的 text 属性中使用的特殊占位符，用于动态插入内容。

标记示例描述
变量{var.player.name}显示指定变量的当前值。
链接{0}, {1}...(核心规则) 引用并显示 links 数组中对应索引的链接。
条件{cond.desc_id}从 conds 中选择一段符合条件的文本显示。
随机{random.event_id}从 randoms 中随机选择一段文本显示。
图片{img.image_id}从 imgs 中选择一张图片嵌入。
换行\n用于在文本中手动换行。