From de671ff94c07531723f080c14a98bd94e5bdd84a Mon Sep 17 00:00:00 2001 From: Ding Yuntian <1491671119@qq.com> Date: Wed, 17 Jun 2026 12:51:10 +0800 Subject: [PATCH] =?UTF-8?q?docs(yarn):=20=E6=9B=B4=E6=96=B0=E8=8A=82?= =?UTF-8?q?=E7=82=B9=E7=B1=BB=E5=9E=8B=E8=A7=84=E8=8C=83=E5=B9=B6=E6=96=B0?= =?UTF-8?q?=E5=A2=9E=E7=BB=B4=E4=BF=AE=E6=B5=81=E7=A8=8B=E8=A7=84=E8=8C=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Docs/Yarn维修节点类型规范.md | 374 +++++++++++++++++++++++++++++++++++ Docs/Yarn节点类型规范.md | 58 ++++-- 2 files changed, 412 insertions(+), 20 deletions(-) create mode 100644 Docs/Yarn维修节点类型规范.md diff --git a/Docs/Yarn维修节点类型规范.md b/Docs/Yarn维修节点类型规范.md new file mode 100644 index 000000000..b54771115 --- /dev/null +++ b/Docs/Yarn维修节点类型规范.md @@ -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` | 引擎入口 | 仅单出口 `<>` | 无叙事文本，仅做环境初始化与跳转 | +| `init` | `init` | 变量声明与初始状态 | 仅单出口 `<>` | 仅 `<>` / `<>` / 全局参数初始化 | +| `center` | `center` | 阶段调度中枢 | 可多出口 `<>` | 仅按 `$gameStage` 分发，无文本、无选项 | +| `content` | `content` | 阶段内容节点 | 通常单出口 | 可含叙事文本、局部选项、小游戏指令 | +| `performance` | `performance` | 原子化线性演出节点 | 单出口 | timeline、cutscene 等，禁止选项 | +| `event` | `event` | C# 调用的事件响应入口 | 单/多出口 `<>` | 仅轻量路由，禁止大段叙事 | +| `function` | `function` | 纯指令封装 | **禁止 `<>`** | 仅 Command，无文本；命名加 `_Func` 后缀 | +| `end` | `end` | 维修结束/收尾 | 单出口 | 可含少量结束演出，最终必须 `<>` | + + +附加标记（可附加到任何类型）： + +- `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 +--- +<> +<> +<> + +<> +=== +``` + +**约束清单：** + +- 固定命名为 `Start`，标签 `start`。 +- 不写叙事文本、不声明变量、不含选项。 +- 仅做最小必要的环境初始化，然后跳转到 `init`。 + +--- + +### 3.2 init 节点 + +集中声明维修流程所需变量，并设置初始全局参数。与梦境规范中的 `InitParams` 属于同一类型，只是节点名可按项目习惯选择 `VarsInit` 或 `数据初始化`。 + +```yarn +title: VarsInit +tags: init +--- +// 流程阶段 +<> + +// 模块检查标记 +<> +<> +<> + +// 小游戏相关状态 +<> +<> + +<> +=== +``` + +**约束清单：** + +- 标签 `init`，固定命名为 `VarsInit`（或统一使用 `数据初始化`）。 +- 仅包含 `<>`、`<>`、`<>` 等初始化指令。 +- 禁止叙事文本、选项、`<>` 到非 `center` 节点。 +- 同一 project 内，`init` 节点的命名必须一致。 + +--- + +### 3.3 center 节点 + +唯一拥有多出口跳转权的节点，负责按 `$gameStage` 进行阶段调度。 + +```yarn +title: Center +tags: center +--- +// Stage1: 诊室开场 +// Stage2: 后脑检查 +// Stage3: 滤波器深入 +// ... + +<> + <> +<> + <> +<> + <> +<> + <> +<> +=== +``` + +**约束清单：** + +- 标签 `center`，固定命名为 `Center`。 +- 仅按 `$gameStage` 做 `if` 分发，不写叙事文本、不含选项。 +- 维修终止条件统一在此处理（如 `$gameStage == 999` 时跳转到 `end`）。 +- 是同一 project 内**唯一**应该读取 `$gameStage` 的节点。 + +--- + +### 3.4 content 节点 + +维修流程的核心单元，承载阶段中的实际内容：叙事、选项、小游戏指令等。 + +```yarn +title: Stage1 +tags: content +--- +<> +<> +<> +<> +=== +``` + +```yarn +title: 开头对话 +tags: content +--- +hs: 医——生——！ #line:0bade9e + +<> +<> + +// ... 叙事与演出 ... + +<> +<> +=== +``` + +**约束清单：** + +- 标签 `content`。 +- 阶段入口节点建议命名为 `StageN`；阶段内子节点用中文描述性名称。 +- 阶段末尾通常做两件事：设置 `$gameStage`、跳回 `Center`。 +- 允许内部嵌套局部选项，但选项应服务于当前阶段内容，不做跨阶段跳转。 +- 不应读取 `$gameStage` 做复杂分发（这是 `center` 的职责）。 + +--- + +### 3.5 performance 节点 + +原子化线性演出节点，用于 timeline、cutscene 等必须完整播放的演出。 + +```yarn +title: 地铁到站演出 +tags: performance +--- +<> +<> +<> +<> +=== +``` + +**约束清单：** + +- 标签 `performance`。 +- **禁止分支选项**，必须单出口。 +- 保存点只能出现在 `performance` 节点的**开始之前**或**结束之后**，节点内部不允许保存。 +- 可包含 timeline 播放、镜头运动、动画演出等线性指令。 +- 不宜包含需要玩家选择的选项或小游戏交互。 + +--- + +### 3.6 event 节点 + +由 C# 代码调用的事件响应入口，负责把外部游戏事件映射到对应阶段节点。 + +```yarn +title: EmoPlugIn +tags: event +--- +<> +=== +``` + +```yarn +title: OnSalesTurnComplete +tags: event +--- +<> + <> +<> + <> +<> + <> +<> +=== +``` + +**约束清单：** + +- 标签 `event`。 +- 节点标题应表达触发来源，建议使用 `OnXxx` 或「模块 + 事件」形式。 +- 允许根据 `$gameStage` 或少量状态变量做轻量 `if` 分发。 +- **禁止大段对话、旁白、演出文本**。 +- 不应成为玩家直接阅读的内容节点。 + +--- + +### 3.7 function 节点 + +纯指令封装，零文本、零跳转，用于复用一组命令。与梦境规范的 `function` 保持一致，命名加 `_Func` 后缀。 + +```yarn +title: Wave_Show_Func +tags: function +--- +<> +<> +=== +``` + +```yarn +title: Wave_Hide_Func +tags: function +--- +<> +=== +``` + +**约束清单：** + +- 标签 `function`。 +- 命名必须带 `_Func` 后缀。 +- **禁止任何叙事文本、对话、选项**。 +- **禁止任何 `<>`**。 +- 仅包含演出或小游戏相关的 Command。 + +--- + +### 3.8 end 节点 + +维修流程的收尾节点，负责结束演出并触发下一段 Yarn。 + +```yarn +title: End +tags: end +--- +<> +<> + +me: 今天就到这里吧。 #line:xxxxxxxx + +<> +<> +<> +=== +``` + +**约束清单：** + +- 标签 `end`。 +- 可含少量结束演出与收尾对话。 +- 最终必须调用 `<>`，将控制权交还 C#。 +- 不要在一个维修脚本里设置多个 `end` 节点，除非剧情明确需要分支结局。 + +--- + +## 4. 控制流图 + +``` +Start ──<>──> VarsInit / 数据初始化 + │ + ▼ +Center ──<>──> Stage1（content/performance 入口） + │ │ + │ ├── content 子节点 ── ... + │ │ + │ ├── performance 子节点 ──<>──> content 或 end + │ │ + │ └── <> ──> <> + │ + ├──<>──> End ──<> + │ + └── C# 调用 ──> event 节点 ──<>──> 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 | +| ------------------ | ----- | ----- | ------ | ------- | ----------- | ----- | -------- | ----------------- | +| 是否包含叙事文本？ | 禁止 | 禁止 | 禁止 | 允许 | 允许（演出文本） | 禁止 | 禁止 | 允许（少量） | +| 是否包含选项？ | 禁止 | 禁止 | 禁止 | 允许 | 禁止 | 禁止 | 禁止 | 禁止 | +| 是否有 `<>`？ | 仅一个出口 | 仅一个出口 | 可多出口 | 通常一个出口 | 单出口 | 可有 | 禁止 | 最终 `<>` | +| 是否修改 `$gameStage`？ | 禁止 | 可初始化 | 禁止 | 允许 | 禁止 | 尽量避免 | 禁止 | 禁止 | +| 是否被 C# 调用？ | 否 | 否 | 否 | 否 | 否 | 是 | 否 | 否 | +| 是否可作为保存边界？ | 否 | 否 | 否 | 否 | 是（仅开头/结尾） | 否 | 否 | 是 | + + +--- + +## 7. 废弃与占位节点 + +- 废弃或待编辑节点必须附加 `deprecated` 或 `wip` 标签。 +- 任何活跃节点不得 `<>` 到 `deprecated` / `wip` 节点。 +- 任何 C# 代码不得调用 `deprecated` / `wip` 节点。 +- 建议：`deprecated` 用于已废弃的旧节点，`wip` 用于尚未完成的占位节点。 + +--- + +## 8. 设计原则 + +- `**start` 负责启动**：最小初始化 + 跳转到 `init`。 +- `**init` 负责配置**：所有变量声明集中管理。 +- `**center` 负责调度**：打开 `center` 即可一览整个维修流程阶段。 +- `**content` 负责内容**：阶段之间的叙事、选项、小游戏交互隔离，便于单独调整。 +- `**performance` 负责原子化演出**：timeline、cutscene 等必须完整播放，保存边界清晰。 +- `**event` 负责桥接**：把 C# 事件翻译成 Yarn 内部跳转，不掺杂叙事。 +- `**function` 负责复用指令**：零文本零跳转，`_Func` 后缀与梦境规范保持一致。 +- `**end` 负责收尾**：统一出口，统一 `<>`。 + +--- + diff --git a/Docs/Yarn节点类型规范.md b/Docs/Yarn节点类型规范.md index 201d5e304..0eb3df2c7 100644 --- a/Docs/Yarn节点类型规范.md +++ b/Docs/Yarn节点类型规范.md @@ -5,6 +5,8 @@ | 标签 | 职责 | 跳转权限 | 内容限制 | | ---------- | ---- | ----------------------- | ---------------------- | +| `start` | 引擎入口 | **仅单出口 `<>`** | 无叙事文本，仅初始化与跳转 | +| `init` | 变量初始化 | **禁止 `<>`** | 仅 `<>` / `<>` | | `hub` | 导航中枢 | **可 `<>` 多个节点** | 仅选项骨架，无叙事文本 | | `linear` | 线性演出 | **仅可 `<>` 到一个节点** | 可有叙事文本和演出指令 | | `detour` | 内容片段 | **禁止 `<>`** | 可有叙事文本、画面指令、局部选项 | @@ -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 --- <> <> @@ -46,8 +49,9 @@ title: Start **约束清单：** - **固定命名**：节点 title 必须为 `Start` -- **极简**：仅初始化 + 跳转到首个 linear（或首个 hub）；不写 ``、对话、选项 -- **InitParams**：通过 `<>` 调用；变量声明集中在 `InitParams` function 节点，不散落在 Start +- **固定标签**：`tags: start` +- **极简**：仅初始化 + 跳转到首个 init（如 `InitParams`）及首个 linear（或首个 hub）；不写 ``、对话、选项 +- **InitParams**：通过 `<>` 调用；变量声明集中在 `InitParams` init 节点，不散落在 Start - **唯一出口**：末尾仅一个 `<>`，指向正式剧情入口（通常为 linear） 叙事、演出、分支选项一律放在 `Start` 之后的首个 linear（如 `开场`）及后续节点中。 @@ -154,7 +158,6 @@ tags: detour | ---- | ---- | ------------- | | `_Func` | 只读：根据当前变量输出演出 | 禁止 | | `_Set` | 写入：变更进度/状态（可含演出指令） | 允许 | -| 无后缀 | `InitParams`：全局变量声明 | 仅 `<>` | `set_global_param`（场景、音量等展示上下文）不计入「修改 `$` 变量」。 @@ -190,13 +193,23 @@ tags: function === ``` -**特例：InitParams** +**约束清单：** -`InitParams` 的职责是全局变量声明与初始值设定，属于项目启动时的根级配置，不加 `_Func` / `_Set` 后缀。 +- **零文字**：禁止任何对话、旁白、选项文字 +- **零跳转**：禁止任何 `<>` +- **纯 Command**：仅 `<>`、`<>`、`<>`、`<>` 等指令 +- **后缀语义**：`_Func` 禁止 `<>` / `<>`；`_Set` 必须含至少一处 `$` 变量写入 +- **标签大写**：`tags: function`（首字母大写） + +--- + +### 3.5 init 节点 + +变量声明与初始值设定的独立类型。`InitParams` 属于项目启动时的根级配置，统一使用 `tags: init`。 ```yarn title: InitParams -tags: function +tags: init --- <> <> @@ -208,9 +221,9 @@ tags: function - **零文字**：禁止任何对话、旁白、选项文字 - **零跳转**：禁止任何 `<>` -- **纯 Command**：仅 `<>`、`<>`、`<>`、`<>`、`<>` 等指令 -- **后缀语义**：`_Func` 禁止 `<>` / `<>`；`_Set` 必须含至少一处 `$` 变量写入 -- **标签大写**：`tags: function`（首字母大写） +- **纯声明**：仅 `<>`、`<>`（初始值）、`<>` +- **集中管理**：所有全局变量声明集中在 `InitParams` init 节点，不散落在 `Start` 或其他节点 +- **标签小写**：`tags: init` --- @@ -248,6 +261,10 @@ linear（如：开场）──>> hub / linear / NextYarn │function │ 被 hub/detour/linear 通过 <> 调用 │(零文本) │ └─────────┘ + +┌─────────┐ +│ init │ 被 Start 通过 <> 调用，仅 declare / set +└─────────┘ ``` --- @@ -255,20 +272,21 @@ linear（如：开场）──>> hub / linear / NextYarn ## 5. 快速检查表 -| 检查项 | Start | hub | linear | detour | function | -| --------------- | ----- | ----- | -------- | -------- | ---------------------- | -| 是否包含选项骨架？ | 禁止 | 必须 | 禁止 | 仅局部 | 禁止 | -| 是否包含叙事文本？ | 禁止 | 禁止 | 允许 | 允许 | **禁止** | -| 是否有 `<>`？ | 仅一个出口 | 允许多出口 | 仅一个出口 | **禁止** | **禁止** | -| 后缀是否正确？ | - | - | - | - | **`_Func` / `_Set`，InitParams 无后缀** | -| 标签是否正确？ | 无 tags | `hub` | `linear` | `detour` | `function` | +| 检查项 | start | init | hub | linear | detour | function | +| --------------- | ----- | ----- | ----- | -------- | -------- | ---------------------- | +| 是否包含选项骨架？ | 禁止 | 禁止 | 必须 | 禁止 | 仅局部 | 禁止 | +| 是否包含叙事文本？ | 禁止 | 禁止 | 禁止 | 允许 | 允许 | **禁止** | +| 是否有 `<>`？ | 仅一个出口 | 禁止 | 允许多出口 | 仅一个出口 | **禁止** | **禁止** | +| 后缀是否正确？ | - | 无后缀 | - | - | - | **`_Func` / `_Set`** | +| 标签是否正确？ | `start` | `init` | `hub` | `linear` | `detour` | `function` | --- ## 6. 设计原则 -- **Start 负责启动**：InitParams + 跳转入口，与叙事彻底分离 +- **Start 负责启动**：`tags: start`，跳转入口，与叙事彻底分离 +- **init 负责变量初始化**：`InitParams` 集中声明，不散落在 Start - **hub 负责路由**：打开任意 hub 即可一览场景结构，无需滚屏 - **linear 负责推进**：无分支过场，单向流动 - **detour 负责填充**：内容抽离后可被多处复用，修改不影响整体结构