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

让脚本检查进入提交流程

让脚本检查进入提交流程

多人维护 Ink 脚本时,最浪费时间的不是复杂运行时故障,而是语法错误、临时文本和关键节点缺失进入评审后才被发现。本节把这些低成本检查收敛成一条可重复执行的门禁:本地提交前尽早失败,远端流水线再执行同一套规则。

学习目标

  • 把 Ink 编译、内容规则和关键节点检查串成一个可重复执行的命令
  • 用 Git 提交钩子在提交前阻止明显有问题的剧情脚本
  • 明确本地钩子与远端 CI 的职责边界,避免检查只在某台机器生效

把检查变成一条门禁链

提交阶段适合拦截“确定有问题且检查成本低”的错误。推荐顺序是先编译,再做团队内容规则检查,最后验证约定的关键剧情入口是否仍然存在;任一环节失败就停止提交。

Ink 脚本提交门禁流程

这里的“关键路径检查”不是完整剧情自动游玩,而是提交阶段的轻量契约:例如主入口、存档恢复点、主要结局 knot 不应被误删或改名。真正需要选择序列、变量状态和结局内容断言时,应放到独立的运行时测试中。

建立统一检查脚本

下面假设主入口是 story/main.ink,团队要求保留 intro、checkpoint、ending_good 三个 knot,并禁止把 TODO_REVIEW、FIXME_STORY、TEMP_TEXT 这类临时标记提交进仓库。把规则集中到 tools/check_ink.py,团队成员和 CI 都执行同一个文件。

python
from pathlib import Path
import re
import subprocess
import sys

ROOT = Path(__file__).resolve().parents[1]
STORY_DIR = ROOT / "story"
ENTRY = STORY_DIR / "main.ink"
OUTPUT = ROOT / "build" / "story.json"

OUTPUT.parent.mkdir(parents=True, exist_ok=True)

try:
    result = subprocess.run(
        ["inklecate", "-o", str(OUTPUT), str(ENTRY)],
        cwd=ROOT,
        text=True,
        capture_output=True,
        check=False,
    )
except FileNotFoundError:
    print("inklecate not found")
    sys.exit(1)

if result.returncode != 0:
    print(result.stdout, end="")
    print(result.stderr, end="", file=sys.stderr)
    sys.exit(result.returncode)

print("[1/3] compile: OK")

ink_files = list(STORY_DIR.rglob("*.ink"))
blocked = re.compile(r"\b(?:TODO_REVIEW|FIXME_STORY|TEMP_TEXT)\b")

bad_files = []
for path in ink_files:
    if blocked.search(path.read_text(encoding="utf-8")):
        bad_files.append(path.relative_to(ROOT))

if bad_files:
    print("blocked markers found in:")
    for path in bad_files:
        print(f"  {path}")
    sys.exit(1)

print("[2/3] content: OK")

knot_pattern = re.compile(
    r"^\s*===\s*([A-Za-z_][A-Za-z0-9_]*)\s*===\s*$",
    re.MULTILINE,
)
declared = set()

for path in ink_files:
    declared.update(
        knot_pattern.findall(path.read_text(encoding="utf-8"))
    )

required = {"intro", "checkpoint", "ending_good"}
missing = sorted(required - declared)

if missing:
    print("missing required knots:")
    for knot in missing:
        print(f"  {knot}")
    sys.exit(1)

print("[3/3] key knots: OK")
print("INK_CHECK_OK")

预期输出

text
[1/3] compile: OK
[2/3] content: OK
[3/3] key knots: OK
INK_CHECK_OK

三个关键 knot 和禁止标记都属于项目约定,应由团队按实际剧情调整。脚本先调用编译器,因此普通语法错误、无效引用等编译问题会比内容规则更早失败,不会被后续检查掩盖。

接入 Git 提交前检查

不要把脚本逻辑直接写死在某个成员的 .git/hooks 目录。下面把钩子保存到仓库的 .githooks/pre-commit,再让当前克隆使用这个版本化目录;钩子本身只调用统一检查脚本。

bash
mkdir -p .githooks

cat > .githooks/pre-commit <<'EOF'
#!/usr/bin/env bash
set -euo pipefail

python3 tools/check_ink.py
EOF

chmod +x .githooks/pre-commit
git config core.hooksPath .githooks
git config --get core.hooksPath

预期输出

text
.githooks

之后执行 git commit 时,只要检查脚本返回非零状态,提交就会被阻止。core.hooksPath 是每个克隆仓库的本地配置,因此新成员仍需要完成一次初始化;可以把这一步放进项目的开发环境初始化脚本。

让远端流水线复用同一条命令

本地 hook 只能提高反馈速度,不能作为唯一门禁,因为成员可以未配置 hook,也可以主动跳过。远端 CI 应再次执行同一个检查入口,而不是复制另一份规则。

bash
python3 tools/check_ink.py

预期输出

text
[1/3] compile: OK
[2/3] content: OK
[3/3] key knots: OK
INK_CHECK_OK

这样规则只维护一份:本地提交前负责“尽快告诉作者哪里错了”,远端流水线负责“保证进入主分支的内容一定跑过检查”。当团队以后增加禁用标签、命名规范或真正的剧情路径测试时,也应继续从这个统一入口扩展。

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

目录与阅读设置

阅读设置

17

记录一个想法

让脚本检查进入提交流程

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

登录哪都通