Infant God

快速上手Yarn Spinner

7 min read

注意这份文档是AI自动生成的（除了那个对话流程示意图）

新.yarn 语法、自动化校验、SO 与 BugReport

这份文档面向新加入项目的文案同学，目标是两件事：

  1. 快速写出能跑的 .yarn。
  2. 知道出错时该看哪里、改哪里。

用法（先选路径）

快速导航

  • 想先复制一个可运行模板：看 2. 最小可运行模板
  • 想确认 header/选项 metadata 写法：看 3. 项目里常用的 .yarn 写法
  • 想知道保存后为什么脚本会变：看 4. 自动改写流水线
  • 想知道提交前必须跑什么：看 5. 自动化校验怎么用
  • 想定位最常见报错：看 5.3 常见报错对照
  • 想知道命令参数去哪查：看 7. Yarn 命令怎么查
  • 想提 Bug：看 8. 自动化报 Bug

1. 先记住这 5 件事

  1. 对话脚本都在 Assets/Resources/YarnScripts。
  2. 保存 .yarn 后会触发自动处理，文件可能被自动改写，这是正常现象。
  3. 提交前至少跑一次 InfantGod/Tools/Run All Auto Validations。
  4. 报错先看 Unity Console，日志里通常有 文件:行号。

2. 最小可运行模板

2.1 普通节点

title: Example_Node
when: $CurrentDay >= 1
---
Aistalt: 这里是一个最小节点。#Tech
->下一句
    <<jump Example_Next>>
===

2.2 角色入口节点（常见于 *.LiveEntry.yarn）

title: Live_Entry_Soldier
tracking:always
when: $CurrentDay >= 2 and not visited("Entry_Soldier_1")
Character: Soldier
---
<<set $LastSpokenCharacter = Character.Soldier>>
<<AddNPC Soldier>>
<<jump Entry_Soldier_1>>
===

Character: 节点建议始终设置 $LastSpokenCharacter，否则会被 Character Checker 标出来。

3. 项目里常用的 .yarn 写法

3.1 Header（节点头）常用字段

  • title: 节点名（必须唯一）。
  • when: 进入条件。
  • tracking:always 允许 visited("Node") 正确记录。
  • tags: 常见 #hub、#reach（流校验里的锚点）。
  • Character: 角色入口节点使用。
  • GenerateOptionText: GenerateOption 目标节点的选项文案 key。
  • Topic: Topic 条件（格式见下文）。

3.2 选项与分支

  • -> 选项。
  • ⇒ 随机/并列分支常见写法。
  • <<jump Node>>、<<if ...>>、<<once>>、<<once if ...>> 常用。
  • visited("Node") 用于回看是否到达过某节点。

3.3 选项 metadata（重点）

推荐直接写在选项行尾：

->尝试安抚对方 <<once if $Level_Topic_Insight>=1>>
    #Topic:Topic_Insight:1
    #Check:Empathy:12:Topic_Insight
    #Modify:Memory_X:true:1:Modify_知道了关键线索

字段说明：

  • #Check:Attr:Difficulty[:Topic]
  • #Modify:Var:true/false:DiceModifier:TextKey
  • #Topic:Topic_A:值
    支持 OR：Topic_A:1/Topic_B:2
    支持 AND：Topic_A:1+Topic_B:2
    不要混用 / 和 +。

4. 自动改写流水线（保存后“自己变了”是为什么）

项目有统一管线：YarnHashtagMetadataAutomationPipeline。对 .yarn 导入后会按顺序处理：

  1. WasVisited() 自动替换为 visited("当前节点title")。
  2. #Tech>=3 这类简写自动替换为 <<if Tech()>=3>>#Tech。
  3. 从 when / 选项 <<if $Level_Topic_...>> 推导并更新 Topic: 或 #Topic:...。
  4. 根据 <<declare>> 同步 Memory 资产。

另外还有 tracking 工具：会扫描 visited("Node")，自动给目标节点补 tracking:always。

