tinbird/aibis-dream
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a3f3fadaba5879a59b7e31f14aa99f47b8075fbd
aibis-dream/Docs/Yarn节点类型规范.md
T

9.5 KiB
Raw Blame History

Yarn 节点类型规范

1. 节点类型与跳转权限

标签 职责 跳转权限 内容限制
start 引擎入口 仅单出口 <<jump>> 无叙事文本，仅初始化与跳转
init 变量初始化 禁止 <<jump>> 仅 <<declare>> / <<set>>
hub 导航中枢 可 <<jump>> 多个节点 仅选项骨架，无叙事文本
linear 线性演出 仅可 <<jump>> 到一个节点 可有叙事文本和演出指令
detour 内容片段 禁止 <<jump>> 可有叙事文本、画面指令、局部选项
function 功能函数 禁止 <<jump>> 禁止任何文字内容，仅 Command

2. 命名规则

节点标签 命名示例 规则
start Start 固定命名，固定标签 start
init InitParams 无后缀；仅 declare
hub 教室、天台、走廊 场景名或状态名
linear 海边、开场动画 事件名或过场名
detour 观察、趴回去再睡会、女孩 中文动宾/名词短语
function（只读） 展示山_Func _Func 后缀；不修改 $ 变量
function（写入） 捡起矢车菊_Set _Set 后缀；会修改 $ 变量

3. 各类型详细规范

3.0 Start 节点（引擎入口）

Yarn Spinner 默认从名为 Start 的节点开始运行。它属于独立的 start 类型，固定标签 start，职责仅是启动流程，不写叙事。

title: Start
tags: start
---
<<detour InitParams>>
<<jump 开场>>
===

约束清单：

  • 固定命名：节点 title 必须为 Start
  • 固定标签：tags: start
  • 极简：仅初始化 + 跳转到首个 init（如 InitParams）及首个 linear（或首个 hub）；不写 <i>、对话、选项
  • InitParams：通过 <<detour InitParams>> 调用；变量声明集中在 InitParams init 节点，不散落在 Start
  • 唯一出口：末尾仅一个 <<jump>>，指向正式剧情入口（通常为 linear）

叙事、演出、分支选项一律放在 Start 之后的首个 linear（如 开场）及后续节点中。

3.1 hub 节点

唯一拥有多出口跳转权的节点类型，负责场景导航。

title: 天台
tags: hub
---
<<set_global_param dream1scene 3>>

->检查
    <<detour 天台检查>>
    <<jump 天台>>          # 允许：返回自身 hub
->上去 <<if $gameStage<3>>
    <<detour 上去_没有门>>
    <<jump 天台>>          # 允许：返回自身 hub
->上楼
    <<hide_sprite>>
    <<jump 走廊>>          # 允许：跳转到其他 hub
->进入天文台 <<if $gameStage==3>>
    <<hide_sprite>>
    <<jump 天文台>>        # 允许：跳转到其他 hub
===

约束清单：

  • 仅存放选项骨架和流程骨架，不写叙事文本
  • 选项目标为 detour（内容）或 <<jump>> 到其他 hub/linear
  • 循环回自身时必须显式 <<jump 自身名>>

3.2 linear 节点

仅允许一个出口，用于强制剧情推进。

title: 海边
tags: linear
---
<<stop_music event:/Music/mus_dream1 fade>>
<<hide_sprite>>
<i>你的身体仿佛正在黑暗中褪去。</i>

# ... 大量线性叙事 ...

<<hide_dialog>>
<<wait 2>>
<<play_timeline 醒来>>

<<NextYarn>>              # 仅一个出口
===

约束清单：

  • 无分支选项（或仅有伪选项无实际分流）
  • 末尾只能有一个 <<jump>> 目标（或 <<NextYarn>>）
  • 可包含演出指令和叙事文本

3.3 detour 节点

禁止任何 <<jump>>，执行完毕后控制权交还调用方。

title: 天台检查
tags: detour
---
->窗户
    <i>天文台下面有一排窗户...</i>
->地上 <<if $gameStage < 3>>
    <i>地上排布着黑乎乎脏兮兮的隔热砖...</i>
    <<if $scj==0>>
        <<detour 捡起矢车菊_Set>>
    <<endif>>
->远眺
    <<detour 展示山_Func>>
===

