游戏叙事与剧情 / 系统课时
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 报导入、程序集、引用错误 | 插件版本、资源类型、脚本引用是否匹配 |

这个顺序的价值在于:只要上一层还没通过,下一层出现的错误往往只是结果。例如源码本身无法编译时,先处理运行时 Story 初始化没有意义。
用最小故事先排除语法问题
把复杂剧情暂时缩成一个确定能运行的最小文件,可以快速判断是编译环境坏了,还是原剧情中的语法、跳转或条件出了问题。下面的 main.ink 是测试输入文件,由后面的 inklecate 命令负责编译和运行:
-> start
=== start ===
你站在门前。
* [敲门]
门内没有回应。
-> END
* [离开]
你转身离开。
-> END如果 inklecate 已加入 PATH,可以直接用播放模式验证:
inklecate -p main.ink预期输出:
你站在门前。
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 字段,再运行场景:
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());
}
}预期输出:
你站在门前。如果最小 Ink 能在 inklecate 中运行,但这里失败,问题已经从“剧情语法”缩小到 Unity 导入、插件版本或资源引用。反过来,如果这段能输出正文,说明编译产物与运行时都正常,原项目中的故障应继续从具体 master、INCLUDE 或业务脚本查起。
修复后只验证一条链路
修复时不要同时改剧情、插件和 UI。先保存 Ink 源码并确认对应 master 的编译错误消失,再确认 Unity 中的导入资源已更新,最后运行最小探针。这样每一步都有明确的通过条件,也能避免旧产物、旧引用和真正的语法错误互相干扰。