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

Ink 编译失败先查哪几层

Ink 编译失败先查哪几层

Ink 编译报错最怕一上来就在 Unity 里乱改。更有效的方法是把链路拆成 Ink 源码、INCLUDE 依赖、编译产物和 Unity 导入四层,先确认故障属于哪一层,再做最小化验证。

学习目标

  • 能按固定顺序判断编译失败发生在哪一层。
  • 能用最小 Ink 故事和编译器输出排除语法与依赖问题。
  • 能区分 Ink Unity Integration 1.x 与 2.x 的产物差异,避免加载错对象。

先把报错放回正确层级

一次“Ink 编译失败”可能并不是同一种故障。最先看的应该是第一条 Ink 相关错误,而不是后面由它连锁触发的空引用、资源加载失败或 UI 异常。

层级 典型现象 优先检查
Ink 源码 编译器直接指出行号或语法错误 choice、divert、条件块、knot/stitch 写法
INCLUDE 依赖 找不到文件、主文件无法完整编译 INCLUDE 路径、文件名、主文件与 include 文件关系
编译产物 源码已修复,但 Unity 仍在使用旧内容 当前导入产物是否已刷新、是否混用旧 JSON
Unity 导入 Inspector 或 Console 报导入、程序集、引用错误 插件版本、资源类型、脚本引用是否匹配

Ink 编译故障的四层定位流程

这个顺序的价值在于:只要上一层还没通过,下一层出现的错误往往只是结果。例如源码本身无法编译时,先处理运行时 Story 初始化没有意义。

用最小故事先排除语法问题

把复杂剧情暂时缩成一个确定能运行的最小文件,可以快速判断是编译环境坏了,还是原剧情中的语法、跳转或条件出了问题。下面的 main.ink 是测试输入文件,由后面的 inklecate 命令负责编译和运行:

ink
-> start

=== start ===
你站在门前。
* [敲门]
    门内没有回应。
    -> END
* [离开]
    你转身离开。
    -> END

如果 inklecate 已加入 PATH,可以直接用播放模式验证:

bash
inklecate -p main.ink

预期输出:

text
你站在门前。
1: 敲门
2: 离开

不同版本的交互提示符可能略有差异,但如果这里仍然出现编译错误,问题还停留在 Ink 源码或编译器环境,不要继续排查 Unity UI。把原文件内容逐段加回,直到错误重新出现,通常就能把范围缩到某个条件块、divert 或 INCLUDE。

再检查 INCLUDE 与主文件关系

多文件剧情要确认当前文件到底是“可独立运行的主文件”,还是只被其他文件 INCLUDE 的片段。include 文件本身没有完整入口并不等于主剧情有问题,真正需要通过编译的是引用它的 master。

排查时先确认 INCLUDE 指向的文件真实存在,再检查相对路径和文件名是否与项目中一致。如果错误在修改某个 include 后出现,应回到引用它的 master 查看编译结果,因为最终故事是从 master 汇总出来的。

确认 Unity 加载的是当前产物

以 Ink Unity Integration 2.x 为例,可以用一个最小组件验证 InkFile 是否能成功创建 Story。把通过前面测试的 Ink 文件拖到 inkFile 字段,再运行场景:

csharp
using Ink.Runtime;
using Ink.UnityIntegration;
using UnityEngine;

public sealed class InkCompileProbe : MonoBehaviour
{
    [SerializeField] private InkFile inkFile;

    private void Start()
    {
        if (inkFile == null)
        {
            Debug.LogError("InkFile not assigned.");
            return;
        }

        var story = new Story(inkFile.storyJson);
        Debug.Log(story.Continue().TrimEnd());
    }
}

预期输出:

text
你站在门前。

如果最小 Ink 能在 inklecate 中运行,但这里失败,问题已经从“剧情语法”缩小到 Unity 导入、插件版本或资源引用。反过来,如果这段能输出正文,说明编译产物与运行时都正常,原项目中的故障应继续从具体 master、INCLUDE 或业务脚本查起。

修复后只验证一条链路

修复时不要同时改剧情、插件和 UI。先保存 Ink 源码并确认对应 master 的编译错误消失,再确认 Unity 中的导入资源已更新,最后运行最小探针。这样每一步都有明确的通过条件,也能避免旧产物、旧引用和真正的语法错误互相干扰。

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

目录与阅读设置

阅读设置

17

记录一个想法

Ink 编译失败先查哪几层

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

登录哪都通