diff --git a/design/dev/architecture/adr-0007-rng-single-stream.md b/design/dev/architecture/adr-0007-rng-single-stream.md new file mode 100644 index 00000000..2dc2ad81 --- /dev/null +++ b/design/dev/architecture/adr-0007-rng-single-stream.md @@ -0,0 +1,73 @@ +# ADR-0007: 全游戏随机流统一评估（RNG Single Stream Evaluation） + +## Status + +评估书——**待用户裁决**（本 ADR 是裁决闸，裁决前不动任何代码）。 + +背景：2026-09-27 用户在[关卡节点图生成](../../gdd/systems/冒险循环/关卡节点图生成.md)拍板点②两轮复裁终选「随机数统一用一个流」（全面执行），并拍板执行路径 = **先出本评估书再动手**、节点图特性实施排队其后。本评估书按用户要求如实给出：现行机制事实、统一流的真实改动面、三个备选与推荐。裁决本 ADR 后按裁决执行。 + +## Date + +2026-09-27 + +## Context + +### 用户动因（如实记录） + +用户质疑链全程：①问「增流是什么、文档没说明」→ ②质疑「借流复现口径变含糊」论断：「如果所有的随机数获取都是有完整记录的，那不是都可以一一复现吗？我觉得你的理论不对」→ ③收到机制澄清（复现=主种子+计数器按位重推导、非日志回放）与两条代价说明后，仍两轮终裁「统一用一个流」。动因解读：用户重视**单一随机源的心智简洁**，对"七条流"的分栏结构存疑（直觉=繁琐），并认为完整记录即可复现一切。 + +### 现行机制事实（全部带代码锚） + +| 事实 | 锚点 | +|---|---| +| 唯一主种子：冒险开始恰一次注入，禁中途重播种（全零断言） | `game/core/rng_service.gd:80-105` | +| 唯一派生公式族：derive(stream, scope) = mix64(SALT_s XOR (master + scope×GOLDEN)) | `game/core/rng_service.gd:61-77` | +| 七条流 = 七个盐值常量（同一公式、同一主种子） | `game/core/rng_service.gd:14-24` | +| 零旁路随机：randomize()/自建 RNG 硬性红线 | CLAUDE.md 硬性红线；`rng_service.gd:4` | +| 每流独立计数器；快照观测面 counter() | `rng_service.gd:36,140-142` | +| 复现 = 按（流，号位）重新推导，非日志回放 | registry `rng_service`/`stream_seed_derivation` 条目 | +| 计数器实际持久化：**现行存档未写各流计数器**（adventure_runner 摘要只落 master_seed） | `game/core/adventure_runner.gd:59,83,217` | +| 黄金向量断言（R3 8 常量） | `game/smoke/smoke_all.gd:34-36,3121+` | +| MC 逐局独立种子 | `game/smoke/adventure_monte_carlo.gd:15,52` | + +**核心发现**：字面目标「全游戏随机数派生自同一个源、可逐位复现、没有多套随机」——**现行架构已经满足**。七条流不是七个随机源，是同一主种子的七个盐值分栏（分栏只改派生种子，不改源）。真正剩下的唯一改动 = **把七条分栏计数器并为一个全局计数器**（物理并流）。 + +### 七流消费点清单（并流迁移面） + +| 流 | 消费点 | 取号时机 | +|---|---|---| +| board_gen | `board_generator.gd:16`、`battle_orchestrator.gd:141` | 每张棋盘 | +| reward_roll | `reward_economy.gd:61` | 每次装板批 | +| encounter | `battle_orchestrator.gd:116` | 每次战斗实例化（数量骰） | +| armor_roll | `damage_controller.gd:286`（流名走配置 `db.settlement.armor_roll_stream`） | 每次命中掷点 | +| behavior_roll | 战斗结算开轮摇号（SkillLottery；子流 scope = spawn_index×1000000+序） | 每敌每轮 | +| variant_place | `battle_orchestrator.gd:198` | 每板变异布置 | +| gp_drop | `battle_orchestrator.gd:737` | 每战末掉落掷定 | + +## Alternatives Considered + +### 方案甲：字面达成·维持分栏（node_map 作第八栏） + +承认字面目标已满足（核心发现）；节点图抽签按既有增流纪律接入第八栏。零迁移、位置语义（号位=第 N 次某类事件）完整保留、黄金向量与对拍口径不动。 + +### 方案乙：物理并流（用户终裁方向，如实评估） + +单盐单全局计数器：derive(scope) = mix64(SALT_0 XOR (master + scope×GOLDEN))，scope = 全局顺序号。三个后果（均已向用户两轮呈报，此处落档）： + +1. **号位失去事件语义**——第 N 号只回答"全局第 N 次取数"，不再回答"第 N 次什么"。玩家换条路（战斗次数变化）后，同一 N 号对应的事件种类漂移。 +2. **路线依赖**——任何一处随机事件数量/顺序变化平移其后全部骰子；对拍工具"行数恒等纯次序位移"性质失效；"这局 Boss 为什么没中"类单点归因需全序重放。 +3. **连带改动面**——七消费点迁移（上表 6 文件）；armor_roll 流名配置语义失效（`db.settlement.armor_roll_stream` 并流后无意义）；behavior_roll 子流位（spawn_index×STRIDE）重设计；快照契约登记面变更（7 计数器→1，实际存档未持久化计数器故代码迁移面小）；R3 黄金向量 8 常量全量重生成；MC/对拍读数与旧基线断档（全部历史基线作废重测）。 + +### 方案丙：并流 + 全事件日志（用户的「完整记录」模型落地） + +乙 + 每次取数落盘（流名/号位/用途/返回值），以此恢复单点定位能力。代价 = 乙全部代价 + 每次取数的写盘开销与日志体积；且日志回放与按位重推导并存 = 两套复现机制并存。 + +## Recommendation + +**推荐甲**：用户的核心诉求（单一随机源、完整可复现、无多套随机）现行架构字面满足；乙/丙是为一个已满足的目标支付真实的分析能力与一次性迁移成本。本 ADR 按用户裁决路径交付评估，**若用户裁决维持乙，上表「连带改动面」即实施批工单，按乙执行，本特性排队其后**——两个方向都已备好，裁决即动。 + +## Consequences + +- 裁决甲：节点图生成实施批按第八栏增流推进（改代码+金向量+冒烟断言三件套），本评估书归档为架构记录。 +- 裁决乙：先开 rng 架构批（迁移工单如上），全量回归后节点图生成实施批接续；历史 MC 基线全部作废重测归曲线调参批。 +- 裁决丙：同乙，另加日志面设计与写盘性能验收。 diff --git a/design/gdd/02-系统清单.md b/design/gdd/02-系统清单.md index 8c2120ec..a9b87863 100644 --- a/design/gdd/02-系统清单.md +++ b/design/gdd/02-系统清单.md @@ -42,7 +42,7 @@ | 文件 | 一句话概要 | 状态 | |---|---|---| | `关卡节点地图.md` | 单关内的节点图选路与推进 | 已定稿 | -| `关卡节点图生成.md` | 单关节点图的逐局随机来源：图模板池、抽签与实例化（实施未开工） | 设计草案·拍板点①④⑤已裁决 | +| `关卡节点图生成.md` | 单关节点图的逐局随机来源：图模板池、抽签与实例化（实施排队 ADR-0007 裁决后） | 设计草案·拍板点全落文 | | `冒险结构.md` | 整局冒险的关卡序列、失败与大奖励 | 已定稿·自旧体系迁移 | | `难度曲线与Boss.md` | 难度曲线、期望值带与 Boss 设计 | 已定稿·自旧体系迁移 | | `元进度.md` | 跨局成长（旧体系未单独成文） | 已定稿·已实现（2026-09-21 实现批，数值 provisional 归设计批标定） | diff --git a/design/gdd/06-待办清单.md b/design/gdd/06-待办清单.md index 191fb103..9551cd34 100644 --- a/design/gdd/06-待办清单.md +++ b/design/gdd/06-待办清单.md @@ -215,11 +215,11 @@ #### 关卡内结构随机生成（哈迪斯 / 哥布林弹珠式布局变化） -**现状**：用户 2026-09-20 方向性提及布局随机变化（哈迪斯 / 哥布林弹珠式）；现行节点图读关卡表固定行集。**2026-09-27 拍板立项**，设计文档已交付：[关卡节点图生成](systems/冒险循环/关卡节点图生成.md)（图模板池逐局抽签+三级台阶+测量对账）。**首轮裁决**：①第一关参与抽签、仅首次冒险走固定脚本④池规模每关 5 张⑤关卡开始逐关抽确认；骨架多份随机调取=路线确认。②③已补证据面待复裁（文档证据面 A/B，荐②A③C）。 +**现状**：用户 2026-09-20 方向性提及布局随机变化（哈迪斯 / 哥布林弹珠式）。**2026-09-27 拍板立项**，设计文档 [关卡节点图生成](systems/冒险循环/关卡节点图生成.md) v0.3：图模板池逐局抽签+三级台阶+测量对账；五拍板点全部裁决落文——①首关参与抽签仅首次冒险固定脚本④池每关 5 张⑤逐关抽确认②统一用一个流（rng 架构批先行，ADR-0007）③机制先行骨架随后。实施排队架构批裁决后。 **归属**：[关卡节点图生成](systems/冒险循环/关卡节点图生成.md)（设计 owner；行集内容责任方仍为[冒险结构](systems/冒险循环/冒险结构.md)，行进与图合法性校验归[关卡节点地图](systems/冒险循环/关卡节点地图.md)） -**状态**：已立项·设计草案 v0.2（①④⑤已裁决落文；②③待复裁） +**状态**：已立项·设计草案 v0.3（拍板点全落文；实施前置=ADR-0007 裁决落地） ### 难度曲线与Boss @@ -379,6 +379,14 @@ NodeOverlay 现行实态为模态覆盖层：恢复点全量服务（回复读 ### 数据配置 +#### 全游戏随机流统一架构批（七流并一评估，ADR-0007） + +**现状**：2026-09-27 用户两轮复裁终选「随机数统一用一个流」，先出评估书再动手。评估书已交付：[ADR-0007](../dev/architecture/adr-0007-rng-single-stream.md)——核心发现：字面目标「单一随机源、逐位可复现」现行已满足（七流=同一主种子的盐值分栏，非七个随机源）；待裁决=甲维持分栏/乙物理并流（七消费点迁移+向量重生成+MC 基线作废）/丙并流+全事件日志；并流主要代价=分析面损失（存档未持久化流计数器）。 + +**归属**：[数据配置](systems/表现与支撑/数据配置.md) + [ADR-0007](../dev/architecture/adr-0007-rng-single-stream.md)；节点图生成特性（拍板点②）实施排队其后 + +**状态**：已立项·ADR-0007 评估书已交付待裁决（2026-09-27） + ### 教学引导 diff --git a/design/gdd/systems/冒险循环/关卡节点图生成.md b/design/gdd/systems/冒险循环/关卡节点图生成.md index 070294a0..3003b188 100644 --- a/design/gdd/systems/冒险循环/关卡节点图生成.md +++ b/design/gdd/systems/冒险循环/关卡节点图生成.md @@ -1,7 +1,7 @@ # 关卡节点图生成 > 一句话：单关节点图怎么从固定配置变成逐局随机——图模板池、抽签与实例化 -> 状态：设计草案 v0.2（2026-09-27 立项；拍板点①④⑤已裁决落文，②③证据面已补待复裁；实施未开工） +> 状态：设计草案 v0.3（2026-09-27 立项；拍板点五项全部裁决落文；实施前置 = 全游戏随机流统一架构批裁决落地——见拍板点②与 ADR-0007） > 旧版参考：无（旧体系未单独成文；本事项自 2026-09-20 起登记 [06-待办清单](../../06-待办清单.md)「关卡内结构随机生成」条目） ## 设计目的 @@ -58,7 +58,7 @@ 模板池挂在关卡表逐关行上：行集从"单一节点集合"扩为"模板池"。**N=1 的池里只有现行那张图，逐局抽签退化回固定图**——这是**回滚档**（本文含义：任何一关把池缩回一张模板，该关行为就与今日固定配置逐位等价的保险形态）。整个设计因此可增量落地：先全关 N=1，再逐关扩池。 -抽签消费主种子派生的封闭命名流，流名提案 `node_map`（增流须单独拍板——rng_service 流清单是封闭的，见拍板点②）。 +抽签消费主种子派生的封闭命名流，流名提案 `node_map`（接入形态随拍板点②裁决：第八栏增流 or 统一流口径——架构批 [ADR-0007](../../../dev/architecture/adr-0007-rng-single-stream.md) 结论定）。 **内容纪律**：每张新模板等于一个小内容批——模板里每个战斗与 Boss 节点都必须在敌人与棋盘生成的数值表里有精确行，义务从冒险结构加关纪律的"每关一行集"细化到"每模板一行集"；冒烟覆盖义务同批扩为遍历池内全部模板校验，不只抽中的那张。 @@ -121,8 +121,8 @@ | # | 拍板点 | 状态 | |---|---|---| | ① | 第一关（教学关）是否参与抽签 | **已裁决（2026-09-27）**：参与——仅首次冒险走固定脚本，见「首次冒险的固定脚本」节 | -| ② | `node_map` 随机流增流 | 待复裁——证据面 A 给出释义与两选项（原荐 A） | -| ③ | 台阶一实施时点 | 待复裁——证据面 B 给出台阶一详解与三选项（原荐 C） | +| ② | `node_map` 随机流增流 | **已裁决（2026-09-27 两轮复裁）**：统一用一个流——全游戏 rng 架构批先行（评估书 [ADR-0007](../../../dev/architecture/adr-0007-rng-single-stream.md)），本特性实施排队其后 | +| ③ | 台阶一实施时点 | **已裁决（2026-09-27）**：机制先行骨架随后——特性内先落抽签机制（池暂 N=1 行为零变化）、骨架内容批随后扩池；整体仍排在架构批落地之后 | | ④ | 首版池规模 | **已裁决（2026-09-27）**：每关 5 张起步（调参表已投值） | | ⑤ | 抽签时点 = 关卡开始逐关抽 | **已裁决（2026-09-27）**：确认 | @@ -137,6 +137,8 @@ | A 增流（原荐） | 清单加 `node_map` 栏，抽签独立记账 | 三件套成本；图的抽签可独立复现，与其它系统零耦合 | | B 借现有流 | 从某条现有流取号 | 省三件套；但这笔账和那个系统的账搅在一起——重放对方系统的随机序列会被抽签挤位，复现口径变含糊，不推荐 | +**裁决注记（2026-09-27）**：用户两轮复裁后终选「统一用一个流」（全面执行），执行路径 = 全游戏 rng 架构批先行、本特性排队其后。评估书已交付：[ADR-0007](../../../dev/architecture/adr-0007-rng-single-stream.md)——核心发现：字面目标「单一随机源、逐位可复现」现行架构已满足（七条流系同一主种子的七个盐值分栏而非七个随机源）；待裁决项 = 是否进一步并掉分栏计数器（方案甲维持分栏 / 乙物理并流 / 丙并流+全事件日志）。 + #### 证据面 B：台阶一详解与实施时点（拍板点③的背景） 台阶一（图模板抽签）落地后的样子： @@ -169,6 +171,8 @@ ## P0 最小闭环（台阶一实施批） +> 实施前置：全游戏随机流统一架构批（[ADR-0007](../../../dev/architecture/adr-0007-rng-single-stream.md)）裁决落地——抽签随机量的接入形态（第八栏增流 or 并流口径）随其结论定。 + 1. 关卡表逐关行扩模板池结构（承载归数据配置，schema 细节随实施批定）。 2. 池内全部模板加载期预校验（违规致命，fail-fast 不变）。 3. 存档域加「首次冒险已进行」布尔位：开始新冒险读标志（false = 首次脚本模式，全关零抽签取现行固定模板），冒险收束点置位（三结局同写，写入只在收束挂点）。 @@ -213,3 +217,4 @@ |---|---|---| | v0.1 | 2026-09-27 | **设计草案成文（立项批，用户拍板立项——06 条目「关卡内结构随机生成」随批改状态）**：概念三件套（图模板/模板池/图模板抽签，N=1 回滚档）、抽签时机（开始关卡内逐关抽、主种子派生 `node_map` 流提案）、三级台阶路线（抽签→属性随机→全程序）、MC 测量对账三条款（分层出数/基线可比/实施门=曲线调参批后）、五拍板点、依赖表与验收草案。实施未开工；术语入 registry 词汇表随定稿批执行 | | v0.2 | 2026-09-27 | **首轮裁决落文批（用户拍板①④⑤+路线确认）**：①第一关参与抽签、仅首次冒险走固定脚本——新增「首次冒险的固定脚本」节（存档域布尔标志「首次冒险已进行」、收束点置位、边界与测量口径，P0/验收/依赖表同步）；④首版池规模=每关 5 张（调参表投值）；⑤抽签时点确认；用户并裁「骨架不完全固定、多份随机调取」= 台阶一路线确认（台阶节补白话块+教学位随骨架走注记）。②③补证据面待复裁——新增「拍板点证据面」节：A=随机流/增流白话释义+两选项；B=台阶一详解（玩家看到什么/做三件/不做两件/内容形态 15 骨架/遭遇表按编号共用约束）+实施时点三选项（A 立即全上/B 等调参批/C 机制先行骨架随后，荐 C）；测量对账实施门条款同步改"随机量扩池守门、机制可先行"口径 | +| v0.3 | 2026-09-27 | **②③终裁落文批（用户两轮复裁）**：②统一用一个流·全面执行——全游戏 rng 架构批先行（[ADR-0007](../../../dev/architecture/adr-0007-rng-single-stream.md) 评估书交付：核心发现=七流系同一主种子的盐值分栏、字面目标现行已满足；待裁决=甲维持分栏/乙物理并流/丙并流+全事件日志），本特性实施排队其后（P0 补前置行、抽签节流形态改随 ADR 结论）；③特性内机制先行骨架随后（池暂 N=1、骨架内容批扩池）；证据面 A 补裁决注记。06 新立「全游戏随机流统一架构批」条目（数据配置节） |