tinbird/aibis-dream
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(yarn): 更新节点类型规范并新增维修流程规范

Browse Source
This commit is contained in:
dingyuntian
2026-06-17 12:51:10 +08:00
parent fc4b1c8805
commit de671ff94c
2 changed files with 412 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Docs/Yarn维修节点类型规范.md
+374
View File
@@ -0,0 +1,374 @@
# Yarn 维修节点类型规范
本规范适用于 `Assets/Yarn/FP/` 下的维修流程脚本，包括：
- `FP_Huoshan1`
- `FP_Peipei1` / `FP_Peipei2` / `FP_Peipei3`
- `FP_Shitou1` / `FP_Shitou2`
- `FP_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` 的节点开始运行。它不属于任何功能类型，职责仅是启动流程。
```yarn
title: Start
tags: start
---
<<init_environment Day>>
<<init_actor 地铁医生 左边>>
<<show_actor 地铁医生>>
<<jump VarsInit>>
===
```
**约束清单：**
- 固定命名为 `Start`，标签 `start`。
- 不写叙事文本、不声明变量、不含选项。
- 仅做最小必要的环境初始化，然后跳转到 `init`。
---
### 3.2 init 节点
集中声明维修流程所需变量，并设置初始全局参数。与梦境规范中的 `InitParams` 属于同一类型，只是节点名可按项目习惯选择 `VarsInit` 或 `数据初始化`。
```yarn
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` 进行阶段调度。
```yarn
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 节点
维修流程的核心单元，承载阶段中的实际内容：叙事、选项、小游戏指令等。
```yarn
title: Stage1
tags: content
---
<<hide_dialog>>
<<switch_fix_system_to "Clinic">>
<<fade_out 1>>
<<jump 开头对话>>
===
```
```yarn
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 等必须完整播放的演出。
```yarn
title: 地铁到站演出
tags: performance
---
<<hide_dialog>>
<<play_timeline 地铁到站>>
<<wait 2>>
<<jump 诊室外2>>
===
```
**约束清单：**
- 标签 `performance`。
- **禁止分支选项**，必须单出口。
- 保存点只能出现在 `performance` 节点的**开始之前**或**结束之后**，节点内部不允许保存。
- 可包含 timeline 播放、镜头运动、动画演出等线性指令。
- 不宜包含需要玩家选择的选项或小游戏交互。
---
### 3.6 event 节点
由 C# 代码调用的事件响应入口，负责把外部游戏事件映射到对应阶段节点。
```yarn
title: EmoPlugIn
tags: event
---
<<jump 检查情绪>>
===
```
```yarn
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` 后缀。
```yarn
title: Wave_Show_Func
tags: function
---
<<switch_emotion_wave_config "normal">>
<<show_emotion_wave 1>>
===
```
```yarn
title: Wave_Hide_Func
tags: function
---
<<hide_emotion_wave 0.3>>
===
```
**约束清单：**
- 标签 `function`。
- 命名必须带 `_Func` 后缀。
- **禁止任何叙事文本、对话、选项**。
- **禁止任何 `<<jump>>`**。
- 仅包含演出或小游戏相关的 Command。
---
### 3.8 end 节点
维修流程的收尾节点，负责结束演出并触发下一段 Yarn。
```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>>`。
---
Docs/Yarn节点类型规范.md
+38 -20
View File
@@ -5,6 +5,8 @@
| 标签 | 职责 | 跳转权限 | 内容限制 |
| ---------- | ---- | ----------------------- | ---------------------- |
| `start` | 引擎入口 | **仅单出口 `<<jump>>`** | 无叙事文本，仅初始化与跳转 |
| `init` | 变量初始化 | **禁止 `<<jump>>`** | 仅 `<<declare>>` / `<<set>>` |
| `hub` | 导航中枢 | **可 `<<jump>>` 多个节点** | 仅选项骨架，无叙事文本 |
| `linear` | 线性演出 | **仅可 `<<jump>>` 到一个节点** | 可有叙事文本和演出指令 |
| `detour` | 内容片段 | **禁止 `<<jump>>`** | 可有叙事文本、画面指令、局部选项 |
@@ -18,13 +20,13 @@
| 节点标签 | 命名示例 | 规则 |
| ----------------- | ----------------------- | ----------------- |
| `start` | `Start` | **固定命名，固定标签 `start`** |
| `init` | `InitParams` | **无后缀**；仅 declare |
| `hub` | `教室`、`天台`、`走廊` | 场景名或状态名 |
| `linear` | `海边`、`开场动画` | 事件名或过场名 |
| `detour` | `观察`、`趴回去再睡会`、`女孩` | 中文动宾/名词短语 |
| `function`（只读） | `展示山_Func` | **`_Func` 后缀**；不修改 `$` 变量 |
| `function`（写入） | `捡起矢车菊_Set` | **`_Set` 后缀**；会修改 `$` 变量 |
| `function`（初始化特例） | `InitParams` | **无后缀**；仅 declare |
| `Start`（引擎入口特例） | `Start` | **固定命名，不属于四类标签** |
---
@@ -33,10 +35,11 @@
### 3.0 Start 节点（引擎入口）
Yarn Spinner 默认从名为 `Start` 的节点开始运行。它**不属于** hub / linear / detour / function 四类，**不加**上述 `tags`，职责仅是启动流程，不写叙事。
Yarn Spinner 默认从名为 `Start` 的节点开始运行。它属于独立的 `start` 类型，**固定标签 `start`**，职责仅是启动流程，不写叙事。
```yarn
title: Start
tags: start
---
<<detour InitParams>>
<<jump 开场>>
@@ -46,8 +49,9 @@ title: Start
**约束清单：**
- **固定命名**：节点 title 必须为 `Start`
- **极简**：仅初始化 + 跳转到首个 linear（或首个 hub）；不写 `<i>`、对话、选项
- **InitParams**：通过 `<<detour InitParams>>` 调用；变量声明集中在 `InitParams` function 节点，不散落在 Start
- **固定标签**：`tags: start`
- **极简**：仅初始化 + 跳转到首个 init（如 `InitParams`）及首个 linear（或首个 hub）；不写 `<i>`、对话、选项
- **InitParams**：通过 `<<detour InitParams>>` 调用；变量声明集中在 `InitParams` init 节点，不散落在 Start
- **唯一出口**：末尾仅一个 `<<jump>>`，指向正式剧情入口（通常为 linear）
叙事、演出、分支选项一律放在 `Start` 之后的首个 linear（如 `开场`）及后续节点中。
@@ -154,7 +158,6 @@ tags: detour
| ---- | ---- | ------------- |
| `_Func` | 只读：根据当前变量输出演出 | 禁止 |
| `_Set` | 写入：变更进度/状态（可含演出指令） | 允许 |
| 无后缀 | `InitParams`：全局变量声明 | 仅 `<<declare>>` |
`set_global_param`（场景、音量等展示上下文）不计入「修改 `$` 变量」。
@@ -190,13 +193,23 @@ tags: function
===
```
**特例：InitParams**
**约束清单：**
`InitParams` 的职责是全局变量声明与初始值设定，属于项目启动时的根级配置，不加 `_Func` / `_Set` 后缀。
- **零文字**：禁止任何对话、旁白、选项文字
- **零跳转**：禁止任何 `<<jump>>`
- **纯 Command**：仅 `<<set>>`、`<<set_global_param>>`、`<<show_sprite>>`、`<<play_sfx>>` 等指令
- **后缀语义**：`_Func` 禁止 `<<set>>` / `<<declare>>`；`_Set` 必须含至少一处 `$` 变量写入
- **标签大写**：`tags: function`（首字母大写）
---
### 3.5 init 节点
变量声明与初始值设定的独立类型。`InitParams` 属于项目启动时的根级配置，统一使用 `tags: init`。
```yarn
title: InitParams
tags: function
tags: init
---
<<declare $started=false>>
<<declare $gameStage=0>>
@@ -208,9 +221,9 @@ tags: function
- **零文字**：禁止任何对话、旁白、选项文字
- **零跳转**：禁止任何 `<<jump>>`
- **纯 Command**：仅 `<<declare>>`、`<<set>>`、`<<set_global_param>>`、`<<show_sprite>>`、`<<play_sfx>>` 等指令
- **后缀语义**：`_Func` 禁止 `<<set>>` / `<<declare>>`；`_Set` 必须含至少一处 `$` 变量写入
- **标签大写**：`tags: function`（首字母大写）
- **纯声明**：仅 `<<declare>>`、`<<set>>`（初始值）、`<<set_global_param>>`
- **集中管理**：所有全局变量声明集中在 `InitParams` init 节点，不散落在 `Start` 或其他节点
- **标签小写**：`tags: init`
---
@@ -248,6 +261,10 @@ linear（如：开场）──>> hub / linear / NextYarn
│function │ 被 hub/detour/linear 通过 <<detour>> 调用
│(零文本) │
└─────────┘
┌─────────┐
│ init │ 被 Start 通过 <<detour>> 调用，仅 declare / set
└─────────┘
```
---
@@ -255,20 +272,21 @@ linear（如：开场）──>> hub / linear / NextYarn
## 5. 快速检查表
| 检查项 | Start | hub | linear | detour | function |
| --------------- | ----- | ----- | -------- | -------- | ---------------------- |
| 是否包含选项骨架？ | 禁止 | 必须 | 禁止 | 仅局部 | 禁止 |
| 是否包含叙事文本？ | 禁止 | 禁止 | 允许 | 允许 | **禁止** |
| 是否有 `<<jump>>`？ | 仅一个出口 | 允许多出口 | 仅一个出口 | **禁止** | **禁止** |
| 后缀是否正确？ | - | - | - | - | **`_Func` / `_Set`，InitParams 无后缀** |
| 标签是否正确？ | 无 tags | `hub` | `linear` | `detour` | `function` |
| 检查项 | start | init | hub | linear | detour | function |
| --------------- | ----- | ----- | ----- | -------- | -------- | ---------------------- |
| 是否包含选项骨架？ | 禁止 | 禁止 | 必须 | 禁止 | 仅局部 | 禁止 |
| 是否包含叙事文本？ | 禁止 | 禁止 | 禁止 | 允许 | 允许 | **禁止** |
| 是否有 `<<jump>>`？ | 仅一个出口 | 禁止 | 允许多出口 | 仅一个出口 | **禁止** | **禁止** |
| 后缀是否正确？ | - | 无后缀 | - | - | - | **`_Func` / `_Set`** |
| 标签是否正确？ | `start` | `init` | `hub` | `linear` | `detour` | `function` |
---
## 6. 设计原则
- **Start 负责启动**：InitParams + 跳转入口，与叙事彻底分离
- **Start 负责启动**：`tags: start`，跳转入口，与叙事彻底分离
- **init 负责变量初始化**：`InitParams` 集中声明，不散落在 Start
- **hub 负责路由**：打开任意 hub 即可一览场景结构，无需滚屏
- **linear 负责推进**：无分支过场，单向流动
- **detour 负责填充**：内容抽离后可被多处复用，修改不影响整体结构