158 lines
9.4 KiB
Markdown
158 lines
9.4 KiB
Markdown
# Story IR Schema（v0.2，M4 扩展）
|
||
|
||
> v0.2 变更（M4）：新增 `sequences`/`out_ref`（子序列复用）、Option `skip`（押注跳过）、
|
||
> `stage.point_set`（点位集引用 + 坐标校验）；条件/奖励词典外置到 `ir_dictionary.json`。
|
||
> 校验+编译内核收敛进 `ir_core/` 包（CLI 与 M5 Web 后端共用）。
|
||
|
||
Story IR 是"讲故事"与"编译成配置"两段之间的唯一交接棒。它只描述**语义层**
|
||
（语义角色 / 语义场景 / 叙事节点），把真实 ID、prefab 点位、`step` 号、`nextStepId`
|
||
前缀拼接全部留给编译器。
|
||
|
||
配套：
|
||
- 样张：`tools/event_authoring/samples/yuye_koumen.ir.json`
|
||
- 降级目标：`Assets/Scripts/Base/Config/Data/GameEventData.cs`
|
||
- 设计依据：`docs/plans/2026-06-03-event-config-automation-design.md`
|
||
|
||
---
|
||
|
||
## 1. 顶层结构
|
||
|
||
```jsonc
|
||
{
|
||
"id": "QY_YYKM", // group 名（唯一，不与现有内置 group 冲突）
|
||
"title": "雨夜叩门",
|
||
"theme": "正统武侠·道德抉择",
|
||
"scale": "标准奇遇", // 仅元信息，不参与编译
|
||
"roles": [ Role, ... ],
|
||
"stage": Stage,
|
||
"sequences": [ Sequence, ... ], // 可选；可复用子序列（被 out_ref 引用）
|
||
"nodes": [ Node, ... ],
|
||
"endings": [ Ending, ... ]
|
||
}
|
||
```
|
||
|
||
## 2. Role（语义角色）
|
||
|
||
```jsonc
|
||
{ "slot": "NP1", "name": "神秘剑客", "archetype": "负伤外门高手", "camp": 0 }
|
||
```
|
||
- `slot`：编译后写进 `points`/`camp2Fighters` 的语义点位名。`P1`=玩家固定。
|
||
- `archetype`：原型标签，编译期→真实 NPC ID（匹配 `npc_data`）。
|
||
- `camp`：0 中立 / 1 玩家方 / 2 敌方（战斗时用，可省略）。
|
||
|
||
## 3. Stage（语义场景）
|
||
|
||
```jsonc
|
||
{ "type": "门派入口·夜", "reuse_hint": "K3_A", "point_set": "QY_YYKM" }
|
||
```
|
||
- `type`：场景语义；编译器据此 + 所需角色数从点位库挑结构匹配的 prefab。
|
||
- `reuse_hint`：可选，显式指定复用哪个现有 prefab（仅作 BDTree host）。
|
||
- `point_set`：可选，引用的点位集名（默认 = `id`）。对应 `Assets/StreamingAssets/Story/PointSets/{point_set}.points.json`（M1 取点工具产出）。编译期校验：IR 里实际站位的点位名（speaker/actor/move.to/fight 阵营/camera）必须都在该点位集中存在；点位集文件不存在则降级为警告（`--strict-points` 下视为错）。
|
||
|
||
## 4. Node（叙事节点）
|
||
|
||
通用字段：`id`（组内唯一）、`kind`。各 `kind` 字段如下：
|
||
|
||
| kind | 字段 | → GameEventData |
|
||
|---|---|---|
|
||
| `narration` | `speaker?`, `text`, `next` | type0；挂角色(默认 P1)用气泡实景呈现，**不走全屏黑幕**；`content`=text |
|
||
| `dialogue` | `speaker`, `text`, `camera?`, `next` | type0；`points`=[speaker]，`content`，`cameraPoint` |
|
||
| `move` | `actor`, `to`, `mode?`(walk/teleport/remove), `speed?`, `ani?`, `next` | type0；`points`/`movePoint`/`moveStatus` |
|
||
| `anim` | `actor`, `ani`, `angle?`, `next` | type0；`anis`=[ani,angle] |
|
||
| `choice` | `options`:[Option] | type1；每 option 一行 |
|
||
| `choice_once` | `options`:[Option] | type2；编译器保证有恒满足兜底项 |
|
||
| `random` | `branches`:[{`weight`,`goto`}] | type3；`weight`+`nextStepId` |
|
||
| `fight` | `fight_type`(1 击倒/2 死斗), `camp2`:[slot], `camp1?`:[slot], `win`, `lose` | type0；`camp2Fighters`,`fightStatus`=[type,win,lose] |
|
||
| `reward` | `grants`:[Grant], `next` | type0；`resultRewardIds` 或 `roleActionCode` |
|
||
| `out_ref` | `ref`(子序列 id), `next` | 编译前预展开成普通节点（见 §4.1）；本节点不直接产行 |
|
||
|
||
### 4.1 Sequence / out_ref（子序列复用，对应 `OutRefStoryNodeData`）
|
||
|
||
```jsonc
|
||
// 顶层 sequences：可复用子序列
|
||
{ "id": "seq_cheer", "nodes": [ {Node}, ... ] }
|
||
// 引用它的节点
|
||
{ "id": "ref_a", "kind": "out_ref", "ref": "seq_cheer", "next": "end_win" }
|
||
```
|
||
- **语义**：把一段公共流程（庆功/过场/结算）抽成子序列，多处 `out_ref` 复用，避免重复手写。
|
||
- **编译**（对齐 `StorylineMgr.ReplaceStoryEventData` 的展开）：编译前把每个 `out_ref` 节点 `r` 摊平——
|
||
克隆 `ref` 子序列的节点，id 加 `{r.id}__` 前缀，内部跳转同步加前缀；子序列出口（`next` 为空的尾节点）
|
||
的 `next` 接到 `r.next`；指向 `r` 的跳转改写为子序列入口 `{r.id}__{首节点}`。
|
||
- **多处复用不撞 id**：不同 `out_ref` 节点前缀不同 → 各自一份独立行。
|
||
- **限制**：M4 仅支持**一层**（子序列内不得再含 `out_ref`），违者校验报错；子序列内跳转目标须落在子序列内或共享结局。
|
||
|
||
### Option（选项）
|
||
```jsonc
|
||
{ "text": "收留他", "condition": Condition?, "reward": {"grants":[Grant]}?,
|
||
"skip": { "node": "end_bet", "reward": {"grants":[Grant]} }?, "goto": "end_ally" }
|
||
```
|
||
- `text`→`choose`，`condition`→`condition`，`reward`→`resultRewardIds`（选项被选后自身发的奖励/扣费），`goto`→`nextStepId`。
|
||
- **`skip`（押注跳过，对应 `skipNodeId`+`skipReward`）**：选该项时**把 `skip.reward` 注入 `skip.node` 那行的奖励**，常配合 `goto` 越过中间战斗直达结算行（押对了→不打了直接领彩头）。
|
||
- 编译：选项行写 `skipNodeId = skip.node`（裸节点 id，运行时 `ChooseTaskUI` 自动拼 `{group}_` 查行）、`skipReward = compile(skip.reward)`。
|
||
- 注意：运行时是**覆盖** `skip.node` 行的 `resultRewardIds`（非追加）→ 让 `skip.node` 的自带 grants 为空、彩头全由 `skip.reward` 给。
|
||
- 校验：`skip.node` 须可解析；`skip.reward.grants` 非空且合法。
|
||
|
||
## 5. Ending（结局）
|
||
```jsonc
|
||
{ "id": "end_ally", "summary": "结义同盟", "grants": [Grant], "result": "success" }
|
||
```
|
||
- `result`：可选，`success`(默认,→`gameTaskStatus`1) / `fail`(→2) / `end`(→3)。决定收尾分支。
|
||
- 编译为**两行**：① 结算行（`missionText`=summary + `resultRewardIds`/`roleActionCode`，`gameTaskStatus`=0，
|
||
`nextStepId`→终结行）；② 裸终结行（仅 `gameTaskStatus`）。
|
||
- **为何拆两行**：`EventRefreshStepAction` 在 `RefreshStep()` 返回 false（即下一步 `gameTaskStatus>0`）时
|
||
返回 `Failure`，会中断该步 Sequence——若把奖励与 `gameTaskStatus` 放同一行，发奖励/入门的 Action 被跳过。
|
||
终结行触发 `DirectStoryEnd`（复位镜头 `otherTarget=null` / 恢复玩家控制 / 结束剧情）。与可视化编辑器
|
||
及内置奇遇 `Qiyu/QY10_A.json`（末节点 `taskStatus:1`、内容为空、奖励在前置节点）一致。
|
||
|
||
## 6. Condition / Grant 词典（外置 `ir_dictionary.json`）
|
||
|
||
> M4 起词典外置到 `tools/event_authoring/ir_dictionary.json`，编译器（`ir_core`）与 M5 Web 前端共读。
|
||
> 新增**查表类** kind 只改该 JSON、零代码；需引擎特例的 kind 标 `"engine": true`。
|
||
> 编译器对未登记 kind **报错不静默**。下表为当前登记项（随推进扩充）。
|
||
|
||
### Condition（→ `condition` 字段）
|
||
```jsonc
|
||
{ "kind": "银两", "op": ">=", "value": 500 } // → "V19,2,500" (op: >=→2)
|
||
```
|
||
| kind | 真实ID | 说明 |
|
||
|---|---|---|
|
||
| 银两 | V19 | 门派金钱（`RewardItems` 特判 schoolMoney） |
|
||
|
||
### Grant（→ `resultRewardIds` 或行为码）
|
||
```jsonc
|
||
{ "kind": "银两", "value": 200 } // → "V19,200"（正=给，负=扣）
|
||
{ "kind": "道具", "item": "P6", "value": 3 } // → "P6,3"
|
||
{ "kind": "友好度", "target": "NP1", "value": 30 } // → "NP1,V15,30"
|
||
{ "kind": "入门", "target": "NP1" } // → roleActionCode "JoinToPlayerSch=NP1"
|
||
```
|
||
| kind | 真实ID/机制 |
|
||
|---|---|
|
||
| 银两 | V19 |
|
||
| 道具 | 由 `item` 指定（drop_item_data ID） |
|
||
| 友好度 | V15（需 `target` NPC slot） |
|
||
| 入门 | roleActionCode `JoinToPlayerSch`（NPC 加入玩家门派） |
|
||
|
||
> 词典随 MVP 推进扩充；编译器对未登记的 kind 报错，不静默产出。
|
||
|
||
## 7. 编译器降级不变量（与 StorylineMgr 现有逻辑一致）
|
||
- 自动生成 `step`（按节点拓扑序）。
|
||
- 自动给 `id`/`nextStepId`/`fightStatus[1..2]` 拼 `{group}_` 前缀。
|
||
- 所有跳转目标（`next`/`goto`/`win`/`lose`/`branches[].goto`）必须可解析到某节点或结局，否则编译失败。
|
||
- 每个 `choice`/`choice_once` 至少一个无 `condition`（或恒满足）的兜底项，否则编译失败。
|
||
|
||
## 8. 多语言 / 本地化
|
||
|
||
游戏本地化走 `SGameText`（重写 `Text.text` setter）。剧情对话气泡 `TaskDialogUI.contentText`
|
||
已是 `SGameText`，链路可用。规则：
|
||
|
||
- **文本一律用简体中文撰写**（`content`/`choose`/`summary`），作为 canonical key：
|
||
- **简体↔繁体**：`SGameText` 字符级机械转换，自动覆盖，无需额外工作。
|
||
- **韩文(及未来语言)**：`SGameText` 用中文整句作 key 查 `StreamingAssets/i18n/ko.tsv`。
|
||
- 编译器附带产出 `{group}.i18n.tsv`（中文 key 列 + 空韩文列），翻译填好后合并进 `ko.tsv`，
|
||
新剧情文本即纳入本地化，不会成为漏网。
|
||
- **占位符**：需动态插入角色名时用游戏既有约定（如 `{NP1}`、`{A5,NP1}`），编译器原样保留。
|
||
注意：含占位的整句**韩文查表会 miss**（拿到的是替换后的完整串）→ 简繁不受影响，韩文 fallback 中文。
|
||
这是项目级已知限制（待 `SGameText.SetFormat` 模板方案解决），故重要台词尽量少用占位。
|
||
- **运行时前提**：剧情文本的显示组件必须是 `SGameText`。对话气泡已满足；黑屏旁白/选项 UI
|
||
若发现是原生 `Text`，需在游戏侧补挂 `SGameText`（属游戏侧改造，不在编译器范围）。
|