12 KiB
12 KiB
Yarn 维修节点类型规范
本规范适用于 Assets/Yarn/FP/ 下的维修流程脚本，包括：
FP_Huoshan1FP_Peipei1/FP_Peipei2/FP_Peipei3FP_Shitou1/FP_Shitou2FP_Prologue
注意：
FP_Day*_sleep属于梦境脚本，沿用《Yarn 节点类型规范.md》；FP_Day*_begin/mid/night属于外出/日常脚本，不在本规范范围内。
1. 节点类型与跳转权限
| 类型 | 标签 | 职责 | 跳转权限 | 内容限制 |
|---|---|---|---|---|
start |
start |
引擎入口 | 仅单出口 <<jump>> |
无叙事文本，仅做环境初始化与跳转 |
init |
init |
变量声明与初始状态 | 仅单出口 <<jump>> |
仅 <<declare>> / <<set>> / 全局参数初始化 |
center |
center |
阶段调度中枢 | 可多出口 <<jump>> |
仅按 $gameStage 分发，无文本、无选项 |
content |
content |
阶段内容节点 | 通常单出口 | 可含叙事文本、局部选项、小游戏指令 |
performance |
performance |
原子化线性演出节点 | 单出口 | timeline、cutscene 等，禁止选项 |
event |
event |
C# 调用的事件响应入口 | 单/多出口 <<jump>> |
仅轻量路由，禁止大段叙事 |
function |
function |
纯指令封装 | 禁止 <<jump>> |
仅 Command，无文本；命名加 _Func 后缀 |
end |
end |
维修结束/收尾 | 单出口 | 可含少量结束演出，最终必须 <<NextYarn>> |
附加标记（可附加到任何类型）：
deprecated：已废弃节点，运行时不可达。wip：待编辑/占位节点，运行时不可达。
2. 命名规则
| 类型 | 命名示例 | 规则 |
|---|---|---|
start |
Start |
固定命名，首字母大写 |
init |
VarsInit、数据初始化 |
建议统一为 VarsInit；如项目已有 数据初始化，可保留但同一 project 内保持一致 |
center |
Center |
固定命名，每个维修 Yarn project 一个 |
content |
Stage1、开头对话、检查情绪、旋钮调节 |
阶段入口建议用 StageN；阶段内子节点用中文动宾/名词短语 |
performance |
地铁到站演出、手术动画、滤波器启动动画 |
中文描述性名称，明确表达演出内容 |
event |
EmoPlugIn、IntoEyeView、OnSalesTurnComplete |
用 OnXxx 或模块名 + 事件名，表达触发来源 |
function |
Wave_Show_Func、Wave_Hide_Func、Module_HighlightOff_Func |
领域_动作_Func 或 模块_动作_Func，PascalCase；必须带 _Func 后缀 |
end |
End、Stage8_End |
统一用 End 或带阶段前缀的结束名 |
3. 各类型详细规范
3.1 start 节点
Yarn Spinner 默认从名为 Start 的节点开始运行。它不属于任何功能类型，职责仅是启动流程。
title: Start
tags: start
---
<<init_environment Day>>
<<init_actor 地铁医生 左边>>
<<show_actor 地铁医生>>
<<jump VarsInit>>
===
约束清单：
- 固定命名为
Start，标签start。 - 不写叙事文本、不声明变量、不含选项。
- 仅做最小必要的环境初始化，然后跳转到
init。
3.2 init 节点
集中声明维修流程所需变量，并设置初始全局参数。与梦境规范中的 InitParams 属于同一类型，只是节点名可按项目习惯选择 VarsInit 或 数据初始化。
title: VarsInit
tags: init
---
// 流程阶段
<<declare $gameStage=1>>
// 模块检查标记
<<declare $emoChecked=false>>
<<declare $memoryChecked=false>>
<<declare $logicChecked=false>>
// 小游戏相关状态
<<declare $salesTurnIndex=0>>
<<declare $knobFailCount=0>>
<<jump Center>>
===
约束清单：
- 标签
init，固定命名为VarsInit（或统一使用数据初始化）。 - 仅包含
<<declare>>、<<set>>、<<set_global_param>>等初始化指令。 - 禁止叙事文本、选项、
<<jump>>到非center节点。 - 同一 project 内，
init节点的命名必须一致。
3.3 center 节点
唯一拥有多出口跳转权的节点，负责按 $gameStage 进行阶段调度。
title: Center
tags: center
---
// Stage1: 诊室开场
// Stage2: 后脑检查
// Stage3: 滤波器深入
// ...
<<if $gameStage == 1>>
<<jump Stage1>>
<<elseif $gameStage == 2>>
<<jump Stage2>>
<<elseif $gameStage == 3>>
<<jump Stage3>>
<<elseif $gameStage == 999>>
<<jump End>>
<<endif>>
===
约束清单：
- 标签
center，固定命名为Center。 - 仅按
$gameStage做if分发，不写叙事文本、不含选项。 - 维修终止条件统一在此处理（如
$gameStage == 999时跳转到end）。 - 是同一 project 内唯一应该读取
$gameStage的节点。
3.4 content 节点
维修流程的核心单元，承载阶段中的实际内容：叙事、选项、小游戏指令等。
title: Stage1
tags: content
---
<<hide_dialog>>
<<switch_fix_system_to "Clinic">>
<<fade_out 1>>
<<jump 开头对话>>
===
title: 开头对话
tags: content
---
hs: 医——生——！ #line:0bade9e
<<change_actor_state 捂头表情idle 火山>>
<<fade_in_actor 火山>>
// ... 叙事与演出 ...
<<set $gameStage = 2>>
<<jump Center>>
===
约束清单：
- 标签
content。 - 阶段入口节点建议命名为
StageN；阶段内子节点用中文描述性名称。 - 阶段末尾通常做两件事：设置
$gameStage、跳回Center。 - 允许内部嵌套局部选项，但选项应服务于当前阶段内容，不做跨阶段跳转。
- 不应读取
$gameStage做复杂分发（这是center的职责）。
3.5 performance 节点
原子化线性演出节点，用于 timeline、cutscene 等必须完整播放的演出。
title: 地铁到站演出
tags: performance
---
<<hide_dialog>>
<<play_timeline 地铁到站>>
<<wait 2>>
<<jump 诊室外2>>
===
约束清单：
- 标签
performance。 - 禁止分支选项，必须单出口。
- 保存点只能出现在
performance节点的开始之前或结束之后，节点内部不允许保存。 - 可包含 timeline 播放、镜头运动、动画演出等线性指令。
- 不宜包含需要玩家选择的选项或小游戏交互。
3.6 event 节点
由 C# 代码调用的事件响应入口，负责把外部游戏事件映射到对应阶段节点。
title: EmoPlugIn
tags: event
---
<<jump 检查情绪>>
===
title: OnSalesTurnComplete
tags: event
---
<<if $salesTurnIndex == 1>>
<<jump 销售转动_语义合成>>
<<elseif $salesTurnIndex == 2>>
<<jump 销售转动_语言审查>>
<<elseif $salesTurnIndex == 3>>
<<jump 销售转动_异常检测>>
<<endif>>
===
约束清单：
- 标签
event。 - 节点标题应表达触发来源，建议使用
OnXxx或「模块 + 事件」形式。 - 允许根据
$gameStage或少量状态变量做轻量if分发。 - 禁止大段对话、旁白、演出文本。
- 不应成为玩家直接阅读的内容节点。
3.7 function 节点
纯指令封装，零文本、零跳转，用于复用一组命令。与梦境规范的 function 保持一致，命名加 _Func 后缀。
title: Wave_Show_Func
tags: function
---
<<switch_emotion_wave_config "normal">>
<<show_emotion_wave 1>>
===
title: Wave_Hide_Func
tags: function
---
<<hide_emotion_wave 0.3>>
===
约束清单：
- 标签
function。 - 命名必须带
_Func后缀。 - 禁止任何叙事文本、对话、选项。
- 禁止任何
<<jump>>。 - 仅包含演出或小游戏相关的 Command。
3.8 end 节点
维修流程的收尾节点，负责结束演出并触发下一段 Yarn。
title: End
tags: end
---
<<fade_out 1>>
<<wait 1>>
me: 今天就到这里吧。 #line:xxxxxxxx
<<hide_dialog>>
<<wait 2>>
<<NextYarn>>
===
约束清单：
- 标签
end。 - 可含少量结束演出与收尾对话。
- 最终必须调用
<<NextYarn>>，将控制权交还 C#。 - 不要在一个维修脚本里设置多个
end节点，除非剧情明确需要分支结局。
4. 控制流图
Start ──<<jump>>──> VarsInit / 数据初始化
│
▼
Center ──<<jump>>──> Stage1（content/performance 入口）
│ │
│ ├── content 子节点 ── ...
│ │
│ ├── performance 子节点 ──<<jump>>──> content 或 end
│ │
│ └── <<set $gameStage>> ──> <<jump Center>>
│
├──<<jump>>──> End ──<<NextYarn>>
│
└── C# 调用 ──> event 节点 ──<<jump>>──> content 子流程
5. $gameStage 使用规范
$gameStage是center节点的调度主键。- 类型可以为
int或string，但同一 Yarn project 内必须保持一致。 - 只有
center节点读取$gameStage。 content节点在末尾写入$gameStage，然后跳回center。- 终止值（如
999或"流程结束"）统一在center中处理。
6. 快速检查表
| 检查项 | start | init | center | content | performance | event | function | end |
|---|---|---|---|---|---|---|---|---|
| 是否包含叙事文本？ | 禁止 | 禁止 | 禁止 | 允许 | 允许（演出文本） | 禁止 | 禁止 | 允许（少量） |
| 是否包含选项？ | 禁止 | 禁止 | 禁止 | 允许 | 禁止 | 禁止 | 禁止 | 禁止 |
是否有 <<jump>>？ |
仅一个出口 | 仅一个出口 | 可多出口 | 通常一个出口 | 单出口 | 可有 | 禁止 | 最终 <<NextYarn>> |
是否修改 $gameStage？ |
禁止 | 可初始化 | 禁止 | 允许 | 禁止 | 尽量避免 | 禁止 | 禁止 |
| 是否被 C# 调用？ | 否 | 否 | 否 | 否 | 否 | 是 | 否 | 否 |
| 是否可作为保存边界？ | 否 | 否 | 否 | 否 | 是（仅开头/结尾） | 否 | 否 | 是 |
7. 废弃与占位节点
- 废弃或待编辑节点必须附加
deprecated或wip标签。 - 任何活跃节点不得
<<jump>>到deprecated/wip节点。 - 任何 C# 代码不得调用
deprecated/wip节点。 - 建议：
deprecated用于已废弃的旧节点，wip用于尚未完成的占位节点。
8. 设计原则
**start负责启动**：最小初始化 + 跳转到init。**init负责配置**：所有变量声明集中管理。**center负责调度**：打开center即可一览整个维修流程阶段。**content负责内容**：阶段之间的叙事、选项、小游戏交互隔离，便于单独调整。**performance负责原子化演出**：timeline、cutscene 等必须完整播放，保存边界清晰。**event负责桥接**：把 C# 事件翻译成 Yarn 内部跳转，不掺杂叙事。**function负责复用指令**：零文本零跳转，_Func后缀与梦境规范保持一致。**end负责收尾**：统一出口，统一<<NextYarn>>。