5. 自动化校验怎么用

5.1 一键入口（文案最常用）

菜单：InfantGod/Tools/Run All Auto Validations

它会串行执行 Memory、Yarn 命令校验、Header 校验、Speaker 校验、GenerateOption 校验、RG 预制体/Email 自动补齐、Attachment 本地化等。

5.2 流校验（查不可达、死路、条件矛盾）

  • 静态流：InfantGod/Tools/Yarn/Run Flow Validation
  • 动态流：InfantGod/Tools/Yarn/Run Dynamic Flow Validation
  • 配置入口节点：InfantGod/Tools/Yarn/Dynamic Flow Validation Settings
  • 报告 CSV：Assets/Resources/ValidationReports

动态流尚未配置入口时，会默认从带 #reach 的节点起跑。#hub/#reach 节点在失败判定里作为锚点处理。

5.3 常见报错对照（实用版）

  • TopicRequirement is deprecated
    改成 Topic: Topic_X:Value。
  • Unknown attr in Check header / Unknown SkillCheck attr
    属性 TechName 不存在于 Define/Attr。
  • Unknown topic / Level topic variable references unknown topic
    Topic TechName 不存在于 Define/Topic。
  • Invalid Modify format
    #Modify 必须是 4 段：Var:Bool:整数:TextKey。
  • AddOption references missing node
    目标节点名拼错或不存在。
  • ShowImage attachment 'xxx' not found / is not Image type
    检查 Define/Attachment 里 TechName 和媒体类型。
  • 缺失 GenerateOptionText
    被 GenerateOption BaseName N 选中的节点缺 header。
  • 说话人未匹配
    该说话人不在 Prefabs/NPC 的 NPCInfo.TechName 里。
  • Aistalt 连续对白缺少人格标签
    连续行建议补 #Empathy/#Tech/#Troll/#Kitsch。

6. SO（ScriptableObject）哪些要关心

6.1 文案强相关（建议掌握）

  • Define/Attr：检定属性来源（#Check 用）。
  • Define/Topic：Topic TechName 与等级阈值（Topic、$Level_Topic_* 用）。
  • Define/Attachment：<<ShowImage ...>> 引用对象。
  • Define/Email：<<AddEmail ...>> 引用对象。
  • Define/Memory：由 <<declare>> 与工具联动生成/更新。

6.2 中相关（按需求了解）

  • Define/Hex、Define/Review、Define/Goods、Define/InteractItem、Define/Situation。

6.3 很多时候不用你手动建

以下会自动补齐或同步：

  • <<AddEmail ...>> 缺失 Email 资产可自动创建。
  • RG_ 说话人缺预制体可自动创建。
  • Attachment 本地化 key/I2 词条可自动补。
  • Memory_* 相关资产可从 <<declare>> 同步。

7. Yarn 命令怎么查（不靠猜）

  • 打开 Window/Yarn Spinner/Yarn Commands Analyzer。
  • 可直接看到当前项目注册的 YarnCommand / YarnFunction。
  • 不确定命令参数时，先查这个窗口。

8. 自动化报 Bug（给策划/程序最快）

游戏内入口是 TaskBar 的 BugReport 菜单：

  1. 填标题 + 详情。
  2. 可点截图（会暂时隐藏界面后抓图）。
  3. 勾选“包含截图”后提交。

建议最少提供以下信息：

  1. 节点 title（或文件名+行附近文本）。
  2. 复现步骤（1/2/3）。
  3. 期望结果 vs 实际结果。
  4. 复现概率（必现/偶现）。
  5. 是否是最新脚本与最新校验后出现。

9. 提交前 checklist（建议固定执行）

  1. 运行 Run All Auto Validations。
  2. Console 无 Error（Warning 至少理解原因）。
  3. 关键分支做一次流校验并看 CSV。
  4. 检查自动改写后的 diff，确认没有误改语义。
  5. 新增命令/TechName 都能在对应 SO 找到实体。

Graph View

Backlinks