深入解析inkle/ink项目的JSON运行时格式

深入解析inkle/ink项目的JSON运行时格式

ink inkle's open source scripting language for writing interactive narrative. 项目地址: https://gitcode.com/gh_mirrors/ink/ink

前言

inkle/ink是一个强大的交互式叙事引擎，它允许创作者编写复杂的非线性故事。了解其JSON运行时格式对于开发者深入理解ink引擎的工作原理至关重要。本文将全面解析ink的JSON运行时格式，帮助开发者更好地理解和扩展ink的功能。

整体结构

ink编译后的JSON文件采用了一种低层次的运行时格式，由简单的基础构建块组成。顶层结构包含两个关键属性：

{
    "inkVersion": 10,
    "root": <根容器>
}

其中：

• inkVersion表示格式版本号
• root是整个故事的最外层容器

容器(Container)详解

容器是ink JSON格式中最基础也是最重要的数据结构，它贯穿整个引擎。在JSON中，容器表现为数组形式，但具有一些特殊属性：

1. 基本结构：容器本质上是一个数组，但最后一个元素具有特殊含义
2. 特殊属性：最后一个元素可以是null或包含额外属性的对象
3. 命名元素：容器可以包含命名的子元素，这些子元素不直接包含在数组中

容器属性对象

最后一个元素如果是对象，可以包含：

• #n：容器名称
• #f：标志位(bit flags)
• 其他命名子容器

标志位含义

#f可以包含以下标志位的组合：

• 0x1：记录访问次数
• 0x2：记录最后访问的回合数
• 0x4：仅记录开始访问(用于区分不同行为)

容器示例

1. 简单容器：

[5, 6, null]

2. 命名容器：

["^Hello world", {"#n": "hello"}]

3. 带嵌套和标志位的容器：

["^test", {"subContainer": [5, 6, null], "#f": 3}]

值(Value)类型

ink支持多种值类型，用于故事内容和逻辑计算：

字符串值

• 表示方式：以^开头的字符串
• 示例："^Hello world"
• 特例：换行符直接表示为"\n"

数值类型

• 整数和浮点数：使用标准JSON表示
• 示例：5, 5.6

特殊值类型

1. 转向目标(Divert target)：

   • 表示变量转向目标
   • 格式：{"^->": "path.to.target"}

2. 变量指针(Variable pointer)：

   • 表示变量引用
   • 格式：{"^var": "varname", "ci": 0}
   • ci(上下文索引)含义：
     • -1：未确定
     • 0：全局变量
     • 1+：调用栈中的局部变量

3. Void：

   • 表示无返回值
   • 格式："void"

控制命令(Control Commands)

控制命令是指导引擎执行特定操作的指令：

| 命令 | 描述 | |------|------| | "ev" | 开始逻辑评估模式 | | "/ev" | 结束逻辑评估模式 | | "out" | 将评估栈顶值输出到主文本流 | | "pop" | 从评估栈弹出值(不输出) | | "->->"/"~ret" | 从调用栈返回(分别用于隧道和函数) | | "du" | 复制评估栈顶值 | | "str"/"/str" | 开始/结束字符串评估模式 | | "nop" | 空操作 | | "choiceCnt" | 推送当前选择数量到评估栈 | | "turn"/"turns" | 推送当前回合数/上次访问回合数 | | "visit" | 推送当前容器访问次数 | | "seq" | 生成序列随机索引 | | "thread" | 创建新线程 | | "done" | 尝试关闭活动线程 | | "end" | 立即结束故事流 |

原生函数(Native Functions)

ink支持多种数学和逻辑运算，这些函数从评估栈获取参数并将结果推回栈中：

• 算术运算："+", "-", "/", "*", "%", "_"(取负)
• 比较运算："==", ">", "<", ">=", "<=", "!="
• 逻辑运算："!", "&&", "||"
• 其他："MIN", "MAX"

布尔值采用C风格表示：非零为真，零为假。

转向(Divert)

转向有多种形式，用于控制故事流程：

1. 标准转向：

   {"->": "path.to.target"}
   

2. 变量转向：

   {"->": "variableTarget", "var": true}
   

3. 函数调用：

   {"f()": "path.to.func"}
   

4. 隧道转向：

   {"->t->": "path.tunnel"}
   

5. 外部函数调用：

   {"x()": "externalFuncName", "exArgs": 5}
   

条件转向可通过"c": true属性表示。

变量操作

变量赋值

• 全局变量赋值：

  {"VAR=": "money", "re": true}
  

• 临时变量赋值：

  {"temp=": "x"}
  

变量引用

{"VAR?": "danger"}

读取计数

{"CNT?": "the_hall.light_switch"}

选择点(ChoicePoint)

选择点用于生成选择实例，其JSON结构为：

{
    "*": "path.when.chosen",
    "flag": 18
}

标志位(flag)含义：

• 0x1：有条件
• 0x2：有起始内容
• 0x4：有选择专用内容
• 0x8：是隐形默认选择
• 0x10：仅一次(默认)

路径(Paths)表示

路径用于引用层次结构中的内容，使用点分隔语法：

• 绝对路径：path.to.target
• 相对路径：以.开头，如.^.1
• 路径元素类型：
  • 名称：引用命名内容
  • 索引：引用数组位置
  • 父级：使用^表示

结语

理解ink的JSON运行时格式对于深入使用和扩展ink引擎至关重要。本文详细解析了ink JSON格式的各个组成部分，包括容器结构、值类型、控制命令、转向机制等核心概念。掌握这些知识将帮助开发者更好地调试ink故事、开发自定义工具，甚至扩展ink引擎的功能。

ink inkle's open source scripting language for writing interactive narrative. 项目地址: https://gitcode.com/gh_mirrors/ink/ink