游戏叙事与剧情 / 系统课时

整理可交付的剧情脚本包

整理可交付的剧情脚本包

剧情写完并不等于可以交付。本节把分散的 Ink 脚本、变量约定、测试记录和校验工具整理成一套明确的交付结构,让程序、美术或后续编剧拿到包后能快速定位入口、理解外部变量,并判断当前版本是否通过验收。

学习目标

  • 按项目约定整理 Ink 脚本、文档、测试记录和工具文件
  • 明确文件命名、外部变量以及剧情入口的交付契约
  • 使用自动校验脚本发现缺文件、重复变量等常见交付问题

先固定交付结构

Ink 本身不会强制团队采用某一种目录,因此真正重要的是项目内保持一致。一个可维护的剧情包至少要让接收方快速找到剧情入口、拆分脚本、变量说明和测试结果。

下面是一种适合中小型剧情项目的约定。main.ink 是项目约定的总入口,而不是 Ink 强制要求的固定文件名;如果游戏工程使用其他入口名,应以双方约定为准。

Ink 剧情脚本交付包结构

脚本拆分时,文件名应表达剧情职责,例如 prologue.ink、chapter_01.ink、ending_bad.ink。避免 new.ink、final2.ink、test-copy.ink 这类只能靠作者记忆理解的名称。临时实验文件也不要混入正式交付目录。

把变量变成接入契约

剧情中的变量不只是编剧内部细节。只要变量会被游戏读取、写入或持久化,它就已经成为剧情脚本与游戏代码之间的接口,交付时必须说明名称、方向、类型含义和使用时机。

例如,可以在 docs/variables.md 中维护如下约定:

text
变量:player_reputation
方向:游戏写入,剧情读取
含义:玩家当前声望等级
取值:0~100
默认值:0
使用位置:主线分支、结局判定

变量:ending_id
方向:剧情写入,游戏读取
含义:最终结局编号
可能值:normal、good、bad
写入时机:进入最终结局节点后

这类文档的重点不是重复脚本,而是回答接入方最关心的问题:谁负责写、谁负责读、什么时候有效、允许什么值。如果某个变量已经废弃,应从正式契约中删除或明确标记废弃状态,避免程序继续依赖旧字段。

保留可以复查的测试结果

测试结果不要只写“已测通过”。一个可追溯的 qa/test-results.md 至少应记录测试版本、覆盖范围、关键分支和遗留问题。例如可以记录主线是否能从入口走到结束、关键 choice 是否全部可达、外部变量缺省时是否有合理行为,以及主要结局是否实际触发。

测试记录还应区分“已通过”和“暂未覆盖”。未覆盖并不等同于失败,但必须让接收方知道风险仍然存在。如果修改了条件判断、变量名或跳转目标,原来的测试结论也应重新确认,不能继续沿用旧版本的通过记录。

用脚本做交付前校验

仅靠人工检查很容易漏掉缺失文档或重复变量。下面的 Python 工具可以放在 tools/validate_delivery.py,用于检查约定文件是否存在,并扫描所有 .ink 文件中的顶层 VAR 声明是否重名。它校验的是本课约定的交付结构,不代表 Ink 官方规定。

python
from pathlib import Path
import re
import sys

VAR_PATTERN = re.compile(r"^\s*VAR\s+([A-Za-z_][A-Za-z0-9_]*)\s*=", re.MULTILINE)
REQUIRED_PATHS = [
    "story/main.ink",
    "docs/variables.md",
    "qa/test-results.md",
]


def main() -> int:
    root = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
    errors: list[str] = []

    for relative_path in REQUIRED_PATHS:
        if not (root / relative_path).is_file():
            errors.append(f"missing required file: {relative_path}")

    declarations: dict[str, list[str]] = {}
    for ink_file in sorted((root / "story").rglob("*.ink")):
        text = ink_file.read_text(encoding="utf-8")
        for name in VAR_PATTERN.findall(text):
            relative = ink_file.relative_to(root).as_posix()
            declarations.setdefault(name, []).append(relative)

    for name, files in declarations.items():
        if len(files) > 1:
            errors.append(f"duplicate VAR {name}: {', '.join(files)}")

    if errors:
        for error in errors:
            print(f"[ERROR] {error}")
        return 1

    print("[OK] delivery package is ready")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

在剧情包根目录执行:

bash
python3 tools/validate_delivery.py .

当约定文件存在且没有重复的 VAR 声明时,预期输出为:

text
[OK] delivery package is ready

如果缺少文件或发现重复变量,脚本会输出对应的 [ERROR] 并以非零状态结束。它不能代替 Ink 编译、剧情遍历和游戏内联调,但很适合作为提交代码、打包版本或交给程序之前的最后一道结构检查。

交付时只留下接收方需要的东西

正式交付前,应确认剧情入口与游戏工程中的加载约定一致,脚本引用的文件全部包含在包内,公开变量与 variables.md 一致,测试记录对应当前版本,并清理个人备份、废弃草稿、编辑器缓存和临时导出文件。

交付包的目标不是保存作者工作的全部过程,而是提供一个入口明确、接口明确、状态可验证、后续能够继续扩展的版本。做到这一点后,新成员即使没有参与前期创作,也能从目录、变量契约和测试结果快速接手剧情脚本。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

整理可交付的剧情脚本包

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通