约束清单：

  • 禁止任何 <<jump>>
  • 允许内部嵌套选项（仅限局部选择，不影响全局导航）
  • 允许调用其他 detour（<<detour 子内容>>）和 function（<<detour 展示山_Func>>）
  • 负责叙事文本、画面指令、局部状态变更

3.4 function 节点

纯指令容器，零文本。统一 tags: function，按是否修改 $ 变量区分后缀：

后缀 职责 修改 $ 变量？
_Func 只读：根据当前变量输出演出 禁止
_Set 写入：变更进度/状态（可含演出指令） 允许

set_global_param（场景、音量等展示上下文）不计入「修改 $ 变量」。

只读示例（_Func）

title: 展示走廊_Func
tags: function
---
<<if $gameStage==0>>
    <<show_sprite "D1S走廊1">>
<<elseif $gameStage==1>>
    <<show_sprite "D1S走廊2">>
<<else>>
    <<show_sprite "D1S走廊3">>
<<endif>>
===

写入示例（_Set）

title: 捡起矢车菊_Set
tags: function
---
<<set $scj=1>>
<<if $gameStage==0>>
    <<show_sprite "D1S天台-地板1">>
<<else>>
    <<show_sprite "D1S天台-地板2">>
<<endif>>
<<set $gameStage=1>>
===

约束清单：

  • 零文字：禁止任何对话、旁白、选项文字
  • 零跳转：禁止任何 <<jump>>
  • 纯 Command：仅 <<set>>、<<set_global_param>>、<<show_sprite>>、<<play_sfx>> 等指令
  • 后缀语义：_Func 禁止 <<set>> / <<declare>>；_Set 必须含至少一处 $ 变量写入
  • 标签大写：tags: function（首字母大写）

3.5 init 节点

变量声明与初始值设定的独立类型。InitParams 属于项目启动时的根级配置，统一使用 tags: init。

title: InitParams
tags: init
---
<<declare $started=false>>
<<declare $gameStage=0>>
<<declare $ppStage=0>>
===

约束清单：

  • 零文字：禁止任何对话、旁白、选项文字
  • 零跳转：禁止任何 <<jump>>
  • 纯声明：仅 <<declare>>、<<set>>（初始值）、<<set_global_param>>
  • 集中管理：所有全局变量声明集中在 InitParams init 节点，不散落在 Start 或其他节点
  • 标签小写：tags: init

4. 调用关系图

Start ──<<detour>>──> InitParams
  │
  │ <<jump>>
  ▼
linear（如：开场）──>> hub / linear / NextYarn

┌─────────┐     <<jump>>      ┌─────────┐
│  hub    │ ─────────────────> │  hub    │
│ (多出口) │                    │ (多出口) │
└────┬────┘                    └─────────┘
     │
     │ <<detour>>    ┌─────────┐
     └──────────────>│ detour  │ ──>> 可嵌套调用其他 detour
                     │(无jump) │
                     └────┬────┘
                          │
                          ▼
                     自然返回调用方 hub

┌─────────┐     <<jump>>      ┌─────────┐
│  hub    │ ─────────────────>│ linear  │
│ (多出口) │                    │(单出口)  │
└─────────┘                    └────┬────┘
                                    │
                                    │ <<jump>> 到下一 hub/linear/NextYarn
                                    ▼

┌─────────┐
│function │  被 hub/detour/linear 通过 <<detour>> 调用
│(零文本)  │
└─────────┘

┌─────────┐
│  init   │  被 Start 通过 <<detour>> 调用，仅 declare / set
└─────────┘

5. 快速检查表

检查项 start init hub linear detour function
是否包含选项骨架？ 禁止 禁止 必须 禁止 仅局部 禁止
是否包含叙事文本？ 禁止 禁止 禁止 允许 允许 禁止
是否有 <<jump>>？ 仅一个出口 禁止 允许多出口 仅一个出口 禁止 禁止
后缀是否正确？ - 无后缀 - - - _Func / _Set
标签是否正确？ start init hub linear detour function

6. 设计原则

  • Start 负责启动：tags: start，跳转入口，与叙事彻底分离
  • init 负责变量初始化：InitParams 集中声明，不散落在 Start
  • hub 负责路由：打开任意 hub 即可一览场景结构，无需滚屏
  • linear 负责推进：无分支过场，单向流动
  • detour 负责填充：内容抽离后可被多处复用，修改不影响整体结构
  • function 负责纯逻辑：零文本保证指令安全；_Func 只读、_Set 写入，后缀一眼识别副作用
Reference in New Issue View Git Blame Copy Permalink