refactor: production 解散+docs 并入 design+tests 归 game 三层收敛——active.md/roadmap/stage/review-mode 升根目录;qa 报告→design/qa(gate-checks/alpha 验收/任务书→research);docs/→design/dev+registry 并档+散提案→research;tests/→game/tests(空架子 README+示例,真测试在 game/smoke);game/tools→tools+样例输出→sim-data;qa-data→sim-data;design/ux→gdd/ux;删 loop-dashboard.html(可再生成)+route_overlay_preview(零引用);钩子三件+loop_dashboard/balance_verifier/render_sample_sheet 路径随迁;断链修复 12 文件,余 7 条全为搬前幽灵链
This commit is contained in:
DKChan committed
1 parent
97e20d51fb
commit
7f24b640ea
179 files changed
+81
-579
No files matched your search
@@ -0,0 +1,129 @@
|
||||
# ADR-0001: 事件总线与编排载体（Event Bus & Orchestration Carrier）
|
||||
|
||||
## Status
|
||||
Accepted（2026-09-12，solo 模式用户授权代决；用户迭代期可随时推翻重议——推翻时须走本 ADR 修订 + 下游 AC 连锁复核）
|
||||
|
||||
## Date
|
||||
2026-09-12
|
||||
|
||||
## Engine Compatibility
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Engine** | Godot 4.7.2-stable |
|
||||
| **Domain** | Core / Scripting（Signal/Callable/生命周期） |
|
||||
| **Knowledge Risk** | LOW（4.x 基线稳定；4.5–4.7 变更清单零命中，godot-specialist 校验通过） |
|
||||
| **References Consulted** | `docs/engine-reference/godot/`（VERSION / breaking-changes / deprecated-apis / current-best-practices）；godotengine/godot#6360 |
|
||||
| **Post-Cutoff APIs Used** | None |
|
||||
| **Verification Required** | None（切片 88/88 冒烟已实证：双源 round_end 汇聚、可回放步骤流） |
|
||||
|
||||
## ADR Dependencies
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Depends On** | None |
|
||||
| **Enables** | ADR-0003（场景结构引用本 ADR 的接线纪律）；A2/B1 全部事件序类 AC 从纸面契约转为可执行 |
|
||||
| **Blocks** | 正式工程骨架搭建（架构文档 Required ADRs 条件） |
|
||||
| **Ordering Note** | 与 ADR-0008（切片机制正式化）并行无冲突；B1 结算触发语义以本 ADR 载体承载 |
|
||||
|
||||
## Context
|
||||
|
||||
### Problem Statement
|
||||
A2（三事件外发）、A3（stopped 直发 round_end，双发射源）、B1（结算触发 = Waiting 相位编排点、不依赖事件到达序）之间的信号载体需要一个落地形态——GDD 层只定行为契约（A2 OQ2 / B1 OQ1 均登记为"实现期 ADR 确认项"）。
|
||||
|
||||
### Constraints
|
||||
- 单线程回合制（D2 EC13）；Core 层零 UI 依赖、headless 可跑（D2 Rule 7）
|
||||
- 结算可回放是硬承诺（B1 Core Rule 15：禁 await、零随机）
|
||||
- 事件序契约：`flag_judged` < `round_end` 全路径统一，但到达序不承载语义
|
||||
- RefCounted 纯逻辑类无场景表示，无法在 .tscn 编辑器里对接信号
|
||||
|
||||
### Requirements
|
||||
- 支持 A2 三事件面 + A3 stopped 直发的双发射源汇聚
|
||||
- 支持多订阅者（B1 facts 缓冲；呈现层只订 B1/runner）
|
||||
- 测试可捕获事件序列（A2/B1 AC 的事件捕获断言面）
|
||||
- 生命周期确定（无悬挂连接、无循环引用）
|
||||
|
||||
## Decision
|
||||
|
||||
**组合根直连 signal 接线 + B1 Waiting 相位触发；否决 autoload 全局事件总线。**
|
||||
|
||||
1. **信号载体**：A2（RefCounted）声明并发射 GDD 三事件——`cell_revealed` / `flag_judged` / `round_end_board`（GDD 概念名 `round_end` 棋盘路径的实现实名）；A3 停手路径发射 `round_end_stopped`（payload 与棋盘路径同构）。回发 `next_round_mode` / `battle_over` 同为 A3/B1 侧 signal。
|
||||
2. **接线位置**：全部 signal.connect 发生在**组合根**（主场景 Node 的装配代码）——core↔core 无静态耦合，依赖单向由接线拓扑保证。RefCounted 无 .tscn 编辑器对接能力，组合根是唯一自然落点。
|
||||
3. **B1 触发**：订阅 A3 相位变更（→Waiting）触发结算事务；触发判定只读 A3 相位观测量与 `last_round_end`，**不消费事件到达序**（同步发射 + 双发射源的正确防御—— specialist 确认信号为同步发射、多订阅者投递序 = 连接序 FIFO）。
|
||||
4. **订阅纪律**：呈现层**永不直接订阅 A2/A3**——只订 B1 步骤流 / runner（切片现状固化，防呈现层绕过编排读核心生命周期状态——切片缺陷②教训）。
|
||||
|
||||
### Architecture Diagram
|
||||
|
||||
```
|
||||
[A2 minesweeper_rules]──cell_revealed/flag_judged/round_end_board──┐
|
||||
[A3 action_economy]────round_end_stopped / phase→Waiting──────────┤
|
||||
▼
|
||||
[组合根 main 装配接线]→[B1 battle_orchestrator]
|
||||
│ 步骤流行协议
|
||||
▼
|
||||
[D1 视图单元（只订 B1/runner）]
|
||||
```
|
||||
|
||||
### Key Interfaces
|
||||
|
||||
- 信号均为 **方法 Callable 连接**（见禁令）；信号参数带类型标注仅作文档，无运行时检查——payload 校验由消费侧断言承载（A2 AC 前言口径）。
|
||||
- A2 事件捕获测试 API：冒烟经 signal connect 到捕获数组（AC 前言"事件捕获断言面"的落地形态）。
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### Alternative 1: autoload 全局事件总线
|
||||
- **Description**: 中心 autoload 单例持有全部具名信号，系统经总线收发。
|
||||
- **Pros**: 解耦发射者/订阅者；全局可发现。
|
||||
- **Cons**: 全局耦合（任何系统可达任何信号——与"依赖单向"原则冲突）；单线程回合制无此需求；事件溯源变难。
|
||||
- **Rejection Reason**: 过度设计；切片直连形态已验证且更简单。
|
||||
|
||||
### Alternative 2: 轮询（B1 每帧查 A3 相位）
|
||||
- **Description**: B1 在 process 中轮询 A3 相位观测量。
|
||||
- **Cons**: 延迟（帧粒度）+ 空转；与"回合制无逐帧玩法逻辑"原则冲突。
|
||||
- **Rejection Reason**: 无收益；信号已同步即时。
|
||||
|
||||
### Alternative 3: 回调注册表（A2 持有 handler 列表）
|
||||
- **Description**: A2 暴露 register(handler) API，非 signal。
|
||||
- **Cons**: 非 GDScript 惯用；多订阅者接线繁琐；丢掉引擎信号工具链（.tscn 对接、调试器可视）。
|
||||
- **Rejection Reason**: signal 即本用途的引擎原生方案。
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
- 事件生命周期**确定性优于 Node 方案**：RefCounted 引用计数归零即双向自动断连，无 queue_free 帧末窗口（specialist 核实）——不存在"向半死对象发射"
|
||||
- 组合根接线使依赖方向可视化、可审计；切片 88/88 已验证
|
||||
|
||||
### Negative
|
||||
- 组合根承担全部接线职责——视图单元增多时接线代码线性增长（切片 main.gd 433 行已容纳；演进为装配器函数分组即可）
|
||||
- 信号同步发射的再入语义需实现者理解（本 ADR 的"不依赖到达序"即防御）
|
||||
|
||||
### Risks
|
||||
- **lambda 捕获 self 的循环引用**：GDScript lambda 捕获持强引用——短命 RefCounted 以捕获 self 的 lambda 连到长命发射者会延长生命周期乃至成环，自动断连永不触发 → **缓解（固化为本 ADR 静态规则）**：core↔core 信号连接只许方法 Callable；发射者禁止持有对订阅者的反向引用
|
||||
- 信号参数无运行时类型检查 → 缓解：消费侧断言（既有 AC 口径）+ 呈现载荷 schema 成文义务（code-conventions）
|
||||
|
||||
## GDD Requirements Addressed
|
||||
|
||||
| GDD System | Requirement | How This ADR Addresses It |
|
||||
|------------|-------------|--------------------------|
|
||||
| a2-minesweeper-rules.md | Core Rule 2 三事件回边契约（发射面封闭）；OQ2 事件外发载体 | signal 载体 + 实名映射（round_end→round_end_board）+ 组合根接线；捕获 API 承载 AC 断言面 |
|
||||
| b1-settlement.md | Core Rule 2 结算触发 = Waiting 相位编排点；OQ1 事件总线载体 | 订阅 A3 相位触发、只读 last_round_end、不依赖到达序 |
|
||||
| a3-action-economy.md | Rule 9 round_end 双发射源（stopped 直发、payload 同构） | round_end_stopped 独立信号，同构 payload 由组包纪律保证 |
|
||||
| systems-index.md | 唯一回边裁决（A2 只外发、B4/B1 订阅） | 组合根接线拓扑 = 裁决的落地形态 |
|
||||
|
||||
## Performance Implications
|
||||
- **CPU**: 信号发射 = 同步调用链，回合制下每事务个位数次发射——可忽略
|
||||
- **Memory**: 方法 Callable 弱引用目标、不延长生命周期；lambda 禁令消除成环风险
|
||||
- **Load Time**: 无
|
||||
- **Network**: 不适用
|
||||
|
||||
## Migration Plan
|
||||
切片即本决策的实现（`core/minesweeper_rules.gd` 三信号、`action_economy.gd` round_end_stopped、`battle_orchestrator.gd` 双源汇聚）——无迁移，正式化 = 把接线纪律与静态规则写入扫描域（ADR-0004）。
|
||||
|
||||
## Validation Criteria
|
||||
- A2/B1 冒烟事件捕获断言面全绿（既有 88 条覆盖）
|
||||
- 静态扫描：core↔core 连接零 lambda；发射者零反向引用（ADR-0004 扫描域承载）
|
||||
- 回放确定性：同种子同输入步骤流逐行相同（B1 AC-33 先例，切片已证）
|
||||
|
||||
## Related Decisions
|
||||
- ADR-0003（场景结构与组合根）、ADR-0004（测试载体与静态扫描域）
|
||||
- docs/architecture/architecture.md（Data Flow §2 事件路径）
|
||||
@@ -0,0 +1,119 @@
|
||||
# ADR-0002: 渲染器与窗口配置（Renderer & Window Config）
|
||||
|
||||
## Status
|
||||
Accepted（2026-09-12，solo 模式用户授权代决；迭代期可推翻重议）
|
||||
|
||||
## Date
|
||||
2026-09-12
|
||||
|
||||
## Engine Compatibility
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Engine** | Godot 4.7.2-stable |
|
||||
| **Domain** | Rendering |
|
||||
| **Knowledge Risk** | MEDIUM（渲染域为 4.5–4.7 变更集中地——本 ADR 相关项已逐条核实，godot-specialist 校验通过） |
|
||||
| **References Consulted** | `docs/engine-reference/godot/`（四文件）；Godot 4.3 release notes（Compatibility 特性补齐）；Godot Docs Environment and post-processing |
|
||||
| **Post-Cutoff APIs Used** | None |
|
||||
| **Verification Required** | 首次正式导出时核对 gl_compatibility 在目标硬件清单上的实际表现（首次 release 导出 checklist 既有项） |
|
||||
|
||||
## ADR Dependencies
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Depends On** | None |
|
||||
| **Enables** | ADR-0003（工程骨架的 project.godot 基线）；D1 正式化 |
|
||||
| **Blocks** | 正式工程骨架搭建 |
|
||||
| **Ordering Note** | B5 战斗表现若需 HDR 2D 届时复议（见 Risks） |
|
||||
|
||||
## Context
|
||||
|
||||
### Problem Statement
|
||||
technical-preferences 将渲染器选择（Forward+ vs gl_compatibility）登记为实现期 ADR；project.godot 的窗口/stretch 基线需要显式定稿——4.7 新项目默认值与训练数据不同（stretch mode canvas_items / aspect expand / Windows 驱动 D3D12），必须显式落盘防漂移。
|
||||
|
||||
### Constraints
|
||||
- 2D 回合制；draw calls < 200 预算；无 3D、无移动端
|
||||
- headless 测试链路不初始化渲染器（dummy DisplayServer）——测试与渲染器解耦
|
||||
- 引擎知识 MEDIUM 风险：渲染域选型必须基于已核实清单
|
||||
|
||||
### Requirements
|
||||
- 满足视觉锚（数字可读性、双通道、绘制优先级）所需的渲染能力
|
||||
- PC（Steam）硬件门槛尽量低
|
||||
- project.godot 各键显式写入（防未来 config_version 升级漂移）
|
||||
|
||||
## Decision
|
||||
|
||||
**渲染器 = gl_compatibility；窗口基座 1280×800（切片已验证值）、stretch mode = canvas_items、aspect = expand；全部键显式写入 project.godot。**
|
||||
|
||||
```ini
|
||||
rendering/renderer/rendering_method="gl_compatibility"
|
||||
rendering/renderer/rendering_method.mobile="gl_compatibility" ; PC 无关，显式对齐防混淆
|
||||
display/window/size/viewport_width=1280
|
||||
display/window/size/viewport_height=800
|
||||
display/window/stretch/mode="canvas_items"
|
||||
display/window/stretch/aspect="expand"
|
||||
; display/window/dpi/allow_hidpi —— 4.x 默认 true，无需写入（勿关闭）
|
||||
```
|
||||
|
||||
- **否决 Forward+**：2D 重 UI 无收益；4.6 起 Windows 新项目 D3D12 默认只作用于 Vulkan 系（Forward+/Mobile）——选 gl_compatibility（OpenGL 3.3）**完全绕开 D3D12 新驱动线**，这是 MEDIUM 风险域里的降险选择；GPU 门槛最低。
|
||||
- **stretch/aspect 与 4.7 新项目默认一致**（canvas_items/expand）——仍显式落盘，防引擎默认未来变化。
|
||||
- **基座 1280×800** = 切片验证值（非引擎默认 1152×648，亦非本 ADR 初稿设想的 1920×1080）；expand 使 16:9 全屏显示正常适配，D1 正式化时如需调整走本 ADR 修订。
|
||||
|
||||
### Architecture Diagram
|
||||
（不适用——配置决策；headless dummy DisplayServer 与本决策完全解耦，冒烟链路不受影响）
|
||||
|
||||
### Key Interfaces
|
||||
- project.godot 键集如上（显式全落盘）；渲染器相关代码面 = CanvasItem/Control 绘制（三渲染器共用管线，重 UI 场景 Compatibility 开销最低——specialist 核实）。
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### Alternative 1: Forward+（Vulkan/D3D12）
|
||||
- **Description**: 4.7 新项目默认渲染器。
|
||||
- **Pros**: HDR 2D、高级后处理全量可用。
|
||||
- **Cons**: 2D 回合制无收益；D3D12 为 4.6 起新默认驱动线（成熟度风险敞口）；GPU 门槛更高。
|
||||
- **Rejection Reason**: 零收益 + 增加风险敞口；B5 若需 HDR 2D 届时复议。
|
||||
|
||||
### Alternative 2: 沿用引擎新项目默认不显式配置
|
||||
- **Cons**: 渲染方法默认 forward_plus；基座默认 1152×648 与切片验证值不符；未来 config_version 升级可能漂移。
|
||||
- **Rejection Reason**: 违背"显式落盘防漂移"要求。
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
- 绕开 D3D12 驱动线与 Vulkan 门槛——MEDIUM 风险域降险
|
||||
- headless 测试与渲染器解耦（已核实），CI 零 GPU 依赖
|
||||
- **B5 复议空间存在**：Compatibility 自 4.3 起已支持 2D 灯光+阴影与 glow/bloom——多数 2D 表现需求无需离开本渲染器
|
||||
|
||||
### Negative
|
||||
- 无 HDR 2D（Forward+/Mobile 专属）；glow 实现不同且部分属性隐藏——B5 视觉上限受此约束
|
||||
- Compatibility 已知渲染问题两条登记（GH-110670 HDR2D+tonemap glow 压暗 / GH-90259 开阴影灯光变亮）——B5 采用相关特性时核对
|
||||
|
||||
### Risks
|
||||
- B5 需要超出现有能力的表现 → 缓解：复议通道 = 本 ADR 修订（迁移成本 2D 项目可控）
|
||||
- OpenGL 3.3 在极旧硬件的覆盖 → 缓解：目标平台 PC Steam 主流硬件；首次导出 checklist 核对
|
||||
|
||||
## GDD Requirements Addressed
|
||||
|
||||
| GDD System | Requirement | How This ADR Addresses It |
|
||||
|------------|-------------|--------------------------|
|
||||
| technical-preferences.md | Renderer 选择留实现期 ADR；draw calls < 200 | gl_compatibility + 自绘/控件混合渲染在此预算内宽裕 |
|
||||
| game-concept.md | 视觉锚三条硬约束 | canvas_items stretch 保证数字缩放清晰；Compatibility 2D 管线满足绘制优先级栈 |
|
||||
| d2-data-config.md | Rule 7 headless 工程债 | dummy DisplayServer 与渲染器解耦（已核实） |
|
||||
|
||||
## Performance Implications
|
||||
- **CPU**: Compatibility 2D 管线开销最低（重 UI 场景——specialist 核实）
|
||||
- **Memory**: 三渲染器中最低
|
||||
- **Load Time**: 无差异
|
||||
- **Network**: 不适用
|
||||
|
||||
## Migration Plan
|
||||
切片 project.godot 已写 gl_compatibility——正式工程直接继承；补齐基座尺寸与 stretch 键显式落盘。
|
||||
|
||||
## Validation Criteria
|
||||
- draw calls 实测 < 200（D1 集成时用编辑器 profiler 核对）
|
||||
- 16:9 全屏 / 窗口两种形态下数字可读性目检（视觉锚 1）
|
||||
- headless 冒烟不受渲染器影响（88/88 维持）
|
||||
|
||||
## Related Decisions
|
||||
- ADR-0003（场景结构——project.godot 同批落盘）、ADR-0010（B5 战斗舞台，未立项）
|
||||
- docs/engine-reference/godot/current-best-practices.md §1（新项目默认值差异）
|
||||
@@ -0,0 +1,139 @@
|
||||
# ADR-0003: 场景结构与棋盘渲染（Scene Structure & Board Rendering）
|
||||
|
||||
## Status
|
||||
Accepted（2026-09-12，solo 模式用户授权代决；迭代期可推翻重议）
|
||||
**部分修订（2026-09-23）**：Decision 3 棋盘渲染形态条款由 [ADR-0006](adr-0006-board-node2d-rendering.md) 部分取代——棋盘本体定向迁 Node2D 渲染（D 区 Phase A 先行，B 区舞台后续批），「禁盲目迁移」条款解除，其登记的探针耦合成本转为迁移批义务（实证收敛为 `_cells` 键面 + `click_cell` + `cell_size` 三点，公共面契约保持即可零改造）。Alternative 2（逐格 Node2D）的否决理由「无必要」因表现层升级需求不再成立；autoload 清单、类形态、CJK 字体前置等其余条款不变。
|
||||
|
||||
## Date
|
||||
2026-09-12
|
||||
|
||||
## Engine Compatibility
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Engine** | Godot 4.7.2-stable |
|
||||
| **Domain** | Core / Scripting + UI |
|
||||
| **Knowledge Risk** | LOW-MEDIUM（结构决策 LOW；渲染呈现项 MEDIUM——CanvasItem 线条 AA 羽化移除已核实，godot-specialist 校验含 2 项实质修正后通过） |
|
||||
| **References Consulted** | `docs/engine-reference/godot/`（四文件）；godotengine/godot#6360（--script 无 autoload） |
|
||||
| **Post-Cutoff APIs Used** | None |
|
||||
| **Verification Required** | CJK 字体随包发行的显示核对（首次正式导出 checklist 增补项）；D1 正式化时若执行 _draw 迁移则另核命中测试/无障碍 |
|
||||
|
||||
## ADR Dependencies
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Depends On** | ADR-0001（组合根接线纪律）、ADR-0002（project.godot 基线同批落盘） |
|
||||
| **Enables** | 正式工程骨架搭建；D1 正式化 |
|
||||
| **Blocks** | ADR-0004 扫描域（引用本 ADR 的 core 隔离规则） |
|
||||
| **Ordering Note** | 棋盘渲染形态裁决（本 ADR §Decision 3）与 ADR-0004 探针耦合——见 Decision 3 的迁移工作项 |
|
||||
|
||||
## Context
|
||||
|
||||
### Problem Statement
|
||||
正式工程骨架需要定稿：autoload 清单、core/presentation 的类形态与目录结构、棋盘渲染的实现路径。切片已验证一套形态，但初稿 ADR 把"自绘 _draw()"当作切片事实——godot-specialist 校验发现切片 BoardView 实为 **GridContainer + 逐格常驻控件**，本 ADR 按校验修正。
|
||||
|
||||
### Constraints
|
||||
- Core 层零 UI 依赖、headless 可跑（D2 Rule 7）；--script 模式下 core 禁裸引用 autoload 全局标识符（编译期即炸——见 ADR-0004）
|
||||
- 同屏 draw calls < 200；棋盘 ≤12×12（MVP 量级）＋数字/小人/旗/变异多层叠加（视觉锚绘制优先级栈）
|
||||
- 领域命名规范（docs/code-conventions.md：禁 ID 前缀、头注溯源）
|
||||
|
||||
### Requirements
|
||||
- 切片验证过的结构不推倒（用户拍板"按常规老路子"）
|
||||
- 呈现层与核心的写边界：核心写调用唯一发生在组合根
|
||||
- 中文文案可显示（运行时默认字体无 CJK 字形——specialist 核实）
|
||||
|
||||
## Decision
|
||||
|
||||
**1. autoload 清单 = {ConfigDB, RngService}（定名锁定），仅此两个。**
|
||||
战斗编排器等核心类为普通类、由组合根按局实例化——非 autoload、非场景节点。
|
||||
|
||||
**2. 类形态与目录结构：core/ 纯逻辑类 = RefCounted；ConfigDB/RngService = autoload Node 单例（引擎约束：autoload 脚本必须 extends Node）；presentation/ = Control 派生视图单元。**
|
||||
|
||||
```
|
||||
res://
|
||||
├── core/ # RefCounted 纯逻辑（board_generator / minesweeper_rules /
|
||||
│ # action_economy / battle_orchestrator / unit_container /
|
||||
│ # status_container / reward_economy / level_runner / 数据类）
|
||||
│ # —— 零 Control 引用、零 .tscn preload、零 autoload 全局标识符裸引用
|
||||
├── data/
|
||||
│ ├── schemas/ # D2 schema 类（Resource 派生——D2 体系，非本 ADR 变更项）
|
||||
│ └── tables/ # .tres 数值表（单一事实源）
|
||||
├── presentation/
|
||||
│ ├── views/ # 九单元：BoardView / HUDView / BattleLogView / ItemWindowOverlay /
|
||||
│ │ # NodeOverlay / LevelStripView / TunePanel / UiKit
|
||||
│ ├── hud_presenter.gd
|
||||
│ └── main.tscn + main.gd # 组合根：模式流转 + 信号接线 + 核心写调用唯一落点
|
||||
├── smoke/ # 冒烟脚本 + 探针场景（ADR-0004）
|
||||
└── docs/architecture/
|
||||
```
|
||||
|
||||
**3. 棋盘渲染形态：MVP 沿用切片已验证形态——GridContainer + 逐格常驻控件（BoardView 持 `_cells`，refresh 内逐格更新）；自绘 `_draw()` 迁移登记为 D1 正式化候选工作项（非本 ADR 承诺）。**
|
||||
|
||||
- specialist 校验事实：切片 BoardView = GridContainer + 逐格 Button（`_paint_cell` 逐格更新），三探针与该形态耦合（ui_probe 断言 `_cells` 非空、click_probe 依赖 `click_cell` 入口）。初稿"_draw 是切片形态的正式化"**不成立**，按事实修正。
|
||||
- 形态对比留档：逐格控件（现状）= 命中测试/悬停/焦点由引擎承担、探针兼容；代价 = 控件树随格数增长（12×12=144 控件，实测无压力）。`_draw()` = 单 draw call、绘制优先级栈完全可控；代价 = 自建命中测试/悬停 + **三个探针改造**（`_cells` 断言与 `click_cell` 入口失效）+ 无障碍面缺失 + 需补 `Viewport.push_input` 端到端输入探针。
|
||||
- 裁决：D1 正式化 GDD 评审时按当时视觉需求（biome 色板、雾纹理、动效复杂度）二选一；在此之前禁盲目迁移（探针改造是隐藏成本）。任一形态下 CanvasItem 线条 AA 羽化移除（4.7）需注意——格边框用填充 `draw_rect` 不受影响。
|
||||
|
||||
**4. CJK 字体前置（specialist 补登，两种形态都受影响）**：Godot 运行时默认字体不含 CJK 字形——全部中文文案（按钮/标签/结算明细）必须**随包发行 CJK 字体并设为 theme 默认字体**。登记为 D1 正式化硬性前置项 + 首次导出 checklist 项。
|
||||
|
||||
### Architecture Diagram
|
||||
见 `docs/architecture/architecture.md` System Layer Map + Module Ownership（本 ADR 是其工程形态落点）。
|
||||
|
||||
### Key Interfaces
|
||||
- 组合根 = 唯一核心写调用落点（settle_batch / submit_window_selection / runner 推进）——切片纪律转正
|
||||
- 视图单元 = 信号外发 + setter 只读注入（BoardView 只读 A2、动作信号外发不碰核心写）
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### Alternative 1: 战斗编排器设为 autoload
|
||||
- **Cons**: 编排器持有跨局状态却永生——生命周期与战斗域契约冲突（Uninit/BattleOver 状态机要求按局重建）；与"autoload = 全局基础设施"边界冲突。
|
||||
- **Rejection Reason**: 切片形态（按局实例化）已验证且语义正确。
|
||||
|
||||
### Alternative 2: 棋盘 = 每格一个 Node2D
|
||||
- **Pros**: 独立节点动画/模组方便。
|
||||
- **Cons**: 每节点处理开销与 Control/Node2D 混管复杂度；无必要（specialist 指出 2D 同材质有批处理，draw call 论据最弱，但节点开销与混管论据成立）。
|
||||
- **Rejection Reason**: 逐格控件已覆盖需求且已验证。
|
||||
|
||||
### Alternative 3: TileMapLayer 承载棋盘
|
||||
- **Cons**: 4.5 物理分块默认变更（纯视觉不踩，但物理用途即触）；瓦片语义与"变体标记/数字/旗多层叠加"不匹配。
|
||||
- **Rejection Reason**: 语义不匹配是硬伤；现形态无此问题。
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
- 结构与切片零迁移成本；core 隔离规则可静态扫描（ADR-0004）
|
||||
- 棋盘形态留有 D1 期复议空间且复议成本已如实登记
|
||||
|
||||
### Negative
|
||||
- 逐格控件形态在 D1 需要高表现力时可能仍需迁移 _draw（成本已登记：探针改造 + 命中测试自建 + push_input 端到端探针）
|
||||
- CJK 字体为新增资产义务（发行体积 +）
|
||||
|
||||
### Risks
|
||||
- D1 正式化时遗漏"探针与形态耦合"约束 → 缓解：本 ADR Decision 3 + ADR-0004 探针节双登记
|
||||
- core 类被随手加 autoload 裸引用 → 缓解：ADR-0004 静态扫描（parse 期即炸的事实使该风险自暴露）
|
||||
|
||||
## GDD Requirements Addressed
|
||||
|
||||
| GDD System | Requirement | How This ADR Addresses It |
|
||||
|------------|-------------|--------------------------|
|
||||
| d2-data-config.md | Rule 7 零 UI 依赖；Rule 2 单点访问 | core 隔离规则 + autoload 清单固化（ConfigDB/RngService 定名） |
|
||||
| game-concept.md | 视觉锚（绘制优先级栈、双通道） | 棋盘形态两案对比留档，D1 正式化按锚需求裁决 |
|
||||
| b1-settlement.md | Core Rule 1 编排器按局生命周期 | 编排器非 autoload、组合根按局实例化 |
|
||||
| docs/code-conventions.md | 领域命名 / 组合根纪律 | 目录结构与 Key Interfaces 转正 |
|
||||
|
||||
## Performance Implications
|
||||
- **CPU**: 144 常驻控件逐格更新——切片实测无压力；_draw 迁移后更优（单 draw call）
|
||||
- **Memory**: 可忽略
|
||||
- **Load Time**: CJK 字体载入一次性成本
|
||||
- **Network**: 不适用
|
||||
|
||||
## Migration Plan
|
||||
切片即目标形态（结构零迁移）；CJK 字体接入与 _draw 复议归 D1 正式化批次。
|
||||
|
||||
## Validation Criteria
|
||||
- 冒烟 88/88 + 三探针在正式工程维持全绿
|
||||
- 静态扫描：core/ 零 Control extends / 零 .tscn preload / 零 autoload 全局标识符裸引用（ADR-0004 域）
|
||||
- 中文文案在导出包内显示正常（导出 checklist）
|
||||
|
||||
## Related Decisions
|
||||
- ADR-0001（接线纪律）、ADR-0002（渲染器与窗口键）、ADR-0004（扫描域与探针）
|
||||
- docs/architecture/architecture.md（Module Ownership / Required ADRs——本 ADR 落定后其 §Required ADRs 第 3 项闭合）
|
||||
@@ -0,0 +1,132 @@
|
||||
# ADR-0004: 测试载体与 CI（Test Carrier & CI）
|
||||
|
||||
## Status
|
||||
Accepted（2026-09-12，solo 模式用户授权代决；迭代期可推翻重议）
|
||||
|
||||
## Date
|
||||
2026-09-12
|
||||
|
||||
## Engine Compatibility
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Engine** | Godot 4.7.2-stable |
|
||||
| **Domain** | Core / Scripting（测试与工具链） |
|
||||
| **Knowledge Risk** | LOW（--script/探针模式为 4.x 基线；godot-specialist 校验通过，含两条规则升格） |
|
||||
| **References Consulted** | `docs/engine-reference/godot/`（四文件）；godotengine/godot#6360（--script 模式不加载 autoload + 不注册全局标识符——官方立场） |
|
||||
| **Post-Cutoff APIs Used** | None |
|
||||
| **Verification Required** | None（切片 88/88 + 三探针已实证；CI 外部超时在正式 CI 接入时核对） |
|
||||
|
||||
## ADR Dependencies
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Depends On** | ADR-0003（core 隔离规则是扫描域的输入） |
|
||||
| **Enables** | 全部 GDD AC 的可执行化；正式 CI 接入 |
|
||||
| **Blocks** | `/gate-check` 前置项之一（`/test-setup` 以本 ADR 为基线） |
|
||||
| **Ordering Note** | gdUnit4 复议登记为 D2 OQ1 的关闭形态（推迟，非否决） |
|
||||
|
||||
## Context
|
||||
|
||||
### Problem Statement
|
||||
D2 GDD 定下 `--headless --script` 冒烟载体（脚本 extends SceneTree、autoload 显式实例化），D2 OQ1 留下"gdUnit4 是否引入"待决；切片新增了场景级 UI 探针形态；项目级静态扫描域散落在各 GDD AC（AC-9/17/21/22/43 等）需要一处统一登记。
|
||||
|
||||
### Constraints
|
||||
- headless 全套 < 30s 预算（technical-preferences）
|
||||
- 致命类用例独立进程协议（"调用 → 期望退出码" runner manifest，D2 AC-2b 起）
|
||||
- 呈现层测试必须有承载（切片教训：已定稿 AC 全覆盖 core、呈现层零测试承载 → 缺陷 ①②④⑤ 漏网）
|
||||
|
||||
### Requirements
|
||||
- 双模式边界明确：逻辑冒烟（无 autoload）vs 场景探针（完整项目引导）
|
||||
- 静态扫描规则统一载体，覆盖 D2/A1–B4 各 AC 登记的扫描项
|
||||
- CI 可接入且防挂死
|
||||
|
||||
## Decision
|
||||
|
||||
**双载体 + 统一静态扫描域；gdUnit4 推迟到正式 CI 期。**
|
||||
|
||||
**1. 逻辑冒烟（`--headless --script`）**：脚本 extends SceneTree 以获得 `quit(code)`；ConfigDB/RngService 由脚本显式实例化（引擎事实：--script 模式**不加载 autoload 且不注册全局标识符**——裸引用 = parse error 编译期即炸，GH #6360 官方确认）。Windows 用 console 版 exe 取 stdout。承载：D2/A1–B4 全部纯逻辑 AC + 致命类独立进程 manifest。
|
||||
|
||||
**2. 场景探针（headless 跑 .tscn 探针场景）**：以探针场景为运行目标（`godot --headless --path . res://smoke/<probe>.tscn`）走正常项目引导——autoload 在位、真实 SceneTree、`await process_frame` 有效。承载：呈现层场景级测试（切片三探针 ui_probe / ui_click_probe / ui_tune_probe 为先例）。
|
||||
- **口径修正（specialist 校验）**：click_probe 走 `BoardView.click_cell` 是"真实翻译出口"，**绕过 Viewport GUI 管线**（无命中测试/悬停/焦点）。表述定为"合成输入走真实翻译出口"；真正的端到端输入测试 = `Input.parse_input_event()` / `Viewport.push_input` 带坐标——若 ADR-0003 的 _draw 迁移执行（Button 命中测试消失），push_input 探针从加分项变为**必需项**（登记入迁移工作项）。
|
||||
|
||||
**3. 项目级静态扫描域（统一登记，CI 与冒烟前置双跑）**：
|
||||
|
||||
| # | 规则 | 来源/动机 |
|
||||
|---|---|---|
|
||||
| S1 | 玩法代码禁 `randomize()`、自建 `RandomNumberGenerator` | D2 Rule 5（既有） |
|
||||
| S2 | **禁全局随机函数 `randi()` / `randf()` / `randf_range()`**（全局 RNG 绕开 RngService——specialist 补登漏洞） | D2 Rule 5 补全 |
|
||||
| S3 | core/ 禁 ConfigDB 外 data 表加载（`load(` / `preload(` / `ResourceLoader.load`；schema class_name 直引豁免） | D2 Rule 2（既有） |
|
||||
| S4 | core/ 禁 `extends Control/Node2D`、禁 `.tscn` preload | D2 Rule 7（既有） |
|
||||
| S5 | **core/ 禁裸引用 autoload 全局标识符**（`ConfigDB` / `RngService` 直接写 = script 模式 parse error）——构造注入 only | specialist 升格（切片已合规，规则防复发） |
|
||||
| S6 | core↔core 信号连接只许方法 Callable（禁 lambda 捕获 self）；发射者禁持有订阅者反向引用 | ADR-0001（防循环引用/生命周期延长） |
|
||||
| S7 | B1 编排唯一性：B2/B3/B4 API 符号命中文件 ⊆ B1 文件集；A2/B3/B4 零相互直调 | B1 AC-43（既有） |
|
||||
| S8 | 结算路径 `await` 零命中（B1 结算/编排文件集）；字面量扫描 = warning 级 + 人工三要素复核（D2 AC-14 口径） | B1（既有） |
|
||||
|
||||
**4. CI 防挂死**：任何探针/冒烟调用旁必须配**外部 wall-clock 超时**（命令行 timeout）——引擎自身无死锁探测；探针内 30 帧停滞检测（click_probe 先例）是第一道、外部超时是最后防线。headless 全套 < 30s 预算不变。
|
||||
|
||||
**5. gdUnit4：推迟到正式 CI 期再议**（D2 OQ1 以"deferred"关闭）。它运行在项目模式（autoload 在位），与 SceneTree 冒烟机制正交，引入不废弃既有用例。
|
||||
|
||||
### Architecture Diagram
|
||||
|
||||
```
|
||||
提交 → [静态扫描 S1–S8（秒级）] → [逻辑冒烟 --script（独立进程 manifest，<30s）]
|
||||
→ [场景探针 ×N（headless + 外部超时）] → 全绿放行
|
||||
```
|
||||
|
||||
### Key Interfaces
|
||||
- 冒烟 runner manifest：条目 = "调用 → 期望退出码"（独立进程、游戏通道）——D2 AC-2b 协议延续
|
||||
- 探针退出码：0 = PASS；非 0 = 失败类别；停滞 quit(2)
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### Alternative 1: 立即引入 gdUnit4 并迁移全部冒烟用例
|
||||
- **Pros**: 标准 assertions/参数化/报告；编辑器面板。
|
||||
- **Cons**: 88 条用例迁移成本即刻发生；切片框架已验证且快（~3s）；MVP 期无 CI 基建需求。
|
||||
- **Rejection Reason**: 收益在 CI 期才兑现——推迟（非否决），D2 OQ1 关闭形态。
|
||||
|
||||
### Alternative 2: 仅保留逻辑冒烟、UI 靠人工
|
||||
- **Cons**: 切片缺陷 ①②④⑤ 全部漏过既有 AC 的教训直接否定——呈现层无承载 = 呈现层缺陷零防线。
|
||||
- **Rejection Reason**: 呈现层契约测试是 code-conventions 硬性要求。
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
- 双模式边界以引擎事实固化（parse 期炸 vs 完整引导），不再靠约定俗成
|
||||
- S2/S5/S6 三条 specialist 补登规则堵住静默翻车路径（全局随机绕开、裸引用编译炸、lambda 成环）
|
||||
- 呈现层探针形态沉淀为项目标配（code-conventions 承载）
|
||||
|
||||
### Negative
|
||||
- 静态扫描规则 8 条的维护成本（新规则须挂真实反面案例——code-conventions 纪律）
|
||||
- "真实 UI 路径"表述收窄后，端到端输入覆盖存在已知缺口（_draw 迁移前可接受）
|
||||
|
||||
### Risks
|
||||
- 未被停滞检测覆盖的死锁挂死 CI → 缓解：外部 wall-clock 超时为硬性要求
|
||||
- 扫描规则漏报（启发式）→ 缓解：行为级硬证据并行（可回放断言、headless 实跑合成判定——D2 AC-9/10 模式）
|
||||
|
||||
## GDD Requirements Addressed
|
||||
|
||||
| GDD System | Requirement | How This ADR Addresses It |
|
||||
|------------|-------------|--------------------------|
|
||||
| d2-data-config.md | Rule 6 校验双通道；AC-2b 独立进程协议；OQ1 gdUnit4 | 冒烟框架定稿；manifest 延续；OQ1 关闭为 deferred |
|
||||
| a1–b1 各 GDD | 各自静态扫描 AC（AC-9/17/18/19/21/22/43 模式） | S1–S8 统一登记为项目级域，各 AC 引用本 ADR |
|
||||
| docs/code-conventions.md | 场景探针标配 / 提交前全量 | 双载体 + CI 链路承载 |
|
||||
| b1-settlement.md | AC-43 编排唯一性单向扫描 | S7 载体 |
|
||||
|
||||
## Performance Implications
|
||||
- **CPU**: 全套冒烟 ~3s（切片实测），预算 <30s 富余
|
||||
- **Memory**: headless dummy server 极低
|
||||
- **Load Time**: 探针场景引导一次性
|
||||
- **Network**: 不适用
|
||||
|
||||
## Migration Plan
|
||||
切片 smoke/ 目录即载体（零迁移）；正式 CI 接入时补外部超时包装与 S1–S8 脚本化；`/test-setup` 以本 ADR 为基线脚手架。
|
||||
|
||||
## Validation Criteria
|
||||
- 冒烟 + 探针全绿为提交门（code-conventions"提交前全量"）
|
||||
- 扫描域脚本化后：新增违规案例必须先补扫描规则再修码（缺陷-规范对照表纪律）
|
||||
- `<30s` 预算在 CI 环境复核
|
||||
|
||||
## Related Decisions
|
||||
- ADR-0001（S6 规则来源）、ADR-0003（S4/S5 规则来源、探针形态耦合）
|
||||
- docs/code-conventions.md（缺陷-规范对照表）、各 GDD AC 前言（规范源）
|
||||
@@ -0,0 +1,104 @@
|
||||
# ADR-0005: 存档契约与版本化（Save Contract & Schema Versioning）
|
||||
|
||||
## Status
|
||||
Accepted（2026-09-12，solo 模式用户授权代决；轻量契约 ADR——实现归 D3 Alpha，本 ADR 只锁契约使 Foundation 层 TR 覆盖闭合）
|
||||
|
||||
## Date
|
||||
2026-09-12
|
||||
|
||||
## Engine Compatibility
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Engine** | Godot 4.7.2-stable |
|
||||
| **Domain** | Core（数据/序列化契约） |
|
||||
| **Knowledge Risk** | LOW（契约层； FileAccess/JSON 基线稳定） |
|
||||
| **References Consulted** | `docs/engine-reference/godot/`（四文件）；D2 GDD Rule 8 / EC9 / RNG 生命周期 |
|
||||
| **Post-Cutoff APIs Used** | None |
|
||||
| **Verification Required** | None（D3 实现期按契约验证） |
|
||||
|
||||
## ADR Dependencies
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Depends On** | None |
|
||||
| **Enables** | D3 存档序列化（Alpha）——契约先行，实现期免重议 |
|
||||
| **Blocks** | None |
|
||||
| **Ordering Note** | 清零 Foundation 层 TR 覆盖缺口（requirements-traceability.md 的最后两条 pending） |
|
||||
|
||||
## Context
|
||||
|
||||
### Problem Statement
|
||||
Technical Setup → Pre-Production 门要求"Foundation 层需求 ADR 覆盖零缺口"。63 条 TR 基线中 Foundation 层尚有两条无 ADR 承载：TR-d2-010（SCHEMA_VERSION 版本化）与 TR-gc-002（RNG 快照存续契约）。两者的契约在 D2 GDD 已定但散落，未 ADR 化——本 ADR 收拢，D3 Alpha 实现时照契约执行。
|
||||
|
||||
### Constraints
|
||||
- MVP 无元进度存档（C4/D3 归 Alpha）——本 ADR 不引入任何 MVP 实现
|
||||
- RNG 快照语义已被 D2 GDD（RNG 生命周期）与 B1 GDD（回放切点）锁定——本 ADR 只做契约归集，不改语义
|
||||
|
||||
### Requirements
|
||||
- 版本不匹配拒绝读取（高版本拒读，D2 EC9）
|
||||
- 续玩/复盘可从快照精确恢复随机序列
|
||||
- 快照切点与在飞流实例的互斥有明确归属
|
||||
|
||||
## Decision
|
||||
|
||||
**1. 版本化契约**：`SCHEMA_VERSION` 常量归 D2（既定）；存档文件携带该版本号；**比较逻辑归 D3**（D2 EC9 既有分工）——存档版本 > 当前 SCHEMA_VERSION → 拒绝读取 + 明确错误信息；低版本存档的迁移策略归 D3 Alpha 设计时定（候选：拒读 / 迁移器——届时另议，非本 ADR 范围）。
|
||||
|
||||
**2. RNG 快照契约（从 D2/B1 GDD 收拢为 ADR 登记）**：
|
||||
- 快照内容 = `master_seed` + 各封闭流 scope 计数器 + 意图序列 + 窗口选择序列
|
||||
- **切点规则**：快照切出必须发生在 scope 事件边界之外（无在飞 `open_stream` 实例时）；运行期 scope 事件边界 = board install（A1 取号 / B4 取号）——B1 编排保证无在飞实例跨界（消费侧遵守义务，B1 GDD 回放切点条款）
|
||||
- 违反后果：续玩/复盘与实况分叉（D2 AC-15 语义失效）——该前提由 D3 消费侧遵守，B1 侧编排义务已在位
|
||||
|
||||
**3. 存档内容归属预告（D3 Alpha 实现的输入清单，非本 ADR 决策）**：冒险结构（C2 域）、关卡进度（C1 域）、HP/库存（B1/B4 关卡域）、钥石/天赋（C4 MetaTable）、RAP 不持久（战斗域清零）。D3 GDD 立项时按此清单展开。
|
||||
|
||||
### Architecture Diagram
|
||||
（不适用——契约 ADR；数据流见 architecture.md §Data Flow 3）
|
||||
|
||||
### Key Interfaces
|
||||
- D3 → D2：读取 `SCHEMA_VERSION`（比较方向：存档版本 ≤ 当前才可读）
|
||||
- D3 → RngService：只读计数器接口（D2 已暴露）+ `set_master_seed`（仅 C2 调用——D3 只读快照、恢复时经 C2 重放接线）
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### Alternative 1: 不立 ADR，依赖 D2/D3 GDD 散落条款
|
||||
- **Cons**: gate 的 Foundation 零缺口检查失败；契约散落三处（D2 EC9 / D2 RNG 生命周期 / B1 回放切点），D3 实现时需跨三文档拼装。
|
||||
- **Rejection Reason**: 收拢成本一次会话内，收益是门检查全绿 + D3 立项输入就绪。
|
||||
|
||||
### Alternative 2: 现在就设计存档格式（JSON vs 二进制 vs Resource）
|
||||
- **Cons**: C4/D3 未设计，过早——MVP 无存档需求牵引。
|
||||
- **Rejection Reason**: 违背"schema 先行、数值回填"的项目节奏；格式决策留给 D3 GDD。
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
- Foundation 层 TR 覆盖零缺口（门检查全绿）
|
||||
- D3 立项时的硬输入就绪（版本比较方向、快照内容、切点规则、内容归属清单）
|
||||
|
||||
### Negative
|
||||
- 无（纯收拢，零新约束）
|
||||
|
||||
### Risks
|
||||
- D3 Alpha 实现时偏离切点规则 → 缓解：本 ADR + D2 AC-15 / B1 AC-34 双侧断言承载
|
||||
|
||||
## GDD Requirements Addressed
|
||||
|
||||
| GDD System | Requirement | How This ADR Addresses It |
|
||||
|------------|-------------|--------------------------|
|
||||
| d2-data-config.md | Rule 8 版本化；EC9 高版本拒读；RNG 快照生命周期 | 契约收拢 + 版本比较归属（D3）成文 |
|
||||
| b1-settlement.md | 回放切点契约（快照语义 = seed + 计数器 + 两类输入序列） | 切点规则 ADR 化（无在飞实例时切出，scope 边界 = board install） |
|
||||
| game-concept.md | 存档/冒险/关卡术语层级（C4/D3 Alpha 范围） | 存档内容归属预告清单 |
|
||||
|
||||
## Performance Implications
|
||||
- **CPU / Memory / Load Time / Network**: 无（MVP 零实现；Alpha 期存档体积预期 < 1MB 量级）
|
||||
|
||||
## Migration Plan
|
||||
无迁移（MVP 零实现）。D3 GDD 立项（Alpha 期）以本 ADR 为硬输入。
|
||||
|
||||
## Validation Criteria
|
||||
- D3 实现后：同快照恢复 → 随机序列逐位一致（D2 AC-15 / B1 AC-34 形态）
|
||||
- 版本不匹配路径拒绝读取且错误信息含两侧版本号
|
||||
- tests/integration/ 收录存档往返测试（D3 落地时）
|
||||
|
||||
## Related Decisions
|
||||
- ADR-0001（回放输入序列的载体）、ADR-0004（集成测试载体）
|
||||
- docs/architecture/requirements-traceability.md（TR-d2-010 / TR-gc-002 覆盖闭合）
|
||||
@@ -0,0 +1,141 @@
|
||||
# ADR-0006: 战斗棋盘 Node2D 渲染迁移（Board Node2D Rendering Migration）
|
||||
|
||||
## Status
|
||||
Accepted（2026-09-23 用户拍板方向；本 ADR 落文。Phase A 棋盘实施另批执行；B 区舞台迁移为后续批，本 ADR 只定分工不排期）
|
||||
部分取代 ADR-0003 Decision 3（形态条款定向 Node2D，「禁盲目迁移」解除；autoload 清单 / 类形态 / CJK 字体前置等其余条款不变）
|
||||
|
||||
## Date
|
||||
2026-09-23
|
||||
|
||||
## Engine Compatibility
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Engine** | Godot 4.7.2-stable |
|
||||
| **Domain** | UI / 棋盘渲染 |
|
||||
| **Knowledge Risk** | MEDIUM（SubViewport 内 theme 传播与像素缩放纹路两项待实施批实证；其余为已验证引擎面） |
|
||||
| **References Consulted** | `docs/engine-reference/godot/`；ADR-0003 Decision 3 形态对比留档；art-bible §8.2 画布暂定档 |
|
||||
| **Post-Cutoff APIs Used** | None |
|
||||
| **Verification Required** | SubViewport 内 CJK 字体显式注入核对（实施批）；分辨率两档装板校验（实施批） |
|
||||
|
||||
## ADR Dependencies
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Depends On** | ADR-0001（组合根接线纪律）、ADR-0002（渲染器与窗口键）、ADR-0003（场景结构与渲染形态——本 ADR 修订其 Decision 3） |
|
||||
| **Enables** | 表现层升级（B 区站桩 / 意图三档动画 / P3 演出需要 Node2D 载体）；美术终稿资产 1:1 换入的槽位体系 |
|
||||
| **Blocks** | 无（B 区舞台迁移为本 ADR 分工内的后续批，不阻塞他批） |
|
||||
| **Amends** | ADR-0003 Decision 3（逐格控件形态维持条款）与 Alternative 2（逐格 Node2D 否决——否决理由「无必要」因表现层升级需求不再成立，节点开销论据维持有效） |
|
||||
|
||||
## Context
|
||||
|
||||
### Problem Statement
|
||||
ADR-0003 Decision 3 将棋盘渲染冻结为「GridContainer + 逐格常驻控件」，并登记 _draw/自绘迁移为 D1 正式化候选、迁移前禁盲目动手（探针耦合是登记成本）。2026-09-23 用户拍板：表现层走 Node2D 重构，**只迁战斗棋盘**，开始菜单（ui_assembler build_start_overlay）与各覆盖层保持 Control——分工不是替换。原「禁盲目迁移」条款与现行裁决冲突，需要新 ADR 定向解禁并落分工边界。
|
||||
|
||||
### Constraints
|
||||
- 战斗屏四区布局与分区尺寸是 HUD框架 结构冻结项——本迁移只换渲染技术，四区结构、双舞台常驻、尺寸表零改动（战斗屏进度条退场与四区→三区重排由停点前移批按文档修订流程另行落地，与本批解耦）
|
||||
- 组合根纪律（ADR-0001）：核心写调用唯一落点不变；BoardView 信号外发 + 只读注入模式不变
|
||||
- 性能预算（HUD框架 引用值）：同屏 draw calls < 200；进入战斗屏 500ms 内首格可点
|
||||
- 美术终稿资产全部缺位（样张批未跑）——迁移必须以程序化占位服役为前提，不新增素材前置
|
||||
- core/ 零 UI 依赖（D2 Rule 7）——本迁移全部发生在 presentation/，逻辑层零接触
|
||||
|
||||
### Requirements
|
||||
- B 区战斗画面（站桩立绘、意图三档动画、受击/死亡演出）的后续迁移不被本批堵死——骨架同构可复制
|
||||
- 分辨率两档（1280×800 / 1920×1080，2026-09-22 定案）与「格边长按分辨率档位计算」口径（2026-09-18 拍板，推翻两档定值冻结）继续成立
|
||||
- 三探针（ui_probe / ui_click_probe / ui_layout_probe）与冒烟全量基线不破
|
||||
|
||||
## Decision
|
||||
|
||||
**1. D 区棋盘本体迁 Node2D 渲染，BoardView 类名与公共面契约保持不变。**
|
||||
|
||||
BoardView（`presentation/views/board_view.gd`，现 extends Control + 内部 GridContainer）重构为：Control 壳参与屏幕栅格布局不变，壳内经 **SubViewportContainer + SubViewport + Node2D 世界**（BoardWorld）渲染棋盘。对外契约逐项保持：
|
||||
|
||||
| 契约面 | 消费方 | 保持方式 |
|
||||
|---|---|---|
|
||||
| 类名 `BoardView` / extends Control | ui_assembler 组装、屏幕栅格布局 | 不变 |
|
||||
| 信号 `action_requested` / `hover_forbidden` / `chord_attempted` | 组合根动作通道 | 不变 |
|
||||
| `click_cell(cell, button)` 公共入口 | ui_click_probe 直调路径（ui_click_probe.gd:257–277） | 不变 |
|
||||
| `_cells` 字典（Vector2i → 格单元） | ui_probe `_cells.is_empty()/.size()` 断言（ui_probe.gd:73/187）、ui_click_probe.gd:97 | 键面不变，值 Button → 格单元 Node2D |
|
||||
| `board()` / `set_desaturated()` / `set_identity_resolver()` / `set_variant_mask_resolver()` / `set_cell_area()` / `rebuild()` / `refresh()` | 组合根与探针 | 不变 |
|
||||
| `cell_size` 只读属性 | ui_layout_probe `get("cell_size")`（现返回 null——`_cell` 为私有名） | 增补只读属性，顺手修正 |
|
||||
|
||||
**2. 渲染技术分工表（本 ADR 核心裁决——「三块模型」）。**
|
||||
|
||||
战斗屏渲染技术按内容形态切分，与屏幕布局正交。**战斗屏目标形态 = B/C/D 三区**（2026-09-23 用户裁定：战斗画面不再保留关卡进度条——战斗结束后返回关卡画面，节点链进度只留关卡画面）：
|
||||
|
||||
| 内容 | 渲染技术 | 批次 |
|
||||
|---|---|---|
|
||||
| D 区棋盘本体（格面/数字/旗/徽章/变异纹带/高亮/微光） | **Node2D**（本 ADR） | Phase A（本批立项） |
|
||||
| B 区战斗舞台（主角/敌人站桩、意图三档动画、受击/死亡演出、FX） | **Node2D** | Phase B（后续批，本 ADR 只定分工） |
|
||||
| A 区关卡进度条 | Control | **战斗屏退场且代码退役**（裁定见下；退场落地随停点前移批——流程未倒置前 A 区仍是战斗中唯一节点链可视面，先删致盲，本批不动其现状） |
|
||||
| C 区角色信息（数据框/状态槽/立绘） | Control | 不动 |
|
||||
| D 区 AP 条、按钮组、toast 槽 | Control | 不动 |
|
||||
| B 区结算明细带、回合阶段指示、战斗日志 | Control（文本件） | 不动（Phase B 时留 B 区 Control 半区） |
|
||||
| 全部弹层（选路/节点/结算/图例/营地/开始菜单） | Control | 不动（2026-09-23 用户拍板） |
|
||||
|
||||
**A 区退场形态（2026-09-23 追问裁定）**：LevelStripView **退役，不迁移**；关卡画面**不重新实现**——由 RouteOverlay（整幅节点图选路层，节点态色板语义与压缩条同族、候选按钮与放弃入口在役）升级为常驻页面承接。压缩条唯一存在理由（战斗屏无整图时的常显替代面）随零进度裁定消亡，无独有资产流失；唯一继承面 = 逻辑层节点数据面（runner 只读出口零改动）。退役删除面清单见迁移方案 §1。
|
||||
|
||||
**3. 命中测试 = 板级公式换算单点，非逐格 Area2D。**
|
||||
|
||||
鼠标输入经 BoardView 壳层 `_gui_input` 接收（Control 已有的矩形命中），格坐标 = `floor(local_pos / 格边长)` 单点公式换算——悬停/点选/双击 chord/长按全部复用现有逻辑入口。不为 144 格建 Area2D（节点开销无必要，Alternative 2 论据沿用）；ADR-0003 登记的「自建命中测试」成本由此收敛为一个公式函数。无障碍面缺失为接受后果（沿 ADR-0003 Decision 3 已登记口径，键盘寻格体系延后）。
|
||||
|
||||
**4. 素材槽位按圣经 §8.2 暂定档预留，程序化占位继续服役。**
|
||||
|
||||
格单元内部为固定叠层序的精灵槽位（砖面 < 变异纹带 < 数字/徽章 < 旗 < 焦点高亮），本批全部槽位由程序化绘制填充（现行占位等价平移）；终稿纹理（格面 32×32 暂定档）到位后 1:1 换入，零结构返工。**美术缺口不阻塞本迁移**——样张批终值（格边长×格源占比摩擦，v1.9 待决注记①路线）只换 `set_cell_area` 单点数值，不动架构。
|
||||
|
||||
**5. SubViewport 模式为两舞台统一骨架，Phase B 复制不返工。**
|
||||
|
||||
Phase B 届时将 BattleStageView 同构改造（PanelContainer → Control 壳 + SubViewport 舞台 + 结算明细带 Control 半区）。本批在 ui_assembler 组装侧不引入「单舞台」写死假设，SubViewport 内 theme/字体注入做成可复用挂点（两舞台共用）。
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### Alternative 1: 维持逐格控件形态（ADR-0003 现行）
|
||||
- **Cons**: 表现层升级（站桩动画/演出/FX）在 Control 树内无载体，最终仍需二次迁移；两次改造总成本高于一次定向。
|
||||
- **Rejection Reason**: 2026-09-23 用户已定向 Node2D；本 ADR 职责是把方向落为工程边界。
|
||||
|
||||
### Alternative 2: 直挂 Node2D（Control 壳内手挂 Node2D，无 SubViewport）
|
||||
- **Cons**: 屏幕坐标↔棋盘坐标换算、缩放纪律、两档分辨率适配全部自建；布局联动手工维护。
|
||||
- **Rejection Reason**: SubViewportContainer 是 Control——容器栅格布局引擎原生参与，鼠标坐标引擎换算，内部分辨率固定使像素缩放纪律有单点可管。
|
||||
|
||||
### Alternative 3: 逐格 Area2D 承载命中
|
||||
- **Cons**: 144 个 Area2D 节点开销与信号接线量；命中语义（相邻约束/chord/长按）仍要自建。
|
||||
- **Rejection Reason**: 板级公式换算单点已覆盖全部交互语义，物理命中是纯开销。
|
||||
|
||||
### Alternative 4: TileMapLayer 承载棋盘
|
||||
- **Rejection Reason**: ADR-0003 已否（瓦片语义与变体标记/数字/旗多层叠加不匹配），维持。
|
||||
|
||||
### Alternative 5: B 区与棋盘同批迁移
|
||||
- **Cons**: B 区站桩形态绑美术样张批（剪影/动画方案未冻结），混批互卡。
|
||||
- **Rejection Reason**: 2026-09-23 用户拍板分批——先只迁棋盘，战斗画面 Node 后续完成。
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
- 表现层升级获得渲染载体；棋盘先行验证 SubViewport 骨架，B 区复制模式即可
|
||||
- BoardView 公共面契约保持——三探针与组合根零改造（实证耦合面仅 `_cells` 键面/`click_cell`/`cell_size`，全部保留）
|
||||
- 素材终稿 1:1 换入，样张批与渲染批解耦，互不阻塞
|
||||
- 逻辑层（core/）零接触——MC/模拟试玩/verifier 读数面零影响
|
||||
|
||||
### Negative
|
||||
- Node2D 世界内 theme 不自动继承主场景 Control 主题——CJK 字体与 ui_kit 样式需显式注入（实施批义务，ADR-0003 Decision 4 关联）
|
||||
- 键盘寻格/无障碍面缺失口径延续（已登记接受）
|
||||
- 非整数缩放的像素纹路风险（45/36px 锚点 × 32px 格源非整倍）——沿 §8.2 路线归样张批定终值，架构只保证 `set_cell_area` 单点可调
|
||||
|
||||
### Risks
|
||||
- SubViewport 渲染目标在低端机的显存/带宽开销 → 缓解：棋盘区逻辑分辨率小（≤ 12×12×36px 量级），实施批实测帧预算
|
||||
- 输入路径改 `_gui_input` 后现探针全走 `click_cell` 直调，公式换算无自动化覆盖 → 缓解：实施批增补 push_input 端到端输入探针（ADR-0003 已登记项，本批转义务）
|
||||
|
||||
## Migration Plan
|
||||
Phase A（棋盘，实施另批）：BoardView 内部重构 + 探针增补 + 冒烟全量回归 + 文档随批（HUD框架渲染注记/battle.md 实现注记/architecture.md 模块归属行）。Phase B（B 区舞台，后续批）：同构复制 + 站桩精灵迁移 + 意图动画承载；开工前置 = 样张批冻结剪影与动画方案。战斗屏进度条退场的 GDD 修订面（HUD框架 四区表、关卡节点地图 节点链常显条款、battle.md 像素布局表与 28px 纵向空间再分配）随停点前移批（关卡画面成为常驻枢纽）落地，不随本批。工程细节见同目录 `board-node2d-migration-plan.md`。
|
||||
|
||||
## Validation Criteria
|
||||
- 冒烟全量绿（现行基线不破）；三探针（ui / ui_click / ui_layout）绿
|
||||
- 新增 push_input 端到端输入探针绿（悬停/左键/右键/chord 各一case）
|
||||
- 功能等价清单：数字/旗/徽章/危险红/变异纹带/呼吸微光/悬停/路径预览/灰化（set_desaturated）/出生展开区 R₀ 豁免，逐项可点可验
|
||||
- 性能预算：同屏 draw calls < 200；进入战斗屏 500ms 内首格可点
|
||||
- 分辨率两档（1280×800 / 1920×1080）装板校验通过（12×12 与 10×10 板各验）
|
||||
|
||||
## Related Decisions
|
||||
- ADR-0003（本 ADR 部分取代其 Decision 3；Alternative 2 否决理由更新）
|
||||
- ADR-0001（组合根纪律——BoardView 信号外发模式沿袭）
|
||||
- art-bible §8.2（画布暂定档与缩放纪律）、HUD框架（四区结构冻结与性能预算引用值）、battle.md（格尺寸公式锚点）
|
||||
@@ -0,0 +1,295 @@
|
||||
# Dungeon Sweeper — Master Architecture
|
||||
|
||||
## Document Status
|
||||
|
||||
- Version: 1.3
|
||||
- Last Updated: 2026-09-26（战斗舞台 Node2D 迁移 Phase B：D1 层表 BattleStageView 形态注记——引 ADR-0006；Phase A 注记 2026-09-23）
|
||||
- Engine: Godot 4.7.2-stable（GDScript 单语言；2026-09-07 锁定）
|
||||
- Review Mode: solo（`production/review-mode.txt`，2026-09-12 用户拍板——TD/LP 门禁按 solo 跳过，用户授权架构产出自主推进、迭代期回调）
|
||||
- GDDs Covered: game-concept · game-pillars · systems-index · d2-data-config · a3-action-economy · a4-terrain-variation · b3-status-effect · a1-board-generation · a2-minesweeper-rules · b2-enemy-system · b4-reward-item-economy · b1-settlement（12 份；A5/C1–C4/B5/D3–D6 未设计，按 systems-index 依赖分层预留）
|
||||
- ADRs Referenced: 无（0 份现存）——本文档 Phase 5/6 列出的实现期裁决项即为首批 ADR 候选
|
||||
- Implementation Evidence: 垂直切片 `game/`（2026-09-10 起，冒烟 88/88、三 UI 探针 PASS）——本文档的分层/所有权/数据流均经切片实现验证，非纯纸面设计
|
||||
- Technical Director Sign-Off: 2026-09-12 — APPROVED WITH CONDITIONS（条件：Required ADRs 于正式工程骨架搭建前定稿；`.claude/docs/director-gates.md` 缺失已登记技术债）
|
||||
- Lead Programmer Feasibility: SKIPPED — Solo mode
|
||||
|
||||
---
|
||||
|
||||
## Engine Knowledge Gap Summary
|
||||
|
||||
- **风险等级：MEDIUM**（2026-09-12 `/setup-engine refresh` 后由 HIGH 降级）。4.5→4.7 官方迁移指南已逐条核实并入 `docs/engine-reference/godot/breaking-changes.md` 与 `deprecated-apis.md`；**结论：无一条破坏 GDD 已锁架构契约**（autoload 体系 / .tres 单一事实源 / Callable 信号 / int64 二补数 / headless SceneTree 协议均不受影响）。
|
||||
- 写码纪律不变：不确定的 API 一律查 `docs.godotengine.org/en/4.7/` 核实后再用；4.8（dev 阶段）稳定版发布后跑 `/setup-engine refresh`。
|
||||
- 三类必须入编码纪律的引擎事实（详见 `docs/engine-reference/godot/current-best-practices.md`）：
|
||||
1. **GDScript 4.7 两条语义变化**：打包数组元素赋值不再触发属性 setter；类型化返回的方法覆盖必须显式 `return`。
|
||||
2. **新项目默认值已变**：stretch mode `canvas_items` / aspect `expand`（4.7）；Windows 渲染驱动 D3D12（4.6，仅 Forward+ 线）——创建 project.godot 后逐项核对。
|
||||
3. `Resource.duplicate(true)` 深复制不再覆盖外部子资源——D2 表资源复制语义注意。
|
||||
- 残余风险敞口：modules/ 分域参考未建（按实现期需要建，非阻塞）；UI/渲染域（D1/B5）为 MEDIUM 风险集中地，随 ADR-0002/0003 裁决时对照引擎文档核实。
|
||||
|
||||
---
|
||||
|
||||
## System Layer Map
|
||||
|
||||
20 系统按 systems-index 依赖分层表（systems-design 门禁已评审）映射到标准五层。切片实现已验证该分层（core/ 纯逻辑零 UI 依赖 headless 可跑、presentation/ 组合根模式）。
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────────────┐
|
||||
│ PRESENTATION LAYER │
|
||||
│ D1 HUD 与界面框架 (MVP) · B5 战斗表现 (切片后) │
|
||||
│ D4 音频 (Alpha) · D5 教学引导 (Alpha) │
|
||||
├────────────────────────────────────────────────────────────┤
|
||||
│ FEATURE LAYER │
|
||||
│ B1 战斗结算编排 (MVP) · C1 关卡节点地图 (切片已含 lite) │
|
||||
│ C2 冒险结构 · C3 难度曲线 · C4 元进度 (Alpha) │
|
||||
├────────────────────────────────────────────────────────────┤
|
||||
│ CORE LAYER │
|
||||
│ A1 扫雷棋盘生成 · A2 排雷玩法规则 · B2 敌人系统 │
|
||||
│ B4 地图战斗资源 · A5 扫雷魔法道具 (垂直切片) │
|
||||
├────────────────────────────────────────────────────────────┤
|
||||
│ FOUNDATION LAYER │
|
||||
│ D2 数据配置与数值表 · A3 行动经济 · A4 地形变异 │
|
||||
│ B3 增益/状态系统 · D3 存档序列化 (Alpha) · D6 设置/本地化│
|
||||
├────────────────────────────────────────────────────────────┤
|
||||
│ PLATFORM LAYER │
|
||||
│ Godot 4.7.2 引擎 API 面（GDScript / Resource / │
|
||||
│ SceneTree / Control / InputEvent）——无游戏系统 │
|
||||
└────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
| 系统 | 层 | 里程碑 | headless 约束 | 引擎风险域 |
|
||||
|---|---|---|---|---|
|
||||
| D2 数据配置 | Foundation | MVP | ✅ 完整可跑 | LOW（Resource/.tres 基线稳定） |
|
||||
| A3 行动经济 | Foundation | MVP | ✅ 完整可跑 | LOW（纯逻辑） |
|
||||
| A4 地形变异 | Foundation | MVP | ✅ 完整可跑 | LOW（纯逻辑） |
|
||||
| B3 状态系统 | Foundation | MVP | ✅ 完整可跑 | LOW（RefCounted 纯逻辑） |
|
||||
| A1 棋盘生成 | Core | MVP | ✅ 完整可跑 | LOW（纯逻辑；性能姿态归 ADR-0005） |
|
||||
| A2 排雷规则 | Core | MVP | ✅ 完整可跑 | LOW（零表读取零 UI） |
|
||||
| B2 敌人系统 | Core | MVP | ✅ 完整可跑 | LOW（纯逻辑） |
|
||||
| B4 地图战斗资源 | Core | MVP | ✅ 完整可跑 | LOW（纯逻辑） |
|
||||
| B1 战斗结算编排 | Feature | MVP | ✅ 完整可跑（禁 await） | LOW（纯逻辑；事件载体归 ADR-0001） |
|
||||
| C1 关卡节点地图 | Feature | 垂直切片（lite 已入切片） | ✅（切片 level_runner 先例） | LOW |
|
||||
| C2 冒险结构 | Feature | 垂直切片 | ✅ | LOW |
|
||||
| C3 难度曲线 | Feature | 垂直切片 | ✅ | LOW |
|
||||
| C4 元进度 | Feature | Alpha | ✅ | LOW |
|
||||
| D1 HUD | Presentation | MVP | ❌（UI 层——场景级探针测试承载） | **MEDIUM**（Control/Input/文本域） |
|
||||
| B5 战斗表现 | Presentation | 垂直切片 | ❌ | **MEDIUM**（Animation/Tween/渲染） |
|
||||
| D4 音频 / D5 教学 | Presentation | Alpha | 部分 | LOW-MEDIUM |
|
||||
| D3 存档序列化 | Foundation | Alpha | ✅ | LOW |
|
||||
| D6 设置/本地化 | Foundation | 完整愿景 | ✅ | LOW |
|
||||
|
||||
**MVP 关键路径**（切片已验证）：D2 → A3/A4/B3 → A1 → A2 → B2/B4 → B1 → D1-lite。
|
||||
**依赖分层与唯一回边**：A2 只外发三事件（cell_revealed / flag_judged / round_end），B4/B1 订阅后回调——A2 不依赖任何下游（TD-SYSTEM-BOUNDARY 裁决，全项目唯一允许回边）。
|
||||
|
||||
---
|
||||
|
||||
## Module Ownership
|
||||
|
||||
> 命名遵循 `docs/code-conventions.md`：领域命名、禁 ID 前缀、头注溯源行（实现 GDD：design/gdd/…）。切片已按此规范完成领域命名批。
|
||||
|
||||
### Foundation 层
|
||||
|
||||
| 模块 | Owns（独占） | Exposes | Consumes | 引擎 API |
|
||||
|---|---|---|---|---|
|
||||
| **ConfigDB**（autoload，D2） | 全部玩法数值表（`data/tables/*.tres` + `data/schemas/*.gd`）；SCHEMA_VERSION；加载/校验/override/诊断状态机 | 类型化属性读取；`load_tables(root, collect_only)`；`resolve()`（R1 floor）；debug override；`set_reload_gate()`；诊断收集器 | 无（Foundation 顶点） | Resource/.tres 加载、autoload 生命周期——LOW |
|
||||
| **RngService**（autoload，D2） | master_seed、各流 scope 计数器（封闭流：board_gen / reward_roll；增流走 P1 评审） | `set_master_seed()`（唯一调用方 C2）；`open_stream(stream)` 有状态门面；`derive_at(stream, scope)` 纯函数；只读计数器 | ConfigDB（无） | 无——纯逻辑 |
|
||||
| **action_economy**（A3） | AP/RAP 账本、last_round_end、轮次相位机 {Idle, Active, Waiting}、结束仲裁 | 8 API 全布尔面：notify_round_start / request_dig / request_flag_place / request_flag_pull / request_stop / request_refresh / notify_settlement_done / notify_combat_end；ap/rap/phase 只读 | ConfigDB（ActionEconomyTable）；B1 回发 next_round_mode/battle_over | 无 |
|
||||
| **variation 定义**（A4） | VariationTable schema（现行空清单，合法态）与 F1 候选池门控谓词 | `variant_pool_gate(level_index, board_biome)` | ConfigDB（VariationTable） | 无 |
|
||||
| **status_container**（B3） | 状态实例容器（战斗域生命周期、跨轮跨图延续） | 5 API：notify_battle_start / apply_effect / query_active / decay_round / notify_battle_end | ConfigDB（StatusEffectTable） | 无（RefCounted） |
|
||||
| **save_system**（D3，Alpha） | 存档格式与版本比较 | （未设计——契约锚：SCHEMA_VERSION + master_seed + 各流 scope 计数器快照，须在无在飞 open_stream 实例时切出） | ConfigDB、RngService 只读计数器 | FileAccess——LOW |
|
||||
| **settings/localization**（D6，愿景） | 设置项、翻译数据 | （未设计） | ConfigDB | 无 |
|
||||
|
||||
### Core 层
|
||||
|
||||
| 模块 | Owns | Exposes | Consumes | 引擎 API |
|
||||
|---|---|---|---|---|
|
||||
| **board_generator**（A1） | 生成算法（五阶段管线）、BoardGenTable 回填、生成期指标集、合法性谓词（clearable / R₀≠S / min_safe）、可推理率度量（metric_version） | `generate(L, D, rng) -> Board`；度量独立入口×3（推理器 / F3 度量 / 合法性谓词——独立纯函数、同一实现） | ConfigDB（BoardGenTable/VariationTable）；board_gen 流（一次 open_stream = 一张图）；dig_ap_cost 只读 | 无 |
|
||||
| **minesweeper_rules**（A2） | 棋盘状态（已开集 O / 旗集 G / 小人位）、三事件面、批次仲裁、install 四不变式 | `install_board(board)`；`settle_batch(intents)`（唯一提交入口）；try_dig / try_flag_place / try_flag_pull / try_move（便捷形）；`compute_move_path(cell)` 只读；`retire_board()`；三源拒绝（board_face / resource_face / phase）+ sub_reason 封闭枚举 | A1 产物（Board class_name 数据契约）；A3 try_spend / last_round_end / 相位 | 无（零表读取、零 UI——切片实证） |
|
||||
| **unit_container**（B2） | hero/enemy 单位实例（hp/atk/实例池：池快照+冷却+摇定动作+保底计数）、行值快照 | spawn / query_alive / rollable_skills / special_skills / set_pending_action / pending_action / basic_streak / commit_action / tick_cooldowns / apply_damage / heal / default_target / ambush_grant_plan / despawn_all（2026-09-16 敌人技能池批：query_beat/query_attack/advance 随行为环退役——architecture.md 旧口径残留归 API 面 ADR 批整表复核） | ConfigDB（EnemyTable/SkillTable/HeroTable） | 无 |
|
||||
| **reward_economy**（B4） | 格面资源身份映射（install 期预分配、Ready 只读、换图映射消亡）、极性路由字典面（（类型, 极性）→ 字典行查询；路由执行归 B1 授予段）、F6 当量供给投影 | 封闭 API：roll_board / query_identity / query_full_snapshot / grant / grant_clear / retire_mapping / polarity_row / equivalence_supply / phase / weighted_pick；另有 is_mapped 静默布尔投影（批量工具用） | ConfigDB（RewardTable）；reward_roll 流（scope = 每次 install 批） | 无 |
|
||||
| **helper_items**（A5，垂直切片） | HelperItemTable、探测显影语义 | （未设计——桥接位：A2 查询接口 + A4 counter_item_ids） | A2 / A4 / B4 | 无 |
|
||||
|
||||
### Feature 层
|
||||
|
||||
| 模块 | Owns | Exposes | Consumes | 引擎 API |
|
||||
|---|---|---|---|---|
|
||||
| **battle_orchestrator**（B1） | 段序骨架（七段结构冻结）、轮 facts 缓冲、可回放步骤流、[明细行协议](../../design/gdd/systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋)（15 类行 + 字段分层）、条款③⑤闭合对账、**战斗域全部跨系统调用权** | `begin_battle(encounter)`；窗口/刷新意图提交面（扮演 D1）；`level_clear()`；步骤流（输出契约） | B2/B3/B4 全调用面（**唯一调用方**）；A3 request_refresh 代理 + 回发；A2 install/retire + 三事件订阅；A1 generate（attempt 非 scope 事件）；D2 SettlementTable + set_reload_gate | 无（零随机、禁 await——切片 88 冒烟实证可回放） |
|
||||
| **level_runner**（C1-lite，切片已建） | 关卡域生命周期（节点链推进、共享 B4 + HP 携带、关卡末 level_clear） | 节点推进接口；LevelTable（`level.tres`——节点 enum {battle,reward,rest,boss}、末节点必须 Boss、ConfigDB 跨表校验⑧） | B1 begin_battle、B4 grant_node_active、ConfigDB LevelTable | 无 |
|
||||
| **run_structure**（C2） | 冒险/关卡序列、失败重开、**master_seed 唯一接线方** | （未设计） | RngService.set_master_seed、C3/D2 | 无 |
|
||||
| **difficulty**（C3） | DifficultyTable 回填、全部曲线数值调参所有权、战斗期望表（切片 monte_carlo 为工具原型） | 调参输出（经 D2 R1 解析/编排器传递，禁反向调用生成） | ConfigDB、B1 对账输出（调参约束清单）、A1 报告 C | 无 |
|
||||
| **meta_progression**（C4，Alpha） | MetaTable、钥石/天赋 | （未设计） | D3、C2、ConfigDB | 无 |
|
||||
|
||||
### Presentation 层
|
||||
|
||||
| 模块 | Owns | Exposes | Consumes | 引擎 API |
|
||||
|---|---|---|---|---|
|
||||
| **D1 HUD**（切片 lite 已拆 9 单元：BoardView / HUDView / HudPresenter / BattleLogView / ItemWindowOverlay / NodeOverlay / LevelStripView / TunePanel / UiKit + 组合根 main.gd） | 全部 Control/CanvasLayer（例外：BoardView 棋盘本体与 BattleStageView 站桩本体 = Control 壳 + SubViewportContainer + SubViewport + Node2D 世界〔BoardWorld/CellUnit；StageWorld/StandeeBody——B 区 slot_row 伴随件留壳层〕，探针契约面不变——ADR-0006 棋盘 Node2D 迁移批 Phase A 2026-09-23 / 战斗舞台 Phase B 2026-09-26）、输入→意图翻译（**唯一提交路径 = settle_batch，不直调 A3**）、呈现义务台账（A2×6 / B2×4 / B3×4 / B4×5 / B1×3） | 视图单元接口（信号外发、setter 只读注入） | A2 compute_move_path / ActionOutcome；A3 ap/rap；B1 步骤流行协议（数据源）；ConfigDB display_name | **MEDIUM**：Control / CanvasLayer / draw_* / InputEvent / RichTextLabel——对照 breaking-changes.md 4.5–4.7 条目（CanvasItem 线条无抗锯齿羽化、设备 ID 常量、RichTextLabel 图片参数两轮变化） |
|
||||
| **battle_presentation**（B5，垂直切片后） | 结算动画 / 伤害数字 / 战斗舞台 | （未设计——前置"战斗表现美术测试"锁双舞台陷阱） | B1 步骤流（回放脚本源）、D1 | **MEDIUM**：AnimationPlayer（String→StringName 变更）/ Tween |
|
||||
| **audio**（D4，Alpha） | 音频挂点 | （挂点 = B1 明细行类型流；负反馈聚合——单结算至多一次） | B1 流水 | AudioStreamPlayer（4.7 area_mask 默认 1→0 注意） |
|
||||
| **tutorial**（D5，Alpha） | 教学条目 | （口径来源：A2/A3/B3/B1 各教学条目） | 各上游 | 无 |
|
||||
|
||||
**依赖单向性**：上层可消费下层，禁止反向（C3 禁调用 A1 生成、D1 不直调 A3、A2/B3/B4 零相互直调）。全项目唯一回边 = A2 事件订阅面。
|
||||
|
||||
---
|
||||
|
||||
## Data Flow
|
||||
|
||||
### 1. 帧更新路径（2D 回合制：无逐帧玩法逻辑）
|
||||
|
||||
```
|
||||
Input（鼠标）→ D1 输入翻译 → 意图对象 → A2.settle_batch（唯一提交入口）
|
||||
→ A3.try_spend（原子扣减）→ A2 棋盘效果（挖/连锁/旗/移动）→ 三事件外发
|
||||
→ [棋盘渲染：D1 BoardView 按事件增量重绘；无事件帧 = 静态 + 动效]
|
||||
→ 轮次结束 → A3 Waiting → B1 结算编排（段序七段）→ 明细步骤流 → D1 结算屏逐行呈现
|
||||
```
|
||||
|
||||
- 回合制下每帧只做：输入采样、呈现刷新、动效推进——**玩法状态只在意图事务内变更**（单意图帧输入收集：stop 点击终结当帧）。
|
||||
- 无跨线程玩法数据流（Godot 主线程假设，D2 EC13）；A1 生成若引入 WorkerThread 须走 ADR-0005 裁决（join 先于任何快照切出）。
|
||||
|
||||
### 2. 事件/信号路径（系统间通信，无紧耦合）
|
||||
|
||||
```
|
||||
A2 ──cell_revealed / flag_judged / round_end(棋盘路径)──▶ B1（轮 facts 缓冲）
|
||||
A3 ──round_end(stopped 直发，payload 同构)──────────────▶ B1
|
||||
B1 ──notify_settlement_done(next_round_mode) / notify_combat_end──▶ A3
|
||||
B1 ──apply_effect / apply_damage / grant / stock / advance...──▶ B3/B2/B4（唯一调用方）
|
||||
B1 ──install_board / retire_board──▶ A2 B1 ──generate(L,D)──▶ A1
|
||||
D1 ◀──呈现数据源：A2 事件流 / B1 步骤流 / A3 ap-rap / ConfigDB display_name
|
||||
```
|
||||
|
||||
- **载体裁决待 ADR-0001**：切片事实 = 组合根直连信号接线 + B1 Waiting 相位触发（不依赖事件到达序）；推荐沿用（单线程回合制，KISS），autoload 全局事件总线为否决倾向。
|
||||
- 事件规范序：A2 发射序 = 触发格 BFS、8 邻行主序；事件序契约 `flag_judged` < `round_end` 全路径统一。
|
||||
|
||||
### 3. 存档/读档路径（MVP 无存档；契约已锁）
|
||||
|
||||
- MVP 无元进度持久化（C4/D3 归 Alpha）。**已锁契约**：续玩/复盘快照 = master_seed + 各流 scope 计数器 + 意图序列 + 窗口选择序列；快照切出须发生在无在飞 `open_stream` 实例时（scope 事件边界外——B1 编排保证：切点 = board install 边界）。
|
||||
- 可回放性已实证：切片冒烟同种子双跑步骤流逐行相同（B1 AC-33 前身）。
|
||||
- D3 Alpha 期按此契约设计格式；SCHEMA_VERSION 高版本拒读。
|
||||
|
||||
### 4. 初始化顺序
|
||||
|
||||
```
|
||||
进程启动
|
||||
→ autoload 实例化：ConfigDB → RngService（顺序固定；战斗编排器为普通类、由组合根按局实例化——切片形态）
|
||||
→ ConfigDB._ready()：load_tables 加载 + 校验（致命通道；失败 = 构建中止 + 错误清单）
|
||||
→ 主场景（D1 组合根）装配视图单元 + 信号接线
|
||||
→ C2 begin_run：RngService.set_master_seed()（唯一接线方；两流计数器全零前提）
|
||||
→ B1.begin_battle(encounter)：set_reload_gate(true) → B3 开域 → B2 spawn → A2 install_board(A1.generate) + B4 roll_board（恰一次）→ A3 notify_round_start
|
||||
→ 挖掘循环 …… → battle_over 清理序列 → set_reload_gate(false)
|
||||
→ 关卡末：level_clear()（clear_inventory 恰一次 + 快照计数）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API Boundaries
|
||||
|
||||
> 完整 API 面（含封闭枚举负空间、布尔受理口径、输入×相位矩阵）以各 GDD AC 前言为**规范源**——本节列边界契约与不变式，实现须与 GDD 逐字一致；冲突时以 GDD 为准并走接口漂移修订。
|
||||
|
||||
| 边界 | 契约要点 | 调用方必须遵守的不变式 | 模块保证 |
|
||||
|---|---|---|---|
|
||||
| D1 → A2 | 意图经 `settle_batch(intents)` 提交；不直调 A3 | 单意图帧收集；stop 经批次委托 | 语义序仲裁 + voided 零副作用 |
|
||||
| A2 → A3 | 挖/插/拔 = 先棋盘面判定后 `try_spend`；A2 不可自行扣减 | 相位判定两侧一致（同一矩阵） | 原子事务（余量+扣减+仲裁一体） |
|
||||
| A2 → 下游 | 只外发三事件，payload 字段封闭（digit 恒真透传 / reward_eligible / variant_ids） | 增删事件 = 接口漂移 | 发射面封闭 + 规范序 |
|
||||
| B1 → B2/B3/B4 | 全调用面集中 B1；调用序钉死（query_attack→apply_damage→advance；先兑付后衰减） | 禁第二调用方（静态扫描域：API 符号命中文件 ⊆ B1 文件集） | 恰一次编排纪律（roll_board/decay/清理全序） |
|
||||
| B1 ↔ A3 | 编排期代理 `request_refresh`（玩家意图，禁 RAP 满自动刷）；回发 next_round_mode/battle_over | stopped/ap_exhausted 未刷新回发 new_board = 违约 fail-fast | 刷新受理契约（同 Waiting 多次合法） |
|
||||
| 各系统 → D2 | ConfigDB 类型化属性单点读取 | 禁绕过 ConfigDB load 表、禁缓存副本、禁玩法数值字面量、禁 randomize()/自建 RNG | 校验双通道 + fail-fast 致命 |
|
||||
| A1 → A2 | Board 产物 class_name 数据契约 | install 四不变式校验（violation = 拒绝 + 五类诊断枚举） | 生成期合法性闸（R₀≠S / clearable / min_safe） |
|
||||
| A1 ↔ B1 | attempt 边界非 scope 事件；actuals p10 为对账输入（非 target 参数） | 编排不把重试当取号 | 生成期指标集输出（实测可推理率 / 实际雷数与安全格数 / 重试次数 / 降级与非法产物标记） |
|
||||
| B4 → B3 | buff 类经 B1 调 apply_effect（B4 零跨系统读、零直接接口） | 满层拒绝 = 零兑付 + 明细行（无折算） | 授予时数值快照（抗热重载） |
|
||||
| B1 → D1 | [步骤流行协议](../../design/gdd/systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋)（15 类封闭枚举 + 公共字段 type/source_class/origin_cell/round_index/display_name/value/highlight? + 特有字段 target/effect_id/pool_value） | 无来源行 = 断言失败；呈现侧禁按行序重演 B2 状态机 | 可回放步骤流（同种子逐行相同） |
|
||||
|
||||
**引擎类型核验注记**：接口使用的引擎类型 = Resource / .tres（D2 全表）、RefCounted（容器类）、Signal/Callable（事件载体，ADR-0001）、Control/CanvasLayer/Drawing（D1）、SceneTree headless 协议（测试）——均属 4.x 基线稳定面；4.7 Control 域增量（offset_transform_* 等）已在 breaking-changes.md 登记，D1 采纳前对照核实。
|
||||
|
||||
---
|
||||
|
||||
## ADR Audit
|
||||
|
||||
**现存 ADR：0 份**（`docs/architecture/` 本文档为首个产物；此前架构约束由 GDD 门禁评审 + CLAUDE.md + code-conventions 事实承载）。
|
||||
|
||||
### 已锁决策盘点（GDD 层已定稿，不重复立项 ADR）
|
||||
|
||||
| 决策 | 锁定来源 |
|
||||
|---|---|
|
||||
| GDScript 单语言；autoload = ConfigDB + RngService（定名勿改） | technical-preferences + D2 GDD |
|
||||
| 全部玩法数值 .tres 单一事实源；零字面量；R1 floor 解析；fail-fast 双通道 | D2 Core Rules 1–8 |
|
||||
| RNG 封闭流 + scope 派生（R2 黄金向量）；可回放 = 硬承诺 | D2 R2 + B1 Core Rule 15 |
|
||||
| A2 纯规则引擎（零随机/零表读取/零 UI）+ 三事件面封闭 | A2 Core Rule 1/2 |
|
||||
| B1 编排唯一性 + 七段段序骨架 + 明细行协议 | B1 Core Rule 1/4/14 |
|
||||
| 多敌 side-wide / 出招确定性（技能池批改型：零随机纪律保持、开轮摇号走 behavior_roll 封闭流）/ 固定顺位 / 伏击 cap=4 | B2（2026-09-09 用户拍板；2026-09-16 技能池批改型） |
|
||||
| 奖励五值两类交付轴 / install 预分配 / 关卡域库存 / 窗口单件制 | B4（2026-09-11 用户裁决批） |
|
||||
| weaken 锚 F0 瞬时当量 / 条款①③⑤闭合对账 owner = B1 | B1 F0–F5 |
|
||||
| 领域命名禁 ID 前缀 / 组合根模式 / 呈现层契约成文 | CLAUDE.md + docs/code-conventions.md（切片教训批） |
|
||||
|
||||
### GDD 登记的"实现期 ADR 裁决项"汇总（= Required ADRs 的来源）
|
||||
|
||||
A2 OQ2（事件外发载体）· B1 OQ1（事件总线载体，与 A2 OQ2 同一裁决）· A1 OQ2/OQ3（生成性能姿态 + 度量独立入口）· B2 OQ1（query_attack/ambush_grant_plan 两 face 归属）· B2 OQ5（HeroTable 单行校验落点）· B2 OQ9（零伤害死局跨字段护栏落点）· D2 OQ1（gdUnit4 取舍）· technical-preferences（渲染器选择）· 切片新增正式化批（轮内刷新方案 A / RewardSupplyController / LevelTable / grant_node_active / clear_blast——GDD+registry 修订义务在切片 README）。
|
||||
|
||||
### Traceability Coverage Check
|
||||
|
||||
Technical Requirements Baseline 63 条 → ADR 覆盖 0 条（无 ADR 存在）；按覆盖载体分层：
|
||||
|
||||
| 覆盖载体 | TR 数 | 说明 |
|
||||
|---|---|---|
|
||||
| ✅ 本架构文档（分层/所有权/数据流/API 边界）+ GDD 契约 | 46 | 数据/RNG/核心行为/编排协议类——已锁且切片实证，无需 ADR |
|
||||
| 🔶 待 ADR 裁决 | 12 | 引擎/测试/实现形态类：TR-gc-008（渲染器）、TR-a1-011/012（生成姿态）、TR-d2-014/016（测试载体）、TR-a3-004+TR-b1-001/002（事件载体）、TR-b2-005/006（face 归属）、TR-d2-010+TR-gc-002（D3 契约正式化） |
|
||||
| ⏳ 未设计系统预留 | 5 | A5/C1–C4/D3 关联 TR（随各系统 GDD 立项） |
|
||||
|
||||
**结论：0 条孤儿需求**——46 条由本文档+GDD 承载、12 条待 ADR（见下）、5 条随未设计系统。**2026-09-12 更新：ADR-0001~0004（Foundation 四项）已落定 → 正式工程骨架解冻**；ADR-0005~0008 随对应系统开工前裁决（切片代码可作为参考实现，生产化迁移待 ADR-0008 正式化批）。
|
||||
|
||||
---
|
||||
|
||||
## Required ADRs
|
||||
|
||||
### 必须在正式编码开始前（Foundation 裁决）——✅ 已全部落定（2026-09-12，solo 授权代决，godot-specialist 校验通过）
|
||||
|
||||
1. **✅ ADR-0001 `event-bus-and-orchestration-carrier`**（`adr-0001-event-bus-and-orchestration-carrier.md`）：组合根直连 signal 接线 + B1 Waiting 相位触发；autoload 全局事件总线否决。specialist 增补两条静态规则（方法 Callable only / 发射者禁反向引用）。
|
||||
2. **✅ ADR-0002 `renderer-and-window-config`**（`adr-0002-renderer-and-window-config.md`）：gl_compatibility（绕开 D3D12 新驱动线）；基座 1280×800 + canvas_items + expand 显式落盘。
|
||||
3. **✅ ADR-0003 `scene-structure-and-board-rendering`**（`adr-0003-scene-structure-and-board-rendering.md`）：autoload 仅 {ConfigDB, RngService}；core RefCounted / presentation 九单元组合根；**棋盘渲染 MVP 沿用切片逐格控件形态**（specialist 纠正：切片并非自绘 _draw——迁移登记为 D1 候选工作项含探针改造）；CJK 字体随包为硬性前置。
|
||||
4. **✅ ADR-0004 `test-carrier-and-ci`**（`adr-0004-test-carrier-and-ci.md`）：双载体 + 静态扫描域 S1–S8（specialist 增补 S2 全局 rand* 禁令 / S5 core 禁裸引用 autoload 标识符）+ CI 外部超时；gdUnit4 deferred（D2 OQ1 关闭形态）。
|
||||
|
||||
实现级立场已登记 `docs/registry/architecture.yaml`。
|
||||
|
||||
### 相关系统开工前应有
|
||||
|
||||
5. `/architecture-decision "board-generation-performance"` → ADR-0006：A1 生成性能与异步化（F2c 常数 C 定稿；切片证据 = 10×10/12×12 同步生成可接受——推荐 MVP 同步+加载幕，WorkerThread 留扩展）；度量独立入口确认（切片已实现三入口）。
|
||||
6. `/architecture-decision "unit-api-face-ownership"` → ADR-0007：B2/B1 两 face 归属（query_attack / ambush_grant_plan）+ HeroTable 单行校验落点。
|
||||
7. `/architecture-decision "zero-damage-guard-locus"` → ADR-0008：零伤害死局跨字段/跨表护栏落点（推荐落 D2 跨表校验——切片 LevelTable 校验⑧先例）。
|
||||
8. `/architecture-decision "slice-mechanism-formalization"` → ADR-0009：切片新增机制正式化批（轮内刷新方案 A / RewardSupplyController / LevelTable / grant_node_active / clear_blast）——GDD+registry 接口漂移修订的 ADR 化登记。
|
||||
|
||||
### 已落定（2026-09-12 追加）
|
||||
|
||||
0. **✅ ADR-0005 `save-contract-and-schema-versioning`**（`adr-0005-save-contract-and-schema-versioning.md`）：Foundation 层收口——SCHEMA_VERSION 比较归属 + RNG 快照切点契约 ADR 化（TR-d2-010 / TR-gc-002），Foundation 零缺口闭合。
|
||||
|
||||
### 可推迟
|
||||
|
||||
- ADR-0010 A1 EC5 运行期熔断（连续降级确定性回退已知好种子）
|
||||
- ADR-0011 B5 战斗舞台（棋盘上 vs 独立场景）——"战斗表现美术测试"后裁决
|
||||
- ADR-0012 A5 探测显影接口
|
||||
- ADR-0013 D3 存档格式（RNG 快照契约已由 ADR-0005 锁定，格式归 Alpha）
|
||||
- C2/C3/C4 结构性决策随各系统 GDD 立项
|
||||
|
||||
---
|
||||
|
||||
## Architecture Principles
|
||||
|
||||
1. **Core 纯逻辑、headless 完整可跑**——Core/Feature 玩法逻辑零 Control/场景引用、零 UI 依赖；`--headless --script` 可跑完整战斗（D2 Rule 7 工程债；切片 88 冒烟实证）。输入是意图对象、输出是事件流/步骤流，D1 与输入设备皆可替换。
|
||||
2. **单一事实源与零字面量**——玩法数值只存在于 `data/tables/*.tres`，经 ConfigDB 类型化单点读取；代码零玩法数值字面量；参数禁止跨系统复制（D2 Rule 1/2）。
|
||||
3. **封闭 RNG 与可回放**——玩法代码零随机；一切随机经 RngService 具名封闭流（增流走 P1 评审）；同种子 + 同输入序列 ⇒ 事件流/步骤流逐位相同（结算禁 await，B1 承重约束）。
|
||||
4. **编排唯一性与事件面封闭**——战斗域跨系统调用权集中 B1（静态扫描承载）；A2 三事件面封闭即负空间；每格受理、每雷转化、每次推进、每次衰减各恰一次。
|
||||
5. **fail-fast + 零特判**——数据错误一律致命中止（错误数值上线比崩溃更伤）；API 非法 = 拒绝 + 诊断不静默；变异零运行时分支（行为差异全部由生成端约束保证）。
|
||||
6. **依赖单向 + 组合根模式**——层间单向依赖、唯一回边 = A2 事件订阅面；核心写调用唯一发生在组合根；禁上帝对象（切片 1100 行 main.gd 反面案例 → 9 单元拆分）。
|
||||
7. **呈现层契约成文**——面向呈现的信号载荷必须有成文 schema；模态覆盖层必须有"打开时遮挡物隐藏"场景级断言；场景级 UI 探针测试为标配（切片缺陷 ①②④⑤ 教训沉淀）。
|
||||
|
||||
---
|
||||
|
||||
## Open Questions
|
||||
|
||||
| ID | Summary | Priority | Resolution Path |
|
||||
|----|---------|----------|-----------------|
|
||||
| QQ-01 | 渲染器选择（Forward+ vs gl_compatibility）与项目窗口基线 | High | ADR-0002（正式骨架前） |
|
||||
| QQ-02 | 事件总线载体与 A2 事件捕获测试 API | High | ADR-0001（正式骨架前） |
|
||||
| QQ-03 | gdUnit4 是否引入并迁移冒烟用例 | Medium | ADR-0004（可推迟到正式 CI 期；D2 OQ1） |
|
||||
| QQ-04 | 轮内刷新数值连锁（清图支配性条款⑤ / 真人刷图行为获取期望）重算 | Medium | playtest 实测 + ADR-0008 正式化批 |
|
||||
| QQ-05 | 战斗末可选类"j==0 补发 1 件"兜底是否采纳（切片遗留待办） | Medium | playtest + B4 GDD 修订批 |
|
||||
| QQ-06 | 可选类退出格子池后 buff 频率被动上升（44%→59%）的难度对冲杠杆（敌 HP / 权重 / 幅度） | High | C3 调参 + 切片数据复测 |
|
||||
| QQ-07 | 标错惩罚（A2 OQ1：候选敌方伏击+1；hit=false 无去重的不对称裁决） | Medium | 原型小补丁实测会话（可与 v3 终验合并） |
|
||||
| QQ-08 | B5 双舞台陷阱（战斗发生在棋盘上还是独立场景） | Low（B5 前） | 战斗表现美术测试 → ADR-0010 |
|
||||
| QQ-09 | C3 消费 B1 对账输出的事实依赖回写 systems-index | Low | C3 GDD 定稿时 |
|
||||
| QQ-10 | `.claude/docs/director-gates.md` 缺失（TD-ARCHITECTURE/LP-FEASIBILITY 判据无载体） | Low | 补建 gate 定义文件或维持 solo/lean 模式约定 |
|
||||
@@ -0,0 +1,102 @@
|
||||
# 战斗棋盘 Node2D 渲染迁移方案（Phase A：仅棋盘）
|
||||
|
||||
> 状态：**草稿待审**（2026-09-23 起草，board-node2d-plan-20260923 worktree）。
|
||||
> 上位裁决：ADR-0006（分工与形态）、用户 2026-09-23 拍板「Node2D 重构只迁战斗棋盘，开始菜单/各覆盖层保持 Control；战斗画面 Node 后续批完成」。
|
||||
> 本文档是 Phase A 实施批的工程方案；批准后实施批从本文开工，不再另起炉灶。
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
把 D 区棋盘本体从「GridContainer + 逐格 Button」换成「Control 壳 + SubViewport + Node2D 世界」，BoardView 类名与公共面契约逐项保持——探针与组合根零改造，素材终稿到位后 1:1 换图零返工。
|
||||
|
||||
## 1. 目标形态（已与用户确认的三块模型）
|
||||
|
||||
战斗屏 = 两块 Node2D 舞台 + 一层 Control 面板。术语校准：Godot 没有「Canvas」节点——面板层是 Control 树（常驻顶层与弹层经 CanvasLayer，现状已如此）；Node2D 不参与 Control 容器布局，所以每块舞台包一个 Control 壳（SubViewportContainer）参与屏幕栅格布局，壳内才是 Node2D 世界。
|
||||
|
||||
```
|
||||
BattleScreen（Control 栅格；目标形态 = B/C/D 三区——进度条退场裁定见下）
|
||||
├── B 战斗画面（Phase B 改造，本批不动）
|
||||
│ ├── Node2D 舞台壳：主角/敌人站桩、意图动画、演出（后续批）
|
||||
│ └── Control 半区：结算明细带、回合指示、战斗日志（永久 Control）
|
||||
├── C 角色信息 .................. Control（不动）
|
||||
└── D 扫雷图
|
||||
├── AP 条、按钮组、toast .... Control（不动）
|
||||
└── BoardView（本批改造对象）
|
||||
└── SubViewportContainer（Control 壳，参与布局）
|
||||
└── SubViewport（逻辑分辨率 = 格边长 × 板尺寸）
|
||||
└── BoardWorld（Node2D）
|
||||
└── CellUnit × N（Node2D，每格一个）
|
||||
```
|
||||
|
||||
**进度条退场裁定（2026-09-23 用户）**：战斗画面不再有关卡进度条——战斗结束后返回关卡画面，节点链进度只留关卡画面。
|
||||
|
||||
**A 区代码命运（2026-09-23 追问裁定）：退役，不迁移。关卡画面不重新实现。**
|
||||
|
||||
- **关卡画面 = RouteOverlay 升级**：现役选路覆盖层已是整幅节点图 + 全套节点态语义（暗金已过/金当前/暗未达/亮金候选通道/紫赤 Boss 边（旗朱→紫赤 2026-09-26 封印紫批），与压缩条同一组 UiKit token）+ 候选按钮 + 放弃入口。停点前移批只改开合时机（关卡开始即开、战后返回即开）与流程接线（选路确认不再经兑付停点绕行），渲染本体零重写。
|
||||
- **LevelStripView 不迁移的理由**：它唯一的存在理由 = 战斗屏上看不到整图时的 28px 压缩常显替代面。地图页上压缩条冗余（整图即进度），战斗屏又已裁定零进度显示——迁过去没有消费者。其语义无独有资产（色板/节点态与 RouteOverlay 同族），单链退化渲染（全链横条）被整图布局天然取代。
|
||||
- **唯一继承面 = 逻辑层数据面**：runner 只读出口（`nodes()` / `visited_ids()` / 节点编号空间 / `next_candidates()`）零改动——压缩条与整图本来就消费同一份数据，这正是"退役不迁移"成立的根据。
|
||||
|
||||
排程事实与修订面：
|
||||
|
||||
1. **A 区现状代码继续服役**：当前流程尚未倒置（冒险开局直进战斗，节点图是战后弹层），A 区顶栏是战斗过程中唯一的节点链可视面——先删会致盲。退场落地 = 停点前移批，届时四区→三区。
|
||||
2. **停点前移批的删除面清单**（退役随该批执行）：`LevelStripView` 类、ui_assembler 组装行（:28）、main.gd `strip_view` 引用（:52 等）、ui_probe 两处断言（:77–78 节点条构建检查、:188 报告行）、battle.md A 区条款。
|
||||
3. **该批的 GDD 修订面**：HUD框架.md 四区结构表（含 B/C/D 是否重新编字母）、关卡节点地图.md 节点链常显条款（常显载体随进度条退役，由关卡画面本体承接）、battle.md 像素布局表（28px 纵向空间再分配）。
|
||||
|
||||
## 2. Phase A 范围（本批做）
|
||||
|
||||
1. **BoardView 内部重构**（`presentation/views/board_view.gd`）：
|
||||
- 根仍是 Control（类名/extends 不变），子结构 GridContainer → SubViewportContainer + SubViewport + BoardWorld。
|
||||
- `_cells`：Vector2i → CellUnit（Node2D）字典，键面与现 Dict 同构（探针断言面，见 §4）。
|
||||
- CellUnit 内部固定叠层序：砖面底 < 变异纹带 < 数字/徽章 < 旗 < 焦点高亮——本批全程序化绘制（`_draw`），等价平移现行视觉；每个叠层留 `texture` 槽位（§8.2 暂定档 32×32），终稿纹理换入即用。
|
||||
- 现有行为逐项平移：呼吸微光（StyleBoxFlat 边框 → `_draw` 边框）、悬停反白、路径预览、危险红、双击 chord 检测、`set_desaturated`（ShaderMaterial 挂 BoardWorld 材质）。
|
||||
2. **输入换板**：BoardView 壳层 `_gui_input` 接鼠标 → 格坐标单点公式 `floor(local_pos / cell_edge)` → 复用现有 hover/click/chord/长按逻辑；`action_requested` 信号链不变。
|
||||
3. **`cell_size` 只读属性增补**：现私有名 `_cell`，ui_layout_probe `get("cell_size")` 读到 null——补只读属性，顺手修正。
|
||||
4. **push_input 端到端输入探针**（新增，ADR-0003 登记项转义务）：合成鼠标事件经真实输入路径打 SubViewportContainer，验悬停/左键/右键/chord 四 case——现探针全走 `click_cell` 直调，公式换算无覆盖，这是唯一新增自动化面。
|
||||
5. **冒烟全量回归 + 文档随批**：HUD框架.md 渲染技术注记（v0.x 版本行）、battle.md 实现注记（格尺寸公式锚点不动）、architecture.md BoardView 形态行、ui_kit 同步面清点。
|
||||
|
||||
**不做**（明确出批）：B 区舞台任何改动；素材终稿接入；格边长数值调整（归样张批）；键盘寻格/无障碍（沿 ADR-0003 已接受口径）。
|
||||
|
||||
## 3. Phase B（2026-09-26 已落地——战斗舞台 Node2D 迁移批，台账 170-173）
|
||||
|
||||
- BattleStageView 同构改造**已实施**：PanelContainer → Control 壳（类名/252px/树内位置不变）+ Node2D 舞台半区（SubViewportContainer/SubViewport/StageWorld）+ Control 文本半区（round_label/stage_center/log_view 三件保留）；站桩 StandeeView（Control）退役删除，本体 = StandeeBody（Node2D 世界精灵，行为面 17 方法契约保持）；slot_row+悬停 tooltip 保留 Control 载体挂壳层（伴随件容器 = enemy_box 语义改写）。
|
||||
- Phase A 交付的两挂点已被 Phase B 复用：set_world_font 字体显式注入（C6 判据=注入非空+has_char+宽度>0）与坐标空间分界纪律（世界=局部排布，壳层换算单点 world_to_shell）。
|
||||
- **样张硬前置改判（用户 2026-09-26 裁决①）**：样张批冻结只卡换皮/演出批（循环 2 前置），不卡结构迁移——本节原「Phase B 开工硬前置 = 样张批冻结」条款据此作废；ADR-0006「只卡换皮不卡开工」原则的落文位。
|
||||
|
||||
## 4. 探针与测量面（实证清单）
|
||||
|
||||
| 探针/工具 | 耦合点（实证） | Phase A 处置 |
|
||||
|---|---|---|
|
||||
| ui_probe | `board_view._cells.is_empty()`（:73）、`_cells.size()` 对板宽高（:187）、`board()`/`set_desaturated()` | `_cells` 键面同构即绿，零改 |
|
||||
| ui_click_probe | `click_cell(cell, button)` 直调（:257–277）、`_cells.is_empty()`（:97）；**无合成鼠标事件**（grep parse_input_event/push_input 零命中） | 公共方法保留即绿，零改 |
|
||||
| ui_layout_probe | `get("cell_size")`（:39，现读 null）、`board()` | 增补只读属性（§2.3） |
|
||||
| smoke 行协议同步闸 | 战斗日志 9 类行格式化（smoke_all.gd:3325+）——**是日志行不是棋盘** | 零影响，全量回归覆盖 |
|
||||
| MC / 模拟试玩 / verifier | core/ 逻辑层 | 零接触零影响 |
|
||||
|
||||
## 5. 性能与预算
|
||||
|
||||
- draw calls：CellUnit 同材质 `_draw` 走 2D 批处理，144 格占位态预计个位数批次；预算 < 200 维持（HUD框架 引用值），实施批用 RenderingServer 实测数回填。
|
||||
- 进入战斗屏 500ms 可交互：SubViewport 创建在 `_ready` 一次完成，无逐帧重建；`set_cell_area`/`rebuild` 只重排子节点。
|
||||
- SubViewport 逻辑分辨率 = 格边长 × 板尺寸（≤ 36px × 14 格量级），渲染目标显存占用可忽略；低端机帧预算实施批实测。
|
||||
|
||||
## 6. 风险与对策
|
||||
|
||||
| 风险 | 对策 |
|
||||
|---|---|
|
||||
| SubViewport 内 Label 不继承主场景主题（数字/中文渲染空白或字体错） | 实施批第一小步先做 theme/字体显式注入挂点并用 CJK 冒烟验证——ADR-0006 Verification Required 项 |
|
||||
| 45/36px 锚点 × 32px 格源非整倍缩放出现像素纹路 | 架构只保证 `set_cell_area` 单点可调；数值归样张批（圣经 §8.2 v1.9 注记①路线），本批不裁决 |
|
||||
| `_gui_input` 与 toast/AP 条控件输入抢占 | D 区内部布局不变（Control 兄弟件照旧），棋盘壳是叶节点，抢占面与现 GridContainer 相同；探针四 case 覆盖 |
|
||||
| 改造期行为漂移（呼吸微光/chord 时序等隐性手感） | 功能等价清单（ADR-0006 Validation）逐项人工核对 + 探针自动化面 |
|
||||
|
||||
## 7. 排期与依赖
|
||||
|
||||
| 项 | 估时 | 依赖 |
|
||||
|---|---|---|
|
||||
| 本起草批（ADR-0006 + 本方案 + ADR-0003 注记） | 已完成，待审 | 无 |
|
||||
| Phase A 实施批 | 1–2 天（含探针增补 + 冒烟回归 + 文档随批） | 本方案批准 |
|
||||
| 样张批（素材侧，另线） | 未排 | 主角候选表态 + 复用批审阅 |
|
||||
| Phase B 实施批 | 未排（同构复制，估时随 Phase A 实测修正） | Phase A 落地 + 样张批冻结 |
|
||||
|
||||
与在飞批的关系：曲线调参双刀扫描（worktree hp-bonus-scan-20260923）与本批文件集零交集；UI 复用候选审阅是素材侧独立线，互不阻塞。
|
||||
|
||||
## 8. 验收（实施批完成定义）
|
||||
|
||||
ADR-0006 Validation Criteria 全项：冒烟全量绿 + 三探针绿 + 新增 push_input 探针绿 + 功能等价清单逐项可验 + draw calls < 200 实测回填 + 两档分辨率装板校验（12×12 与 10×10 各验）。
|
||||
@@ -0,0 +1,132 @@
|
||||
# 代码架构审查报告 — 代码组织与封装
|
||||
|
||||
> 日期：2026-09-13
|
||||
> 载体：`game/`（9707 行 GDScript：core 12 文件 / data 11 / presentation 28 / smoke 10）
|
||||
> 基线：`docs/architecture/architecture.md` v1.0 + ADR-0001~0005 + `docs/code-conventions.md`
|
||||
> 触发：用户在 code-review 之后要求补充「代码组织问题 + 封装问题」专项审查
|
||||
> 审查方式：core/presentation 关键文件全读 + S1–S8 静态规则逐条 grep 验证 + 跨层引用面扫描
|
||||
>
|
||||
> **Verdict: CONCERNS** — 分层纪律实测扎实（S1–S7 零违例、仅 2 处已登记例外），但封装收口存在
|
||||
> 一条系统性欠账：核心模块内部状态以公有字段暴露，呈现层已形成链式穿透的既成事实。
|
||||
> 原型期无害；是 ADR-0009「切片机制正式化批」应收口的主题。
|
||||
|
||||
---
|
||||
|
||||
## 1. 正面观察（实测合规项）
|
||||
|
||||
| 规则 | 结论 | 证据 |
|
||||
|---|---|---|
|
||||
| S1/S2 零随机 | ✅ | core 内唯一 `RandomNumberGenerator.new` 在 rng_service.gd:76（所有者本体）；`stream.randf()`（reward_supply_controller.gd:32）取号经 B4 注入封闭流 |
|
||||
| S3 零表加载 | ✅ | core 内唯一 `load()` 在 config_db.gd:81（单点本体） |
|
||||
| S4 core 零 UI | ✅ | core/ 无 Control/Node2D/.tscn 引用（grep 命中均为 `RewardSupplyController` 类名误报与注释） |
|
||||
| S5 零裸引用 autoload | ✅ | core/ 内 ConfigDB/RngService 命中均为日志前缀字符串 |
|
||||
| S6 core↔core 方法 Callable | ✅ | level_runner.gd:130-134 全部方法转发；lambda 仅用于 sort_custom（不捕获 self） |
|
||||
| S7 编排唯一性 | ✅ | B2/B3/B4 调用面 core 内收口于 battle_orchestrator.gd；仅 level_runner.gd:112（grant_node_active，已登记接口漂移）与 :168（in_stock_count 只读）两处例外 |
|
||||
| 呈现层零核心引用 | ✅ | 28 个视图/装配器文件中仅 main.gd（组合根）与 hud_presenter.gd（授权翻译点）触 core |
|
||||
| 封装典范 | — | status_container / reward_supply_controller / b4.query_inventory()：私有状态 + 投影查询 + 授予时快照；battle_orchestrator.diagnostic_snapshot()（:660）为「成文只读出口」正确先例 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 封装问题（按根因 → 表征排序）
|
||||
|
||||
### E1（根因）编排器协作对象全公开，呈现层链式穿透已成既成事实 — P1
|
||||
|
||||
- **位置**：core/battle_orchestrator.gd:20-27（`var a1/a2/a3/b2/b3/b4` 全公有）
|
||||
- **表征**：`b1.a2.board`、`b1.b2.hero.hp`、`b1.a3.phase` 式层层下钻——main.gd 18 处、hud_presenter.gd 15 处。
|
||||
- **影响**：组合根与 presenter 是授权翻译点，但访问形态是「恰好字段公开」而非「B1 提供成文读取面」。
|
||||
S7 只能做文件级扫描（防另写调用方），防不了呈现层意外调用写 API，也防不了读取路径随重构漂移。
|
||||
- **建议**：B1 补聚合呈现快照/查询面（`hud_state()` 一类，先例 = `diagnostic_snapshot()`）；
|
||||
a2–b4 下划线化后经命名代理暴露只读操作。
|
||||
|
||||
### E2（表征）视图绕过 A2 查询面直读原始状态字典 — P1
|
||||
|
||||
- **位置**：core/minesweeper_rules.gd:18-20（`board/revealed/flags` 公开可变）；
|
||||
presentation/views/board_view.gd:278、:303 直接 `_a2.revealed.get(c, {})`
|
||||
- **矛盾点**：board_view.gd:7 头注自称「只读 A2 查询面」——直读 `.revealed` 恰是绕过查询面。
|
||||
B1 自身亦直读（battle_orchestrator.gd:565-569 `a2.board.width/height`）。
|
||||
- **建议**：`revealed/flags` 私有化；补 `reveal_record(c) -> Dictionary`、`board_dimensions()` 查询面。
|
||||
调用点仅 B1 + board_view + main 三处，成本很低。
|
||||
|
||||
### E3（表征）B2 裸字典句柄跨模块传递，API 缺「含死亡残位」查询面 — P2
|
||||
|
||||
- **位置**：core/unit_container.gd:13-14（`hero/enemies` 公开；句柄 = Dictionary 本体，任何持有者可
|
||||
`u.hp = 999` 绕过 apply_damage）
|
||||
- **现症**：hud_presenter.gd:78-79 为渲染死亡残位直读 `b1.b2.enemies` 原始数组——
|
||||
B2 的 `query_alive` 不含死亡单位，API 缺口迫使呈现层越界（B2 头注已登记此痛点）。
|
||||
- **建议**：短期补 `query_all_units()` 投影面把 presenter 需求收进 API；
|
||||
正式化（ADR-0007 两 face 归属裁决时）再决定是否升级 Unit 类型。
|
||||
|
||||
### E4 `db.hero` 表值运行时改写——测试覆盖通道用共享可变单例传参 — P2
|
||||
|
||||
- **位置**：presentation/main.gd:327-329、core/level_runner.gd:60-61,75-76 直接写 `db.hero.atk/max_hp`；
|
||||
B2.spawn 经读表间接获得加成值
|
||||
- **前科**：双写叠加 6→18→54 教训、双基线同步义务（main.gd:187-189 注释）——纪律已成文但机制脆弱。
|
||||
- **建议**：切片保留；将「运行时表可变」登记进 ADR-0009 候选；正式化改参数传递（`spawn(atk_override=...)`）。
|
||||
|
||||
### E5 「只读」字段仅靠纪律，无机制约束 — P2
|
||||
|
||||
- **位置**：core/action_economy.gd:17-20（`phase/ap/rap/last_round_end` 架构文档定义为只读，实际公开可变）；
|
||||
core/rng_service.gd:19（`master_seed` 可绕过 set_master_seed 的计数器全零断言）
|
||||
- **现状**：当前调用方全部合规（A2 经 try_spend/request_dig，B1 经 notify_*，呈现层只读）。
|
||||
- **建议**：下划线化 + 查询方法（`phase()/ap()/rap()`），趁调用方少时收口，成本极低。
|
||||
|
||||
### E6 小项 — P3
|
||||
|
||||
| 项 | 位置 | 说明 |
|
||||
|---|---|---|
|
||||
| 返回类型多态 | core/reward_economy.gd（grant/stock/use 失败返 `false`，query_* 返 `null`） | B1 消费处被迫 `if not (snap is Dictionary)`；统一 `null` 更符合 GDScript 惯例 |
|
||||
| 泄漏原始表行 | core/reward_economy.gd:256-265 `equivalence_supply` 返回 `db.reward.rows` 行引用（可变） | 工具观测面，建议 `duplicate()` |
|
||||
| BoardData 全公开 | core/board_data.gd:8-18「生成后不可变」仅靠注释；视图持板即可读全部雷位（当前未作弊） | 正式化时 duplicate 冻结或下划线化 + 访问器 |
|
||||
| 成员声明位置 | core/action_economy.gd:121 `var _next_round_mode` 声明在中部、使用在前 | 集中到顶部 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 代码组织问题
|
||||
|
||||
### O1 main.gd 回涨至 667 行，再越 ~400 行审视线（规范 1.1）— P1
|
||||
|
||||
- **位置**：presentation/main.gd（667 行）；ui_assembler.gd:3 自记「回涨 761 行触发审视线——拆出」历史
|
||||
- **增长主因**：调试模式（`_start_single/_start_debug_levels/_start_battle/_on_battle_finished` 的
|
||||
`_level_mode` 分支约 100+ 行）糊在组合根。
|
||||
- **建议**：照 tune_sim_controller.gd 先例把调试模式抽成独立控制器，组合根回到纯接线。
|
||||
|
||||
### O2 调试模式与 LevelRunner 平行实现，语义漂移风险 — P1
|
||||
|
||||
- **位置**：「库存跨战斗延续 + HP 携带 + 层级推进」存在两份实现——core/level_runner.gd（正式）与
|
||||
main.gd 调试分支（历史入口）；`level_clear()` 调用时点已各有细节（main.gd:367,376 vs level_runner.gd:167）。
|
||||
- **建议**：调试两层模式直接复用 LevelRunner（其设计目标即此），或抽 `DebugBattleSession`。
|
||||
|
||||
### O3 B1 体量与纯函数沉淀 — P2
|
||||
|
||||
- **位置**：core/battle_orchestrator.gd 718 行（审视线超 300+）；
|
||||
伤害公式族 `_resolve_damage/_charge_damage_component/_armor_effectiveness/_clamped_pool`
|
||||
（约 80 行）为零状态纯算术。
|
||||
- **建议**：按规范 1.2 抽 `DamageMath` 静态宿主类；段序骨架不动、可回放承诺无风险。
|
||||
- **顺带**：core/board_generator.gd:50-55 对同一张合法板调用两次 `measure_inferability`
|
||||
（全库最贵求解器）——合并为一次。
|
||||
|
||||
### O4 呈现层反向依赖 smoke 工具域 — P2
|
||||
|
||||
- **位置**：presentation/tune_sim_controller.gd:23 `load("res://smoke/level_autoplay.gd")`——
|
||||
UI 控制器依赖测试工具目录。
|
||||
- **建议**：「关卡自动模拟循环」上移为共享组件（core 或 lib），smoke 与 tune_sim 共同消费。
|
||||
- **顺带**：main.gd:106,188 与 tune_sim_controller.gd:23 用运行时字符串 `load()`，
|
||||
与 main.gd:16-19 的 `preload` 常量风格混用——统一 `preload`（编译期路径校验）。
|
||||
|
||||
### O5 头注溯源缺失（规范 1.4）— P3
|
||||
|
||||
core/ 12 文件中 4 个缺标准 `# 实现 GDD：...` 行：
|
||||
`board_data.gd`（有 A1 描述但非标准格式）、`config_db.gd`、`rng_service.gd`、`reward_supply_controller.gd`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 建议行动顺序
|
||||
|
||||
1. **P1 三连（合计约 2 天）**：
|
||||
E2（A2 状态私有化 + 查询面）→ E1（B1 呈现快照面）→ O1+O2（调试模式抽离/复用 runner）。
|
||||
完成后 board_view / hud_presenter / main 与 core 的接触面全部变为命名 API，封装收口完成。
|
||||
2. **P2 项并入 ADR-0009「切片机制正式化批」裁决**：E4 表值改写参数化、E3 单位句柄形态、
|
||||
O3 DamageMath 拆分、O4 模拟循环上移。
|
||||
3. **P3 顺手清**（头注补齐、返回值统一、声明位置、preload 统一）。
|
||||
|
||||
> 复审触发：P1 三连落地后重跑本审查核对接触面收口；ADR-0009 落定后正式工程骨架迁移前复核 E3/E4 裁决结果。
|
||||
@@ -0,0 +1,413 @@
|
||||
{
|
||||
"schema_version": 1,
|
||||
"diagram_type": "architecture",
|
||||
"meta": {
|
||||
"title": "Dungeon Sweeper · GDD 概念结构图",
|
||||
"output": "docs/architecture/gdd-concept-map.html",
|
||||
"quality_profile": "showcase",
|
||||
"locale": "zh-CN",
|
||||
"viewBox": [
|
||||
1364,
|
||||
660
|
||||
],
|
||||
"views": [
|
||||
{
|
||||
"id": "core-loop",
|
||||
"label": "核心循环主链",
|
||||
"focus": [
|
||||
"board-gen",
|
||||
"minesweeper",
|
||||
"action-economy",
|
||||
"settlement",
|
||||
"adventure",
|
||||
"difficulty"
|
||||
],
|
||||
"note": "主路径：新雷图 → 挖掘计费 → 轮末结算 → 关卡推进 → 难度抬升。"
|
||||
},
|
||||
{
|
||||
"id": "settlement-hub",
|
||||
"label": "结算枢纽与红线",
|
||||
"focus": [
|
||||
"settlement",
|
||||
"enemy",
|
||||
"status",
|
||||
"rewards",
|
||||
"hud"
|
||||
],
|
||||
"note": "战斗结算是战斗域唯一调用方；呈现层只订阅结算步骤流。"
|
||||
},
|
||||
{
|
||||
"id": "foundation",
|
||||
"label": "支撑底座",
|
||||
"focus": [
|
||||
"data-config",
|
||||
"board-gen",
|
||||
"settlement",
|
||||
"hud"
|
||||
],
|
||||
"note": "ConfigDB 单点 + RngService 四流，被全部系统取用。"
|
||||
}
|
||||
]
|
||||
},
|
||||
"components": [
|
||||
{
|
||||
"id": "board-gen",
|
||||
"type": "backend",
|
||||
"label": "棋盘生成",
|
||||
"sublabel": "可推理·可通关",
|
||||
"pos": [
|
||||
50,
|
||||
300
|
||||
],
|
||||
"size": [
|
||||
130,
|
||||
64
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "minesweeper",
|
||||
"type": "backend",
|
||||
"label": "排雷玩法",
|
||||
"sublabel": "挖格·插旗·连锁",
|
||||
"pos": [
|
||||
240,
|
||||
300
|
||||
],
|
||||
"size": [
|
||||
136,
|
||||
64
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "action-economy",
|
||||
"type": "backend",
|
||||
"label": "行动经济",
|
||||
"sublabel": "AP 账本·停手/刷新",
|
||||
"pos": [
|
||||
436,
|
||||
300
|
||||
],
|
||||
"size": [
|
||||
140,
|
||||
64
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "settlement",
|
||||
"type": "backend",
|
||||
"label": "战斗结算",
|
||||
"sublabel": "轮末编排·逐行兑现",
|
||||
"pos": [
|
||||
648,
|
||||
300
|
||||
],
|
||||
"size": [
|
||||
156,
|
||||
72
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "adventure",
|
||||
"type": "backend",
|
||||
"label": "冒险结构",
|
||||
"sublabel": "关卡序列·大奖励",
|
||||
"pos": [
|
||||
952,
|
||||
300
|
||||
],
|
||||
"size": [
|
||||
136,
|
||||
64
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "difficulty",
|
||||
"type": "backend",
|
||||
"label": "难度曲线与Boss",
|
||||
"sublabel": "期望值带·Dmax",
|
||||
"pos": [
|
||||
1152,
|
||||
300
|
||||
],
|
||||
"size": [
|
||||
150,
|
||||
64
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "aux-items",
|
||||
"type": "backend",
|
||||
"label": "魔法道具",
|
||||
"sublabel": "显影·探测类",
|
||||
"pos": [
|
||||
240,
|
||||
140
|
||||
],
|
||||
"size": [
|
||||
136,
|
||||
64
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "enemy",
|
||||
"type": "backend",
|
||||
"label": "敌人系统",
|
||||
"sublabel": "敌人数据·意图",
|
||||
"pos": [
|
||||
651,
|
||||
140
|
||||
],
|
||||
"size": [
|
||||
150,
|
||||
64
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "hud",
|
||||
"type": "frontend",
|
||||
"label": "HUD框架",
|
||||
"sublabel": "呈现契约·布局",
|
||||
"pos": [
|
||||
244,
|
||||
470
|
||||
],
|
||||
"size": [
|
||||
136,
|
||||
64
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "data-config",
|
||||
"type": "database",
|
||||
"label": "数据配置",
|
||||
"sublabel": "ConfigDB·RngService",
|
||||
"pos": [
|
||||
37,
|
||||
470
|
||||
],
|
||||
"size": [
|
||||
156,
|
||||
64
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "status",
|
||||
"type": "backend",
|
||||
"label": "增益状态",
|
||||
"sublabel": "容器·叠层·衰减",
|
||||
"pos": [
|
||||
614,
|
||||
470
|
||||
],
|
||||
"size": [
|
||||
130,
|
||||
64
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "rewards",
|
||||
"type": "backend",
|
||||
"label": "地图战斗资源",
|
||||
"sublabel": "格面资源·清图奖励",
|
||||
"pos": [
|
||||
776,
|
||||
470
|
||||
],
|
||||
"size": [
|
||||
136,
|
||||
64
|
||||
]
|
||||
}
|
||||
],
|
||||
"boundaries": [
|
||||
{
|
||||
"kind": "region",
|
||||
"label": "排雷循环",
|
||||
"wraps": [
|
||||
"board-gen",
|
||||
"minesweeper",
|
||||
"action-economy",
|
||||
"aux-items"
|
||||
]
|
||||
},
|
||||
{
|
||||
"kind": "region",
|
||||
"label": "战斗循环",
|
||||
"wraps": [
|
||||
"settlement",
|
||||
"enemy",
|
||||
"status",
|
||||
"rewards"
|
||||
]
|
||||
},
|
||||
{
|
||||
"kind": "region",
|
||||
"label": "冒险循环",
|
||||
"wraps": [
|
||||
"adventure",
|
||||
"difficulty"
|
||||
]
|
||||
},
|
||||
{
|
||||
"kind": "region",
|
||||
"label": "表现与支撑",
|
||||
"wraps": [
|
||||
"data-config",
|
||||
"hud"
|
||||
]
|
||||
}
|
||||
],
|
||||
"connections": [
|
||||
{
|
||||
"id": "gen-to-mines",
|
||||
"from": "board-gen",
|
||||
"to": "minesweeper",
|
||||
"label": "生成雷图",
|
||||
"variant": "emphasis"
|
||||
},
|
||||
{
|
||||
"id": "mines-to-ap",
|
||||
"from": "minesweeper",
|
||||
"to": "action-economy",
|
||||
"label": "挖掘花费 AP",
|
||||
"variant": "emphasis"
|
||||
},
|
||||
{
|
||||
"id": "ap-to-settle",
|
||||
"from": "action-economy",
|
||||
"to": "settlement",
|
||||
"label": "round_end",
|
||||
"variant": "emphasis"
|
||||
},
|
||||
{
|
||||
"id": "settle-to-enemy",
|
||||
"from": "settlement",
|
||||
"to": "enemy",
|
||||
"label": "兑现敌人行动"
|
||||
},
|
||||
{
|
||||
"id": "settle-to-status",
|
||||
"from": "settlement",
|
||||
"to": "status",
|
||||
"label": "兑现增益减益",
|
||||
"fromSide": "bottom",
|
||||
"toSide": "top",
|
||||
"labelAt": [
|
||||
679,
|
||||
447
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "settle-to-rewards",
|
||||
"from": "settlement",
|
||||
"to": "rewards",
|
||||
"label": "兑现格面奖励",
|
||||
"fromSide": "bottom",
|
||||
"toSide": "top"
|
||||
},
|
||||
{
|
||||
"id": "settle-to-adv",
|
||||
"from": "settlement",
|
||||
"to": "adventure",
|
||||
"label": "结果推进关卡",
|
||||
"variant": "emphasis"
|
||||
},
|
||||
{
|
||||
"id": "adv-to-diff",
|
||||
"from": "adventure",
|
||||
"to": "difficulty",
|
||||
"label": "关卡定级",
|
||||
"variant": "emphasis",
|
||||
"labelDy": 14
|
||||
},
|
||||
{
|
||||
"id": "diff-to-enemy",
|
||||
"from": "difficulty",
|
||||
"to": "enemy",
|
||||
"label": "数值与 Boss Dmax"
|
||||
},
|
||||
{
|
||||
"id": "mines-to-aux",
|
||||
"from": "minesweeper",
|
||||
"to": "aux-items",
|
||||
"label": "挖掘期使用"
|
||||
},
|
||||
{
|
||||
"id": "base-to-gen",
|
||||
"from": "data-config",
|
||||
"to": "board-gen",
|
||||
"label": "种子与表值",
|
||||
"labelAt": [
|
||||
115,
|
||||
395
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "base-to-settle",
|
||||
"from": "data-config",
|
||||
"to": "settlement",
|
||||
"label": "RNG 流·表值",
|
||||
"fromSide": "top",
|
||||
"toSide": "bottom"
|
||||
},
|
||||
{
|
||||
"id": "settle-to-hud",
|
||||
"from": "settlement",
|
||||
"to": "hud",
|
||||
"label": "结算步骤流",
|
||||
"variant": "dashed",
|
||||
"fromSide": "left",
|
||||
"toSide": "top"
|
||||
},
|
||||
{
|
||||
"id": "adv-to-gen",
|
||||
"from": "adventure",
|
||||
"to": "board-gen",
|
||||
"label": "推进下一关",
|
||||
"variant": "dashed",
|
||||
"fromSide": "bottom",
|
||||
"toSide": "left",
|
||||
"via": [
|
||||
[
|
||||
1020,
|
||||
618
|
||||
],
|
||||
[
|
||||
15,
|
||||
618
|
||||
],
|
||||
[
|
||||
15,
|
||||
332
|
||||
]
|
||||
]
|
||||
}
|
||||
],
|
||||
"cards": [
|
||||
{
|
||||
"dot": "cyan",
|
||||
"title": "核心循环",
|
||||
"items": [
|
||||
"主路径：棋盘生成 → 挖掘计费 → 轮末结算 → 关卡推进 → 难度抬升",
|
||||
"难度参数流入下一关雷图，虚线「推进下一关」闭合整局循环"
|
||||
]
|
||||
},
|
||||
{
|
||||
"dot": "emerald",
|
||||
"title": "结算枢纽与架构红线",
|
||||
"items": [
|
||||
"战斗结算是敌人系统、增益状态、地图战斗资源的唯一调用方",
|
||||
"呈现层只订阅战斗结算步骤流，不直订排雷玩法事件"
|
||||
]
|
||||
},
|
||||
{
|
||||
"dot": "amber",
|
||||
"title": "支撑底座与未上图",
|
||||
"items": [
|
||||
"数据配置（ConfigDB + RngService 四流）被全部系统引用，图中只画主干两笔",
|
||||
"未上图（已定稿）：地形变异、存档序列化、战斗表现、音频、教学引导、设置与本地化",
|
||||
"范围草案：关卡节点地图、元进度"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
File diff suppressed because it is too large.
Load diff
Binary file not shown.
|
After Width: | Height: | Size: 136 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 146 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 171 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 182 KiB |
@@ -0,0 +1,32 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width,initial-scale=1">
|
||||
<title>Archify automated browser evidence · gdd-concept-map.html</title>
|
||||
<style>
|
||||
*{box-sizing:border-box}body{margin:0;padding:24px;background:#e9eef5;color:#172033;font:14px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}header{max-width:1500px;margin:0 auto 18px}h1{margin:0 0 6px;font-size:20px}p{margin:0;color:#526176}.grid{max-width:1500px;margin:auto;display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:18px}figure{margin:0;padding:10px;background:white;border:1px solid #c9d4e3;border-radius:12px;box-shadow:0 10px 30px rgba(15,23,42,.08)}img{display:block;width:100%;height:auto;border:1px solid #e2e8f0}figcaption{padding:9px 4px 2px;color:#526176}@media(max-width:900px){.grid{grid-template-columns:1fr}}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<header><h1>Automated browser evidence</h1><p>gdd-concept-map.html · visual-check containment pass · perceptual visual review pending</p></header>
|
||||
<main class="grid">
|
||||
<figure>
|
||||
<img src="gdd-concept-map.visual-check.1440x900.light.png" alt="light 1440 by 900">
|
||||
<figcaption><strong>LIGHT</strong> · 1440×900 · containment pass</figcaption>
|
||||
</figure>
|
||||
<figure>
|
||||
<img src="gdd-concept-map.visual-check.1440x900.dark.png" alt="dark 1440 by 900">
|
||||
<figcaption><strong>DARK</strong> · 1440×900 · containment pass</figcaption>
|
||||
</figure>
|
||||
<figure>
|
||||
<img src="gdd-concept-map.visual-check.2048x1320.light.png" alt="light 2048 by 1320">
|
||||
<figcaption><strong>LIGHT</strong> · 2048×1320 · containment pass</figcaption>
|
||||
</figure>
|
||||
<figure>
|
||||
<img src="gdd-concept-map.visual-check.2048x1320.dark.png" alt="dark 2048 by 1320">
|
||||
<figcaption><strong>DARK</strong> · 2048×1320 · containment pass</figcaption>
|
||||
</figure>
|
||||
</main>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,548 @@
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"ok": true,
|
||||
"command": "visual-check",
|
||||
"evidenceKind": "automated-browser",
|
||||
"status": "pass",
|
||||
"visualReview": "pending",
|
||||
"artifact": {
|
||||
"path": "D:\\code\\g-plan2\\docs\\architecture\\gdd-concept-map.html",
|
||||
"sha256": "aa7ea12deda2e43cc4d95e8550057f0e4e4d9dc617a968410cd55a0f454dc295",
|
||||
"bytes": 817914
|
||||
},
|
||||
"state": {
|
||||
"detail": "read",
|
||||
"motion": "still"
|
||||
},
|
||||
"chrome": {
|
||||
"status": "available",
|
||||
"executable": "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe"
|
||||
},
|
||||
"diagnostics": [],
|
||||
"containment": {
|
||||
"status": "pass",
|
||||
"viewports": [
|
||||
{
|
||||
"width": 1440,
|
||||
"height": 900,
|
||||
"theme": "light",
|
||||
"innerWidth": 1440,
|
||||
"innerHeight": 900,
|
||||
"scrollWidth": 1440,
|
||||
"scrollHeight": 900,
|
||||
"overflowX": false,
|
||||
"overflowY": false,
|
||||
"ok": true,
|
||||
"readerWidth": 1117,
|
||||
"diagramWidth": 1087,
|
||||
"viewBoxWidth": 1364,
|
||||
"minimumProjectedNodeTextPx": 7.172287390029325,
|
||||
"minimumProjectedNodeText": "可推理·可通关",
|
||||
"minimumProjectedNodeTextDetail": "context",
|
||||
"minimumRequiredNodeTextPx": 6,
|
||||
"readabilityOk": true,
|
||||
"hasLegend": false,
|
||||
"hasNavigationDock": true,
|
||||
"legendDockIntersectionArea": 0,
|
||||
"dockStageIntersectionArea": 0,
|
||||
"dockStageGap": 10.21875,
|
||||
"requiredDockStageGap": 10,
|
||||
"viewerChromeStageOk": true,
|
||||
"viewerChromeReserve": 51,
|
||||
"viewerChromeActive": true,
|
||||
"viewerChromeOk": true,
|
||||
"resolvedTheme": "light"
|
||||
},
|
||||
{
|
||||
"width": 1600,
|
||||
"height": 1000,
|
||||
"theme": "light",
|
||||
"innerWidth": 1600,
|
||||
"innerHeight": 1000,
|
||||
"scrollWidth": 1600,
|
||||
"scrollHeight": 1000,
|
||||
"overflowX": false,
|
||||
"overflowY": false,
|
||||
"ok": true,
|
||||
"readerWidth": 1154,
|
||||
"diagramWidth": 1124,
|
||||
"viewBoxWidth": 1364,
|
||||
"minimumProjectedNodeTextPx": 7.41642228739003,
|
||||
"minimumProjectedNodeText": "可推理·可通关",
|
||||
"minimumProjectedNodeTextDetail": "context",
|
||||
"minimumRequiredNodeTextPx": 6,
|
||||
"readabilityOk": true,
|
||||
"hasLegend": false,
|
||||
"hasNavigationDock": true,
|
||||
"legendDockIntersectionArea": 0,
|
||||
"dockStageIntersectionArea": 0,
|
||||
"dockStageGap": 10.21875,
|
||||
"requiredDockStageGap": 10,
|
||||
"viewerChromeStageOk": true,
|
||||
"viewerChromeReserve": 51,
|
||||
"viewerChromeActive": true,
|
||||
"viewerChromeOk": true,
|
||||
"resolvedTheme": "light"
|
||||
},
|
||||
{
|
||||
"width": 1920,
|
||||
"height": 1080,
|
||||
"theme": "light",
|
||||
"innerWidth": 1920,
|
||||
"innerHeight": 1080,
|
||||
"scrollWidth": 1920,
|
||||
"scrollHeight": 1080,
|
||||
"overflowX": false,
|
||||
"overflowY": false,
|
||||
"ok": true,
|
||||
"readerWidth": 1320,
|
||||
"diagramWidth": 1290,
|
||||
"viewBoxWidth": 1364,
|
||||
"minimumProjectedNodeTextPx": 8.511730205278592,
|
||||
"minimumProjectedNodeText": "可推理·可通关",
|
||||
"minimumProjectedNodeTextDetail": "context",
|
||||
"minimumRequiredNodeTextPx": 6,
|
||||
"readabilityOk": true,
|
||||
"hasLegend": false,
|
||||
"hasNavigationDock": true,
|
||||
"legendDockIntersectionArea": 0,
|
||||
"dockStageIntersectionArea": 0,
|
||||
"dockStageGap": 10.21875,
|
||||
"requiredDockStageGap": 10,
|
||||
"viewerChromeStageOk": true,
|
||||
"viewerChromeReserve": 51,
|
||||
"viewerChromeActive": true,
|
||||
"viewerChromeOk": true,
|
||||
"resolvedTheme": "light"
|
||||
},
|
||||
{
|
||||
"width": 2048,
|
||||
"height": 1320,
|
||||
"theme": "light",
|
||||
"innerWidth": 2048,
|
||||
"innerHeight": 1320,
|
||||
"scrollWidth": 2048,
|
||||
"scrollHeight": 1320,
|
||||
"overflowX": false,
|
||||
"overflowY": false,
|
||||
"ok": true,
|
||||
"readerWidth": 1819,
|
||||
"diagramWidth": 1769,
|
||||
"viewBoxWidth": 1364,
|
||||
"minimumProjectedNodeTextPx": 9,
|
||||
"minimumProjectedNodeText": "可推理·可通关",
|
||||
"minimumProjectedNodeTextDetail": "context",
|
||||
"minimumRequiredNodeTextPx": 6,
|
||||
"readabilityOk": true,
|
||||
"hasLegend": false,
|
||||
"hasNavigationDock": true,
|
||||
"legendDockIntersectionArea": 0,
|
||||
"dockStageIntersectionArea": 0,
|
||||
"dockStageGap": 10.21875,
|
||||
"requiredDockStageGap": 10,
|
||||
"viewerChromeStageOk": true,
|
||||
"viewerChromeReserve": 41,
|
||||
"viewerChromeActive": true,
|
||||
"viewerChromeOk": true,
|
||||
"resolvedTheme": "light"
|
||||
}
|
||||
]
|
||||
},
|
||||
"readability": {
|
||||
"status": "pass",
|
||||
"minimumProjectedNodeTextPx": 6,
|
||||
"viewports": [
|
||||
{
|
||||
"width": 1440,
|
||||
"height": 900,
|
||||
"theme": "light",
|
||||
"innerWidth": 1440,
|
||||
"innerHeight": 900,
|
||||
"scrollWidth": 1440,
|
||||
"scrollHeight": 900,
|
||||
"overflowX": false,
|
||||
"overflowY": false,
|
||||
"ok": true,
|
||||
"readerWidth": 1117,
|
||||
"diagramWidth": 1087,
|
||||
"viewBoxWidth": 1364,
|
||||
"minimumProjectedNodeTextPx": 7.172287390029325,
|
||||
"minimumProjectedNodeText": "可推理·可通关",
|
||||
"minimumProjectedNodeTextDetail": "context",
|
||||
"minimumRequiredNodeTextPx": 6,
|
||||
"readabilityOk": true,
|
||||
"hasLegend": false,
|
||||
"hasNavigationDock": true,
|
||||
"legendDockIntersectionArea": 0,
|
||||
"dockStageIntersectionArea": 0,
|
||||
"dockStageGap": 10.21875,
|
||||
"requiredDockStageGap": 10,
|
||||
"viewerChromeStageOk": true,
|
||||
"viewerChromeReserve": 51,
|
||||
"viewerChromeActive": true,
|
||||
"viewerChromeOk": true,
|
||||
"resolvedTheme": "light"
|
||||
},
|
||||
{
|
||||
"width": 1600,
|
||||
"height": 1000,
|
||||
"theme": "light",
|
||||
"innerWidth": 1600,
|
||||
"innerHeight": 1000,
|
||||
"scrollWidth": 1600,
|
||||
"scrollHeight": 1000,
|
||||
"overflowX": false,
|
||||
"overflowY": false,
|
||||
"ok": true,
|
||||
"readerWidth": 1154,
|
||||
"diagramWidth": 1124,
|
||||
"viewBoxWidth": 1364,
|
||||
"minimumProjectedNodeTextPx": 7.41642228739003,
|
||||
"minimumProjectedNodeText": "可推理·可通关",
|
||||
"minimumProjectedNodeTextDetail": "context",
|
||||
"minimumRequiredNodeTextPx": 6,
|
||||
"readabilityOk": true,
|
||||
"hasLegend": false,
|
||||
"hasNavigationDock": true,
|
||||
"legendDockIntersectionArea": 0,
|
||||
"dockStageIntersectionArea": 0,
|
||||
"dockStageGap": 10.21875,
|
||||
"requiredDockStageGap": 10,
|
||||
"viewerChromeStageOk": true,
|
||||
"viewerChromeReserve": 51,
|
||||
"viewerChromeActive": true,
|
||||
"viewerChromeOk": true,
|
||||
"resolvedTheme": "light"
|
||||
},
|
||||
{
|
||||
"width": 1920,
|
||||
"height": 1080,
|
||||
"theme": "light",
|
||||
"innerWidth": 1920,
|
||||
"innerHeight": 1080,
|
||||
"scrollWidth": 1920,
|
||||
"scrollHeight": 1080,
|
||||
"overflowX": false,
|
||||
"overflowY": false,
|
||||
"ok": true,
|
||||
"readerWidth": 1320,
|
||||
"diagramWidth": 1290,
|
||||
"viewBoxWidth": 1364,
|
||||
"minimumProjectedNodeTextPx": 8.511730205278592,
|
||||
"minimumProjectedNodeText": "可推理·可通关",
|
||||
"minimumProjectedNodeTextDetail": "context",
|
||||
"minimumRequiredNodeTextPx": 6,
|
||||
"readabilityOk": true,
|
||||
"hasLegend": false,
|
||||
"hasNavigationDock": true,
|
||||
"legendDockIntersectionArea": 0,
|
||||
"dockStageIntersectionArea": 0,
|
||||
"dockStageGap": 10.21875,
|
||||
"requiredDockStageGap": 10,
|
||||
"viewerChromeStageOk": true,
|
||||
"viewerChromeReserve": 51,
|
||||
"viewerChromeActive": true,
|
||||
"viewerChromeOk": true,
|
||||
"resolvedTheme": "light"
|
||||
},
|
||||
{
|
||||
"width": 2048,
|
||||
"height": 1320,
|
||||
"theme": "light",
|
||||
"innerWidth": 2048,
|
||||
"innerHeight": 1320,
|
||||
"scrollWidth": 2048,
|
||||
"scrollHeight": 1320,
|
||||
"overflowX": false,
|
||||
"overflowY": false,
|
||||
"ok": true,
|
||||
"readerWidth": 1819,
|
||||
"diagramWidth": 1769,
|
||||
"viewBoxWidth": 1364,
|
||||
"minimumProjectedNodeTextPx": 9,
|
||||
"minimumProjectedNodeText": "可推理·可通关",
|
||||
"minimumProjectedNodeTextDetail": "context",
|
||||
"minimumRequiredNodeTextPx": 6,
|
||||
"readabilityOk": true,
|
||||
"hasLegend": false,
|
||||
"hasNavigationDock": true,
|
||||
"legendDockIntersectionArea": 0,
|
||||
"dockStageIntersectionArea": 0,
|
||||
"dockStageGap": 10.21875,
|
||||
"requiredDockStageGap": 10,
|
||||
"viewerChromeStageOk": true,
|
||||
"viewerChromeReserve": 41,
|
||||
"viewerChromeActive": true,
|
||||
"viewerChromeOk": true,
|
||||
"resolvedTheme": "light"
|
||||
}
|
||||
]
|
||||
},
|
||||
"viewerChrome": {
|
||||
"status": "pass",
|
||||
"viewports": [
|
||||
{
|
||||
"width": 1440,
|
||||
"height": 900,
|
||||
"theme": "light",
|
||||
"innerWidth": 1440,
|
||||
"innerHeight": 900,
|
||||
"scrollWidth": 1440,
|
||||
"scrollHeight": 900,
|
||||
"overflowX": false,
|
||||
"overflowY": false,
|
||||
"ok": true,
|
||||
"readerWidth": 1117,
|
||||
"diagramWidth": 1087,
|
||||
"viewBoxWidth": 1364,
|
||||
"minimumProjectedNodeTextPx": 7.172287390029325,
|
||||
"minimumProjectedNodeText": "可推理·可通关",
|
||||
"minimumProjectedNodeTextDetail": "context",
|
||||
"minimumRequiredNodeTextPx": 6,
|
||||
"readabilityOk": true,
|
||||
"hasLegend": false,
|
||||
"hasNavigationDock": true,
|
||||
"legendDockIntersectionArea": 0,
|
||||
"dockStageIntersectionArea": 0,
|
||||
"dockStageGap": 10.21875,
|
||||
"requiredDockStageGap": 10,
|
||||
"viewerChromeStageOk": true,
|
||||
"viewerChromeReserve": 51,
|
||||
"viewerChromeActive": true,
|
||||
"viewerChromeOk": true,
|
||||
"resolvedTheme": "light"
|
||||
},
|
||||
{
|
||||
"width": 1600,
|
||||
"height": 1000,
|
||||
"theme": "light",
|
||||
"innerWidth": 1600,
|
||||
"innerHeight": 1000,
|
||||
"scrollWidth": 1600,
|
||||
"scrollHeight": 1000,
|
||||
"overflowX": false,
|
||||
"overflowY": false,
|
||||
"ok": true,
|
||||
"readerWidth": 1154,
|
||||
"diagramWidth": 1124,
|
||||
"viewBoxWidth": 1364,
|
||||
"minimumProjectedNodeTextPx": 7.41642228739003,
|
||||
"minimumProjectedNodeText": "可推理·可通关",
|
||||
"minimumProjectedNodeTextDetail": "context",
|
||||
"minimumRequiredNodeTextPx": 6,
|
||||
"readabilityOk": true,
|
||||
"hasLegend": false,
|
||||
"hasNavigationDock": true,
|
||||
"legendDockIntersectionArea": 0,
|
||||
"dockStageIntersectionArea": 0,
|
||||
"dockStageGap": 10.21875,
|
||||
"requiredDockStageGap": 10,
|
||||
"viewerChromeStageOk": true,
|
||||
"viewerChromeReserve": 51,
|
||||
"viewerChromeActive": true,
|
||||
"viewerChromeOk": true,
|
||||
"resolvedTheme": "light"
|
||||
},
|
||||
{
|
||||
"width": 1920,
|
||||
"height": 1080,
|
||||
"theme": "light",
|
||||
"innerWidth": 1920,
|
||||
"innerHeight": 1080,
|
||||
"scrollWidth": 1920,
|
||||
"scrollHeight": 1080,
|
||||
"overflowX": false,
|
||||
"overflowY": false,
|
||||
"ok": true,
|
||||
"readerWidth": 1320,
|
||||
"diagramWidth": 1290,
|
||||
"viewBoxWidth": 1364,
|
||||
"minimumProjectedNodeTextPx": 8.511730205278592,
|
||||
"minimumProjectedNodeText": "可推理·可通关",
|
||||
"minimumProjectedNodeTextDetail": "context",
|
||||
"minimumRequiredNodeTextPx": 6,
|
||||
"readabilityOk": true,
|
||||
"hasLegend": false,
|
||||
"hasNavigationDock": true,
|
||||
"legendDockIntersectionArea": 0,
|
||||
"dockStageIntersectionArea": 0,
|
||||
"dockStageGap": 10.21875,
|
||||
"requiredDockStageGap": 10,
|
||||
"viewerChromeStageOk": true,
|
||||
"viewerChromeReserve": 51,
|
||||
"viewerChromeActive": true,
|
||||
"viewerChromeOk": true,
|
||||
"resolvedTheme": "light"
|
||||
},
|
||||
{
|
||||
"width": 2048,
|
||||
"height": 1320,
|
||||
"theme": "light",
|
||||
"innerWidth": 2048,
|
||||
"innerHeight": 1320,
|
||||
"scrollWidth": 2048,
|
||||
"scrollHeight": 1320,
|
||||
"overflowX": false,
|
||||
"overflowY": false,
|
||||
"ok": true,
|
||||
"readerWidth": 1819,
|
||||
"diagramWidth": 1769,
|
||||
"viewBoxWidth": 1364,
|
||||
"minimumProjectedNodeTextPx": 9,
|
||||
"minimumProjectedNodeText": "可推理·可通关",
|
||||
"minimumProjectedNodeTextDetail": "context",
|
||||
"minimumRequiredNodeTextPx": 6,
|
||||
"readabilityOk": true,
|
||||
"hasLegend": false,
|
||||
"hasNavigationDock": true,
|
||||
"legendDockIntersectionArea": 0,
|
||||
"dockStageIntersectionArea": 0,
|
||||
"dockStageGap": 10.21875,
|
||||
"requiredDockStageGap": 10,
|
||||
"viewerChromeStageOk": true,
|
||||
"viewerChromeReserve": 41,
|
||||
"viewerChromeActive": true,
|
||||
"viewerChromeOk": true,
|
||||
"resolvedTheme": "light"
|
||||
}
|
||||
]
|
||||
},
|
||||
"captures": {
|
||||
"status": "pass",
|
||||
"screenshots": [
|
||||
{
|
||||
"width": 1440,
|
||||
"height": 900,
|
||||
"theme": "light",
|
||||
"innerWidth": 1440,
|
||||
"innerHeight": 900,
|
||||
"scrollWidth": 1440,
|
||||
"scrollHeight": 900,
|
||||
"overflowX": false,
|
||||
"overflowY": false,
|
||||
"ok": true,
|
||||
"readerWidth": 1117,
|
||||
"diagramWidth": 1087,
|
||||
"viewBoxWidth": 1364,
|
||||
"minimumProjectedNodeTextPx": 7.172287390029325,
|
||||
"minimumProjectedNodeText": "可推理·可通关",
|
||||
"minimumProjectedNodeTextDetail": "context",
|
||||
"minimumRequiredNodeTextPx": 6,
|
||||
"readabilityOk": true,
|
||||
"hasLegend": false,
|
||||
"hasNavigationDock": true,
|
||||
"legendDockIntersectionArea": 0,
|
||||
"dockStageIntersectionArea": 0,
|
||||
"dockStageGap": 10.21875,
|
||||
"requiredDockStageGap": 10,
|
||||
"viewerChromeStageOk": true,
|
||||
"viewerChromeReserve": 51,
|
||||
"viewerChromeActive": true,
|
||||
"viewerChromeOk": true,
|
||||
"resolvedTheme": "light",
|
||||
"file": "gdd-concept-map.visual-check.1440x900.light.png"
|
||||
},
|
||||
{
|
||||
"width": 1440,
|
||||
"height": 900,
|
||||
"theme": "dark",
|
||||
"innerWidth": 1440,
|
||||
"innerHeight": 900,
|
||||
"scrollWidth": 1440,
|
||||
"scrollHeight": 900,
|
||||
"overflowX": false,
|
||||
"overflowY": false,
|
||||
"ok": true,
|
||||
"readerWidth": 1117,
|
||||
"diagramWidth": 1087,
|
||||
"viewBoxWidth": 1364,
|
||||
"minimumProjectedNodeTextPx": 7.172287390029325,
|
||||
"minimumProjectedNodeText": "可推理·可通关",
|
||||
"minimumProjectedNodeTextDetail": "context",
|
||||
"minimumRequiredNodeTextPx": 6,
|
||||
"readabilityOk": true,
|
||||
"hasLegend": false,
|
||||
"hasNavigationDock": true,
|
||||
"legendDockIntersectionArea": 0,
|
||||
"dockStageIntersectionArea": 0,
|
||||
"dockStageGap": 10.21875,
|
||||
"requiredDockStageGap": 10,
|
||||
"viewerChromeStageOk": true,
|
||||
"viewerChromeReserve": 51,
|
||||
"viewerChromeActive": true,
|
||||
"viewerChromeOk": true,
|
||||
"resolvedTheme": "dark",
|
||||
"file": "gdd-concept-map.visual-check.1440x900.dark.png"
|
||||
},
|
||||
{
|
||||
"width": 2048,
|
||||
"height": 1320,
|
||||
"theme": "light",
|
||||
"innerWidth": 2048,
|
||||
"innerHeight": 1320,
|
||||
"scrollWidth": 2048,
|
||||
"scrollHeight": 1320,
|
||||
"overflowX": false,
|
||||
"overflowY": false,
|
||||
"ok": true,
|
||||
"readerWidth": 1819,
|
||||
"diagramWidth": 1769,
|
||||
"viewBoxWidth": 1364,
|
||||
"minimumProjectedNodeTextPx": 9,
|
||||
"minimumProjectedNodeText": "可推理·可通关",
|
||||
"minimumProjectedNodeTextDetail": "context",
|
||||
"minimumRequiredNodeTextPx": 6,
|
||||
"readabilityOk": true,
|
||||
"hasLegend": false,
|
||||
"hasNavigationDock": true,
|
||||
"legendDockIntersectionArea": 0,
|
||||
"dockStageIntersectionArea": 0,
|
||||
"dockStageGap": 10.21875,
|
||||
"requiredDockStageGap": 10,
|
||||
"viewerChromeStageOk": true,
|
||||
"viewerChromeReserve": 41,
|
||||
"viewerChromeActive": true,
|
||||
"viewerChromeOk": true,
|
||||
"resolvedTheme": "light",
|
||||
"file": "gdd-concept-map.visual-check.2048x1320.light.png"
|
||||
},
|
||||
{
|
||||
"width": 2048,
|
||||
"height": 1320,
|
||||
"theme": "dark",
|
||||
"innerWidth": 2048,
|
||||
"innerHeight": 1320,
|
||||
"scrollWidth": 2048,
|
||||
"scrollHeight": 1320,
|
||||
"overflowX": false,
|
||||
"overflowY": false,
|
||||
"ok": true,
|
||||
"readerWidth": 1819,
|
||||
"diagramWidth": 1769,
|
||||
"viewBoxWidth": 1364,
|
||||
"minimumProjectedNodeTextPx": 9,
|
||||
"minimumProjectedNodeText": "可推理·可通关",
|
||||
"minimumProjectedNodeTextDetail": "context",
|
||||
"minimumRequiredNodeTextPx": 6,
|
||||
"readabilityOk": true,
|
||||
"hasLegend": false,
|
||||
"hasNavigationDock": true,
|
||||
"legendDockIntersectionArea": 0,
|
||||
"dockStageIntersectionArea": 0,
|
||||
"dockStageGap": 10.21875,
|
||||
"requiredDockStageGap": 10,
|
||||
"viewerChromeStageOk": true,
|
||||
"viewerChromeReserve": 41,
|
||||
"viewerChromeActive": true,
|
||||
"viewerChromeOk": true,
|
||||
"resolvedTheme": "dark",
|
||||
"file": "gdd-concept-map.visual-check.2048x1320.dark.png"
|
||||
}
|
||||
],
|
||||
"contactSheet": "gdd-concept-map.visual-check.html"
|
||||
},
|
||||
"sidecars": {
|
||||
"receipt": "gdd-concept-map.visual-check.json",
|
||||
"contactSheet": "gdd-concept-map.visual-check.html"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,60 @@
|
||||
# Requirements Traceability Matrix — Dungeon Sweeper
|
||||
|
||||
> 生成：2026-09-12 · 源：`docs/architecture/architecture.md` §Technical Requirements Baseline（63 条）+ ADR-0001~0005 · 2026-09-15 雾格移除清理（a4-001/002 需求文本与载体同步现行文档）
|
||||
> 门检查口径：**Foundation 层零缺口** = 每条 Foundation TR 都有明确裁决载体（专项 ADR，或经 design-review 门禁的 Approved GDD 契约 + 本架构文档章节），无未决项。
|
||||
> 状态图例：✅ 已覆盖 · 🔶 待 ADR（非 Foundation，随对应系统开工前裁决）· ⏳ 随未设计系统
|
||||
|
||||
## 覆盖总览
|
||||
|
||||
| 层 | TR 数 | 专项 ADR 覆盖 | GDD 契约 + 架构文档覆盖 | 待裁决 |
|
||||
|---|---|---|---|---|
|
||||
| Foundation | 36 | ADR-0001（a3-004）· ADR-0004（d2-014/016）· ADR-0005（d2-010/gc-002） | 32 条（D2/A3/A4/B3 GDD 均 Approved + 架构文档所有权/API 节） | **0** ✅ |
|
||||
| Core | 21 | ADR-0001（b1-001/002）· ADR-0002（—） | 19 条 | 2（a1-011/012 → ADR-0006） |
|
||||
| Feature | 2 | — | b1 对账协议等 | 0（b1-010 文档承载） |
|
||||
| Presentation / Platform | 4 | ADR-0002（gc-008） | gc-006/007 文档 | 2（gc-004/005 随 D1/B5） |
|
||||
|
||||
## Foundation 层逐条（36 条——零缺口核验）
|
||||
|
||||
| TR | 需求 | 裁决载体 |
|
||||
|---|---|---|
|
||||
| d2-001~003 | 单一事实源 / ConfigDB 单点 / schema 先行 10 表 | D2 GDD（Approved）+ architecture.md §Module Ownership |
|
||||
| d2-004 | 进度键 + R1 floor 解析 | D2 GDD R1 + architecture.md §API Boundaries |
|
||||
| d2-005/006 | RngService 封闭流 / R2 派生与黄金向量 | D2 GDD R2 + architecture.md 原则 3 |
|
||||
| d2-007 | 校验双通道 + 夹具注入 | D2 GDD + ADR-0004（载体） |
|
||||
| d2-008 | 加载期/运行期致命 | D2 GDD Rule 6 |
|
||||
| d2-009 | D2 零 UI 依赖 | D2 GDD Rule 7 + ADR-0003（core 隔离）+ architecture.md 原则 1 |
|
||||
| **d2-010** | SCHEMA_VERSION 版本化 | **ADR-0005** |
|
||||
| d2-011 | debug override 链 | D2 GDD R3 |
|
||||
| d2-012 | 热重载状态机 + reload gate | D2 GDD + B1 GDD（唯一调用方） |
|
||||
| d2-013 | 诊断收集器 | D2 GDD 校验双通道节 |
|
||||
| **d2-014** | 冒烟框架协议 | **ADR-0004** |
|
||||
| **d2-015** | RNG 快照 = seed + 计数器 | **ADR-0005** |
|
||||
| **d2-016** | 项目级静态扫描域 | **ADR-0004**（S1–S8） |
|
||||
| a3-001~003/005~008 | AP/RAP 账本、仲裁、相位机、refresh、表承载、last_round_end | A3 GDD（Approved）+ architecture.md |
|
||||
| **a3-004** | round_end 双发射源 | **ADR-0001**（round_end_board / round_end_stopped） |
|
||||
| a4-001/002 | 变异框架（原雾行跨字段校验已随雾格移除） | A4 GDD（Approved）+ 现行《地形变异》 |
|
||||
| a4-003/004 | 生成期布置执行归 A1 / 零特判 | A4 GDD + A1/A2 GDD |
|
||||
| b3-001~006 | 统一容器 / 时限量纲 / 五 API / 三分支 / 快照 / 不 clamp | B3 GDD（Approved） |
|
||||
|
||||
## Core / Feature / Presentation 层（27 条）
|
||||
|
||||
| TR | 需求 | 载体 | 状态 |
|
||||
|---|---|---|---|
|
||||
| a1-001~010, a2-001~010, b2-001~004/006, b4-001~009, b1-003~009/011 | 各系统行为契约（详见 architecture.md §TR Baseline） | 各 GDD（Approved）+ architecture.md §Module Ownership / §API Boundaries；事件类（a2-002/003、b1-001/002）由 **ADR-0001** 承载 | ✅ |
|
||||
| **a1-011** | 度量独立入口三函数 | 🔶 待 **ADR-0006**（生成性能与异步化——A1 OQ2/OQ3） | 🔶 |
|
||||
| **a1-012** | F2c 成本闸 / 生成性能姿态 | 🔶 待 **ADR-0006**（Core 层，A1 开工前裁决；切片证据已背书同步方案） | 🔶 |
|
||||
| **b2-005**（注：face 归属实为 b2 OQ1 项） | query_attack/ambush_grant_plan 两 face | 🔶 待 **ADR-0007**（单位 API face 归属——B2 OQ1/OQ5） | 🔶 |
|
||||
| **gc-004** | 双舞台资产管线 | ⏳ B5 前美术测试 → ADR-0011 | ⏳ |
|
||||
| **gc-005** | 视觉锚三硬约束 | 🔶 D1 GDD（未写——MVP 层最后一块；切片教训四条为其硬输入） | 🔶 |
|
||||
| gc-006/007 | 性能预算 / 平台输入 | technical-preferences + ADR-0002（窗口基座） | ✅ |
|
||||
| **gc-008** | 渲染器选择 | **ADR-0002** | ✅ |
|
||||
|
||||
## 待裁决 ADR 队列（全部非 Foundation）
|
||||
|
||||
| ADR | 议题 | 触发时机 |
|
||||
|---|---|---|
|
||||
| ADR-0006 | 生成性能与异步化（A1 OQ2/OQ3 + 度量独立入口确认） | A1 生产实现前 |
|
||||
| ADR-0007 | B2/B1 两 face 归属 + HeroTable 单行校验落点 | B2 生产实现前 |
|
||||
| ADR-0008 | 零伤害死局跨字段护栏落点 | D2 生产化前 |
|
||||
| ADR-0009 | 切片机制正式化（轮内刷新 / RewardSupplyController / LevelTable / grant_node_active / clear_blast） | 正式化批 |
|
||||
| ADR-0010~0013 | A1 熔断 / B5 舞台 / A5 显影 / D3 存档格式（契约已由 ADR-0005 锁定） | 各系统 GDD 立项时 |
|
||||
@@ -0,0 +1,155 @@
|
||||
# 代码规范（Dungeon Sweeper）
|
||||
|
||||
> 生效：2026-09-11 · 来源：用户在垂直切片评审中逐一指出的真实陋习与缺陷，全部成文。
|
||||
> 每条规则附本项目真实反面案例（标注缺陷编号/日期）——规则不是抽象美德，是踩过的坑。
|
||||
> 约束范围：`game/`（原 prototypes/ 垂直切片，2026-09-24 转正）代码同尺度；与 CLAUDE.md「硬性红线」节既有硬约束
|
||||
> （数值表单点 / RNG 封闭流 / Core 零 UI / fail-fast / spec-AC 一致性）并行生效，冲突以用户裁决为准。
|
||||
|
||||
**写任何代码前必须通读本文件。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 结构纪律——高内聚、低耦合
|
||||
|
||||
### 1.1 禁止上帝对象
|
||||
一个类只承载一个职责。场景主脚本（main）= **组合根**：模式流转、信号接线、核心写调用的唯一出口；
|
||||
渲染、文案拼装、状态装配一律拆分为独立视图/装配器类。单文件超过 ~400 行即触发审视。
|
||||
|
||||
> **反面案例（2026-09-11，用户："一个工程师看了想吐"）**：main.gd 随功能追加长到 ~1100 行——棋盘渲染、
|
||||
> HUD、结算日志格式化、四种模态覆盖层、调整板、蒙特卡洛模拟器、关卡流程全部糊在一个类里。
|
||||
> 已拆分为 9 个单一职责单元（views/ + hud_presenter），main 降到 433 行组合根。
|
||||
|
||||
### 1.2 一切功能以类封装，禁止裸函数堆
|
||||
设计稿与实现同尺度：功能 = 类（状态 + 行为 + 信号），类是封装的最小交付单位。
|
||||
工具性纯函数只允许挂在明确的宿主类下（静态装配器/工厂），不允许无主散落。
|
||||
|
||||
> **反面案例（2026-09-11，用户："我看你都是函数的方式……没有对象封装吧"）**：供给控制器的伪代码
|
||||
> 以裸函数呈现被否；正式实现按"B4 私有组合件 RewardSupplyController"封装。
|
||||
|
||||
### 1.3 依赖单向，核心写调用收口
|
||||
依赖方向唯一：`views →（信号）→ 组合根 →（写调用）→ core`。
|
||||
视图零核心写调用（纯 setter / 信号外发优先）；"读核心状态 → 拼展示文案"集中于装配器（presenter）；
|
||||
核心写接口（settle_batch / submit_window_selection / runner 推进）只允许在组合根出现。
|
||||
|
||||
### 1.4 命名 = 领域命名，禁止系统 ID 前缀
|
||||
文件名与类名禁止 `a1_`/`b1_`/`c1_` 等系统 ID 前缀（`a1_board_generator.gd` → `board_generator.gd`）。
|
||||
设计追溯不靠前缀：每个核心实现文件头注必须带一行
|
||||
`# 实现 GDD：design/archive/gdd-2026-09-14/<id>-<slug>.md（系统 ID Xn）`（2026-09-14 起旧 GDD 体系封存于归档，头注指归档路径；对应新 systems 文档定稿后再改指 `design/gdd/systems/` 新文档）；系统 ID 只作为文档与 registry 的追溯锚。
|
||||
豁免：D2 schema 类与 autoload（本就领域命名）；文档/夹具登记名（如 b4_golden）属文档层。
|
||||
|
||||
> **反面案例（2026-09-11，用户："是没有代码规范吗"）**：ID 前缀是跟随 GDD 文档名的事实约定，
|
||||
> 从未成文；同目录 `config_db`/`rng_service` 无前缀与 A/B/C 系列并存——两套命名即规范缺失的铁证。
|
||||
|
||||
### 1.5 禁止事实约定
|
||||
任何"大家默认这么做"的惯例必须成文进本文件（或 CLAUDE.md）才算存在。
|
||||
写代码时发现未成文但必须遵守的约定 → 当场补条文，不许靠惯性延续。
|
||||
|
||||
---
|
||||
|
||||
## 2. 契约纪律——跨层/跨类调用的语义
|
||||
|
||||
### 2.1 信号与事件契约成文
|
||||
每个跨类信号：参数语义、发送时点、消费方依赖，必须在发送方头注成文（参照 A2 三事件面先例）。
|
||||
状态机的每次迁移路径都必须发出对应事件——**缺一条路径的事件 = 消费方永久等待 = 软锁**。
|
||||
|
||||
> **反面案例（playtest 缺陷②）**：A2 旗动作花完末点 AP 后相位翻 Waiting 但不发 round_end，
|
||||
> B1 结算点依赖该事件 → 整局软锁。v1 冒烟没抓到是因为自动玩家不用旗——路径覆盖不全的代价。
|
||||
|
||||
### 2.2 跨层标识符语义单一且成文
|
||||
位置（index）/ 句柄（handle）/ 键（key）是三种不同的东西。跨类传递标识符时，
|
||||
传递方的语义必须与接收方契约逐字一致，禁止凭"当前恰好相等"传值。
|
||||
|
||||
> **反面案例（playtest 缺陷④）**：窗口选择契约 = 窗口条目位置，UI 却传库存数组句柄——
|
||||
> 未消耗时二者巧合相等；消耗一件后错位 → 选中件不消耗、邻件被误耗。
|
||||
|
||||
### 2.3 模态覆盖层层级规则
|
||||
覆盖层遮挡关系由场景树加入顺序决定。打开任何模态覆盖层时，必须显式隐藏会遮挡它的全屏层；
|
||||
新增覆盖层必须登记其在 z 序中的位置，并提供"打开可见性"的场景断言。
|
||||
|
||||
> **反面案例（playtest 缺陷⑤）**：数值调整板已实现，但打开时被不透明的开始覆盖层完全遮住
|
||||
> = "点击无反应"。功能存在 ≠ 功能可达。
|
||||
|
||||
### 2.4 状态字段语义显式
|
||||
跨战斗/跨场景携带或恢复的状态字段，其语义来源必须显式（表值 / 明确入参），禁止用入参隐式定义。
|
||||
|
||||
> **反面案例**：B2 spawn 把 hero 的 max_hp 设为入参 hero_hp——跨战斗携带 HP 时上限被压扁，
|
||||
> 恢复点/治疗包的满血守卫全部失效。
|
||||
|
||||
---
|
||||
|
||||
## 3. 测试纪律——"存在"必须证明"可达且正确"
|
||||
|
||||
### 3.1 场景级探针标配
|
||||
每新增一个可交互 UI 区域（视图/覆盖层/面板），必须配套场景级 headless 探针：
|
||||
真实实例化场景 → 驱动真实输入路径 → 断言可见性与状态。**只有 core 层 AC 通过不算有测试**
|
||||
（GDScript 编译不查字典字段与时序，呈现层错误只在运行时暴露）。
|
||||
|
||||
### 3.2 覆盖层/面板必测"打开后可见"
|
||||
凡模态覆盖层，探针必须断言：打开后自身 visible 且遮挡物已隐藏（缺陷⑤回归断言）。
|
||||
|
||||
### 3.3 缺陷修复必须沉淀回归断言
|
||||
每个缺陷修复必须在探针或冒烟中留下能抓住该缺陷的断言（旗动作耗尽 AP → 必须进入第 2 轮；
|
||||
选用道具 → 库存态必须变 Used）。没有回归断言的修复视为未完成。
|
||||
|
||||
### 3.4 提交前全量验证
|
||||
交付前必须全绿：`smoke_all.gd` + 全部场景探针（ui_probe / ui_click_probe / ui_tune_probe）。
|
||||
行为探针使用随机化玩家行为（旗/停手/刷新/无效点击）——自动玩家不做的动作就是测试盲区。
|
||||
|
||||
---
|
||||
|
||||
## 4. 语言纪律——GDScript 4.x 实战坑（本项目踩实）
|
||||
|
||||
1. **多行 lambda 内禁止嵌套 match / 复杂控制流**（解析不可靠，报"Expected expression for match
|
||||
pattern"）——信号处理体一律抽成命名方法 + `bind` 传状态。
|
||||
2. **Dictionary 取值返回 Variant，无类型推断**——参与算术或传参前显式声明类型（`var x: float = ...`）。
|
||||
3. **RichTextLabel：`append_text()` 不回写 `text` 属性**——读可见文本用 `get_parsed_text()`。
|
||||
4. **lambda 捕获循环变量按创建时值**——循环内先落地局部变量再捕获，或用 `bind`。
|
||||
5. **重命名脚本必须同步 `.uid` 文件**（资源身份稳定）；新增 `class_name` 后必须跑一次编辑器扫描
|
||||
刷新全局类缓存，否则 `--headless --script` 模式解析失败。
|
||||
6. **`print` 格式占位符与实参类型必须匹配**（`%d` 配 String = 静默输出字面量）——工具输出错
|
||||
等于没有输出。
|
||||
|
||||
---
|
||||
|
||||
## 5. 数值与汇报纪律
|
||||
|
||||
### 5.1 数值口径必须显式标注尺度
|
||||
任何期望值/均值汇报必须写明口径：**每格 / 每板 / 每战 / 每关**。混用口径 = 误导
|
||||
（"可选类 3.32"不加"每板"，会被读成每格期望 >1）。
|
||||
|
||||
### 5.2 调参先测量，改后复测
|
||||
改任何玩法数值前，先用扫描工具产出基线（通关率/难度类读数走 `balance_verifier.py` 冒险段——单关直入口口径已退役，机制类读数走 `reward_expectation.gd` 等）；
|
||||
改完必须复测回填数据。禁止拍脑袋调参。
|
||||
|
||||
### 5.3 数值设计必须跨尺度推演
|
||||
在单一尺度校准的数值，必须推演其在更大尺度的复合结果（每战合理 × 关内囤积 = 关卡灾难）。
|
||||
|
||||
> **反面案例（2026-09-11）**：可选类 25% 格子配比在单战斗尺度校准（击杀需求 18/54），
|
||||
> ×"库存关内延续"× 5 张板复合后 = 每关 24.8 件、刀总伤 180 > Boss 130 HP——预警⑥在关卡尺度坐实。
|
||||
|
||||
### 5.4 用户拍板的实现零发挥
|
||||
拍板范围外的细节一律不自行补全——以"待办问题"清单列出等裁决。
|
||||
（反面案例：清图奖励被自行设计成入库刀，用户纠正为"一次性高额伤害不入库"。）
|
||||
|
||||
---
|
||||
|
||||
## 6. 流程纪律
|
||||
|
||||
1. **大改动三段走**：设计稿/伪代码 → 用户审阅 → 实现 → 修改记录（README + session-state）。实现不得先于审阅。
|
||||
2. **实现批收尾双登记**：切片 README 修改记录 + `production/session-state/active.md` 条目，缺一不可。
|
||||
3. **规范变更必须成文进本文件**——发现未成文约定、或用户裁决产生新规则，当场补条文。
|
||||
4. **呈现层缺陷的教训回写 D1 GDD 设计输入**（信号载荷 schema / 场景级测试 / 时点状态可见性）。
|
||||
|
||||
---
|
||||
|
||||
## 附：缺陷-规范对照表（本项目真实案例，2026-09-11）
|
||||
|
||||
| 缺陷 | 现象 | 根因 | 对应规则 |
|
||||
|---|---|---|---|
|
||||
| ① UI 抖动/"第3轮"消失 | 悬停文案换行推挤侧栏，末行被挤出视口 | 动态内容参与布局回流 | 1.1 拆分 + 视图定长槽（HUDView） |
|
||||
| ② Boss 战 AP 用完不结算（软锁） | 插旗耗尽末点 AP 后整局冻结 | 旗动作路径缺轮末事件 | 2.1 事件发射完整性 |
|
||||
| ④ 道具使用后不消失 | 选用件留存、邻件被误耗 | 窗口位置 vs 库存句柄错位 | 2.2 标识符语义单一 |
|
||||
| ⑤ 调整板点击无反应 | 面板已实现但被开始层遮挡 | 模态打开未隐藏遮挡物 | 2.3 层级规则 + 3.2 |
|
||||
| 上帝对象 | main.gd ~1100 行 | 职责无边界持续堆积 | 1.1–1.3 |
|
||||
| ID 前缀命名 | a1_/b1_ 与领域命名并存 | 事实约定未成文 | 1.4–1.5 |
|
||||
| 可选类每关 24.8 件 | 速杀退化、囤刀秒 Boss | 单尺度校准未做跨尺度推演 | 5.3 |
|
||||
@@ -0,0 +1,162 @@
|
||||
# 文档写作规范（写文档前必读）
|
||||
|
||||
> **地位**：本文是本项目文档写作的规范权威，与 `docs/code-conventions.md`（代码规范）对等——写代码前必读代码规范，写文档前必读本文。CLAUDE.md 只保留导航指针，细则以本文为准。
|
||||
> **适用范围**：`design/` 下一切现行文档（顶层文档、`systems/` 系统文档、`design/ux/`、`design/art/`、`design/research/`）与 `production/` 会话记录；`docs/` 其他说明文档参照执行。
|
||||
> **成文**：2026-09-14。整合来源：用语纪律（2026-09-09 评审确立）· 文档形态纪律（2026-09-13 评审确立）· 两件套与树形文档体系纪律（2026-09-14 用户拍板）· 新骨架过渡口径（2026-09-14 用户拍板）· 可读性纪律（2026-09-14 用户提出）· 引用纪律（2026-09-14 用户提出）· 概念封装纪律（2026-09-15 用户提出）。
|
||||
|
||||
## 0. 总纲
|
||||
|
||||
文档是写给人看的：先让人读懂，再谈结构整齐。默认读者没有读过项目历史——可能是半年后的你自己，也可能是未来的协作者。下面所有规则都为这个读者服务。
|
||||
|
||||
## 1. 可读性第一（最高纪律）
|
||||
|
||||
**读者测试是每个小节的验收标准**：只读这一节，回答三个问题——
|
||||
|
||||
1. 这节管的是谁/什么？
|
||||
2. 在什么情况下？
|
||||
3. 会发生什么？
|
||||
|
||||
答不出来，就重写这一节，而不是给看不懂的地方补注释。
|
||||
|
||||
**与旧体系门禁的关系**：旧体系的 lean 格式六条硬规则与 `tools/gdd_lint.py` 门禁已随 2026-09-14 归档停用（PostToolUse 钩子同批停用，工具本体留 `tools/` 备查），此后仅用于解读 `design/archive/` 里的旧文档（解读时注意其表格占比口径为 30%，2026-09-14 由 60% 放宽）。现行文档不跑 lint；可读性是唯一的内容质量门。旧模板文件留档 `.claude/docs/templates/` 备查。
|
||||
|
||||
## 2. 白话写作规则
|
||||
|
||||
写文档像向朋友当面解释你的游戏。具体做法：
|
||||
|
||||
1. **完整句子优先**：用完整的句子把话说完；一段只说一件事，长句拆短句。
|
||||
2. **禁止碎片笔记体**：正文不得写压缩碎片，不得把 `A→B→C` 箭头链当叙述（流程交给字符画，见第 3 节），不得使用只有作者自己懂的缩略语。
|
||||
3. **每节人话开头**：每个小节的第一段先用白话说清"这是什么、为什么需要它"，然后再展开细节。做到只读各节第一段，就能看懂整篇文档的故事线。
|
||||
4. **术语首现即解释**：专业术语或项目概念第一次出现时，用一句话（可以用括号）解释它是什么，之后才允许直接使用。玩家会看到的专属名词（如"显影尘"）同样要说清。
|
||||
5. **叙述优先于引用**：AC-x、F-x 等编号引用不进正文叙述，只出现在验收标准与附录；正文用直白语言把规则本身说出来。
|
||||
6. **反面基准**：数据库条目、会议纪要、只有评审工具能"读懂"的表格堆——都不是我们要的文档。
|
||||
|
||||
## 3. 表达分工：散文、表格、字符画、公式
|
||||
|
||||
不同内容用不同载体，各司其职：
|
||||
|
||||
| 内容 | 载体 | 纪律 |
|
||||
|---|---|---|
|
||||
| 规则的来龙去脉、行为逻辑 | 散文段 | 每段 ≤240 字，一段一件事 |
|
||||
| 枚举、数值、边界、依赖 | 表格 | 表格只放可列举的事实；禁止把需要解释的内容塞进单元格让读者自己拼 |
|
||||
| 流程、状态流转 | 字符画（代码块） | 禁止用散文逐步描述流程 |
|
||||
| 公式 | 结论先行 | 先一行加粗结论，再放公式代码块、变量表与验算表；公式本体必须保留 |
|
||||
| 体验锚点 | 关键词表 | 支柱/关键词/机制承诺 三列表，禁止长篇情绪描述 |
|
||||
|
||||
节点内顺序：先人话，再表格枚举，再字符流程图，最后公式举证。
|
||||
|
||||
**规则两段式**：核心规则先写"人话阶段"（作用于哪个系统、什么情况下、谁触发、触发后发生什么），再写"举证阶段"（逐效果给出计算方法或公式；纯流程规则明写"无计算"）。规则名禁止纯名词短语（反面例："获取路由"）。
|
||||
|
||||
## 4. 用语纪律（禁自造黑话）
|
||||
|
||||
文档、评审输出、日志与一切沟通中**禁止自造黑话**——比喻性生造词、只有作者自己懂的缩略语（历史反例："非雾腿""双闸"）。
|
||||
|
||||
- 只能使用：（a）人人可懂的直白语言，或（b）游戏行业通用术语（如 flood fill、战争迷雾、连锁展开、结算、增益/减伤）。
|
||||
- 需要指代新概念时，用直白的描述性短语（正例："实测可推理率"——限定语与规范名绑定）。
|
||||
- 确需给新概念命名时：首次出现处必须附一句白话定义，并登记 `design/registry` 术语条目——不得让读者猜测比喻含义。
|
||||
- 唯一例外：玩家在游戏里也会看到的专属名词（道具名、界面用语，如"显影尘""探巢摆钟"）。文档内部的机制概念不得造词。
|
||||
|
||||
## 5. 结构纪律
|
||||
|
||||
| 规则 | 内容 |
|
||||
|---|---|
|
||||
| 树形文档体系 | 全部设计文档构成一棵树；文档增删必须同步根索引 `design/gdd/02-系统清单.md` |
|
||||
| 一页纸节点 | 一节、一条规则的内容控制在一页纸内（约 ≤80 行）；装不下就拆节，禁止铺开 |
|
||||
| 一系统一文档 | 每个子系统一份设计文档，不建 analysis 推演件；两三句能说清的"为什么"直接写进设计目的或规则正文 |
|
||||
| 正文只写现行规则 | 禁止删除线、"（作废）"、"（日期+拍板）"式注记；修订只进文末「版本历史」表；义务台账、拍板记录等审计信息入 `design/registry` 或附录，不入正文 |
|
||||
| 后置 ≠ 删除 | P1/P2 后置的内容逐条列出；复活后置项 = 修订文档，禁止静默加回 |
|
||||
| 数值纪律 | 正文定规则、取值域、单位；平衡值进 `data/tables/`，provisional 必须标注；已锁数值事实源 = `data/tables/` 与 `design/registry/entities.yaml`。**强制收口条款（2026-09-17 数值压缩批后补成）**：① **双写失同步禁止**——任何数值变更（压缩 / 换装 / 投值 / 区间平移 / 增减行）必须同时同步所有引用该数值的 GDD 表格正文、registry `entities.yaml` 的 `mvp_content` / `value_status`、相关待办清单现状——三类之一未更新即视为该变更**未完成**（先例：2026-09-17 整体数值压缩批只动了 `.tres` 与切片代码，未同步 `地图战斗资源.md` / `增益状态.md` 正文表格、`entities.yaml` mvp_content、`06-待办清单.md` 的 `heal 负向直伤` 条目，造成文档滞后）；② **调参表锁数后删现行值列**——数值已锁定的调参表必须删除「现行值」列（敌人系统 v0.6 先例），仅保留 schema 模板与取值域，指路存根指向 `data/tables/<file>.tres` 与 `registry/entities.yaml` 对应条目；③ **覆盖范围** = 奖励 / 状态 / 敌人 / 技能 / 充能 / 护甲等级 / 区间掷点 / 难度曲线 / D_ref 等所有数值字段；④ **维护通道** = 走「设计批 → 同步批」两段式——数值表改完不等于修订完成，须同步收口后方可记入版本历史；⑤ **压缩/换装批** = 一律走「`.tres` 落批 + 切片 smoke 跑通 + GDD 表格指路化 + registry mvp_content 指路化 + 待办清单现状刷新」五步全收才记版本号，缺步则版本号不增 |
|
||||
|
||||
## 6. 文档类型与骨架
|
||||
|
||||
**顶层文档**：
|
||||
|
||||
| 文档 | 管什么 |
|
||||
|---|---|
|
||||
| `00-游戏概念.md` | 一句话概念、目标受众、世界观命名、术语层级 |
|
||||
| `01-核心循环.md` | 玩家醒来→做什么→得到什么→又想做什么，一条线讲清 |
|
||||
| `02-系统清单.md` | 根索引：循环 × 子系统总表 + 文档树导航 |
|
||||
| `03-内容规模.md` | 几个关卡、几种敌人、几种道具——做多少砍多少 |
|
||||
| `04-美术音频方向.md` | 参考图、参考游戏、风格关键词 |
|
||||
| `05-不做清单.md` | 明确写：这些我不要 |
|
||||
| `06-待办清单.md` | 全项目待办事项的唯一登记处；各系统文档的「待办」节只留指路存根 |
|
||||
|
||||
**系统文档骨架**（`systems/` 下统一采用）：
|
||||
|
||||
| 章节 | 要求 |
|
||||
|---|---|
|
||||
| 文首引言 | 一句话定位 + 状态（已定稿/范围草案/待设计）+ 旧版参考链接 |
|
||||
| 设计目的 | 2-4 句白话，为什么需要这个系统 |
|
||||
| 系统范围 | 负责/不负责两张表；表前一段白话说明边界 |
|
||||
| 在核心循环中的位置 | 处于哪一段、上下游是谁（字符画一行 + 两句白话） |
|
||||
| 核心规则 | 领域章节 ×2–6，每节一页纸 |
|
||||
| 依赖与输出 | 上游/下游/对外事件与接口（表格；引用纪律见第 8 节） |
|
||||
| P0 最小闭环 / P1·P2 后置 | MVP 最小集合与后置清单 |
|
||||
| 调参表 | 参数名/取值域/现行值，provisional 标注 |
|
||||
| 验收标准 | 可验证的判据 |
|
||||
| 待办（可选） | 指路存根：条目单点登记 `06-待办清单.md`（见第 8 节「待办单点登记」），本节不再逐条登记 |
|
||||
| 版本历史 | 表格 |
|
||||
|
||||
**命名**：中文、见名知意（如"游戏概念""棋盘生成"）；禁止 a1_/b1_ 编号前缀；不留纯空目录。正文中指代子系统一律用中文规范名；英文代号（供代码标识符与工具链）对照表见 `design/gdd/02-系统清单.md`，旧代号（a1–d6）仅限解读归档时使用，不得写进现行文档。
|
||||
|
||||
## 7. 概念封装纪律（概念对象化建模）
|
||||
|
||||
动笔之前先做概念建模：像写代码划分对象那样，把设计切成分界清晰的概念——每个概念有自己的规范名、自己的属性、自己的规则，概念之间靠显式关系（包含、挂载、引用）连接，而不是把所有内容揉进一个概念里。揉团的代价雾格事故已经付过一次（见第 8 节反例对照）：概念没有边界，删除修改就得全仓翻找。
|
||||
|
||||
| 规则 | 内容 |
|
||||
|---|---|
|
||||
| 概念即对象 | 核心概念各自独立成体，有规范名、有属性、有规则边界；下笔前先能用一句"它是谁、它管什么"说清，说不清就是还没想完 |
|
||||
| 属性归属唯一 | 每个属性只归一个概念——离开 A 就没有意义的属性写在 A 名下，禁止上提给容器、也不下压给成员 |
|
||||
| 包含关系显式写 | 容器与成员的关系明文写出谁是容器、谁是成员、一对几（例：棋盘包含多个格）；禁止让读者从散文里反推结构 |
|
||||
| 概念状态用枚举 | 概念的类型与状态写成封闭枚举并列全成员（例：格的类型 = 安全格 / 雷格，格的状态 = 未开 / 已开）；禁止用散文形容词零散罗列状态 |
|
||||
| 附加物独立成对象 | 挂在概念上的附加内容若自己有一组属性或规则要写（例：格上的奖励/惩罚 = 格面资源），就是独立对象——父概念只保留挂载位（如"有无资源资格"），禁止把附加物摊平成父概念的一堆属性字段 |
|
||||
| 关系不吸内容 | 概念间关系只写"有没有关系、是什么关系"；对方的属性与规则留在对方名下——与第 8 节"引用不转述"同源 |
|
||||
|
||||
**切分正例**（现行排雷循环即按此切分）：棋盘是地图级对象，包含多个格；格是成员对象，雷格/安全格是它的枚举属性；格上可能挂的奖励或惩罚（格面资源）是独立对象，本体与规则归地图战斗资源与战斗结算，格只保留"有无资源资格"一个挂载位。反面基准：把奖励的类型、数值、极性全摊开写成格子的属性字段——奖励规则一改，棋盘文档就得跟着改，这便是没封装。
|
||||
|
||||
**落盘载体**：概念对象登记 `design/registry/entities.yaml`（owner 与 referenced_by 由此机械维护）；文档里概念怎么切，registry 就怎么登记，代码里的对象划分与之同构。
|
||||
|
||||
**与引用纪律的关系**：本节管单个概念的边界与归属（概念级封装），第 8 节管概念之间、文档之间的引用（跨文档解耦）——先有封装，第 8 节的单点定义、反向边与删除 SOP 才有干净的作用对象。
|
||||
|
||||
## 8. 引用纪律（跨文档高内聚低耦合）
|
||||
|
||||
目标：修改或删除一个概念时，只改它的 owner 文档；引用方最多删掉一个链接。反例对照 = 2026-09-14 雾格删除事故——雾格/迷雾/fog 三名并存、雾机制被织进多份文档的规则正文，导致全仓几十处文字修改与大量事后一致性复查。
|
||||
|
||||
| 规则 | 内容 |
|
||||
|---|---|
|
||||
| 单点定义 | 每个概念只在 owner 文档里定义一次，registry 术语条目登记其规范名 |
|
||||
| 规范名唯一 | 正文只准用规范名，禁止别名散开——否则删除时 grep 搜不全 |
|
||||
| 引用不转述 | 跨文档引用 = 规范名 + 链接，禁止复述对方的规则细节、公式与数值；若发现自己需要一条规则，那是自己的概念，就地定义 |
|
||||
| 引用落到对外承诺 | 跨文档链接只锚到对方文档明示的对外内容（事件、接口、规则条目），不锚其内部细节 |
|
||||
| 依赖逐条列出 | 系统文档的「依赖与输出」节逐条列出本系统依赖的他人概念（规范名 + 链接）——这份清单就是删除概念时的影响面清单 |
|
||||
| 引用必登记反向边 | 引用他系统概念时，在被引方的 registry 条目 `referenced_by` 里登记——影响面靠它机械列出，不靠全仓搜 |
|
||||
| 链接断了也好读 | 引用处的句子在链接失效后仍通顺完整（写"变异规则见《地形变异》"，不把半截语义挂在链接里） |
|
||||
| 待办单点登记 | 全项目待办事项单点登记于 `design/gdd/06-待办清单.md`：系统文档的「待办」节只留指路存根，不得自建条目表；新增待办条目直接登记清单，裁决后改「状态」列留痕、不删条目 |
|
||||
|
||||
**引用格式**：一律 Markdown 相对链接，指向文件、必要时带节锚点（例：`[地形变异 · 变异类型](systems/排雷循环/地形变异.md#变异类型)`）——机械可查，死链可被工具检出。
|
||||
|
||||
**删除概念 SOP**：① 查 registry 该条目的 `referenced_by`，得到影响面清单 → ② owner 文档删除概念 → ③ 纯引用方删链接即完事；机制被织入对方规则的，按清单逐处修订 → ④ 收尾跑一遍死链检查，全绿即干净。
|
||||
|
||||
**诚实边界**：机制耦合无法靠删链接消灭——别人的规则真的因你的概念而改变时，改内容不可避免。引用纪律保证的是：这类修改有一份现成清单（反向边 + 依赖节），不用事后全仓搜索。
|
||||
|
||||
## 9. 归档与事实源
|
||||
|
||||
- `design/archive/gdd-2026-09-14/` 是旧版 GDD 体系的只读归档：不维护、不修改，**禁止作为事实引用**。
|
||||
- 旧文档里的概念写进现行文档时，必须翻译成现行术语与现行决策口径（例：雾格已从设计中移除，不得作为现行机制引用）。
|
||||
- registry 中 owner 仍指向旧 GDD 路径的条目，在对应新系统文档定稿后逐条改指新路径。
|
||||
|
||||
## 10. 会话记录纪律
|
||||
|
||||
`production/session-state/active.md` 每条进度 ≤3 行（粗体键 + 短句）；详情一律外链到对应文档或报告，禁止把定稿摘要、义务清单整段塞进条目。
|
||||
|
||||
## 版本历史
|
||||
|
||||
| 版本 | 日期 | 说明 |
|
||||
|---|---|---|
|
||||
| v1 | 2026-09-14 | 首版成文：整合用语纪律、文档形态纪律、两件套与树形文档体系、新骨架过渡口径，新增可读性第一纪律与系统文档骨架 |
|
||||
| v2 | 2026-09-14 | 新增第 7 节引用纪律（跨文档高内聚低耦合：单点定义 / 规范名唯一 / 引用不转述 / 反向边登记 / 删除概念 SOP），原 7/8 节顺延为 8/9 |
|
||||
| v3 | 2026-09-15 | 命名纪律补充：现行文档代号清偿完毕，子系统统一以中文规范名指代；英文代号对照表落盘 `design/gdd/02-系统清单.md`，旧代号仅限解读归档 |
|
||||
| v4 | 2026-09-15 | 用语纪律正例去雾：第 4 节正例"剔除雾格后的可推理率"改为现行指标"实测可推理率"（原指标随雾格移除已删）；规则文字与历史反例"非雾腿"、第 8 节雾格移除去向说明均不动 |
|
||||
| v5 | 2026-09-15 | 新增第 7 节概念封装纪律（概念对象化建模：概念即对象 / 属性归属唯一 / 包含关系显式写 / 概念状态用枚举 / 附加物独立成对象 / 关系不吸内容），原 7/8/9 节顺延为 8/9/10，第 6 节骨架表与 CLAUDE.md 摘要的章节指针同步改指 |
|
||||
| v6 | 2026-09-16 | 待拍板收编批：第 8 节引用纪律新增「待拍板单点登记」（待拍板事项单点登记 `design/gdd/06-待拍板清单.md`，系统文档只留指路存根，新增条目直接登记清单）；第 6 节顶层文档表补入 `06-待拍板清单.md`，骨架表「待拍板」行改为指路存根口径 |
|
||||
| v7 | 2026-09-16 | 06 清单改版（用户拍板）：「待拍板」术语全仓改「待办」，清单更名 `design/gdd/06-待办清单.md`；清单内格式由四列表格改为「循环 → 系统 → 条目（四级标题）+ 粗体属性段（现状 / 归属 / 状态）」，条目解决后状态改"已解决（日期）"留痕；第 6 节顶层文档表与骨架表、第 8 节「待办单点登记」同步改指 |
|
||||
@@ -0,0 +1,46 @@
|
||||
# Godot — Version Reference
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Engine Version** | 4.7.2-stable（2026-08-18 发布） |
|
||||
| **Project Pinned** | 2026-09-07 |
|
||||
| **LLM Knowledge Cutoff** | May 2025（训练数据覆盖 ~4.3/4.4） |
|
||||
| **Risk Level** | **MEDIUM**（2026-09-12 降级）——4.5→4.7 API 级破坏性变更已逐条核实（源：官方迁移指南），无一条破坏本项目架构契约；残余风险 = 4.8（dev 阶段）未来升级 + 未覆盖的运行期边角行为，代理写码规则不变：不确定的 API 一律查 `docs.godotengine.org/en/4.7/` 或 WebSearch 核实后再用 |
|
||||
| **Last Docs Verified** | 2026-09-12（4.5/4.6/4.7 迁移指南逐条核实 + 版本检查：4.7.2 仍为最新稳定版，4.8 仅 dev 快照） |
|
||||
|
||||
## Post-Cutoff Version Timeline
|
||||
|
||||
| Version | 发布 | 与本项目相关要点 |
|
||||
|---|---|---|
|
||||
| 4.4 | 2025-03（训练覆盖边缘） | — |
|
||||
| 4.5-stable | 2025-09-15 | stencil 效果、无障碍改进；4.5.2（2026-03-19）为末版维护；**逐条变更已核实（2026-09-12）** |
|
||||
| 4.6-stable | 2026-02 起（4.6.1 2026-02） | Modern 主题、flexible docks、编辑器 QoL；4.6.3 维护；**逐条变更已核实（2026-09-12）** |
|
||||
| **4.7-stable** | 2026-06（**4.7.2 = 2026-08-18，本项目锁定**） | 见下；**逐条变更已核实（2026-09-12）** |
|
||||
| 4.8 | dev 快照 1–4（开发中） | 无稳定版发布日期；稳定版发布后跑 `/setup-engine refresh` |
|
||||
|
||||
## 4.7 与本项目相关的变更（已核实）
|
||||
|
||||
- `Tween.tween_await()`（信号等待）——**不影响** B1"结算逻辑禁 await"约束（那是设计约束，非引擎限制）
|
||||
- Control `offset_transform_*`（平移/旋转/缩放 Control 而不影响容器布局）——D1 HUD 可用
|
||||
- DrawableTexture2D、AreaLight3D、HDR 输出、新 Asset Store——本项目暂不依赖
|
||||
- 2D：CollisionShape2D 单向碰撞方向属性、conic gradient、AtlasTexture 进 TextureRect
|
||||
- **GDScript 两条语义变化**（打包数组元素赋值不触发属性 setter；类型化返回覆盖必须显式 return）——详见 `current-best-practices.md`
|
||||
- **新项目默认值已变**（stretch mode `canvas_items`、aspect `expand`；4.6 起 Windows 驱动 D3D12）——详见 `current-best-practices.md`
|
||||
- Android/iOS/XR 增强——本项目 PC 先行，无关
|
||||
|
||||
## Migration Guides（升级/写码前必读）
|
||||
|
||||
- 4.7: https://docs.godotengine.org/en/4.7/tutorials/migrating/upgrading_to_godot_4.7.html
|
||||
- 4.6 / 4.5 同路径模式：`.../tutorials/migrating/upgrading_to_godot_4.6.html`、`..._4.5.html`
|
||||
- 三份指南的逐条中文对照与项目相关性标注见 `breaking-changes.md`（2026-09-12 版）
|
||||
|
||||
## Note
|
||||
|
||||
**MEDIUM 风险处置（2026-09-12 更新）**：4.5→4.7 的 API 级破坏性变更清单已逐条核实并入 `breaking-changes.md`，deprecated → replacement 对照已并入 `deprecated-apis.md`；对本项目的结论 = **无一破坏 GDD 已锁架构契约**。残余风险两项：① 4.8 未来升级（dev 阶段，稳定版后 refresh）；② 运行期边角行为（迁移指南未覆盖的引擎内部行为差异）——代理写码规则保持不变：**不确定的 API 一律查 `docs.godotengine.org/en/4.7/` 或 WebSearch 核实后再用**。
|
||||
|
||||
## Verification History
|
||||
|
||||
| 日期 | 动作 |
|
||||
|---|---|
|
||||
| 2026-09-07 | 初次锁定 4.7.2；核实版本时间线与 4.7 特性清单 |
|
||||
| 2026-09-12 | `/setup-engine refresh`：4.5/4.6/4.7 官方迁移指南逐条核实（breaking-changes.md 逐条清单 + deprecated-apis.md 对照表 + 新建 current-best-practices.md）；版本检查确认 4.7.2 仍为最新稳定版（4.8 仅 dev）；风险等级 HIGH → MEDIUM |
|
||||
@@ -0,0 +1,115 @@
|
||||
# Godot Breaking Changes（4.4 → 4.7）
|
||||
|
||||
> **Last verified: 2026-09-12**（官方迁移指南三份逐条核实——4.5/4.6/4.7 API 级清单已补全，原 2026-09-07"待 refresh"状态解除）
|
||||
> 训练数据覆盖至 ~4.4：4.4 及以前的变更视为"已知基线"，4.5+ 为超出截止的增量。
|
||||
> 官方迁移指南（升级/写码前必读）：
|
||||
> - 4.5：https://docs.godotengine.org/en/4.7/tutorials/migrating/upgrading_to_godot_4.5.html
|
||||
> - 4.6：https://docs.godotengine.org/en/4.7/tutorials/migrating/upgrading_to_godot_4.6.html
|
||||
> - 4.7：https://docs.godotengine.org/en/4.7/tutorials/migrating/upgrading_to_godot_4.7.html
|
||||
>
|
||||
> 项目相关性图例：🔵 需要留意（本项目域内）/ ⚪ 本项目不用（3D/XR/网络/移动/GLTF/编辑器插件）。
|
||||
> 本项目形态：2D 回合制、GDScript 单语言、Control 重 UI、autoload + .tres、无 3D/物理/网络。
|
||||
|
||||
## 4.5（2025-09-15）
|
||||
|
||||
### API 级变更
|
||||
|
||||
| 类/方法 | 变更 | GDScript 兼容 | 项目相关性 |
|
||||
|---|---|---|---|
|
||||
| `Resource.duplicate(true)` | 深复制**不再覆盖外部子资源**；旧行为需 `duplicate_deep(DEEP_DUPLICATE_ALL)` | 行为变更 | 🔵 D2 schema/表资源复制语义注意 |
|
||||
| `Node.set_name` | 参数 `String` → `StringName` | 兼容 | 🔵 |
|
||||
| `JSONRPC.set_scope` | 更名 `set_method` | ❌ | ⚪ |
|
||||
| `Node.get_rpc_config` | 更名 `get_node_rpc_config` | ❌ | ⚪（RPC 不用） |
|
||||
| `RenderingServer.instance_reset_physics_interpolation` | **移除** | ❌ | ⚪（3D 插值） |
|
||||
| `RenderingServer.instance_set_interpolated` | **移除** | ❌ | ⚪ |
|
||||
| TextServer/Font/CanvasItem/TextLine/TextParagraph 全部 draw 方法 | 新增可选 `oversampling` 参数 | 兼容 | 🔵 D1 自绘文字 |
|
||||
| `TextServerExtension` 四个 draw 虚方法 | 同上签名变化 | ❌（全不兼容） | ⚪（不实现 TextServer 扩展） |
|
||||
| `RichTextLabel.add_image`/`update_image` | `size_in_percent` → `width_in_percent` + `height_in_percent` | 兼容 | 🔵（低——富文本用图时） |
|
||||
| C# `RenderingDevice.Features.Address` | 更名 `BufferDeviceAddress` | 仅 C# | ⚪（C# 不用） |
|
||||
| GLTF Accessor/BufferView 十字段 | int32 → int64 / 枚举化 | 仅 C# | ⚪（GLTF 不用） |
|
||||
|
||||
### 行为变更
|
||||
|
||||
- **TileMapLayer 物理分块默认开启**；`get_coords_for_body_rid()` 返回值变化；需 4.4 精确行为设 `physics_quadrant_size=1` —— 🔵 若棋盘实现走 TileMapLayer（当前设计倾向自绘，未定）
|
||||
- 3D 模型导入 skeleton 行为修复（新文件新行为；旧文件需改 Import Naming Version）—— ⚪
|
||||
- Navigation 区域默认异步线程更新；navmesh 合并次序变化 —— ⚪（A2 用自研 BFS，不用 NavigationServer）
|
||||
- Jolt：`areas_detect_static_bodies` 设置移除 —— ⚪
|
||||
- `ProjectSettings.add_property_info()` 对缺失/非法键（含 `usage`）告警 —— 🔵（若程序化注册设置项）
|
||||
|
||||
## 4.6（2026-02）
|
||||
|
||||
### API 级变更
|
||||
|
||||
| 类/方法 | 变更 | GDScript 兼容 | 项目相关性 |
|
||||
|---|---|---|---|
|
||||
| `FileAccess.get_as_text` | `skip_cr` 参数**移除** | ❌ | 🔵 文本读取路径 |
|
||||
| `FileAccess.create_temp` | `mode_flags` int → `ModeFlags` 枚举 | 兼容性检查变化 | 🔵 |
|
||||
| AnimationPlayer `assigned_animation`/`autoplay`/`current_animation` | `String` → `StringName`（`get_queue()`、`current_animation_changed` 信号参数同步） | ❌（类型不兼容） | 🔵 B5 期 |
|
||||
| SpringBoneSimulator3D 三个枚举 | 移至 `SkeletonModifier3D` | ❌ | ⚪ |
|
||||
| StreamPeerTCP / TCPServer | `disconnect_from_host`/`get_status`/`poll`、`is_connection_available`/`is_listening`/`stop` 上移至 `StreamPeerSocket`/`SocketServer` 基类 | 兼容（继承） | ⚪（网络不用） |
|
||||
| `Control.grab_focus`/`has_focus`、`LineEdit.edit`、`SplitContainer.clamp_split_offset`、`FileDialog.add_filter` | 新增可选参数 | 兼容 | 🔵 D1 |
|
||||
| EditorFileDialog | `add_side_menu` **移除**；17 方法 / 8 属性 / 4 信号并入 `FileDialog` 基类 | 兼容（继承） | ⚪（编辑器） |
|
||||
| `Performance.add_custom_monitor` | 新增可选 `type` 参数 | 兼容 | 🔵（调试遥测可选） |
|
||||
|
||||
### 行为 / 格式变更
|
||||
|
||||
- **TSCN 格式**：`load_steps` 不再写入、节点唯一 ID 入文件——双向兼容，但 VCS diff 变大（可 Project > Tools > Upgrade Project Files 预升级）—— 🔵
|
||||
- **Glow 默认值大改**（blend mode Soft Light → Screen、intensity 0.8 → 0.3、各 level 重排）；Mobile 渲染器 glow 重写 —— 🔵 D1/B5 用 2D Glow 时注意视觉基底已变
|
||||
- AStar2D/AStar3D/AStarGrid2D：`from_id` 被禁用/固体时返回空路径 —— ⚪（自研 BFS）
|
||||
- **新项目默认值**：Windows 渲染驱动 D3D12；3D 物理引擎 Jolt —— 🔵 创建 project.godot 时须知（本项目 2D、无 3D 物理，渲染驱动选择归实现期 ADR）
|
||||
|
||||
## 4.7（2026-06；4.7.2 = 本项目锁定版本）
|
||||
|
||||
### API 级变更
|
||||
|
||||
| 类/方法 | 变更 | GDScript 兼容 | 项目相关性 |
|
||||
|---|---|---|---|
|
||||
| **GDScript 语义 ①** | 打包数组元素赋值不再触发整属性 setter（GH-113228） | 语义变化 | 🔵 全部 .gd 代码 |
|
||||
| **GDScript 语义 ②** | 覆盖类型化返回方法：返回类型自动继承，必须显式 `return`（GH-115763） | 语义变化 | 🔵 全部 .gd 代码 |
|
||||
| `Object.is_class()` | 参数 `String` → `StringName` | 兼容 | 🔵 |
|
||||
| `PhysicsServer2D.body_set_shape_as_one_way_collision` | 新增可选 `direction`（= CollisionShape2D 单向碰撞方向属性的 server 层） | 兼容 | 🔵（已核实特性的 API 面） |
|
||||
| `PhysicsServer2DExtension._body_set_shape_as_one_way_collision` | 新增**必填** `direction` | ❌ | ⚪（不写 PhysicsServer 扩展） |
|
||||
| `CanvasItem` 线条绘制 | 不再自动加抗锯齿羽化；粗线需手动绘制（GH-105122） | 行为变更 | 🔵 D1 自绘 |
|
||||
| Input 设备 ID | 鼠标/键盘设备 ID `0` → `InputEvent.DEVICE_ID_MOUSE` / `DEVICE_ID_KEYBOARD` 常量 | 行为变更 | 🔵 D1 输入 |
|
||||
| `Control.accessibility_live` | 枚举类型 `DisplayServer.` → `AccessibilityServer.AccessibilityLiveMode` | 仅 C# 不兼容 | 🔵（低） |
|
||||
| RichTextLabel 图片参数 | `add_image`/`update_image` width/height int→float；`width_in_percent/height_in_percent` → `width_unit/height_unit`；常量 `UPDATE_WIDTH_IN_PERCENT` → `UPDATE_WIDTH_UNIT` | ❌（常量更名） | 🔵（低） |
|
||||
| `Animation.length` | 元数据 float → double | 仅 C# 不兼容 | 🔵（低，B5 期） |
|
||||
| AnimationNodeBlendSpace1D/2D | 布尔 `sync` 属性 → `SyncMode` 枚举（`sync_mode`） | 行为变更 | ⚪（3D 动画树） |
|
||||
| `Font.find_variation` / `TreeItem.select` / `ZIPPacker.start_file` / `Image.save_exr`×2 | 新增可选参数 | 兼容 | ⚪/🔵 |
|
||||
| `AudioEffectSpectrumAnalyzer.tap_back_pos` | **移除** | ❌ | ⚪（D4 Alpha 期若用频谱分析注意） |
|
||||
| `EditorSceneFormatImporter` 七常量 | 并入 `ImportFlags` 枚举 | 仅 C# 源不兼容 | ⚪ |
|
||||
| `EditorVCSInterface._commit` | 新增 `amend` 参数 | ❌ | ⚪ |
|
||||
| `OptimizedTranslation.generate` | 返回 void → bool | 仅 C# 二进制 | ⚪ |
|
||||
| `AudioStreamPlayer.area_mask` | 默认 1 → 0 | 行为变更 | ⚪（D4 Alpha 期注意） |
|
||||
|
||||
### 行为 / 默认值变更
|
||||
|
||||
- `LinearToSRGB` visual shader 不再 clamp 到 [0,1]（Mobile/Forward+）—— 🔵（若写 shader）
|
||||
- **新项目默认值**：stretch mode `disabled` → `canvas_items`、stretch aspect `keep` → `expand` —— 🔵 **创建 project.godot 时须知（训练数据默认值已过时）**
|
||||
- macOS 最低版本 10.13 → 11 —— ⚪
|
||||
- `LookAtModifier3D.relative` 默认 true → false —— ⚪
|
||||
- `ResourceImporterDynamicFont.hinting` 默认 1 → 3 —— 🔵（字体导入）
|
||||
- `rendering/reflections/sky_reflections/roughness_layers` 默认 7 → 8 —— ⚪（3D）
|
||||
|
||||
## 已知基线（≤4.4，训练数据内，低风险）
|
||||
|
||||
- 4.x 系列：Tween 一律经 `create_tween()` 获取（Tween 节点已废）；信号连接用 `Callable` 语法；`@onready`/`@export` 注解体系；int 恒 64 位（D2 R2 规约依赖此语义，4.x 内稳定）
|
||||
|
||||
## 本项目影响评估（2026-09-12 复核）
|
||||
|
||||
| 变更 | 影响 |
|
||||
|---|---|
|
||||
| 4.7 全部已核实特性 | 均为增量，无破坏 D2/A3 已批准规约的项 |
|
||||
| **4.5–4.7 逐条 API 变更** | **无一破坏 GDD 已锁架构契约**（autoload 体系 / .tres 单一事实源 / Callable 信号 / int64 二补数 / headless SceneTree 协议均不受影响） |
|
||||
| 需入编码规范的项 | GDScript 两条新语义（打包数组 setter / 显式 return）→ `current-best-practices.md` |
|
||||
| 需项目设置留意的项 | 新项目默认值已变（stretch mode / aspect / D3D12）→ `current-best-practices.md` |
|
||||
| `Resource.duplicate(true)` 语义收窄 | D2 表资源含外部子资源时的复制语义注意 |
|
||||
|
||||
## Pending
|
||||
|
||||
- [x] 4.4→4.5 breaking changes 逐条清单（2026-09-12 官方迁移指南）
|
||||
- [x] 4.5→4.6 breaking changes 逐条清单（2026-09-12 官方迁移指南）
|
||||
- [x] 4.6→4.7 breaking changes 逐条清单（2026-09-12 官方迁移指南）
|
||||
- [x] 各版本 deprecated → replacement 对照表（见 `deprecated-apis.md`，2026-09-12）
|
||||
- [ ] 4.8 逐条清单（当前仅 dev 快照；稳定版发布后跑 `/setup-engine refresh`）
|
||||
- [ ] modules/ 分域参考（按实现期需要建，非阻塞）
|
||||
@@ -0,0 +1,49 @@
|
||||
# Godot 当前最佳实践（4.7 视角，post-cutoff）
|
||||
|
||||
> **Last verified: 2026-09-12**（源：官方迁移指南 4.5/4.6/4.7 逐条核实 + 4.7 release 页）
|
||||
> 用途：训练数据（~4.4）之后的实践差异速查。写码代理在以下事项上**不要**按训练数据默认值行事。
|
||||
|
||||
## 1. 新建 project.godot 的默认值差异（最易踩坑）
|
||||
|
||||
| 设置 | 训练数据默认（≤4.4） | 4.7 实际新项目默认 | 生效版本 |
|
||||
|---|---|---|---|
|
||||
| `display/window/stretch/mode` | `disabled` | `canvas_items` | 4.7（新项目） |
|
||||
| `display/window/stretch/aspect` | `keep` | `expand` | 4.7（新项目） |
|
||||
| `rendering/rendering_device/driver.windows` | Vulkan（Forward+） | D3D12 | 4.6（新项目） |
|
||||
| `physics/3d/physics_engine` | GodotPhysics3D | Jolt | 4.6（新项目；本项目 2D、无 3D 物理，无关） |
|
||||
|
||||
本项目为 2D 棋盘 UI：stretch mode / aspect 的最终选择归渲染器实现期 ADR，但须知道**引擎新项目默认值已不是训练数据里的那个**——新建工程后检查这三项。
|
||||
|
||||
## 2. GDScript 4.7 两条语义变化（建议入编码规范）
|
||||
|
||||
1. **打包数组元素赋值不再触发属性 setter**（4.7，GH-113228）：`my_packed_array[i] = v` 不再调用所在对象的 property setter——依赖 setter 副作用的写法必须改为显式赋回 + 显式调用 setter。D2 schema 类若以 setter 做校验，注意此差异。
|
||||
2. **类型化返回的方法覆盖必须显式 `return`**（4.7，GH-115763）：覆盖带返回类型的方法时返回类型自动继承，缺少 return 直接报错（旧版隐式返回 null）——虚方法覆盖一律显式写 return。
|
||||
|
||||
## 3. 资源与文件
|
||||
|
||||
- `Resource.duplicate(true)`（4.5 起）：深复制**只覆盖内部子资源**，不再覆盖外部子资源；需旧行为用 `duplicate_deep(DEEP_DUPLICATE_ALL)`。D2 表资源含外部子资源时注意复制语义。
|
||||
- `FileAccess.get_as_text()` 的 `skip_cr` 参数已移除（4.6）——换行处理如需自定义须自行实现。
|
||||
- TSCN 格式（4.6）：`load_steps` 不再写入、节点唯一 ID 入文件——双向兼容，但 VCS diff 会变大（可 Project > Tools > Upgrade Project Files 预升级，减少一次性大 diff）。
|
||||
- `ProjectSettings.add_property_info()`（4.5）：对缺失/非法键（含 `usage`）告警；改用 `set_as_basic()` / `set_restart_if_changed()` / `set_as_internal()`。
|
||||
|
||||
## 4. 2D / UI / 文本
|
||||
|
||||
- `CanvasItem` 线条绘制**不再自动加抗锯齿羽化**（4.7）——粗线/描边需手动方案（D1 自绘棋盘格边框时注意）。
|
||||
- 输入设备 ID：比较输入来源时用 `InputEvent.DEVICE_ID_MOUSE` / `DEVICE_ID_KEYBOARD` 常量，**不要硬编码 0**（4.7）——D1 输入路由。
|
||||
- 字体导入 `hinting` 默认 1 → 3（4.7）；TextServer/Font/CanvasItem 全部 draw 方法新增可选 `oversampling` 参数（4.5）——自绘文字（数字标签）可显式控制过采样。
|
||||
- RichTextLabel 图片参数两轮变化：4.5 `size_in_percent` → `width_in_percent`+`height_in_percent`；4.7 → `width_unit`/`height_unit`（bool → `ImageUnit`），常量 `UPDATE_WIDTH_IN_PERCENT` → `UPDATE_WIDTH_UNIT`。
|
||||
- **Glow 默认值大改**（4.6）：blend mode Soft Light → Screen、intensity 0.8 → 0.3、各 level 重排——2D 后处理发光的视觉基底已变，调参以 4.7 默认为起点。
|
||||
- `Control.grab_focus` / `has_focus` 新增可选参数（4.6，`hide_focus` / `ignore_hidden_focus`）——焦点可视化管理更细。
|
||||
|
||||
## 5. 4.7 已核实新特性（本项目可用的增量）
|
||||
|
||||
- `Tween.tween_await()`：信号等待语法糖——**注意** B1 结算逻辑禁 await 是设计约束（可回放步骤流），该 API 不改变该约束
|
||||
- Control `offset_transform_*`：平移/旋转/缩放 Control 不影响容器布局——D1 HUD 局部动效可用
|
||||
- CollisionShape2D 单向碰撞方向属性（+ `PhysicsServer2D.body_set_shape_as_one_way_collision` 的 `direction` 参数）——本项目棋盘非物理驱动，暂不依赖
|
||||
- conic gradient、AtlasTexture 进 TextureRect——D1 贴图/着色可选
|
||||
- DrawableTexture2D、AreaLight3D、HDR 输出、内置 VirtualJoystick、新 Asset Store——本项目暂不依赖
|
||||
- `Font.find_variation` 扩展（palette_index / custom_colors）、`TreeItem.select` 扩展——低相关
|
||||
|
||||
## 6. 本项目不消费的域（相关变更可忽略）
|
||||
|
||||
3D 渲染与物理（Jolt 行为变化 / SoftBody / WorldBoundary / SpringBone / LookAtModifier）、XR/OpenXR、网络（StreamPeerTCP/TCPServer 方法上移、RPC 更名）、GLTF 导入（int64 字段）、移动端导出（Android 模板结构变化、.NET 9）、编辑器插件 API（ImportFlags / VCS / ExportPlatform）。
|
||||
@@ -0,0 +1,51 @@
|
||||
# Godot Deprecated APIs（Don't use X → Use Y）
|
||||
|
||||
> **Last verified: 2026-09-12**
|
||||
> 4.5–4.7 移除/更名/签名变化对照已补全（源 = 官方迁移指南，2026-09-12 逐条核实）。仍不含 4.8（dev 阶段）。**不要向本表添加未经验证的条目。**
|
||||
|
||||
## 4.7 release 页核实
|
||||
|
||||
- 4.7 release 页未列出新的 API 弃用；完整清单以其迁移指南为准（已逐条核实，见下节）
|
||||
|
||||
## 4.5–4.7 移除 / 更名 / 签名变化对照（源 = 官方迁移指南）
|
||||
|
||||
| Don't use | Use | Since | GDScript 影响 | 项目相关性 |
|
||||
|---|---|---|---|---|
|
||||
| `RenderingServer.instance_reset_physics_interpolation()` | （无替代——API 移除） | 4.5 | ❌ 移除 | ⚪ |
|
||||
| `RenderingServer.instance_set_interpolated()` | （无替代——API 移除） | 4.5 | ❌ 移除 | ⚪ |
|
||||
| `JSONRPC.set_scope()` | `set_method()` | 4.5 | ❌ 更名 | ⚪ |
|
||||
| `Node.get_rpc_config()` | `get_node_rpc_config()` | 4.5 | ❌ 更名 | ⚪ |
|
||||
| `Node.set_name(name: String)` | `set_name(name: StringName)` | 4.5 | 兼容（自动转换） | 🔵 |
|
||||
| `TextServerExtension` 四个 draw 虚方法 | 签名新增 `oversampling` | 4.5 | ❌（虚方法覆盖不兼容） | ⚪ |
|
||||
| RichTextLabel `size_in_percent` 参数 | `width_in_percent` + `height_in_percent` | 4.5 | 兼容（参数拆分） | 🔵（低） |
|
||||
| `FileAccess.get_as_text(skip_cr)` | `get_as_text()`（**skip_cr 参数移除**） | 4.6 | ❌ 参数移除 | 🔵 |
|
||||
| `EditorFileDialog.add_side_menu()` | （无替代；EditorFileDialog 17 方法/8 属性/4 信号并入 `FileDialog`） | 4.6 | ❌ 移除 | ⚪ |
|
||||
| AnimationPlayer `assigned_animation` / `autoplay` / `current_animation`（String） | `StringName`（含 `get_queue()`、`current_animation_changed` 参数） | 4.6 | ❌ 类型不兼容 | 🔵（B5 期） |
|
||||
| SpringBoneSimulator3D 三个枚举 | `SkeletonModifier3D.BoneDirection` / `.RotationAxis` | 4.6 | ❌ | ⚪ |
|
||||
| `AudioEffectSpectrumAnalyzer.tap_back_pos` | （无替代——属性移除） | 4.7 | ❌ 移除 | ⚪（D4 期注意） |
|
||||
| AnimationNodeBlendSpace1D/2D `sync: bool` 属性 | `sync_mode: SyncMode` 枚举 | 4.7 | ❌ 属性类型变化 | ⚪ |
|
||||
| RichTextLabel `ImageUpdateMask.UPDATE_WIDTH_IN_PERCENT` | `UPDATE_WIDTH_UNIT`；`width/height_in_percent` 参数 → `width/height_unit`（bool → `ImageUnit`） | 4.7 | ❌ 常量/参数更名 | 🔵（低） |
|
||||
| `Object.is_class("X")`（String 字面量） | `is_class(&"X")`（StringName） | 4.7 | 兼容 | 🔵 |
|
||||
| `EditorVCSInterface._commit()` | 签名新增 `amend` | 4.7 | ❌（虚方法覆盖不兼容） | ⚪ |
|
||||
| `PhysicsServer2DExtension._body_set_shape_as_one_way_collision()` | 签名新增必填 `direction` | 4.7 | ❌（虚方法覆盖不兼容） | ⚪ |
|
||||
| C# `RenderingDevice.Features.Address` | `BufferDeviceAddress` | 4.5 | 仅 C# | ⚪ |
|
||||
| GLTF Accessor/BufferView 十字段（int） | int64 / 强类型枚举 | 4.5 | 仅 C# | ⚪ |
|
||||
|
||||
## 训练数据内基线（≤4.4，高置信，本项目相关）
|
||||
|
||||
| Don't use | Use | Since | 备注 |
|
||||
|---|---|---|---|
|
||||
| `Tween` 节点 / `create_tween()` 以外的补间获取 | `create_tween()` / `tween_property()` | 4.0 | Tween 节点已移除 |
|
||||
| 旧式 `connect("sig", instance, "method")` | `signal.connect(callable)` | 4.0 | Callable 语法 |
|
||||
| `onready var` | `@onready var` | 4.0 | 注解体系 |
|
||||
| `export var` | `@export var` | 4.0 | |
|
||||
| `RandomNumberGenerator` 自建实例（玩法侧） | `RngService.open_stream(stream)` | 本项目 | D2 Rule 5（项目级禁令，非引擎弃用） |
|
||||
| `randomize()`（玩法代码） | 禁止——种子归 `RngService.set_master_seed()`（C2 调用） | 本项目 | D2 Rule 5 |
|
||||
| `yield` | `await` | 4.0 | 4.7 新增 `Tween.tween_await()`；但 B1 结算逻辑禁 await（设计约束） |
|
||||
|
||||
## Pending
|
||||
|
||||
- [x] 4.5 deprecated → replacement 对照（2026-09-12）
|
||||
- [x] 4.6 deprecated → replacement 对照（2026-09-12）
|
||||
- [x] 4.7 deprecated → replacement 对照（2026-09-12）
|
||||
- [ ] 4.8 对照（dev 阶段；稳定版发布后 `/setup-engine refresh`）
|
||||
@@ -339,7 +339,7 @@
|
||||
|
||||
#### 战斗屏 C 区预留区接线（魔法道具槽 + 本关强化列表，2026-09-26 登记）
|
||||
|
||||
**现状**：C 区精简批（台账 165，[battle.md](../ux/battle.md) §信息归属原则与分区唯一展示面）已在 C 区落两个预留区壳——魔法道具槽（4 空槽占位，数量/交互形态未定稿）、本关强化列表（空态隐藏，`set_level_bonuses` 接线面已留）。两者均零数据接线：魔法道具槽待魔法道具批定稿道具形态后接库存只读面；本关强化列表待锻造/大奖励/关卡奖励节点呈现批接 runner 加算区投影（bonus{atk,max_hp,armor_class}）。
|
||||
**现状**：C 区精简批（台账 165，[battle.md](ux/battle.md) §信息归属原则与分区唯一展示面）已在 C 区落两个预留区壳——魔法道具槽（4 空槽占位，数量/交互形态未定稿）、本关强化列表（空态隐藏，`set_level_bonuses` 接线面已留）。两者均零数据接线：魔法道具槽待魔法道具批定稿道具形态后接库存只读面；本关强化列表待锻造/大奖励/关卡奖励节点呈现批接 runner 加算区投影（bonus{atk,max_hp,armor_class}）。
|
||||
|
||||
**归属**：魔法道具批（道具槽）/ 表现层升级批（本关强化列表）· 载体 `hero_info_panel_view.gd`
|
||||
|
||||
|
||||
@@ -61,7 +61,7 @@
|
||||
|
||||
弃图率 / 每轮刷新率随试玩日志采集；预警阈值须有基线读数才能定（2026-09-18 拍板：现在定是拍脑袋）——随验收读数重测批出基线，数字与调参联动复核。挖掘期当场刷新无结算发生，两读数均不影响对账。
|
||||
|
||||
**基线已采（2026-09-19 验收重测批，读数详见 [判读报告](../../production/qa/acceptance-rerun-20260919.md)）**：MC 完美档弃图 ~0.1 次/局量级（L1 基线格 0.23 / L2 0.03）、normal 档零弃图（模拟画像不主动刷新）；每轮刷新率 ≤0.6%。阈值数字仍归调参批。两读数已固化进 `log_analysis.py` 关卡级统计列（分析器随批升级）。
|
||||
**基线已采（2026-09-19 验收重测批，读数详见 [判读报告](../qa/acceptance-rerun-20260919.md)）**：MC 完美档弃图 ~0.1 次/局量级（L1 基线格 0.23 / L2 0.03）、normal 档零弃图（模拟画像不主动刷新）；每轮刷新率 ≤0.6%。阈值数字仍归调参批。两读数已固化进 `log_analysis.py` 关卡级统计列（分析器随批升级）。
|
||||
|
||||
|
||||
### ⑧ 旗行为基线监控（插旗不可逆批 2026-09-19 落地后的行为监控；原「提案评估前置采集」使命随提案转正终结）
|
||||
@@ -88,7 +88,7 @@
|
||||
|
||||
**局后随手记**（一句话即可，事后对日志）：每局大概掉了多少血 / 有没有整轮一点血没掉的轮次 / 通关与否 / 有没有"这局特别顺/特别倒霉"的体感（种子体感核对用）。
|
||||
|
||||
**结果回流**：日志取数 → 真人修正系数 k（真人整关承伤中位 ÷ 模拟完美档中位，预警线 k<0.3）并入[判读报告](../../production/qa/acceptance-rerun-20260919.md)终稿；①–⑤ 体感按各条目的回流位分流。
|
||||
**结果回流**：日志取数 → 真人修正系数 k（真人整关承伤中位 ÷ 模拟完美档中位，预警线 k<0.3）并入[判读报告](../qa/acceptance-rerun-20260919.md)终稿；①–⑤ 体感按各条目的回流位分流。
|
||||
|
||||
## 验收读数重测批义务（给下一批的输入，非手工项）
|
||||
|
||||
|
||||
@@ -74,7 +74,7 @@
|
||||
|
||||
解锁让玩家变强，难度验收区间随之需要平移——双方约定（难度曲线与Boss 定稿口径）永久强化的影响**不直接改难度判据**，而是按统一换算率折算成通关率带的平移量后套用：完美档 gate 与 normal 目标带的判读口径不变，带随解锁等级平移。
|
||||
|
||||
换算率表（registry 键 `meta_progression_conversion_table`，数值行读 `data/tables/meta.tres` conversion 行族）登记三个属性维度（2026-09-18 拍板；"行" = 表内一条记录，一个属性维度即一行条目，全仓与"行值"同义）。现行表值（2026-09-23 换算率标定批投值——OFAT 冒险注入档与白板同种子配对的逐关条件通关率差实测，冒险条件口径 + 当日数值包现行态；报告 `production/qa/conversion-calibration/calibration.raw.md`，判定端 ④ 段可复判）：
|
||||
换算率表（registry 键 `meta_progression_conversion_table`，数值行读 `data/tables/meta.tres` conversion 行族）登记三个属性维度（2026-09-18 拍板；"行" = 表内一条记录，一个属性维度即一行条目，全仓与"行值"同义）。现行表值（2026-09-23 换算率标定批投值——OFAT 冒险注入档与白板同种子配对的逐关条件通关率差实测，冒险条件口径 + 当日数值包现行态；报告 `../../../qa/conversion-calibration/calibration.raw.md`，判定端 ④ 段可复判）：
|
||||
|
||||
| 换算行 | 折算语义 | 每级带平移量（现行表值） |
|
||||
|---|---|---|
|
||||
|
||||
@@ -105,7 +105,7 @@ Boss 兑付（胜利或英雄死亡）触发关卡收束点，此后不再有选
|
||||
2. 定位信息只有两样：**关卡序号 + 节点编号**。战斗侧拿编号查表、配敌、掷数量、跑技能池、兑踩雷负向——一切战斗内部初始化归战斗循环文档（原"叠伏击"随 2026-09-20 八型批伏击退役改述），图的初始化不为战斗初始化做任何决定。
|
||||
3. 本文不预掷任何战斗数值、不读敌人数量；教学位节点同样掷骰、没有结构豁免（"任何掷骰结果下都稳过"的保证是[难度曲线与Boss](难度曲线与Boss.md)的数值责任）。
|
||||
|
||||
第二关的"新内容 = 既有池新技能"（[技能池提案](../../../../docs/proposal-skill-pool.md)已定）投放时，改的是战斗侧行里引用的技能池内容——节点图结构原样不动，本文无需为投放留任何新结构位。
|
||||
第二关的"新内容 = 既有池新技能"（[技能池提案](../../../research/proposal-skill-pool.md)已定）投放时，改的是战斗侧行里引用的技能池内容——节点图结构原样不动，本文无需为投放留任何新结构位。
|
||||
|
||||
**节点奖励 = 功能道具的正式渠道**（2026-09-17 拍板，原 06 清单条目已解决移除）：奖励节点兑付 = 获得一件功能道具并进入持有域。道具内容、持有域归属与使用窗口语义归[魔法道具](../排雷循环/魔法道具.md)内容重定批——切片期道具内容整批后置，奖励节点**零兑付直通是合法空态**，不是缺陷。
|
||||
|
||||
@@ -185,4 +185,4 @@ Boss 兑付（胜利或英雄死亡）触发关卡收束点，此后不再有选
|
||||
| v1.0 | 2026-09-17 | **定稿**（逐问题拍板，全用户裁决）：① 形态重开——用户拍板重开[05-不做清单](../../05-不做清单.md)「路径分支地图后置」裁定，定稿为**分支节点图**（分层节点图，杀戮尖塔 / 哥布林弹珠同构；方块地牢美术观感、逻辑为节点图），P0 图定稿 + 单链特例先行；② 节点类型定稿四类封闭枚举不扩类；③ 行进交互定稿全节点确认 + 兑付后确认、零自动推进；④ 遭遇构成收窄为编排面三条（战斗内部初始化全归战斗小循环），寻址定稿节点编号升级（`node_depth` 语义升级为关卡内唯一节点编号，表键与字段名零改动，单链零漂移）；⑤ 节点奖励拍板为功能道具的正式渠道（内容归魔法道具内容重定批，切片期直通为合法空态）；⑥ 「精英与 Boss 编码位」（同层多遭遇由节点编号消解，不设编码位）与「多敌数量的消费面」（关卡层零消费）两悬案收口，同场多敌种面拆归战斗侧；⑦ 切片行进代码对照的接口漂移清单登记 06 |
|
||||
| v1.0.1 | 2026-09-17 | **P1 分支节点图内容与实现批落地**（用户拍板任务批——切片代码 / 难度曲线与Boss v0.7 / registry / 06 待办同批）：首张分支图 = 切片关卡 2「第二层 · 幽暗地域」行集落地（9 节点网状图：入口 0 → 中间三层 2/3/2 → Boss 8，真实岔路 4 处，奖励点 + 恢复点各 1，战斗节点 6 + Boss）；行进器图版推进（`choices_presented` 选路态 + `pick_next_node`——零自动推进，战斗胜利不再自动推进、`continue_after_node` 泛化为兑付确认，06 接口漂移清单 ④⑤⑧ 清偿）；图合法性校验落地 `LevelTable.validate`（单链与图同一套算法，L1 零迁移过校验，违规加载致命）；节点图选路 UI（选路覆盖层整图自绘——房间方块 + 通道连线 + 当前/候选高亮，占位图形质量；顶栏图形态渲染行进序列 + 候选）；首页"关卡 2 试玩"直入口（测试模式，≠ 两关序列生效）。本版本号只记实现批状态，图规则口径零改动 |
|
||||
| v1.1 | 2026-09-20 | **商店房扩类（GP+商店房批，用户拍板——与冒险结构 / 战斗结算 / 地图战斗资源 / 难度曲线与Boss / registry / 切片同批）**：① 节点封闭枚举四类→五类（+商店房）；② 编排规则定稿——每关恰 1、关底 Boss 前一位必经位（哈迪斯式"决战前最后一个补给点"定位）；必经位由冒烟断言承载、图合法性六检零新增；③ 兑付定稿——打开商店覆盖层、购买即时生效写统一冒险加算区（与关卡大奖励同账，归冒险结构）、离开后兑付确认；商店房不携带战斗行；④ 节点兑付表 / 纪律表 / 依赖表 / P0 闭环 / 验收标准 / P2「事件类节点候选」注记同步 |
|
||||
| v1.2 | 2026-09-23 | **停点前移批（冒险入口流程倒置修复，用户 2026-09-23 拍板；上位裁决 `docs/architecture/adr-0006-board-node2d-rendering.md` 与 `docs/architecture/board-node2d-migration-plan.md` §1，代码实装另批并行）**：① 行进循环改停点前移口径——关卡开始即呈现节点图选路停点（关卡画面 = 选路覆盖层常驻化，入口节点不自动进入，第一次选路就是"出发"），选路确认进节点，兑付确认后返回关卡画面再选路（战后回图）；兑付后确认、零自动推进两条纪律语义不变，只改承载位；② 呈现侧口径补进度承载条款——关卡画面本体即节点链进度呈现载体（节点态直接读图：已过暗金 / 当前金 / 候选下一跳通道亮金 / Boss 旗朱描边），不另设进度条组件（战斗屏 A 区进度条随批退役）；③ P0 闭环两条、依赖表 HUD 框架行、验收标准「行进自主」条同步。**批内代拍板三项已追认（2026-09-24 用户确认）**：① B/C/D 字母保持不重编；② 28px 纵向空间划归 C/D 底行；③ 关卡画面进度呈现由选路覆盖层节点态承载（登记面见 HUD框架 v0.8） |
|
||||
| v1.2 | 2026-09-23 | **停点前移批（冒险入口流程倒置修复，用户 2026-09-23 拍板；上位裁决 `../../../dev/architecture/adr-0006-board-node2d-rendering.md` 与 `../../../dev/architecture/board-node2d-migration-plan.md` §1，代码实装另批并行）**：① 行进循环改停点前移口径——关卡开始即呈现节点图选路停点（关卡画面 = 选路覆盖层常驻化，入口节点不自动进入，第一次选路就是"出发"），选路确认进节点，兑付确认后返回关卡画面再选路（战后回图）；兑付后确认、零自动推进两条纪律语义不变，只改承载位；② 呈现侧口径补进度承载条款——关卡画面本体即节点链进度呈现载体（节点态直接读图：已过暗金 / 当前金 / 候选下一跳通道亮金 / Boss 旗朱描边），不另设进度条组件（战斗屏 A 区进度条随批退役）；③ P0 闭环两条、依赖表 HUD 框架行、验收标准「行进自主」条同步。**批内代拍板三项已追认（2026-09-24 用户确认）**：① B/C/D 字母保持不重编；② 28px 纵向空间划归 C/D 底行；③ 关卡画面进度呈现由选路覆盖层节点态承载（登记面见 HUD框架 v0.8） |
|
||||
@@ -285,4 +285,4 @@ GP（显示名「金币」）是冒险内的一次性属性提升货币：战斗
|
||||
| v0.6 | 2026-09-21 | **冒险结构实现批落地登记（切片 AdventureRunner + LevelRunner 账本外置 + AdventureTable 建表——与切片代码 / registry / 03 / 06 / roadmap 同批）**：本批只记实现批状态，正文规则口径零改动。落地面 = 三关正式序列生效（首页「开始冒险」）、接口契约四件套正式侧承载（开始关卡 start_level_external / 战斗结果上报共享账本直写 / 治疗封顶回报 apply_rest / 关卡结束 level_finished）、生命账本与 GP 冒险账本上交冒险结构层、大奖励非末关恰兑付一次（末关钥石照记）、冒险摘要五件事产出、主种子恰一次注入（registry rng_service new_adventure 调用权同批登记）、结算受理只算一次；06 待办「两关序列未生效」「切片行进代码与定稿的接口漂移」「冒险表未建表」三条随批解决移除。**规划书冲突按代码为准登记两处**：①大奖励 `_pending_next_level` 置位先于 emit（信号同步派发——处理器内立即确认需标记已就位）；②放弃受理补 state=running 守卫（契约 7 结算受理只算一次的 abandoned 侧对齐） |
|
||||
| v0.7 | 2026-09-21 | **放弃入口界面呈现批（用户拍板「放弃接口也要有」——台账 119，推翻本文原「MVP 无界面入口、呈现后置」条款）**：① 放弃入口挂[关卡节点地图](关卡节点地图.md)选路覆盖层（选路停点 = 天然非战斗期；战斗中拒绝转为防御兜底分支——入口在战斗期不可达）；② 入口只在冒险模式开放，单关测试直入口没有可放弃的冒险对象；③ 正文改现行口径（放弃节 / 验收标准放弃条），P1 后置表「放弃入口的界面呈现」随落地移除（同表「两关序列生效」系 v0.6 已落地漏收口，顺手同口径移除）；④ 验收闸 = ui_probe 三断言（默认隐藏 / 冒险模式可见 / 首战中按下被拒 state 保持 running）+ 冒烟既有放弃两态 API 断言 |
|
||||
| v0.8 | 2026-09-23 | **单关测试直入口退役（用户拍板——唯一试玩入口 = 完整三关冒险）**：正文改现行口径两处（放弃节「按钮只在冒险模式开放」的理由从「单关直入口无冒险对象」改为「选路覆盖层只在冒险模式出现」；验收标准放弃条同步去单关直入口从句）——放弃语义对象（整局冒险）与拒绝分支零改动。版本历史行（v0.7）按 ADR 纪律不回改 |
|
||||
| v0.9 | 2026-09-23 | **停点前移批流程口径对齐（用户 2026-09-23 拍板冒险入口流程倒置修复——与 HUD框架 / 关卡节点地图 / battle.md / `docs/architecture/adr-0006-board-node2d-rendering.md` 同批）**：P0 闭环「开始关卡」条改新流程口径——关卡节点地图加载节点图后停在入口选路停点（关卡画面，选路覆盖层常驻形态），行进自玩家首次选路开始；通读复核其余章节——「通关自动进下一关」属关卡序列层语义（进入下一关后仍出图选路，零矛盾）、接口契约四件套、收束点先清库后宣布、放弃入口（选路停点 = 天然非战斗期）等既有裁决零改动。**批内代拍板三项已追认（2026-09-24 用户确认）**（字母不重编 / 28px 归 C/D 底行 / 进度呈现由选路覆盖层节点态承载）不落本文修订面，登记见 HUD框架 v0.8 |
|
||||
| v0.9 | 2026-09-23 | **停点前移批流程口径对齐（用户 2026-09-23 拍板冒险入口流程倒置修复——与 HUD框架 / 关卡节点地图 / battle.md / `../../../dev/architecture/adr-0006-board-node2d-rendering.md` 同批）**：P0 闭环「开始关卡」条改新流程口径——关卡节点地图加载节点图后停在入口选路停点（关卡画面，选路覆盖层常驻形态），行进自玩家首次选路开始；通读复核其余章节——「通关自动进下一关」属关卡序列层语义（进入下一关后仍出图选路，零矛盾）、接口契约四件套、收束点先清库后宣布、放弃入口（选路停点 = 天然非战斗期）等既有裁决零改动。**批内代拍板三项已追认（2026-09-24 用户确认）**（字母不重编 / 28px 归 C/D 底行 / 进度呈现由选路覆盖层节点态承载）不落本文修订面，登记见 HUD框架 v0.8 |
|
||||
@@ -14,7 +14,7 @@
|
||||
|
||||
## 系统范围
|
||||
|
||||
边界这样划：战斗屏上"发生什么、摆在哪里、是什么意思"已经由两份现行文档定稿——屏级呈现形态归 [战斗屏 UX 规格 battle.md](../../../ux/battle.md)，视觉基调与剪影色彩归 [美术圣经 art-bible](../../../art/art-bible.md)。本文只负责"这些东西怎么动"，而且是排期靠后的打磨项（见 [不做清单](../../05-不做清单.md)：战斗动画演出是 MVP 内的打磨项，一律排后）。
|
||||
边界这样划：战斗屏上"发生什么、摆在哪里、是什么意思"已经由两份现行文档定稿——屏级呈现形态归 [战斗屏 UX 规格 battle.md](../../ux/battle.md)，视觉基调与剪影色彩归 [美术圣经 art-bible](../../../art/art-bible.md)。本文只负责"这些东西怎么动"，而且是排期靠后的打磨项（见 [不做清单](../../05-不做清单.md)：战斗动画演出是 MVP 内的打磨项，一律排后）。
|
||||
|
||||
负责：
|
||||
|
||||
@@ -28,7 +28,7 @@
|
||||
|
||||
| 不负责 | 归谁 |
|
||||
|---|---|
|
||||
| 屏级呈现形态与呈现语义（四区布局、敌人呈现〔站桩形态〕、明细带、高光行） | [battle.md](../../../ux/battle.md) 与 [HUD 框架](../表现与支撑/HUD框架.md)，本文只引用 |
|
||||
| 屏级呈现形态与呈现语义（四区布局、敌人呈现〔站桩形态〕、明细带、高光行） | [battle.md](../../ux/battle.md) 与 [HUD 框架](../表现与支撑/HUD框架.md)，本文只引用 |
|
||||
| 视觉基调、剪影哲学、色彩与图标键契约 | [art-bible](../../../art/art-bible.md)，本文只引用 |
|
||||
| 结算逻辑与逐行流水本身 | [战斗结算](战斗结算.md) |
|
||||
| 敌种视觉状态的数据面（哪个敌种有几态、什么姿态） | [敌人系统](敌人系统.md) |
|
||||
@@ -49,7 +49,7 @@
|
||||
|
||||
### 不另起场景：在既有呈现上叠加动画密度
|
||||
|
||||
战斗屏是挖掘与结算两种形态共用的同一张屏：常驻双舞台（白话：战斗画面与扫雷图同屏常驻，像同一块屏上的两个舞台），结算期不切换场景，裁决与理由见 [battle.md 布局决策 1](../../../ux/battle.md)。所以战斗表现的工作不是另做一个战斗场景，而是在既有呈现上叠加动画密度与演出——这是本系统范围边界的第一条。
|
||||
战斗屏是挖掘与结算两种形态共用的同一张屏：常驻双舞台（白话：战斗画面与扫雷图同屏常驻，像同一块屏上的两个舞台），结算期不切换场景，裁决与理由见 [battle.md 布局决策 1](../../ux/battle.md)。所以战斗表现的工作不是另做一个战斗场景，而是在既有呈现上叠加动画密度与演出——这是本系统范围边界的第一条。
|
||||
|
||||
"发生什么"与"怎么动"因此分了工：敌人死亡是血条归零后灰化加碎裂退场、禁止瞬间消失，结算明细带逐行滚动，完美排雷与标中旗有高光行强调——这些呈现语义已由 battle.md 与 HUD 框架定稿，本文不复述。本文将来承接的只是其上的动画密度：受击反馈、弹道、退场动画等类别。
|
||||
|
||||
@@ -81,7 +81,7 @@
|
||||
|
||||
样张是前置美术测试的判定物；本节把"怎么算过"在测试组织前写成文，避免临场现定标准。成文做法参照 [art-bible](../../../art/art-bible.md) §1.4 格子样张测试（内容清单、按序验收项、判定与回退），判据全部落到已冻结的现行口径上——本节不定任何新的视觉参数。
|
||||
|
||||
样张内容清单（一组齐备，缺项即无效）：按 [battle.md 布局决策 1](../../../ux/battle.md) 的常驻双舞台四区布局整屏出样；角色剪影按棋盘格、结算明细带、战斗舞台三个语境同图摆放；~~敌人卡两候选形态对照（卡片式与站桩式各一版，其余内容不变）~~——**本项已由 2026-09-20 形态裁决提前收口（全站桩定稿、卡片式退役），正式样张按站桩形态单版出样即可**（owner 修订，对照义务解除；见 06 待办「敌人卡形态」销项，台账 99）；受击、退场、高光兑现三组动画关键帧条（每组至少起、中、末三帧）；敌人姿态精灵与数字、旗、小人同格叠放的遮挡对照组至少一组。
|
||||
样张内容清单（一组齐备，缺项即无效）：按 [battle.md 布局决策 1](../../ux/battle.md) 的常驻双舞台四区布局整屏出样；角色剪影按棋盘格、结算明细带、战斗舞台三个语境同图摆放；~~敌人卡两候选形态对照（卡片式与站桩式各一版，其余内容不变）~~——**本项已由 2026-09-20 形态裁决提前收口（全站桩定稿、卡片式退役），正式样张按站桩形态单版出样即可**（owner 修订，对照义务解除；见 06 待办「敌人卡形态」销项，台账 99）；受击、退场、高光兑现三组动画关键帧条（每组至少起、中、末三帧）；敌人姿态精灵与数字、旗、小人同格叠放的遮挡对照组至少一组。
|
||||
|
||||
验收项按序判定，第一项不过 = 整张否决（继承格子样张"数字可读性定风格"的次序）：
|
||||
|
||||
@@ -105,7 +105,7 @@
|
||||
| 上游 | [HUD 框架](../表现与支撑/HUD框架.md) | 四区布局、战斗画面区（四区中的 B 区）演出区结构、敌人呈现（站桩形态）与明细带呈现语义——本文在其上叠加密度 |
|
||||
| 上游 | [敌人系统](敌人系统.md) | 资产需求下限三类与敌种姿态数据面——数据已锁，本文出终稿；另登记一项随样张一并裁决的事项：敌人层绘制优先级的插入位置 |
|
||||
| 上游 | [art-bible](../../../art/art-bible.md)（现行权威） | 剪影、色彩、图标键契约、各阶段氛围——表现侧约束 |
|
||||
| 上游 | [battle.md](../../../ux/battle.md)（现行权威） | 屏级呈现形态与呈现语义 |
|
||||
| 上游 | [battle.md](../../ux/battle.md)（现行权威） | 屏级呈现形态与呈现语义 |
|
||||
| 协作 | [音频](../表现与支撑/音频.md) | 坍塌显形动画与音效方向系同批配对登记，将来对位设计（挂点未定） |
|
||||
|
||||
## P0 最小闭环
|
||||
|
||||
@@ -12,7 +12,7 @@ HUD框架把各玩法系统产生的事实变成玩家看得见、点得动、
|
||||
|
||||
## 系统范围
|
||||
|
||||
边界这样划：本系统管"怎么呈现、怎么翻译输入、弹层怎么排队"。一个动作合不合法、结果算什么意思，归排雷玩法、行动经济、战斗结算等上游裁定；画面具体长什么样、组件落在哪一像素，屏级权威是 [battle.md](../../../ux/battle.md)——本文只锁系统级契约。
|
||||
边界这样划：本系统管"怎么呈现、怎么翻译输入、弹层怎么排队"。一个动作合不合法、结果算什么意思，归排雷玩法、行动经济、战斗结算等上游裁定；画面具体长什么样、组件落在哪一像素，屏级权威是 [battle.md](../../ux/battle.md)——本文只锁系统级契约。
|
||||
|
||||
负责：
|
||||
|
||||
@@ -33,7 +33,7 @@ HUD框架把各玩法系统产生的事实变成玩家看得见、点得动、
|
||||
|---|---|
|
||||
| 任何玩法状态与玩法数值 | 各玩法系统；数值表本体归[数据配置](数据配置.md) |
|
||||
| 合法性判定与机制语义裁定 | [排雷玩法](../排雷循环/排雷玩法.md)、[行动经济](../排雷循环/行动经济.md)、[战斗结算](../战斗循环/战斗结算.md) |
|
||||
| 屏级布局与动画时长的像素级裁决 | [battle.md](../../../ux/battle.md) |
|
||||
| 屏级布局与动画时长的像素级裁决 | [battle.md](../../ux/battle.md) |
|
||||
| 美术终稿与动画密度 | [art-bible](../../../art/art-bible.md)与[战斗表现](../战斗循环/战斗表现.md) |
|
||||
| 音频、教学内容、本地化文本生产 | [音频](音频.md)、[教学引导](教学引导.md)、[设置与本地化](设置与本地化.md) |
|
||||
| 任何随机消费 | 无——呈现层零随机 |
|
||||
@@ -62,9 +62,9 @@ HUD框架站在玩家与全部玩法系统之间：挖掘期它是输入的翻
|
||||
| C 角色信息 | 左下 240×548 | 生命 / 攻击 / 储备数据框、状态效果槽、小人立绘 |
|
||||
| D 扫雷图 | 中下约 1036×548（原右下面板删除后横向加宽） | 行动点条与按钮组、棋盘本体、toast 槽 |
|
||||
|
||||
分区尺寸与组件落位的像素级裁决归 [battle.md](../../../ux/battle.md)；三区结构与双舞台常驻是结构冻结项，修订走文档修订而非调参。节点链进度不在战斗屏呈现——它由关卡画面（选路覆盖层常驻形态）的节点态承载，见[关卡节点地图](../冒险循环/关卡节点地图.md)。
|
||||
分区尺寸与组件落位的像素级裁决归 [battle.md](../../ux/battle.md)；三区结构与双舞台常驻是结构冻结项，修订走文档修订而非调参。节点链进度不在战斗屏呈现——它由关卡画面（选路覆盖层常驻形态）的节点态承载，见[关卡节点地图](../冒险循环/关卡节点地图.md)。
|
||||
|
||||
**结论**：棋盘格边长取两档定值——12×12 的板用 36px、10×10 的板用 45px（[battle.md](../../../ux/battle.md) 拍板值）；下式不推导这两档，只在装板时校验"定值塞得进扫雷图区"，违例立即报错中止。
|
||||
**结论**：棋盘格边长取两档定值——12×12 的板用 36px、10×10 的板用 45px（[battle.md](../../ux/battle.md) 拍板值）；下式不推导这两档，只在装板时校验"定值塞得进扫雷图区"，违例立即报错中止。
|
||||
|
||||
```
|
||||
可行性校验（装板期断言）：
|
||||
@@ -250,6 +250,6 @@ HUD框架站在玩家与全部玩法系统之间：挖掘期它是输入的翻
|
||||
| v0.5 | 2026-09-17 | 数值纪律收口批：调参表标注文档自持口径（无表承载常量的唯一事实源声明） |
|
||||
| v0.6 | 2026-09-20 | **敌人卡形态裁决收口批（与 battle.md / 战斗表现 / 06 清单同批，台账 99）**：全站桩形态拍板——B 区主角与敌人均为无框立绘+底座、状态小图标挂血条正下方，英雄卡/敌人卡退役；B 区行、敌人呈现义务行（载体由卡改立绘，意图占位/共享层数各立绘同值/死亡灰化退场等义务面平移）、下游战斗表现交付行、就地更新示例措辞四处同步；攻击值等规划数据仍归 C 区数据框（C 区不动）。呈现快照数据面零改动（消费字段不变，只换呈现载体） |
|
||||
| v0.7 | 2026-09-20 | **表现层三批落地 + 义务清单补行（代码同日三批：样式收敛 / 站桩改造 / 结算演出链）**：呈现义务来源清单补「关卡节点地图」行（节点链进度常显 + 选路覆盖层只读呈现——此前漏登记）；新增结算演出覆盖层（跨区弹道/光带载体，兑现演出因果可视）；减动效承诺落地（UiKit.motion 单点包装全部呈现层 tween 时长，开启时长减半、可挖域呼吸停格；切片期入口 = TunePanel 开关，正式设置层归设置批）。代码侧站桩载体（StandeeView）与卡片退役随 v0.6 裁决执行 |
|
||||
| v0.8 | 2026-09-23 | **停点前移批（冒险入口流程倒置修复，用户 2026-09-23 拍板；上位裁决 `docs/architecture/adr-0006-board-node2d-rendering.md` 与 `docs/architecture/board-node2d-migration-plan.md` §1，代码实装另批并行）**：① 战斗屏布局四区 → 三区——删 A 区关卡进度条行（LevelStripView 退役删除，节点链进度呈现移出战斗屏、只留关卡画面）；C/D 区纵向 520 → 548；装板校验变量与实算同步（棋盘区高 504、可用高度 488）；② 呈现义务来源清单「关卡节点地图」行改承载口径——节点链进度由关卡画面选路覆盖层节点态承载（暗金已过 / 金当前 / 候选下一跳通道亮金 / Boss 旗朱描边），不另设进度条组件；③ 「四区」措辞全线改「三区」（负责表、节题、结构冻结、验收、下游战斗表现交付行），双舞台常驻语义不动。**批内代拍板三项已追认（2026-09-24 用户确认）**：① B/C/D 字母保持不重编（字母是跨文档/代码注释的承载标识）；② A 区 28px 纵向空间划归 C/D 底行（520 → 548；1920 档换算仍归表现层升级批）；③ 关卡画面进度呈现由选路覆盖层节点态直接承载、不另设进度条组件 |
|
||||
| v0.8 | 2026-09-23 | **停点前移批（冒险入口流程倒置修复，用户 2026-09-23 拍板；上位裁决 `../../../dev/architecture/adr-0006-board-node2d-rendering.md` 与 `../../../dev/architecture/board-node2d-migration-plan.md` §1，代码实装另批并行）**：① 战斗屏布局四区 → 三区——删 A 区关卡进度条行（LevelStripView 退役删除，节点链进度呈现移出战斗屏、只留关卡画面）；C/D 区纵向 520 → 548；装板校验变量与实算同步（棋盘区高 504、可用高度 488）；② 呈现义务来源清单「关卡节点地图」行改承载口径——节点链进度由关卡画面选路覆盖层节点态承载（暗金已过 / 金当前 / 候选下一跳通道亮金 / Boss 旗朱描边），不另设进度条组件；③ 「四区」措辞全线改「三区」（负责表、节题、结构冻结、验收、下游战斗表现交付行），双舞台常驻语义不动。**批内代拍板三项已追认（2026-09-24 用户确认）**：① B/C/D 字母保持不重编（字母是跨文档/代码注释的承载标识）；② A 区 28px 纵向空间划归 C/D 底行（520 → 548；1920 档换算仍归表现层升级批）；③ 关卡画面进度呈现由选路覆盖层节点态直接承载、不另设进度条组件 |
|
||||
| v0.9 | 2026-09-23 | 渲染技术注记（棋盘 Node2D 迁移批 Phase A，代码实装同批；上位裁决 ADR-0006）：棋盘本体 Node2D 化——BoardView 内部由 GridContainer+逐格控件改为 Control 壳 + SubViewport + Node2D 世界，类名/信号/公共方法契约不变、探针零改造；三区布局与性能预算（同屏 draw calls < 200）不变；程序化占位视觉等价平移，素材终稿按 art-bible §8.2 格面 32×32 暂定档槽位 1:1 换入 |
|
||||
| v0.10 | 2026-09-26 | 渲染技术注记（战斗舞台 Node2D 迁移批 Phase B，代码实装同批；上位裁决 ADR-0006）：B 区战斗舞台 Node2D 化——BattleStageView 内部由 PanelContainer+Control 站桩改为 Control 壳 + SubViewportContainer + SubViewport + Node2D 世界（StageWorld/StandeeBody），类名/setter 面/公共方法契约不变、调用点零改造；状态图标行与悬停 tooltip 保留 Control 载体挂壳层（伴随件）；C6 字体注入挂点复用（set_world_font）；三区布局与性能预算（同屏 draw calls < 200）不变；占位表现等价平移（时序常量逐字对照——等价证明见 production/qa/battle-stage-node2d-等价证明-2026-09-26.md） |
|
||||
@@ -29,7 +29,7 @@
|
||||
| 不负责 | 归谁 |
|
||||
|---|---|
|
||||
| 呈现语义与可访问性基线本体（字号下限、闪烁上限、纯鼠标可玩等） | [HUD 框架](HUD框架.md) |
|
||||
| 逐行结算的呈现规则 | [battle.md](../../../ux/battle.md) 与 [HUD 框架](HUD框架.md)，本文只引用 |
|
||||
| 逐行结算的呈现规则 | [battle.md](../../ux/battle.md) 与 [HUD 框架](HUD框架.md)，本文只引用 |
|
||||
| 减动效开启后动画怎么演 | [战斗表现](../战斗循环/战斗表现.md)——本文提供开关，动画侧兑现归对方 |
|
||||
| 音量调节对声音怎么生效 | [音频](音频.md)——生效侧归对方，口径已对齐（2026-09-18 音频成文） |
|
||||
| 文案内容本体（教学条目、界面用语等写了什么） | 各系统文档——本文只做翻译生产，不改含义 |
|
||||
@@ -61,7 +61,7 @@
|
||||
|
||||
| 输入 | 登记处 | 将来要做的 |
|
||||
|---|---|---|
|
||||
| 减动效开关 | [HUD 框架](HUD框架.md)的可访问性基线与 [battle.md](../../../ux/battle.md)的呈现承诺；[战斗表现](../战斗循环/战斗表现.md)已登记承接其动画侧 | 提供开关：开启后全部动画有时长减半或直达终态的通路。呈现侧的约束以 battle.md 与 HUD 框架为权威，本文不复述 |
|
||||
| 减动效开关 | [HUD 框架](HUD框架.md)的可访问性基线与 [battle.md](../../ux/battle.md)的呈现承诺；[战斗表现](../战斗循环/战斗表现.md)已登记承接其动画侧 | 提供开关：开启后全部动画有时长减半或直达终态的通路。呈现侧的约束以 battle.md 与 HUD 框架为权威，本文不复述 |
|
||||
| 音量控制入口 | 归档对本系统的常规分工登记；[音频](音频.md)已登记同款分工 | 在设置里提供音量入口；生效侧归音频（口径已对齐） |
|
||||
| 键位映射表 | [HUD 框架](HUD框架.md)定稿登记的交付物输入（全键族） | 如何转化成设置项（比如是否允许改键）待设计 |
|
||||
| 结算风味词 | 归档概念层增补批随巢穴隐喻换轴登记（"封印 / 镇 / 反制"一类类型风味词），只登记了存在、各归各的时机 | 内容与形态未定，本文只登记这条输入在 |
|
||||
|
||||
@@ -48,7 +48,7 @@
|
||||
战斗屏是**上下文相关屏**（仅由战斗节点进入），非顶层常驻。关卡内节点进度常驻关卡画面（选路覆盖层的常驻形态，节点态即进度呈现：已过暗金、当前金、候选通道亮金、Boss 紫赤描边），战斗屏零进度承载——战斗结束返回关卡画面，玩家始终知道自己身处图中第几环。
|
||||
|
||||
- 上游屏：关卡节点图（分支节点图形态，切片第一关为单链特例）
|
||||
- 下游屏：节点奖励/恢复覆盖层（NodeOverlay，已有 demo 组件——建议后续单独出 spec `design/ux/node-reward.md`）
|
||||
- 下游屏：节点奖励/恢复覆盖层（NodeOverlay，已有 demo 组件——建议后续单独出 spec `design/gdd/ux/node-reward.md`）
|
||||
- 平行屏：结算明细回看 overlay（本屏内域屏）、图例面板 overlay（本屏内域屏）
|
||||
|
||||
---
|
||||
@@ -142,7 +142,7 @@
|
||||
| B | 主角站桩立绘 | 站桩（无框立绘+底座） | HP 条悬浮头顶、状态效果小图标一排挂血条正下方（形状+色相双通道、层数角标）——**HP 与状态效果的唯一展示面（2026-09-26 信息归属拍板，原 C 区状态槽职责〔悬停 tooltip 来源+语义+剩余结算次数〕并入本组件）**；攻击值等规划数据仍归 C 区数据框（2026-09-20 全站桩拍板，英雄卡退役） | 悬停状态小图标看 tooltip | HUDView 拆分改造 |
|
||||
| B | 敌人站桩立绘 ×1–3 | 站桩（无框立绘+底座） | 血条+顺位徽标悬浮头顶、状态小图标挂血条正下方（敌方 side-wide 增益各立绘同值呈现——蓄力/硬化/削弱/暴走/警觉；伏击层数通道随 2026-09-20 八型批退役——数据源 = 战斗结算流水经增益状态投影，敌人系统×4④；2026-09-16 敌人技能池批改型：行为环点拆除〔proposal §2.4〕，意图占位 = 本拍摇定结果的动画占位——普通攻击零表示 / 特殊技类型级提示，敌方增益〔蓄力/硬化〕入状态图标行）；死亡灰化加碎裂退场直接演在立绘上（2026-09-20 全站桩拍板，敌人卡退役）；底座下名字行 = 纯名字 + 护甲类型图标（形状+色相双通道），AC 数值不展示——2026-09-26 终裁（用户口径：HP 信息已足够，攻防数值不直接写上；护甲类型图标保留克制对策可读性——类型可读、数值隐藏） | 只读 | 新建 |
|
||||
| B | 轮次·阶段指示 | 标签 | "第 N 轮 · 挖掘中/结算中"（终局定格「战斗结束」；Boss 变体附 Boss 名） | 只读 | 新建 |
|
||||
| B | 结算明细带 | 滚动列表 | 结算期逐行流水（[战斗结算](../gdd/systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋) 9 类行协议）；挖掘期收起为上轮摘要 1 行 | 点击展开明细回看 overlay | battle_log_view.gd 改造 |
|
||||
| B | 结算明细带 | 滚动列表 | 结算期逐行流水（[战斗结算](../systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋) 9 类行协议）；挖掘期收起为上轮摘要 1 行 | 点击展开明细回看 overlay | battle_log_view.gd 改造 |
|
||||
| B | 结算明细回看 | 模态 overlay | 完整流水逐行（现行 9 类行协议；未生效类行聚合计数） | 关闭 | battle_log_view.gd 改造 |
|
||||
| C | 攻击数据框 | 直角细线数据框 | 攻击值 + 修正来源角标 + 护甲 AC（AC 二轮拍板 2026-09-26 补入——我方 AC 唯一展示面；原「HP/攻击/RAP 显示」——HP 与 RAP 随信息归属拍板迁出本组件） | 只读 | HUDView 拆分 |
|
||||
| C | 魔法道具槽（预留） | 图标槽（数量待魔法道具定稿） | 随身战斗用道具的唯一展示面；空槽虚线占位，不预设交互（挖掘期指向交互归 E 区既有裁决） | 悬停 tooltip（道具语义） | 新建（随魔法道具批） |
|
||||
@@ -273,7 +273,7 @@
|
||||
| 弃图刷新（挖掘期，非轮出口） | `ux_refresh_attempt` | {result: accepted/rejected_rap/rejected_cap, round_refresh_index: 1..2}——刷新使用（难度曲线与Boss OQ6）与行动经济 OQ3 预警阈值观测；每轮 0–2 次（布局决策 4 cap=2） |
|
||||
| 拒绝/voided | `ux_reject` | {source: board/resource/phase, sub_reason} |
|
||||
| 提示触发/关闭 | `ux_hint_shown` | {hint_id: chord/no_adjacent} |
|
||||
| 呈现订阅（不改核心） | 排雷玩法三事件 / [战斗结算](../gdd/systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋)步骤流（9 类行协议，含终局判定行） / battle_over / level_clear | 载荷 schema 成文义务见 §Data Requirements——旧版台账 entry 17①（HUD框架硬性要求） |
|
||||
| 呈现订阅（不改核心） | 排雷玩法三事件 / [战斗结算](../systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋)步骤流（9 类行协议，含终局判定行） / battle_over / level_clear | 载荷 schema 成文义务见 §Data Requirements——旧版台账 entry 17①（HUD框架硬性要求） |
|
||||
|
||||
**持久状态写入**全部经组合根唯一路径（settle_batch / request_refresh / runner 推进）——UI 层禁直调核心写（架构七原则"依赖单向组合根"）。
|
||||
|
||||
@@ -305,7 +305,7 @@
|
||||
| BFS 移动路径 | 排雷玩法 `compute_move_path` | Read | 布局决策 3 合法性指示消费 |
|
||||
| 拒绝原因 | 排雷玩法 `sub_reason` 封闭枚举 + 行动经济 资源面 | Read | 三源（board/resource/phase）映射文案——呈现层契约成文；资源面原因无上游载荷（行动经济 仅 bool + debug 诊断），客户端按动作上下文推断 |
|
||||
| AP / RAP / 本轮刷新计数 | 行动经济 | Read | 常显；刷新入口可用性 = RAP 读数客户端预判（RAP≥8）+ `request_refresh` 返回值（行动经济 无 `can_request_refresh` API——仅 bool 返回 + 只读观测量；行动经济 EC13 拒绝合法可见） |
|
||||
| 结算流水行（9 类封闭协议） | [战斗结算](../gdd/systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋) 流水协议 | Read | 逐行来源标注（P2）；未生效类行（奖励未生效）聚合计数呈现 |
|
||||
| 结算流水行（9 类封闭协议） | [战斗结算](../systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋) 流水协议 | Read | 逐行来源标注（P2）；未生效类行（奖励未生效）聚合计数呈现 |
|
||||
| 判定 verdict | 战斗结算 判定段 | Read | 终局画面数据锚 |
|
||||
| 敌单位 hp/顺位/摇定动作（pending_skill/type/name）/敌方增益/enemy_id/存活 | 敌人系统 只读面（经战斗结算呈现快照） | Read | 意图线索映射全局恒定（敌人系统×4②，技能池批三档口径）；**despawn 前捕获**（旧版台账 entry 17③——缺陷②教训） |
|
||||
| 状态效果投影（含空态/极性/溢出） | 增益状态 投影口径 | Read | 极性映射数据源 = 战斗结算 SettlementTable 效果语义，非 magnitude 符号（增益状态×③） |
|
||||
@@ -391,12 +391,12 @@
|
||||
|
||||
1. **Player journey map 未建**——建议实现前补建（`design/player-journey.md`），校准挖掘→结算→终局情绪曲线与 art-bible §2 能量档的匹配
|
||||
2. **`design/accessibility-requirements.md` 未建**（gate-check Pre-Production 缺口）——本 spec 内建 WCAG AA 基线承诺，正式分层（文本缩放/色盲模式/按键重映射）待该文档定稿
|
||||
3. **`design/ux/interaction-patterns.md` 未建**——本 spec 新引入待入库 pattern：toast 双源拒绝、逐行兑现明细带、悬停预承诺光标、点阵资源显示（/ux-design patterns 批次入库）
|
||||
3. **`design/gdd/ux/interaction-patterns.md` 未建**——本 spec 新引入待入库 pattern：toast 双源拒绝、逐行兑现明细带、悬停预承诺光标、点阵资源显示（/ux-design patterns 批次入库）
|
||||
4. **战斗表现美术测试**（game-concept 已登记，战斗表现批次前强制）：本 spec 的常驻双舞台分屏（布局决策 1）是测试的布局输入——**敌人卡形态已裁决（2026-09-20 用户看对照样张拍板）：全站桩式（无框立绘+底座），主角同样站桩、状态小图标挂血条下，卡片式整体退役**；本 spec 已随裁决改写（原"按卡片式起草"条款作废），站桩式不改变分区结构。对照样张存档 `production/mockups/enemy-card-vs-standee-mockup.html`
|
||||
5. **移动动画形态**（布局决策 3）：≤150ms 短滑为推荐值，playtest 观测「移动太瞬/太拖」反馈后调
|
||||
6. **明细带挖掘期是否常驻上轮摘要**：常驻（现方案）vs 结算后即收起——playtest 观测回看频率
|
||||
7. **Gamepad 导航序**：Partial 支持（非 MVP 门禁）——焦点环顺序待 gamepad 批次定
|
||||
8. **NodeOverlay / 关卡结算屏**：相邻域屏，建议后续 spec `design/ux/node-reward.md` + `design/ux/level-clear.md`（本 spec 只锁出口锚点）
|
||||
8. **NodeOverlay / 关卡结算屏**：相邻域屏，建议后续 spec `design/gdd/ux/node-reward.md` + `design/ux/level-clear.md`（本 spec 只锁出口锚点）
|
||||
9. **TunePanel 退役计划**：正式侧归元进度（天赋树），切片调试入口在《HUD框架》标注退役时点
|
||||
10. **提示文案定稿**：chord 提示/空态文案归实现期文案 pass，本 spec 只锁必含要点与形态约束
|
||||
11. **弃图刷新上游修订（已落稿 2026-09-12，布局决策 4）**：行动经济（Active 相位受理 + 每轮上限 2 次 + Waiting 代理退役 + 旧旗作废裁决 + 时间税失效预警）、排雷玩法（Active·仅刷新路径装板受理）、战斗结算（stopped/ap_exhausted 恒 same_board + `refresh_board` 挖掘期刷新编排；AC-29 改写/AC-30 恒 same_board）、registry `rap_rules` 同步、旧版 systems-index 修订块登记。遗留观察项：当场刷新的节奏健康由行动经济 OQ3 弃图率/刷新率预警承载，playtest 复核
|
||||
@@ -435,7 +435,7 @@
|
||||
| 2026-09-15 | 雾格残留清理：格态收窄为已开 / 未开两态（删除雾图变体状态行、四格态 AC 与已开雾格 tint / 雾区全开信号两条 AC）；图例面板与 toast 槽去掉雾条目与雾首遇提示；BoardView 纹带、绘制优先级与色弱冗余改按通用变异纹带表述；`ux_hint_shown` 的 hint_id 枚举去掉 fog_first；输入义务与 §13 义务对照表去掉 地形变异×3 一项；目标感知示例与提示文案 OQ 措辞同步。本 spec 不装载被移除机制的呈现义务 |
|
||||
| 2026-09-16 | 格面资源批 UI 欠账收口（随 2026-09-15 可选类道具删除的代码收口同步文档）：① 布局四区化——删 E 区道具面板行、布局决策 2（道具窗口形态=右栏原位激活）整段删除（编号留空防交叉引用失锚）、ASCII 线框图重绘为 A/B/C/D 四区（D 区横向加宽 ~1036px）、A 区节点链示例改文字签槽实际渲染（战/赏/疗/王）；② States 删道具窗口态与零库存空态（「道包空空」）；③ 结算口径五段化（授予→增益/减益→战斗→衰减→判定）与明细行 10 类封闭协议（删 15 类行、四类行旧口径；「奖励未生效」行保留）；④ 交互/动效/事件表删道具窗口行、跳过按钮、`ux_window_choice`、`submit_window_selection`；⑤ 数据源登记删 `query_inventory` 与窗口载荷，奖励身份按现行 `query_identity` 只读回调口径校正；⑥ 验收清单删窗口断言、五区改四区、未生效类行改现行两型（溢出未生效/奖励未生效）；⑦ 关卡末清库反馈义务改载魔法道具背包（随魔法道具 P0 落地，本批不设计具体呈现）；⑧ OQ7（道具窗口原位激活）删除、OQ 重编号，「囤刀待机」等旧可选类措辞清理。本 spec 不装载被删除机制的呈现义务 |
|
||||
| 2026-09-20 | **敌人卡形态裁决收口（2026-09-20 用户看对照样张拍板，06 待办「敌人卡形态」解决移除——台账 99）**：全站桩形态定稿——① B 区主角与敌人均为无框立绘+底座（站桩式），**英雄卡/敌人卡组件整体退役，卡片式不再作为候选**；主角血条悬浮头顶、状态效果小图标一排挂血条正下方，敌人血条+顺位徽标悬浮头顶、状态小图标同款挂血条下；攻击值等规划数据仍归 C 区数据框（C 区不动）；② 布局表 B 区行、Component Inventory 英雄卡/敌人卡两行随裁决改写（敌方 side 池共享层数各立绘同值、意图动画占位等既有语义平移到站桩载体，不随形态改变）；③ ASCII 线框图 B 区重绘（旧"意图:爪击/环点"示意早已随行为环退役，本次一并清掉）；④ OQ4 改写为裁决已收口注记，对照样张存档 `production/mockups/`；呈现义务细节重述（受击/退场演出挂点等）随表现层升级批执行 |
|
||||
| 2026-09-23 | **停点前移批（冒险入口流程倒置修复，用户 2026-09-23 拍板；上位裁决 `docs/architecture/adr-0006-board-node2d-rendering.md` 与 `docs/architecture/board-node2d-migration-plan.md` §1，代码实装另批并行）**：① 布局四区 → 三区——删布局表 A 区关卡进度条行与 Component Inventory LevelStripView 行（LevelStripView 退役删除，节点链进度只留关卡画面，战斗屏零进度承载）；C/D 底行 520 → 548；ASCII 线框图重绘为 B/C/D 三区；② 新流程口径落文——关卡画面（选路覆盖层常驻形态）为关卡内常驻枢纽：Navigation Position 图、到达语境、Entry 表、信息层级第 5 层、Data Requirements 节点图行改「关卡开始即出图选路、战后返回关卡画面再选路」；③ AC 四区措辞改三区。**批内代拍板三项已追认（2026-09-24 用户确认）**：① B/C/D 字母保持不重编；② 28px 纵向空间划归 C/D 底行（520 → 548）；③ 关卡画面进度呈现由选路覆盖层节点态承载（暗金已过 / 金当前 / 亮金候选通道 / 旗朱 Boss）、不另设进度条组件 |
|
||||
| 2026-09-23 | **停点前移批（冒险入口流程倒置修复，用户 2026-09-23 拍板；上位裁决 `../../dev/architecture/adr-0006-board-node2d-rendering.md` 与 `../../dev/architecture/board-node2d-migration-plan.md` §1，代码实装另批并行）**：① 布局四区 → 三区——删布局表 A 区关卡进度条行与 Component Inventory LevelStripView 行（LevelStripView 退役删除，节点链进度只留关卡画面，战斗屏零进度承载）；C/D 底行 520 → 548；ASCII 线框图重绘为 B/C/D 三区；② 新流程口径落文——关卡画面（选路覆盖层常驻形态）为关卡内常驻枢纽：Navigation Position 图、到达语境、Entry 表、信息层级第 5 层、Data Requirements 节点图行改「关卡开始即出图选路、战后返回关卡画面再选路」；③ AC 四区措辞改三区。**批内代拍板三项已追认（2026-09-24 用户确认）**：① B/C/D 字母保持不重编；② 28px 纵向空间划归 C/D 底行（520 → 548）；③ 关卡画面进度呈现由选路覆盖层节点态承载（暗金已过 / 金当前 / 亮金候选通道 / 旗朱 Boss）、不另设进度条组件 |
|
||||
| 2026-09-23 | 实现注记（棋盘 Node2D 迁移批 Phase A，代码实装同批；上位裁决 ADR-0006）：棋盘渲染 Node2D 化（BoardView = Control 壳 + SubViewportContainer + SubViewport + Node2D 世界，信号/click_cell/_cells 契约保持，新增 push_input 端到端输入探针）；格尺寸公式锚点不变（set_cell_area = floor((min(宽,高) − 预留 − (N−1)×格间距) / N) 单点可调），布局与交互语义零改动 |
|
||||
| 2026-09-26 | 实现注记（战斗舞台 Node2D 迁移批 Phase B，代码实装同批；上位裁决 ADR-0006）：B 区战斗画面 Node2D 化（BattleStageView = Control 壳 + SubViewportContainer + SubViewport + Node2D 世界，站桩本体 StandeeBody 世界精灵；set_enemies/clear_enemies/on_step_row_fx/gray_all_enemies 等 setter 面签名保持，弹道落点锚点=壳层口径 world_to_shell 单点）；状态图标行与悬停 tooltip 保留 Control 载体挂壳层；三区布局尺寸零改动（B 区外框 252px 逐位） |
|
||||
| 2026-09-26 | **封印紫批**（用户拍板）：插旗呈现色 旗朱 #C63D22 → 封印紫 #7C3AA8（色相 ≈267°，避开禁入带）——旗字形/已承诺封印框/旗化暴击弹道随批换色；拒绝边框闪语义归危险红；Boss 节点描边归紫赤本色。修订记录历史行旗朱字样系当时口径留痕不改 |
|
||||
@@ -4,7 +4,7 @@
|
||||
> **Author**: user + ux-designer
|
||||
> **Last Updated**: 2026-09-20（退役术语扫描批：pattern 2 退役留档、pattern 8 消费面注记、未生效类行枚举收敛，见文末修订记录）
|
||||
> **Template**: Interaction Pattern Library
|
||||
> **来源**: `design/ux/battle.md`（2026-09-12 /ux-review APPROVED）已拍板内容的成文固化——本库不引入新设计决策
|
||||
> **来源**: `design/gdd/ux/battle.md`（2026-09-12 /ux-review APPROVED）已拍板内容的成文固化——本库不引入新设计决策
|
||||
|
||||
---
|
||||
|
||||
@@ -84,7 +84,7 @@ MVP 未使用标准控件（不入库）：toggle / dropdown / input field / tab
|
||||
**Description**: 轮末结算逐行流水实时呈现 + 可回看——「扫雷之因逐行兑现为战果」（P2 归因）的承载面。挖掘期收起为 1 行上轮摘要；结算期展开 84px 实时流；点击开完整回看 overlay。
|
||||
|
||||
**Specification**:
|
||||
- 数据源：[战斗结算](../gdd/systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋)步骤流（9 类行封闭协议（现行）；公共字段 `type/source_class/origin_cell/round_index/display_name/value/highlight?`）；**无来源行 = 断言失败**
|
||||
- 数据源：[战斗结算](../systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋)步骤流（9 类行封闭协议（现行）；公共字段 `type/source_class/origin_cell/round_index/display_name/value/highlight?`）；**无来源行 = 断言失败**
|
||||
- 行模板：「{行为} {值} → {目标}（来源）」——来源标注（第 N 轮 · 安全格式）；行文案最长 token = 道具名（4 汉字），模板预留 40% 膨胀宽度
|
||||
- 聚合纪律：未生效类行（奖励未生效——现行 9 类行协议唯一未生效型，2026-09-20 收敛）按聚合计数呈现（防逐行惩罚轰炸）；衰减行聚合计数；效果行 value=单次贡献值、禁与 pool_value（池合成值）相加呈现；零值行可见不吞（免伤轮归因不断点）
|
||||
- 高亮：highlight 字段 {flag_hit, clear_reward_h2, perfect_broken} → 金框强调；完美排雷 = 独立高光行 + 全屏喝彩级反馈
|
||||
@@ -92,7 +92,7 @@ MVP 未使用标准控件（不入库）：toggle / dropdown / input field / tab
|
||||
- 击杀标记呈现（H3 数据源 = 战斗结算流水击杀结果字段）
|
||||
|
||||
**When to Use**: 任何「因果可归因」的逐行流水呈现
|
||||
**When NOT to Use**: 自造行类型/字段（9 类封闭枚举（现行）——增删 = 接口漂移，须走[《战斗结算》](../gdd/systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋)修订）
|
||||
**When NOT to Use**: 自造行类型/字段（9 类封闭枚举（现行）——增删 = 接口漂移，须走[《战斗结算》](../systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋)修订）
|
||||
|
||||
**Reference**: battle.md §Component Inventory 结算明细带、§AC 信息与归因；归档《战斗结算》（b1-settlement.md）Core Rule 14 / Visual Req
|
||||
|
||||
@@ -0,0 +1,150 @@
|
||||
# 验收读数重测批——判读报告（初稿，真人位留空）
|
||||
|
||||
- **日期**：2026-09-19
|
||||
- **口径依据**：`docs/acceptance-ap6-ac.md` v1.0（定稿判读规则全文照搬执行）
|
||||
- **被测构建**：master @ d236d9f（技能池新效应词汇批后；乘区接线+削弱续时+甲效换装+充能退役+rider 五次数值行为变更叠加后的首次全量重测）
|
||||
- **执行环境**：独立 worktree `D:\code\g-plan2-acceptance-rerun`（分支 `acceptance-rerun-20260919`）——绕开主工作区并行会话未提交改动
|
||||
- **数据源状态**：① 模拟批 ✅ 完成（两关 × N=30 × 种子 4200+30 × 策略 both，共 1200 局）② 日志批 ✅ 完成 ③ **真人批 ⬜ 缺位**（3–5 局基线档待用户补跑，k 系数待并入）——按口径「三数据源全部跑完再判读」，本报告全部结论为**初稿**，终稿待真人批合入
|
||||
- **前置验证**：worktree 冒烟 317 项 0 失败（run_smoke 三闸全过）✅
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 核心发现：窄种子窗 × 复用放大——掷点统计失真（本批最重要产出；2026-09-19 深勘后根因已修正定稿）
|
||||
|
||||
**一句话**：d20 掷点流的派生公式本身是均匀的，但「30 个连续种子 × 每局只消费头部 ~17~40 个 scope × 每种子被复用 ~40 局」的组合，把头部窗口自身的面值彩票放大 ~40 倍灌进全部聚合统计——验收的档位分布/EV gate 读数因此失真。**修正记录**：本报告首稿曾定性为"派生种子首输出缺陷、真实玩家体验受损"，经 2000 种子全局对照与跨步种子对照推翻——公式无恙、玩家单局影响≈机会涨落水平，真实受害者是测量有效性。
|
||||
|
||||
### 证据链（可复现，探针脚本形态见附录）
|
||||
|
||||
1. **逐位比对**：种子 4227 首局前 23 个日志掷点与 `rng.open_stream("armor_roll")` 逐 scope 首输出序列**完全一致**——日志掷点 = 派生种子首输出，无其他变换。
|
||||
2. **逐种子失真**：真实日志按种子聚合 18 点数 0→131（种子 4211 = 0、4227 = 120）；二项分布下 n≈700 的 σ≈6，此散布远超抽样涨落——复用放大实锤（每局重吃同一种子的头部窗口，窗口彩票 ×40）。
|
||||
3. **全局均匀对照**：2000 个跨步种子 × 头部 31 scope 等权聚合，χ²=22.8（19df 95% 临界 30.1）——**派生公式全局无偏**；splitmix 混淆版同样干净（χ²=23.5），混淆不解决本问题（问题不在公式）。
|
||||
4. **窗口彩票对照**：MC 实际窗口（连续 30 种子 × 头部 41 scope）18 点 +35% 集中在高权重头部；同规模跨步种子窗口 χ²=26 正常——特定窗口运气 × 复用 = 失真。
|
||||
5. **真实消费模式复现**：按「30 种子 × 40 局 × 每局 8~31 掷」聚合，复现 18 点 +57%（1876/23822）的日志签名。
|
||||
6. **排除项**：纯随机种子首输出均匀（4 万次最大偏差 2.7σ）——引擎 PCG 本体无恙。
|
||||
|
||||
### 影响面评估（修正后）
|
||||
|
||||
- **玩家单局体验：≈无**。一局只有 ~17~40 次掷点，即使种子头部窗口有偏，也与普通骰子运气无法区分（17 次均匀掷点本身就有 ±10pp 级涨落）。**首稿"玩家体验随种子漂移"的说法降级为理论可能性**（只有在单局掷点数大幅增长的未来内容里才可能被感知）。
|
||||
- **测量有效性：实害**。验收掷点面（档位分布/EV/nat20）与任何基于这 30 个种子的聚合统计，都被窗口彩票 ×40 放大污染——本批阶段一两个 gate FAIL 由此归因，不能算到机制或数值头上。**同构隐患**：五条流（board_gen/reward_roll/encounter/armor_roll/behavior_roll）共享此消费模式，窄种子窗 + 短消费窗 + 复用的分析面都会中招。
|
||||
- **潜在陷阱（非现行故障）**：若未来种子外露（种子分享玩法）或单局掷点数大增，窄窗彩票从测量问题升级为体验问题。
|
||||
|
||||
### 修复方向（三案，均已评估；探针级验证见附录）
|
||||
|
||||
- **方案 A（推荐，零游戏代码）**：掷点统计面改用宽种子带——如 4200 起步长 7919 取 ≥100 个种子（保留 4200–4229 子段则历史坐标仍可比），窗口彩票按 1/√种子数摊平；实现 = MC 工具加一档「掷点扫描批」参数。承伤/通关率等压力读数同理受益。
|
||||
- **方案 B（可选加固，一处小改）**：`rng_service.gd` 派生前对 master 做一次非线性混淆（如 splitmix64 finalizer）——任何窄种子窗表现如随机抽样，根治"连续小整数种子"陷阱。逐 scope 回放语义不变；代价 = 黄金向量重登记 + 冒烟回归。全局均匀性已被证明，此案是防御性投资，不紧急。
|
||||
- **方案 C（用户提案：真随机 + 逐次记录）**：技术上可行但代价不成比例——存档序列化快照契约（master_seed）、反事实重算工具（analyze_playtest 依赖确定性重模拟）、逐次可回放语义全部重做，记录文件随局数无限增长；而它解决的问题 A/B 已以小得多的代价覆盖。不推荐，除非未来设计转向"非确定性掷点"价值观。
|
||||
- **共性注记**：无论何案，单局 17~40 掷的"运气窗"本身（某局恰好 18 点多）是骰子本性，修复对象是"系统性放大"而非"运气存在"。
|
||||
|
||||
### B 案落地结果（2026-09-19 用户拍板 B 案，同日实施收口）
|
||||
|
||||
- **实现**：`rng_service.gd` R2→R3——derive = mix64(SALT XOR wrap64(master + scope×GOLDEN))，splitmix64 finalizer 变体（乘数 0xBF58476D1CE4E5B9 / 0x94D049BB133111EB、加数同 GOLDEN_RATIO）；**全程 63 位掩码**（有符号 int64 算术移位在正值域与逻辑移位逐位一致——与 Python 参考实现对齐的关键）。逐 scope 复放语义/计数器契约/存档快照契约不变。
|
||||
- **黄金向量**：8 常量全量重登记（冒烟 R3 向量断言 + registry stream_seed_derivation 条目 + Formulas-R3 指向），Python 参考实现与 GDScript 实现逐位交叉验证一致；R2 旧向量作废。
|
||||
- **冒烟**：316 项 0 失败三闸全过（317→316 = 一条"探针首掷恰好暴击才触发"的条件断言在新序列下不触发，良性）。
|
||||
- **R3 版模拟批重跑（1200 局）验证**：
|
||||
- 18 点异常**消失**（1740→846，期望 1010，残差回落到 30 种子窗口彩票的理论噪声带 ≈2σ_eff）；
|
||||
- nat20 暴击率 5.92%（带内 PASS）；主角→敌全额率 100% PASS；
|
||||
- **敌→主角 EV 减免 25.6% 仍高于理论 21.25%——但现在是干净读数**：档位分布 ×0.25 档 16.6%（理论 10%）、全额 50.0%（理论 55%），指向主角有效 AC 被护甲强化（ac_up）供给抬高 ~1.2 点。这是 B 案清除 RNG 噪声后**首次可见的真实设计信号**，归调参批处置（护甲强化供给是合法杠杆位）；
|
||||
- 压力面结论对 RNG 改版稳健：L1 完美档基线格 87% 通关/承伤均 17.0/p90 24，与改版前同方向同量级——阶段二"压力不足"判定不变，仍顺延调参批；
|
||||
- 同种子历史坐标随 R3 改版整体作废（预期内，已登记 registry 批注）。
|
||||
- **遗留提示**：B 案消除的是"窄窗彩票被系统性放大"，30 种子的窗口彩票噪声本身仍在（档位分布 gate 若按 ±2σ 独立样本口径判读仍会误报）——**建议阶段一正式重跑时叠加 A 案**（掷点统计面用宽种子带，如 4200+i×7919 × ≥100 种子），两案正交不冲突。
|
||||
|
||||
### A 案叠加落地结果（2026-09-19 用户拍板 A/B 叠加，同日实施收口）
|
||||
|
||||
- **实现**：`level_monte_carlo.gd` 增第 5 参种子模式 `shared|unique`（缺省 shared = 旧行为零变更，保留同种子 A/B 对照用法；unique = 逐局独立种子 seed0+全局序号）。unique 模式下每个 (种子， scope) 恰消费一次 → 聚合掷点统计回归标准二项分布，±2σ gate 口径重新有效——这是 A 案的本质：消除复用权重，而非换种子段。
|
||||
- **A+B 版模拟批重跑（两关 1200 局，逐局独立种子）验证**：
|
||||
- d20 直方图**全面干净**：20 面值全部落在期望 1011 的 ±2.3σ 内（对照：R2 版 18 点 +57%≈20σ）；
|
||||
- nat20 暴击率 5.12%（带内 PASS）；主角→敌 / 敌→主角暴击率 5.13%/5.09% 双向对齐理论；
|
||||
- **敌→主角档位分布失真仍在但已是干净设计信号**：全额 50.9%（理论 55%，-7.6σ）、×0.25 档 15.0%（理论 10%，+15σ）——指向主角有效 AC 被护甲强化（ac_up +1×2 层）供给抬高 ~1.5 点，EV 减免 24.59% 同源。此偏差**真实且显著**，归调参批裁决（重新校准 gate 把 AC 增益期计入理论模型，或调护甲供给）；
|
||||
- 压力面第三次复测稳如磐石：L1 完美档基线格 87% 通关/承伤 16.8/p90 24——R2/R3/A+B 三批同向同量级，"压力不足"判定与 RNG 无关焊死；L2 完美档 87%/13.9·21；
|
||||
- 弃图率读数稳定（完美档 0.02-0.10 次/局，normal 0）。
|
||||
- **A+B 叠加后的验收口径状态**：掷点面 gate 判读从此有效；阶段一正式重跑数据 = 本批（T220949/T221847 两文件）；同种子历史坐标已三重作废（R3 改版 + unique 模式），坐标可比性锚改为「本批 A+B 数据」。
|
||||
|
||||
---
|
||||
|
||||
## 阶段一：机制验收（日志批，gate 判读——全部受发现①污染，仅记录现状）
|
||||
|
||||
数据：两份 MC 日志共 318,626 行、1200 局、20,945 次掷点。
|
||||
|
||||
| 指标 | 读数 | 期望带 | 判读 | 注记 |
|
||||
|---|---|---|---|---|
|
||||
| 零承伤轮（窄口径） | 0 / 8076 攻击落地轮 | 0 | ✅ PASS | 伤害下限 1 生效 |
|
||||
| 零掉血轮（宽口径） | 6706 / 13364 敌战轮（50.2%） | observe | 记录 | 与真人旧读数对照待真人批 |
|
||||
| nat20 暴击率 | 4.53% | 5%±2pp | ✅ PASS（带污染注记） | 种子头部偏置使逐种子暴击率漂移大 |
|
||||
| 档位分布（敌→主角） | 全额 50.8%/×0.75 15.0%/×0.5 21.6%/×0.25 12.6% | 55/15/20/10 各±2σ | ❌ FAIL | 归因=RNG 偏置为主 + 护甲强化增益抬 AC 混入（全额缺口方向与增益一致，但幅度超增益可解释范围） |
|
||||
| 玩家侧全额率 | 主角→敌 EV 减免 0.00% | 100% 全额 | ✅ PASS | 敌 AC 关内 0 生效 |
|
||||
| EV 减免（敌→主角） | 23.98% | 21.25%±2pp | ❌ FAIL | 同上归因 |
|
||||
| Boss 血量锚 | 表值 hp=58（蛛化卓尔精灵） | r_boss=150÷153.5≈0.98 | ⚠️ 锚过期 | 口径写于压缩批与卓尔加血前（150→÷3→58）；锚值重校准归调参批，本批记录现状 |
|
||||
| 增益战斗期复原 | 三类可复原（attack_up/weaken/减伤族） | observe | ✅ 记录 | 复原面工作正常 |
|
||||
| 快照 buffs 非空 | **8790/14402** | 恒空（盲区口径=0） | ⚠️ 盲区口径已破 | rider/状态批后快照开始携带 buffs（疑 duration-2 状态使衰减段后仍有存留）——**好消息**（盲区闭合），口径文档需改写该节 |
|
||||
| 数据质量·解析失败 | 0 | 0 | ✅ PASS | |
|
||||
| 数据质量·未配对 battle_end | **1200（系统性 1/局）** | 0 | ⚠️ 行序伪影 | 每局恰 1 条 battle_end 落到 run 行切分点之后（level_end 先于 battle_end 落盘）；不影响核心统计（分析器不依赖 battle_end），行序归因待核 |
|
||||
|
||||
## 阶段二：压力验收（模拟批基线格，初稿判读——顺延至掷点修复后终判）
|
||||
|
||||
### 第一关（生死带主判据格：MC perfect 基线格 atk+0%/hp+0%，n=30）
|
||||
|
||||
| 指标 | 读数 | gate | 判读 |
|
||||
|---|---|---|---|
|
||||
| 整关承伤分布 | p10=13.0 / p50=18 / p90=25.0 / max=28 | p10∈[35,45] 且 p90∈[55,65] | ❌ FAIL（远低于带下沿——压力不足方向） |
|
||||
| 通关率 | 87% | [35%, 65%] | ❌ FAIL（越上界） |
|
||||
| 通关余量 | 胜局剩余 HP 均 7.4 | p90≤13 且 p10≥3（收敛后 gate） | observe（未收敛） |
|
||||
| 平均轮数 | 16.4 | observe | 记录 |
|
||||
| 盲挖档（normal 基线格）通关率 | 73% | observe（生死带下 0% 为预期态） | 记录——73% 与生死带预期相悖，同证压力不足 |
|
||||
|
||||
### 第二关（对照面，无独立 gate）
|
||||
|
||||
| 指标 | 读数 |
|
||||
|---|---|
|
||||
| 完美档基线格通关率 / 承伤 p50/p90 | 87% / 15.5 / 21.2 |
|
||||
| 盲挖档基线格通关率 | 83% |
|
||||
| 台阶倒挂 | L1 87% vs L2 87%——倒挂消失（旧读数 65vs90→65vs80→本批持平），方向性好转 |
|
||||
|
||||
### F4 满配格（gate：普通场 ≤20% / Boss 场 ≤50% 生效 max_hp）
|
||||
|
||||
| 关卡 | 普通场 | Boss 场 | 判读 |
|
||||
|---|---|---|---|
|
||||
| L1 | 6.5% | 15.7% | ✅ PASS |
|
||||
| L2 | 5.9% | 22.8% | ✅ PASS |
|
||||
|
||||
### 战斗级承伤带（普通 ≤20% / Boss ≤50%，全网格聚合）
|
||||
|
||||
全部 9 个（关×类型×深度）分组 ✓ PASS；Boss 战单独出列读数：L1 Boss 场均承伤 26.7% max_hp / 5.9 轮，L2 Boss 35.7% / 5.0 轮——Boss 承伤占比显著高于普通场（设计方向：Boss 是主要伤害来源），无不可控死法迹象（败北节点全部集中于 Boss 位，普通位败北为 0）。
|
||||
|
||||
### 阶段二初稿结论
|
||||
|
||||
双 gate（承伤带 + 通关率）双败，方向一致=**压力不足**（完美档太容易通关、承伤远低于生死带）。按归因规则本应走 §4e 阶梯（敌方输出侧），但发现①属实现缺陷且优先级在前（§4e 边界 1）——**建议顺序：掷点修复批 → 阶段一重跑 → 阶段二调参批**。附带提醒：修复掷点会轻微改变承伤/通关读数（掷点分布变了），调参批应在修复后的重测读数上工作。
|
||||
|
||||
---
|
||||
|
||||
## 07⑦ 刷新经济监控——基线读数（本批搭车项，2026-09-19 首批基线）
|
||||
|
||||
分析器已新增两读数（`log_analysis.py` 关卡级统计：弃图率=每局受理刷新次数，与 MC 刷新/局同口径；每轮刷新率=刷新次数÷结算轮数）。**首批基线**：
|
||||
|
||||
| 数据面 | 弃图率（次/局） | 每轮刷新率 | 样本 |
|
||||
|---|---|---|---|
|
||||
| MC L1 完美档基线格 | 0.23 | — | 30 局 |
|
||||
| MC L2 完美档基线格 | 0.03 | — | 30 局 |
|
||||
| MC 全网格 L1 完美档 | 0.08 | 0.006 | 300 局 |
|
||||
| MC 全网格 L2 完美档 | 0.01 | 0.001 | 300 局 |
|
||||
| MC 全网格 normal 档（两关） | 0.00 | 0.000 | 600 局 |
|
||||
| 真人日志参照（并行会话今日 600 局模拟，非本批数据） | 完美档 0.12 | 0.008 | 供交叉参照 |
|
||||
|
||||
解读起点（供调参批参考，非结论）：完美档低频弃图（~0.1 次/局量级）、normal 档零弃图——与「完美档卡死才刷新」的口径一致（auto_player 刷新=卡死解除手段）；normal 档零使用提示 1 RAP 定价对普通玩家可能偏贵或无感知，真人批数据将回答。**阈值数字仍归调参批**（口径不变：现在定是拍脑袋）。
|
||||
|
||||
**顺带核查项**：07⑥ 速杀退化预警的读数（战斗结束未开资格格占比）经核对**现役日志不可推导**——battle_end 行仅含 result+hero_hp，无格面开格状态面。采集义务需等埋点（board 状态入结算快照或独立行），本批不硬做，注记后延。
|
||||
|
||||
---
|
||||
|
||||
## 待办与回流
|
||||
|
||||
1. **真人批**（用户）：基线档 3–5 局 → k 系数 + 零掉血轮宽口径真人对照 → 本报告终稿。
|
||||
2. **掷点测量修复**（待拍板选案）：方案 A（宽种子带，零代码）/方案 B（master 混淆加固，黄金向量重登记）/方案 C（真随机+记录，不推荐）；选 A 则登记 06 待办为「验收掷点扫描种子带改造」，选 B 则为 rng_service 加固批；阶段一在修复后重跑。
|
||||
3. **口径文档连带修订**（归合并批）：`docs/acceptance-ap6-ac.md` 快照 buffs 盲区节改写、Boss 血量锚参照值重校准（58 现值）、§2 消费读数行补刷新两读数；`06-待办清单`「刷新经济性监控」条目保留至调参批定阈值。
|
||||
4. **曲线调参批门**：确认改为「掷点测量修复 + 阶段一重跑后」起跑（原门=验收读数）。
|
||||
|
||||
## 附录：探针脚本（复现用）
|
||||
|
||||
本批全部 RNG 探针为一次性 `/tmp` 脚本（rng_probe*.gd），核心复现路径：
|
||||
① 从日志抽种子 4227 首局前 23 掷与 `open_stream("armor_roll")` 逐 scope 首输出逐位比对；
|
||||
② `SALT_ARMOR_ROLL ^ (seed + scope×GOLDEN) & 0x7FFF…` 直喂 `RandomNumberGenerator.randi_range(1,20)` 画头部直方图；
|
||||
③ 按 30 种子×40 局×8~31 掷聚合复现失真签名。诊断用工程内探针 `smoke/rng_face_probe.gd` 已随批删除，不留残留。
|
||||
@@ -0,0 +1,104 @@
|
||||
# 数值验证报告（20260922-200721）
|
||||
|
||||
- 采集规模：直入口每格 100 局 · 基线冒险 60 局/画像 · 战役 60 局/画像 · 种子 8000 起逐局独立 · 锻造花费策略 = hp_first
|
||||
- 切片版本：e8d8d60 · 表状态：判定带与表值溯源见 tools/balance_verifier.py 文件头
|
||||
|
||||
## ① 直入口基线通关率（验收带判定）
|
||||
|
||||
| 层 | 画像 | 通关/局数 | 通关率±95%CI | 验收带 | 判定 |
|
||||
|--------|--------|-----------|--------------|---------|------------------------------|
|
||||
| 第一层 | 普通档 | 59/100 | 59.0% ±9.6 | [35,55] | 越上界（高于 55% 达 4.0 点） |
|
||||
| 第二层 | 普通档 | 50/100 | 50.0% ±9.8 | [25,45] | 越上界（高于 45% 达 5.0 点） |
|
||||
| 第三层 | 普通档 | 24/100 | 24.0% ±8.4 | 未定 | 带未定（只测不判） |
|
||||
| 第一层 | 完美档 | 70/100 | 70.0% ±9.0 | [35,65] | 越上界（高于 65% 达 5.0 点） |
|
||||
| 第二层 | 完美档 | 46/100 | 46.0% ±9.8 | [35,65] | 落带 [35,65] ✓ |
|
||||
| 第三层 | 完美档 | 22/100 | 22.0% ±8.1 | 未定 | 带未定（只测不判） |
|
||||
|
||||
## ② 零永久强化冒险：止步分布与败退节点（用户判据③）
|
||||
|
||||
### 普通档（60 局）
|
||||
|
||||
- 止步分布：止步第1层 20（33%）、止步第2层 4（7%）、止步第3层 11（18%）、通关 25（42%）
|
||||
- 第一层通过率（冒险口径交叉核对）：66.7%
|
||||
- 败退节点分布（失败局归因）：
|
||||
- 第一层·节点6·Boss ×17
|
||||
- 第三层·节点9·Boss ×11
|
||||
- 第二层·节点9·Boss ×4
|
||||
- 第一层·节点4·战斗 ×2
|
||||
- 第一层·节点3·战斗 ×1
|
||||
|
||||
### 完美档（60 局）
|
||||
|
||||
- 止步分布：止步第1层 22（37%）、止步第2层 2（3%）、止步第3层 7（12%）、通关 29（48%）
|
||||
- 第一层通过率（冒险口径交叉核对）：63.3%
|
||||
- 败退节点分布（失败局归因）：
|
||||
- 第一层·节点6·Boss ×13
|
||||
- 第三层·节点9·Boss ×7
|
||||
- 第一层·节点4·战斗 ×6
|
||||
- 第一层·节点3·战斗 ×2
|
||||
- 第二层·节点9·Boss ×2
|
||||
- 第一层·节点1·战斗 ×1
|
||||
|
||||
## ③ 营地循环爬升（用户判据④：5 次通关 → 下一层可过）
|
||||
|
||||
### 普通档（60 局战役）
|
||||
|
||||
- 钥石：全程入账 2166 · 终态余额 12 · 锻造终态 = 生命+27/攻击+9/护甲+9
|
||||
- 道具工坊解锁时点（魔法道具面，局内效果未实装只报不判）：显影尘 第 1 局、工兵令 第 1 局、探宝罗盘 第 1 局、探巢摆钟 第 1 局、地穴全图卷 第 2 局、爆破工兵包 第 2 局
|
||||
|
||||
- 判据：累计通过第一层 5 次后，第二层条件通关率（滑窗 10 局）——越上界（高于 45% 达 55.0 点）（触发时注入 = 生命+15/攻击+3/护甲+1）
|
||||
- 判据：累计通过第二层 5 次后，第三层条件通关率（滑窗 10 局）——带未定（只测不判）（触发时注入 = 生命+15/攻击+3/护甲+1）
|
||||
|
||||
| 局 | 注入(flat) | 钥石 | 第1层率(窗) | 第2层率(窗) | 第3层率(窗) | 终局 |
|
||||
|--------|--------------|------|-------------|-------------|-------------|-----------|
|
||||
| 第1局 | 血0/攻0/甲0 | 8 | 100%(n=1) | 100%(n=1) | 0%(n=1) | 止步第3层 |
|
||||
| 第4局 | 血12/攻2/甲0 | 13 | 100%(n=4) | 100%(n=4) | 75%(n=4) | 通关 |
|
||||
| 第7局 | 血15/攻4/甲1 | 2 | 100%(n=7) | 100%(n=7) | 86%(n=7) | 通关 |
|
||||
| 第10局 | 血15/攻4/甲4 | 4 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第13局 | 血18/攻5/甲4 | 14 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第16局 | 血18/攻6/甲5 | 49 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第19局 | 血18/攻6/甲6 | 84 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第22局 | 血21/攻6/甲6 | 83 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第25局 | 血21/攻7/甲6 | 82 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第28局 | 血21/攻7/甲7 | 81 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第31局 | 血21/攻7/甲7 | 26 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第34局 | 血24/攻7/甲7 | 134 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第37局 | 血24/攻8/甲7 | 79 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第40局 | 血24/攻8/甲7 | 24 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第43局 | 血24/攻8/甲8 | 132 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第46局 | 血24/攻8/甲8 | 240 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第49局 | 血27/攻8/甲8 | 104 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第52局 | 血27/攻8/甲8 | 212 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第55局 | 血27/攻9/甲8 | 76 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第58局 | 血27/攻9/甲8 | 184 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
|
||||
### 完美档（60 局战役）
|
||||
|
||||
- 钥石：全程入账 2143 · 终态余额 233 · 锻造终态 = 生命+27/攻击+9/护甲+8
|
||||
- 道具工坊解锁时点（魔法道具面，局内效果未实装只报不判）：显影尘 第 2 局、工兵令 第 2 局、探宝罗盘 第 2 局、探巢摆钟 第 2 局、地穴全图卷 第 2 局、爆破工兵包 第 2 局
|
||||
|
||||
- 判据：累计通过第一层 5 次后，第二层条件通关率（滑窗 10 局）——越上界（高于 65% 达 35.0 点）（触发时注入 = 生命+12/攻击+4/护甲+2）
|
||||
- 判据：累计通过第二层 5 次后，第三层条件通关率（滑窗 10 局）——带未定（只测不判）（触发时注入 = 生命+12/攻击+4/护甲+2）
|
||||
|
||||
| 局 | 注入(flat) | 钥石 | 第1层率(窗) | 第2层率(窗) | 第3层率(窗) | 终局 |
|
||||
|--------|--------------|------|-------------|-------------|-------------|-----------|
|
||||
| 第1局 | 血0/攻0/甲0 | 0 | 0%(n=1) | — | — | 止步第1层 |
|
||||
| 第4局 | 血12/攻1/甲0 | 0 | 75%(n=4) | 100%(n=3) | 100%(n=3) | 通关 |
|
||||
| 第7局 | 血12/攻4/甲2 | 1 | 86%(n=7) | 100%(n=6) | 100%(n=6) | 通关 |
|
||||
| 第10局 | 血15/攻5/甲3 | 5 | 90%(n=10) | 100%(n=9) | 100%(n=9) | 通关 |
|
||||
| 第13局 | 血18/攻5/甲4 | 40 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第16局 | 血18/攻6/甲4 | 26 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第19局 | 血18/攻6/甲6 | 61 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第22局 | 血21/攻6/甲6 | 60 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第25局 | 血21/攻7/甲6 | 59 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第28局 | 血21/攻7/甲7 | 58 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第31局 | 血21/攻7/甲7 | 3 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第34局 | 血24/攻7/甲7 | 111 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第37局 | 血24/攻8/甲7 | 56 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第40局 | 血24/攻8/甲7 | 1 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第43局 | 血24/攻8/甲8 | 109 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第46局 | 血24/攻8/甲8 | 217 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第49局 | 血27/攻8/甲8 | 81 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第52局 | 血27/攻8/甲8 | 189 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第55局 | 血27/攻9/甲8 | 53 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第58局 | 血27/攻9/甲8 | 161 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
@@ -0,0 +1,105 @@
|
||||
# 数值验证报告（20260923-043341）
|
||||
|
||||
- 采集规模：直入口每格 100 局 · 基线冒险 60 局/画像 · 战役 60 局/画像 · 种子 8000 起逐局独立 · 锻造花费策略 = hp_first
|
||||
- 切片版本：3309aae · 表状态：判定带与表值溯源见 tools/balance_verifier.py 文件头
|
||||
|
||||
## ① 直入口基线通关率（验收带判定）
|
||||
|
||||
| 层 | 画像 | 通关/局数 | 通关率±95%CI | 验收带 | 判定 |
|
||||
|----|------|-----------|--------------|--------|------|
|
||||
|
||||
## ② 零永久强化冒险：止步分布与败退节点（用户判据③）
|
||||
|
||||
### 普通档（60 局）
|
||||
|
||||
- 止步分布：止步第1层 29（48%）、止步第2层 26（43%）、止步第3层 5（8%）
|
||||
- 第一层通过率（冒险口径交叉核对）：51.7%
|
||||
- 败退节点分布（失败局归因）：
|
||||
- 第二层·节点9·Boss ×13
|
||||
- 第一层·节点4·战斗 ×12
|
||||
- 第一层·节点6·Boss ×12
|
||||
- 第二层·节点1·战斗 ×8
|
||||
- 第一层·节点3·战斗 ×5
|
||||
- 第二层·节点6·战斗 ×4
|
||||
- 第三层·节点1·战斗 ×3
|
||||
- 第二层·节点0·战斗 ×1
|
||||
- 第三层·节点9·Boss ×1
|
||||
- 第三层·节点0·战斗 ×1
|
||||
|
||||
### 完美档（60 局）
|
||||
|
||||
- 止步分布：止步第1层 6（10%）、止步第2层 41（68%）、止步第3层 13（22%）
|
||||
- 第一层通过率（冒险口径交叉核对）：90.0%
|
||||
- 败退节点分布（失败局归因）：
|
||||
- 第二层·节点9·Boss ×25
|
||||
- 第二层·节点1·战斗 ×13
|
||||
- 第三层·节点1·战斗 ×7
|
||||
- 第一层·节点4·战斗 ×6
|
||||
- 第三层·节点9·Boss ×3
|
||||
- 第二层·节点6·战斗 ×3
|
||||
- 第三层·节点0·战斗 ×2
|
||||
- 第三层·节点6·战斗 ×1
|
||||
|
||||
## ③ 营地循环爬升（用户判据④：5 次通关 → 下一层可过）
|
||||
|
||||
### 普通档（60 局战役）
|
||||
|
||||
- 钥石：全程入账 1614 · 终态余额 153 · 锻造终态 = 生命+21/攻击+6/护甲+6
|
||||
- 道具工坊解锁时点（魔法道具面，局内效果未实装只报不判）：显影尘 第 2 局、工兵令 第 2 局、探宝罗盘 第 4 局、探巢摆钟 第 4 局、地穴全图卷 第 5 局、爆破工兵包 第 5 局
|
||||
|
||||
- 判据：累计通过第一层 5 次后，第二层条件通关率（滑窗 10 局）——越上界（高于 45% 达 25.0 点）（触发时注入 = 生命+6/攻击+1/护甲+0）
|
||||
- 判据：累计通过第二层 5 次后，第三层条件通关率（滑窗 10 局）——带未定（只测不判）（触发时注入 = 生命+9/攻击+2/护甲+2）
|
||||
|
||||
| 局 | 注入(flat) | 钥石 | 第1层率(窗) | 第2层率(窗) | 第3层率(窗) | 终局 |
|
||||
|--------|--------------|------|-------------|-------------|-------------|-----------|
|
||||
| 第1局 | 血0/攻0/甲0 | 0 | 0%(n=1) | — | — | 止步第1层 |
|
||||
| 第4局 | 血0/攻0/甲0 | 6 | 50%(n=4) | 0%(n=2) | — | 止步第2层 |
|
||||
| 第7局 | 血6/攻0/甲0 | 7 | 71%(n=7) | 20%(n=5) | — | 止步第2层 |
|
||||
| 第10局 | 血6/攻1/甲0 | 7 | 60%(n=10) | 33%(n=6) | 50%(n=2) | 通关 |
|
||||
| 第13局 | 血9/攻2/甲1 | 10 | 80%(n=10) | 44%(n=9) | 75%(n=4) | 通关 |
|
||||
| 第16局 | 血9/攻2/甲2 | 0 | 80%(n=10) | 60%(n=10) | 50%(n=6) | 止步第3层 |
|
||||
| 第19局 | 血12/攻2/甲2 | 12 | 100%(n=10) | 70%(n=10) | 38%(n=8) | 止步第3层 |
|
||||
| 第22局 | 血12/攻3/甲3 | 36 | 100%(n=10) | 80%(n=10) | 30%(n=10) | 止步第3层 |
|
||||
| 第25局 | 血12/攻4/甲3 | 26 | 100%(n=10) | 80%(n=10) | 10%(n=10) | 止步第3层 |
|
||||
| 第28局 | 血12/攻4/甲4 | 41 | 100%(n=10) | 90%(n=10) | 10%(n=10) | 通关 |
|
||||
| 第31局 | 血12/攻4/甲4 | 23 | 100%(n=10) | 90%(n=10) | 20%(n=10) | 通关 |
|
||||
| 第34局 | 血15/攻4/甲4 | 31 | 100%(n=10) | 100%(n=10) | 50%(n=10) | 通关 |
|
||||
| 第37局 | 血15/攻5/甲5 | 39 | 100%(n=10) | 100%(n=10) | 80%(n=10) | 通关 |
|
||||
| 第40局 | 血15/攻5/甲5 | 134 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第43局 | 血18/攻5/甲5 | 79 | 100%(n=10) | 100%(n=10) | 80%(n=10) | 通关 |
|
||||
| 第46局 | 血18/攻6/甲5 | 37 | 100%(n=10) | 100%(n=10) | 80%(n=10) | 通关 |
|
||||
| 第49局 | 血18/攻6/甲5 | 145 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第52局 | 血18/攻6/甲6 | 90 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第55局 | 血18/攻6/甲6 | 198 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第58局 | 血21/攻6/甲6 | 81 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
|
||||
### 完美档（60 局战役）
|
||||
|
||||
- 钥石：全程入账 1922 · 终态余额 11 · 锻造终态 = 生命+21/攻击+7/护甲+7
|
||||
- 道具工坊解锁时点（魔法道具面，局内效果未实装只报不判）：显影尘 第 1 局、工兵令 第 1 局、探宝罗盘 第 2 局、探巢摆钟 第 2 局、地穴全图卷 第 2 局、爆破工兵包 第 2 局
|
||||
|
||||
- 判据：累计通过第一层 5 次后，第二层条件通关率（滑窗 10 局）——越上界（高于 65% 达 25.0 点）（触发时注入 = 生命+9/攻击+1/护甲+0）
|
||||
- 判据：累计通过第二层 5 次后，第三层条件通关率（滑窗 10 局）——带未定（只测不判）（触发时注入 = 生命+9/攻击+3/护甲+0）
|
||||
|
||||
| 局 | 注入(flat) | 钥石 | 第1层率(窗) | 第2层率(窗) | 第3层率(窗) | 终局 |
|
||||
|--------|--------------|------|-------------|-------------|-------------|-----------|
|
||||
| 第1局 | 血0/攻0/甲0 | 15 | 100%(n=1) | 0%(n=1) | — | 止步第2层 |
|
||||
| 第4局 | 血3/攻1/甲0 | 8 | 100%(n=4) | 50%(n=4) | 0%(n=2) | 止步第3层 |
|
||||
| 第7局 | 血9/攻2/甲0 | 12 | 100%(n=7) | 57%(n=7) | — | 止步第2层 |
|
||||
| 第10局 | 血9/攻3/甲1 | 12 | 100%(n=10) | 70%(n=10) | 43%(n=7) | 通关 |
|
||||
| 第13局 | 血9/攻3/甲3 | 62 | 100%(n=10) | 90%(n=10) | 50%(n=10) | 止步第3层 |
|
||||
| 第16局 | 血12/攻3/甲3 | 10 | 100%(n=10) | 90%(n=10) | 50%(n=10) | 止步第3层 |
|
||||
| 第19局 | 血12/攻4/甲4 | 38 | 100%(n=10) | 100%(n=10) | 60%(n=10) | 通关 |
|
||||
| 第22局 | 血12/攻4/甲4 | 33 | 100%(n=10) | 100%(n=10) | 50%(n=10) | 通关 |
|
||||
| 第25局 | 血15/攻5/甲4 | 28 | 100%(n=10) | 100%(n=10) | 60%(n=10) | 止步第3层 |
|
||||
| 第28局 | 血15/攻5/甲4 | 23 | 100%(n=10) | 100%(n=10) | 70%(n=10) | 通关 |
|
||||
| 第31局 | 血15/攻5/甲5 | 118 | 100%(n=10) | 100%(n=10) | 70%(n=10) | 止步第3层 |
|
||||
| 第34局 | 血18/攻5/甲5 | 76 | 100%(n=10) | 100%(n=10) | 70%(n=10) | 通关 |
|
||||
| 第37局 | 血18/攻5/甲5 | 34 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第40局 | 血18/攻6/甲5 | 142 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第43局 | 血18/攻6/甲6 | 100 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第46局 | 血18/攻6/甲6 | 195 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第49局 | 血21/攻6/甲6 | 78 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第52局 | 血21/攻6/甲6 | 173 | 100%(n=10) | 100%(n=10) | 80%(n=10) | 通关 |
|
||||
| 第55局 | 血21/攻7/甲6 | 56 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第58局 | 血21/攻7/甲6 | 164 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
@@ -0,0 +1,103 @@
|
||||
# 数值验证报告（20260923-050222）
|
||||
|
||||
- 采集规模：直入口每格 100 局 · 基线冒险 60 局/画像 · 战役 60 局/画像 · 种子 8000 起逐局独立 · 锻造花费策略 = hp_first
|
||||
- 切片版本：3309aae · 表状态：判定带与表值溯源见 tools/balance_verifier.py 文件头
|
||||
|
||||
## ① 直入口基线通关率（验收带判定）
|
||||
|
||||
| 层 | 画像 | 通关/局数 | 通关率±95%CI | 验收带 | 判定 |
|
||||
|----|------|-----------|--------------|--------|------|
|
||||
|
||||
## ② 零永久强化冒险：止步分布与败退节点（用户判据③）
|
||||
|
||||
### 普通档（60 局）
|
||||
|
||||
- 止步分布：止步第1层 29（48%）、止步第2层 30（50%）、止步第3层 1（2%）
|
||||
- 第一层通过率（冒险口径交叉核对）：51.7%
|
||||
- 败退节点分布（失败局归因）：
|
||||
- 第一层·节点4·战斗 ×12
|
||||
- 第一层·节点6·Boss ×12
|
||||
- 第二层·节点1·战斗 ×12
|
||||
- 第二层·节点9·Boss ×12
|
||||
- 第一层·节点3·战斗 ×5
|
||||
- 第二层·节点6·战斗 ×5
|
||||
- 第二层·节点0·战斗 ×1
|
||||
- 第三层·节点1·战斗 ×1
|
||||
|
||||
### 完美档（60 局）
|
||||
|
||||
- 止步分布：止步第1层 6（10%）、止步第2层 45（75%）、止步第3层 8（13%）、通关 1（2%）
|
||||
- 第一层通过率（冒险口径交叉核对）：90.0%
|
||||
- 败退节点分布（失败局归因）：
|
||||
- 第二层·节点1·战斗 ×17
|
||||
- 第二层·节点9·Boss ×17
|
||||
- 第二层·节点6·战斗 ×11
|
||||
- 第一层·节点4·战斗 ×6
|
||||
- 第三层·节点1·战斗 ×4
|
||||
- 第三层·节点6·战斗 ×2
|
||||
- 第三层·节点0·战斗 ×1
|
||||
- 第三层·节点9·Boss ×1
|
||||
|
||||
## ③ 营地循环爬升（用户判据④：5 次通关 → 下一层可过）
|
||||
|
||||
### 普通档（60 局战役）
|
||||
|
||||
- 钥石：全程入账 1553 · 终态余额 92 · 锻造终态 = 生命+21/攻击+6/护甲+6
|
||||
- 道具工坊解锁时点（魔法道具面，局内效果未实装只报不判）：显影尘 第 2 局、工兵令 第 2 局、探宝罗盘 第 4 局、探巢摆钟 第 4 局、地穴全图卷 第 5 局、爆破工兵包 第 5 局
|
||||
|
||||
- 判据：累计通过第一层 5 次后，第二层条件通关率（滑窗 10 局）——越上界（高于 45% 达 5.0 点）（触发时注入 = 生命+6/攻击+1/护甲+0）
|
||||
- 判据：累计通过第二层 5 次后，第三层条件通关率（滑窗 10 局）——带未定（只测不判）（触发时注入 = 生命+9/攻击+3/护甲+2）
|
||||
|
||||
| 局 | 注入(flat) | 钥石 | 第1层率(窗) | 第2层率(窗) | 第3层率(窗) | 终局 |
|
||||
|--------|--------------|------|-------------|-------------|-------------|-----------|
|
||||
| 第1局 | 血0/攻0/甲0 | 0 | 0%(n=1) | — | — | 止步第1层 |
|
||||
| 第4局 | 血0/攻0/甲0 | 6 | 50%(n=4) | 0%(n=2) | — | 止步第2层 |
|
||||
| 第7局 | 血3/攻1/甲0 | 7 | 71%(n=7) | 20%(n=5) | 0%(n=1) | 止步第3层 |
|
||||
| 第10局 | 血6/攻1/甲0 | 7 | 60%(n=10) | 33%(n=6) | 50%(n=2) | 通关 |
|
||||
| 第13局 | 血9/攻2/甲1 | 15 | 80%(n=10) | 33%(n=9) | — | 止步第2层 |
|
||||
| 第16局 | 血9/攻2/甲2 | 30 | 80%(n=10) | 40%(n=10) | 50%(n=4) | 止步第3层 |
|
||||
| 第19局 | 血9/攻3/甲2 | 42 | 100%(n=10) | 50%(n=10) | 33%(n=6) | 止步第3层 |
|
||||
| 第22局 | 血9/攻3/甲3 | 12 | 100%(n=10) | 60%(n=10) | 33%(n=9) | 通关 |
|
||||
| 第25局 | 血12/攻3/甲3 | 57 | 100%(n=10) | 70%(n=10) | — | 止步第2层 |
|
||||
| 第28局 | 血12/攻4/甲3 | 59 | 100%(n=10) | 80%(n=10) | 10%(n=10) | 止步第3层 |
|
||||
| 第31局 | 血12/攻4/甲4 | 87 | 100%(n=10) | 80%(n=10) | 30%(n=10) | 通关 |
|
||||
| 第34局 | 血15/攻4/甲4 | 95 | 100%(n=10) | 90%(n=10) | 50%(n=10) | 通关 |
|
||||
| 第37局 | 血15/攻5/甲4 | 3 | 100%(n=10) | 100%(n=10) | 80%(n=10) | 通关 |
|
||||
| 第40局 | 血15/攻5/甲5 | 98 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第43局 | 血15/攻5/甲5 | 18 | 100%(n=10) | 90%(n=10) | 80%(n=10) | 通关 |
|
||||
| 第46局 | 血18/攻5/甲5 | 126 | 100%(n=10) | 90%(n=10) | 80%(n=10) | 通关 |
|
||||
| 第49局 | 血18/攻6/甲5 | 84 | 100%(n=10) | 90%(n=10) | 80%(n=10) | 通关 |
|
||||
| 第52局 | 血18/攻6/甲5 | 29 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第55局 | 血18/攻6/甲6 | 137 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第58局 | 血18/攻6/甲6 | 20 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
|
||||
### 完美档（60 局战役）
|
||||
|
||||
- 钥石：全程入账 1935 · 终态余额 24 · 锻造终态 = 生命+21/攻击+7/护甲+7
|
||||
- 道具工坊解锁时点（魔法道具面，局内效果未实装只报不判）：显影尘 第 1 局、工兵令 第 1 局、探宝罗盘 第 2 局、探巢摆钟 第 2 局、地穴全图卷 第 2 局、爆破工兵包 第 2 局
|
||||
|
||||
- 判据：累计通过第一层 5 次后，第二层条件通关率（滑窗 10 局）——越上界（高于 65% 达 35.0 点）（触发时注入 = 生命+9/攻击+1/护甲+0）
|
||||
- 判据：累计通过第二层 5 次后，第三层条件通关率（滑窗 10 局）——带未定（只测不判）（触发时注入 = 生命+9/攻击+2/护甲+1）
|
||||
|
||||
| 局 | 注入(flat) | 钥石 | 第1层率(窗) | 第2层率(窗) | 第3层率(窗) | 终局 |
|
||||
|--------|--------------|------|-------------|-------------|-------------|-----------|
|
||||
| 第1局 | 血0/攻0/甲0 | 15 | 100%(n=1) | 0%(n=1) | — | 止步第2层 |
|
||||
| 第4局 | 血3/攻1/甲0 | 8 | 100%(n=4) | 50%(n=4) | 0%(n=2) | 止步第3层 |
|
||||
| 第7局 | 血9/攻2/甲0 | 4 | 100%(n=7) | 71%(n=7) | 20%(n=5) | 止步第3层 |
|
||||
| 第10局 | 血9/攻2/甲2 | 11 | 100%(n=10) | 80%(n=10) | 25%(n=8) | 止步第3层 |
|
||||
| 第13局 | 血9/攻3/甲3 | 61 | 100%(n=10) | 100%(n=10) | 40%(n=10) | 止步第3层 |
|
||||
| 第16局 | 血12/攻3/甲3 | 9 | 100%(n=10) | 100%(n=10) | 40%(n=10) | 止步第3层 |
|
||||
| 第19局 | 血12/攻4/甲4 | 50 | 100%(n=10) | 100%(n=10) | 60%(n=10) | 通关 |
|
||||
| 第22局 | 血15/攻4/甲4 | 45 | 100%(n=10) | 100%(n=10) | 60%(n=10) | 通关 |
|
||||
| 第25局 | 血15/攻5/甲4 | 40 | 100%(n=10) | 100%(n=10) | 70%(n=10) | 止步第3层 |
|
||||
| 第28局 | 血15/攻5/甲5 | 48 | 100%(n=10) | 100%(n=10) | 80%(n=10) | 通关 |
|
||||
| 第31局 | 血15/攻5/甲5 | 118 | 100%(n=10) | 90%(n=10) | 80%(n=10) | 止步第3层 |
|
||||
| 第34局 | 血18/攻5/甲5 | 76 | 100%(n=10) | 90%(n=10) | 80%(n=10) | 通关 |
|
||||
| 第37局 | 血18/攻5/甲5 | 34 | 100%(n=10) | 90%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第40局 | 血18/攻6/甲5 | 142 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第43局 | 血18/攻6/甲6 | 100 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第46局 | 血18/攻6/甲6 | 195 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第49局 | 血21/攻6/甲6 | 78 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第52局 | 血21/攻6/甲6 | 186 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第55局 | 血21/攻7/甲6 | 69 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第58局 | 血21/攻7/甲6 | 177 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
@@ -0,0 +1,36 @@
|
||||
# 战斗舞台 Node2D 迁移 · 信号与演出等价证明（循环 1 T4，2026-09-26）
|
||||
|
||||
> 计划书 T4 验收件：时序常量逐字对照旧实现 + 写路径逐行同构（Phase A 先例成文化）+ 调用点 grep 对比零 diff。
|
||||
> 对比基线 = T0 提交 `3db7e87`（迁移前现行态）；迁移后 = worktree battle-stage-node2d-20260926 T3 提交。
|
||||
|
||||
## 1. 调用点 grep 对比（零 diff 实证）
|
||||
|
||||
| 面 | 命令 | 结果 |
|
||||
|---|---|---|
|
||||
| main.gd → stage 调用点（9 处：set_effects_cleared_feedback ×2 / gray_all_enemies ×2 / on_step_row_fx / enemy_standee_center / hero_standee_center / set_settle_focus / set_round_text） | `grep -E "stage\.(hero_standee\|enemy_standee_center\|on_step_row_fx\|gray_all_enemies\|set_round_text\|set_settle_focus\|clear_enemies)"` 老新对拍 | **逐字节一致**（行号 309/310/439/441/475/495/503/768/770 全同） |
|
||||
| hud_presenter.gd → hero_standee 投喂（4 处：set_hero ×2 / set_effects ×2） | 同法对拍 | **逐字节一致**（行号 53/54/79/80 全同——单投喂结构零变） |
|
||||
| hud_presenter.gd / main.gd / core/** 文件级 | `git diff 3db7e87..HEAD --stat` | **零行变更**（投喂链零改动实证；核心层零接触） |
|
||||
|
||||
## 2. 时序常量逐字对照（旧 StandeeView → 新 StandeeBody）
|
||||
|
||||
| 演出 | 旧（Control + tween） | 新（Node2D + tween） | 判定 |
|
||||
|---|---|---|---|
|
||||
| 血条递减 | `motion(0.15)` tween bar value | `motion(0.15)` tween hp_value 属性 | 同 |
|
||||
| 意图弹入 | scale 1.6→ONE，`motion(0.10)`/`motion(0.16)` | `_intent_scale` 1.6→1.0 同时长 | 同 |
|
||||
| 立绘前倾 | rotation 4.0→0.0，`motion(0.10)`/`motion(0.14)` | `_glyph_rot` 同值同时长（旧仅转字形 Label——贴图态无动画，新等价保持） | 同 |
|
||||
| 死亡摇摆 | modulate (0.62,0.62,0.62,0.9)；rotation 2.5→−1.5→0.0，`motion(0.12)`/`(0.1)`/`(0.08)` | 逐字同 | 同 |
|
||||
| 受击闪白 | modulate (1.6,1.4,1.2) `motion(0.08)` → 白/死灰 `motion(0.2)` | 逐字同（终色按 _dead 分支同构） | 同 |
|
||||
| 复活复位 | modulate 白、rotation 0 | 同 | 同 |
|
||||
| 清空反馈微文案 | 1.2s 停留 + `motion(0.8)` 淡出 | 同（载体挂壳层伴随件父层——T3 代拍板③） | 同 |
|
||||
|
||||
## 3. 写路径逐行同构（旧 battle_stage_view.gd → 新）
|
||||
|
||||
- `on_step_row_fx(row)`：type!=""damage" 早退 / target=="hero"|""早退 / `_card_by_name(target)` 空退 / `flash_hit()` + killed→`mark_dead()`——逐行同构；`_card_by_name` 内部实现由「子件 `_name_label.text` contains」改「本体 `display_name()` contains」（语义等价，函数内部实现细节=§9 白名单）。
|
||||
- `set_enemies(cards_data)`：数量分叉（重建 vs 就地 set_data）结构逐行同构；重建侧由 StandeeView.new 改 StandeeBody.new+伴随件挂接（T3 代拍板①④）。
|
||||
- `clear_enemies()` / `gray_all_enemies()` / `set_round_text()` / `set_settle_focus()`：逐行同构（遍历对象 Control→本体）。
|
||||
- 弹道落点：`hero_standee_center()`/`enemy_standee_center()` 签名不变，实现 = 旧「本体 get_global_rect 中心」改 `world_to_shell(本体.position + box*0.5)`——**壳层口径保持（C4：结算演出 SettlementFxView 在 SubViewport 之外）**，返回值语义=站桩盒几何中心不变。
|
||||
- `set_effects/set_effects_cleared_feedback/set_hero`（投喂面）：本体转发伴随件（slot_row），调用方零改造。
|
||||
|
||||
## 4. 已登记的结构性差异（非漂移，改判记录见台账 170/171）
|
||||
|
||||
1. 站桩本体载体 Control→Node2D（本批目标本身）；2. slot_row 伴随件挂壳层；3. enemy_box HBoxContainer→Control 伴随件容器；4. 血条呈现由引擎默认 ProgressBar 改世界直角矩形（色值近似平移——目检清单列「血条观感」项）；5. ui_probe 敌站桩断言改本体探针出口（呈现口径逐字保持）。
|
||||
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,296 @@
|
||||
# 数值验证报告（20260923-084327）
|
||||
|
||||
- 采集规模：基线冒险 100 局/画像 · 战役 60 局/画像 · 种子 8000 起逐局独立 · 锻造花费策略 = hp_first
|
||||
- 切片版本：7fd6fbd · 口径：逐关读数 = 冒险条件口径（单关直入口口径已退役 2026-09-23，带待重锚只测不判——重锚归曲线调参批） · 换算率表值（meta.tres 启动解析）：生命上限每级平移6点 · 基础攻击每级平移9点 · 护甲等级每级平移1点
|
||||
|
||||
## ① 逐关条件通关率（冒险口径——打通 k-1 关才到达第 k 关；带待重锚只测不判）
|
||||
|
||||
| 层 | 画像 | 通关/到达 | 条件通关率±95%CI | 验收带 |
|
||||
|--------|--------|-----------|------------------|--------|
|
||||
| 第一层 | 普通档 | 53/100 | 53.0% ±9.8 | 未定 |
|
||||
| 第二层 | 普通档 | 1/53 | 1.9% ±3.7 | 未定 |
|
||||
| 第三层 | 普通档 | 0/1 | 0.0% ±0.0 | 未定 |
|
||||
| 第一层 | 完美档 | 86/100 | 86.0% ±6.8 | 未定 |
|
||||
| 第二层 | 完美档 | 15/86 | 17.4% ±8.0 | 未定 |
|
||||
| 第三层 | 完美档 | 0/15 | 0.0% ±0.0 | 未定 |
|
||||
|
||||
## ② 零永久强化冒险：止步分布与败退节点（用户判据③）
|
||||
|
||||
### 普通档（100 局）
|
||||
|
||||
- 止步分布：止步第1层 47（47%）、止步第2层 52（52%）、止步第3层 1（1%）
|
||||
- 败退节点分布（失败局归因）：
|
||||
- 第二层·节点1·战斗 ×23
|
||||
- 第一层·节点4·战斗 ×20
|
||||
- 第一层·节点6·Boss ×20
|
||||
- 第二层·节点9·Boss ×19
|
||||
- 第二层·节点6·战斗 ×8
|
||||
- 第一层·节点3·战斗 ×7
|
||||
- 第二层·节点0·战斗 ×2
|
||||
- 第三层·节点1·战斗 ×1
|
||||
|
||||
### 完美档（100 局）
|
||||
|
||||
- 止步分布：止步第1层 14（14%）、止步第2层 71（71%）、止步第3层 15（15%）
|
||||
- 败退节点分布（失败局归因）：
|
||||
- 第二层·节点1·战斗 ×28
|
||||
- 第二层·节点9·Boss ×27
|
||||
- 第二层·节点6·战斗 ×16
|
||||
- 第一层·节点4·战斗 ×11
|
||||
- 第三层·节点1·战斗 ×7
|
||||
- 第三层·节点6·战斗 ×5
|
||||
- 第三层·节点9·Boss ×2
|
||||
- 第一层·节点6·Boss ×2
|
||||
- 第一层·节点3·战斗 ×1
|
||||
- 第三层·节点0·战斗 ×1
|
||||
|
||||
## ③ 营地循环爬升（用户判据④：5 次通关 → 下一层可过）
|
||||
|
||||
### 普通档 · 生命优先（60 局战役）
|
||||
|
||||
- 钥石：全程入账 1262 · 终态余额 26 · 锻造终态 = 生命+18/攻击+6/护甲+6
|
||||
- 道具工坊解锁时点（魔法道具面，局内效果未实装只报不判）：显影尘 第 3 局、工兵令 第 3 局、探宝罗盘 第 5 局、探巢摆钟 第 5 局、地穴全图卷 第 6 局、爆破工兵包 第 6 局
|
||||
|
||||
- 判据：累计通过第一层 5 次后，第二层条件通关率（滑窗 10 局）——带未定（只测不判）（触发时注入 = 生命+3/攻击+1/护甲+0，表值平移 +15.0 点——带重锚后随平移判）
|
||||
- 判据：累计通过第二层 5 次后，第三层条件通关率（滑窗 10 局）——带未定（只测不判）（触发时注入 = 生命+9/攻击+3/护甲+3，表值平移 +48.0 点——带重锚后随平移判）
|
||||
|
||||
| 局 | 注入(flat) | 钥石 | 第1层率(窗) | 第2层率(窗) | 第3层率(窗) | 终局 |
|
||||
|--------|--------------|------|-------------|-------------|-------------|-----------|
|
||||
| 第1局 | 血0/攻0/甲0 | 0 | 0%(n=1) | — | — | 止步第1层 |
|
||||
| 第4局 | 血0/攻0/甲0 | 15 | 25%(n=4) | — | — | 止步第1层 |
|
||||
| 第7局 | 血3/攻0/甲0 | 17 | 43%(n=7) | — | — | 止步第1层 |
|
||||
| 第10局 | 血3/攻0/甲0 | 8 | 40%(n=10) | 0%(n=4) | — | 止步第2层 |
|
||||
| 第13局 | 血3/攻1/甲0 | 19 | 40%(n=10) | — | — | 止步第1层 |
|
||||
| 第16局 | 血6/攻1/甲0 | 11 | 40%(n=10) | 0%(n=7) | — | 止步第2层 |
|
||||
| 第19局 | 血6/攻1/甲1 | 12 | 70%(n=10) | 10%(n=10) | 0%(n=1) | 止步第3层 |
|
||||
| 第22局 | 血6/攻2/甲2 | 15 | 80%(n=10) | 10%(n=10) | — | 止步第2层 |
|
||||
| 第25局 | 血9/攻2/甲2 | 4 | 100%(n=10) | 30%(n=10) | 33%(n=3) | 止步第3层 |
|
||||
| 第28局 | 血9/攻3/甲3 | 29 | 100%(n=10) | 50%(n=10) | 40%(n=5) | 止步第3层 |
|
||||
| 第31局 | 血9/攻3/甲3 | 32 | 100%(n=10) | 60%(n=10) | 43%(n=7) | 通关 |
|
||||
| 第34局 | 血12/攻3/甲3 | 10 | 100%(n=10) | 60%(n=10) | 38%(n=8) | 止步第3层 |
|
||||
| 第37局 | 血12/攻4/甲4 | 38 | 100%(n=10) | 70%(n=10) | 50%(n=10) | 通关 |
|
||||
| 第40局 | 血15/攻4/甲4 | 33 | 100%(n=10) | 80%(n=10) | 50%(n=10) | 止步第3层 |
|
||||
| 第43局 | 血15/攻4/甲4 | 28 | 100%(n=10) | 100%(n=10) | 60%(n=10) | 通关 |
|
||||
| 第46局 | 血15/攻5/甲5 | 23 | 100%(n=10) | 100%(n=10) | 70%(n=10) | 止步第3层 |
|
||||
| 第49局 | 血15/攻5/甲5 | 131 | 100%(n=10) | 100%(n=10) | 70%(n=10) | 通关 |
|
||||
| 第52局 | 血18/攻5/甲5 | 76 | 100%(n=10) | 100%(n=10) | 80%(n=10) | 止步第3层 |
|
||||
| 第55局 | 血18/攻5/甲5 | 21 | 100%(n=10) | 100%(n=10) | 70%(n=10) | 止步第3层 |
|
||||
| 第58局 | 血18/攻6/甲5 | 129 | 100%(n=10) | 100%(n=10) | 80%(n=10) | 通关 |
|
||||
|
||||
### 完美档 · 生命优先（60 局战役）
|
||||
|
||||
- 钥石：全程入账 1810 · 终态余额 124 · 锻造终态 = 生命+21/攻击+7/护甲+6
|
||||
- 道具工坊解锁时点（魔法道具面，局内效果未实装只报不判）：显影尘 第 1 局、工兵令 第 1 局、探宝罗盘 第 2 局、探巢摆钟 第 2 局、地穴全图卷 第 3 局、爆破工兵包 第 3 局
|
||||
|
||||
- 判据：累计通过第一层 5 次后，第二层条件通关率（滑窗 10 局）——带未定（只测不判）（触发时注入 = 生命+6/攻击+1/护甲+0，表值平移 +21.0 点——带重锚后随平移判）
|
||||
- 判据：累计通过第二层 5 次后，第三层条件通关率（滑窗 10 局）——带未定（只测不判）（触发时注入 = 生命+6/攻击+2/护甲+2，表值平移 +32.0 点——带重锚后随平移判）
|
||||
|
||||
| 局 | 注入(flat) | 钥石 | 第1层率(窗) | 第2层率(窗) | 第3层率(窗) | 终局 |
|
||||
|--------|--------------|------|-------------|-------------|-------------|-----------|
|
||||
| 第1局 | 血0/攻0/甲0 | 15 | 100%(n=1) | 0%(n=1) | — | 止步第2层 |
|
||||
| 第4局 | 血6/攻0/甲0 | 16 | 100%(n=4) | 25%(n=4) | — | 止步第2层 |
|
||||
| 第7局 | 血6/攻2/甲0 | 3 | 100%(n=7) | 43%(n=7) | 0%(n=3) | 止步第3层 |
|
||||
| 第10局 | 血6/攻2/甲2 | 30 | 100%(n=10) | 50%(n=10) | 0%(n=5) | 止步第3层 |
|
||||
| 第13局 | 血9/攻2/甲2 | 19 | 100%(n=10) | 60%(n=10) | 14%(n=7) | 通关 |
|
||||
| 第16局 | 血9/攻3/甲2 | 19 | 100%(n=10) | 60%(n=10) | 12%(n=8) | 止步第3层 |
|
||||
| 第19局 | 血12/攻3/甲3 | 60 | 100%(n=10) | 70%(n=10) | 40%(n=10) | 通关 |
|
||||
| 第22局 | 血12/攻4/甲3 | 8 | 100%(n=10) | 80%(n=10) | 50%(n=10) | 止步第3层 |
|
||||
| 第25局 | 血12/攻4/甲4 | 90 | 100%(n=10) | 100%(n=10) | 50%(n=10) | 止步第3层 |
|
||||
| 第28局 | 血15/攻4/甲4 | 98 | 100%(n=10) | 100%(n=10) | 60%(n=10) | 通关 |
|
||||
| 第31局 | 血15/攻5/甲4 | 93 | 100%(n=10) | 100%(n=10) | 60%(n=10) | 通关 |
|
||||
| 第34局 | 血15/攻5/甲5 | 101 | 100%(n=10) | 100%(n=10) | 80%(n=10) | 通关 |
|
||||
| 第37局 | 血18/攻5/甲5 | 59 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第40局 | 血18/攻5/甲5 | 17 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第43局 | 血18/攻6/甲5 | 112 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 止步第3层 |
|
||||
| 第46局 | 血18/攻6/甲6 | 70 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第49局 | 血18/攻6/甲6 | 178 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第52局 | 血21/攻6/甲6 | 61 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第55局 | 血21/攻6/甲6 | 169 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第58局 | 血21/攻7/甲6 | 52 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
|
||||
### 普通档 · 攻击优先（60 局战役）
|
||||
|
||||
- 钥石：全程入账 1311 · 终态余额 75 · 锻造终态 = 生命+18/攻击+6/护甲+6
|
||||
- 道具工坊解锁时点（魔法道具面，局内效果未实装只报不判）：显影尘 第 3 局、工兵令 第 3 局、探宝罗盘 第 5 局、探巢摆钟 第 5 局、地穴全图卷 第 6 局、爆破工兵包 第 6 局
|
||||
|
||||
- 判据：累计通过第一层 5 次后，第二层条件通关率（滑窗 10 局）——带未定（只测不判）（触发时注入 = 生命+3/攻击+2/护甲+0，表值平移 +24.0 点——带重锚后随平移判）
|
||||
- 判据：累计通过第二层 5 次后，第三层条件通关率（滑窗 10 局）——带未定（只测不判）（触发时注入 = 生命+9/攻击+3/护甲+3，表值平移 +48.0 点——带重锚后随平移判）
|
||||
|
||||
| 局 | 注入(flat) | 钥石 | 第1层率(窗) | 第2层率(窗) | 第3层率(窗) | 终局 |
|
||||
|--------|--------------|------|-------------|-------------|-------------|-----------|
|
||||
| 第1局 | 血0/攻0/甲0 | 0 | 0%(n=1) | — | — | 止步第1层 |
|
||||
| 第4局 | 血0/攻0/甲0 | 15 | 25%(n=4) | — | — | 止步第1层 |
|
||||
| 第7局 | 血0/攻1/甲0 | 17 | 43%(n=7) | — | — | 止步第1层 |
|
||||
| 第10局 | 血0/攻1/甲0 | 16 | 40%(n=10) | 25%(n=4) | 0%(n=1) | 止步第3层 |
|
||||
| 第13局 | 血0/攻2/甲0 | 7 | 40%(n=10) | 20%(n=5) | — | 止步第2层 |
|
||||
| 第16局 | 血3/攻2/甲0 | 9 | 40%(n=10) | 14%(n=7) | — | 止步第2层 |
|
||||
| 第19局 | 血6/攻2/甲1 | 24 | 70%(n=10) | 20%(n=10) | 0%(n=2) | 止步第3层 |
|
||||
| 第22局 | 血6/攻2/甲2 | 27 | 90%(n=10) | 20%(n=10) | — | 止步第2层 |
|
||||
| 第25局 | 血6/攻3/甲2 | 16 | 100%(n=10) | 30%(n=10) | 25%(n=4) | 止步第3层 |
|
||||
| 第28局 | 血9/攻3/甲3 | 41 | 100%(n=10) | 50%(n=10) | 33%(n=6) | 止步第3层 |
|
||||
| 第31局 | 血9/攻4/甲3 | 44 | 100%(n=10) | 60%(n=10) | 38%(n=8) | 通关 |
|
||||
| 第34局 | 血12/攻4/甲3 | 46 | 100%(n=10) | 80%(n=10) | 30%(n=10) | 止步第3层 |
|
||||
| 第37局 | 血12/攻4/甲4 | 74 | 100%(n=10) | 90%(n=10) | 40%(n=10) | 通关 |
|
||||
| 第40局 | 血12/攻5/甲4 | 82 | 100%(n=10) | 100%(n=10) | 60%(n=10) | 通关 |
|
||||
| 第43局 | 血15/攻5/甲4 | 77 | 100%(n=10) | 100%(n=10) | 70%(n=10) | 通关 |
|
||||
| 第46局 | 血15/攻5/甲5 | 72 | 100%(n=10) | 100%(n=10) | 80%(n=10) | 止步第3层 |
|
||||
| 第49局 | 血15/攻5/甲5 | 30 | 100%(n=10) | 100%(n=10) | 80%(n=10) | 通关 |
|
||||
| 第52局 | 血15/攻6/甲5 | 125 | 100%(n=10) | 100%(n=10) | 80%(n=10) | 止步第3层 |
|
||||
| 第55局 | 血18/攻6/甲5 | 70 | 100%(n=10) | 100%(n=10) | 70%(n=10) | 止步第3层 |
|
||||
| 第58局 | 血18/攻6/甲5 | 28 | 100%(n=10) | 100%(n=10) | 80%(n=10) | 通关 |
|
||||
|
||||
### 完美档 · 攻击优先（60 局战役）
|
||||
|
||||
- 钥石：全程入账 1798 · 终态余额 112 · 锻造终态 = 生命+21/攻击+7/护甲+6
|
||||
- 道具工坊解锁时点（魔法道具面，局内效果未实装只报不判）：显影尘 第 1 局、工兵令 第 1 局、探宝罗盘 第 2 局、探巢摆钟 第 2 局、地穴全图卷 第 3 局、爆破工兵包 第 3 局
|
||||
|
||||
- 判据：累计通过第一层 5 次后，第二层条件通关率（滑窗 10 局）——带未定（只测不判）（触发时注入 = 生命+3/攻击+2/护甲+0，表值平移 +24.0 点——带重锚后随平移判）
|
||||
- 判据：累计通过第二层 5 次后，第三层条件通关率（滑窗 10 局）——带未定（只测不判）（触发时注入 = 生命+6/攻击+3/护甲+2，表值平移 +41.0 点——带重锚后随平移判）
|
||||
|
||||
| 局 | 注入(flat) | 钥石 | 第1层率(窗) | 第2层率(窗) | 第3层率(窗) | 终局 |
|
||||
|--------|--------------|------|-------------|-------------|-------------|-----------|
|
||||
| 第1局 | 血0/攻0/甲0 | 15 | 100%(n=1) | 0%(n=1) | — | 止步第2层 |
|
||||
| 第4局 | 血0/攻2/甲0 | 16 | 100%(n=4) | 25%(n=4) | — | 止步第2层 |
|
||||
| 第7局 | 血3/攻2/甲0 | 11 | 100%(n=7) | 29%(n=7) | 0%(n=2) | 止步第3层 |
|
||||
| 第10局 | 血6/攻2/甲1 | 3 | 100%(n=10) | 40%(n=10) | 0%(n=4) | 止步第3层 |
|
||||
| 第13局 | 血6/攻3/甲2 | 7 | 100%(n=10) | 50%(n=10) | 17%(n=6) | 通关 |
|
||||
| 第16局 | 血9/攻3/甲2 | 7 | 100%(n=10) | 60%(n=10) | 14%(n=7) | 止步第3层 |
|
||||
| 第19局 | 血9/攻4/甲3 | 48 | 100%(n=10) | 70%(n=10) | 40%(n=10) | 通关 |
|
||||
| 第22局 | 血12/攻4/甲3 | 63 | 100%(n=10) | 80%(n=10) | 50%(n=10) | 止步第3层 |
|
||||
| 第25局 | 血12/攻4/甲4 | 78 | 100%(n=10) | 100%(n=10) | 50%(n=10) | 止步第3层 |
|
||||
| 第28局 | 血12/攻5/甲4 | 86 | 100%(n=10) | 100%(n=10) | 60%(n=10) | 通关 |
|
||||
| 第31局 | 血15/攻5/甲4 | 81 | 100%(n=10) | 100%(n=10) | 60%(n=10) | 通关 |
|
||||
| 第34局 | 血15/攻5/甲5 | 89 | 100%(n=10) | 100%(n=10) | 80%(n=10) | 通关 |
|
||||
| 第37局 | 血15/攻6/甲5 | 47 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第40局 | 血15/攻6/甲5 | 5 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第43局 | 血18/攻6/甲5 | 100 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 止步第3层 |
|
||||
| 第46局 | 血18/攻6/甲6 | 58 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第49局 | 血18/攻6/甲6 | 166 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第52局 | 血18/攻7/甲6 | 49 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第55局 | 血18/攻7/甲6 | 157 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第58局 | 血21/攻7/甲6 | 40 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
|
||||
### 普通档 · 护甲优先（60 局战役）
|
||||
|
||||
- 钥石：全程入账 1145 · 终态余额 59 · 锻造终态 = 生命+18/攻击+5/护甲+6
|
||||
- 道具工坊解锁时点（魔法道具面，局内效果未实装只报不判）：显影尘 第 3 局、工兵令 第 3 局、探宝罗盘 第 5 局、探巢摆钟 第 5 局、地穴全图卷 第 6 局、爆破工兵包 第 6 局
|
||||
|
||||
- 判据：累计通过第一层 5 次后，第二层条件通关率（滑窗 10 局）——带未定（只测不判）（触发时注入 = 生命+3/攻击+0/护甲+1，表值平移 +7.0 点——带重锚后随平移判）
|
||||
- 判据：累计通过第二层 5 次后，第三层条件通关率（滑窗 10 局）——带未定（只测不判）（触发时注入 = 生命+9/攻击+3/护甲+3，表值平移 +48.0 点——带重锚后随平移判）
|
||||
|
||||
| 局 | 注入(flat) | 钥石 | 第1层率(窗) | 第2层率(窗) | 第3层率(窗) | 终局 |
|
||||
|--------|--------------|------|-------------|-------------|-------------|-----------|
|
||||
| 第1局 | 血0/攻0/甲0 | 0 | 0%(n=1) | — | — | 止步第1层 |
|
||||
| 第4局 | 血0/攻0/甲0 | 15 | 25%(n=4) | — | — | 止步第1层 |
|
||||
| 第7局 | 血0/攻0/甲1 | 17 | 43%(n=7) | — | — | 止步第1层 |
|
||||
| 第10局 | 血0/攻0/甲1 | 8 | 40%(n=10) | 0%(n=4) | — | 止步第2层 |
|
||||
| 第13局 | 血3/攻0/甲1 | 8 | 30%(n=10) | — | — | 止步第1层 |
|
||||
| 第16局 | 血3/攻0/甲1 | 19 | 20%(n=10) | — | — | 止步第1层 |
|
||||
| 第19局 | 血3/攻0/甲2 | 11 | 40%(n=10) | — | — | 止步第1层 |
|
||||
| 第22局 | 血3/攻1/甲2 | 13 | 50%(n=10) | 0%(n=9) | — | 止步第2层 |
|
||||
| 第25局 | 血3/攻1/甲3 | 12 | 60%(n=10) | 20%(n=10) | 50%(n=2) | 止步第3层 |
|
||||
| 第28局 | 血6/攻2/甲3 | 27 | 70%(n=10) | 30%(n=10) | 33%(n=3) | 止步第3层 |
|
||||
| 第31局 | 血9/攻2/甲3 | 40 | 90%(n=10) | 40%(n=10) | 50%(n=4) | 通关 |
|
||||
| 第34局 | 血9/攻3/甲3 | 40 | 100%(n=10) | 40%(n=10) | 40%(n=5) | 止步第3层 |
|
||||
| 第37局 | 血9/攻3/甲4 | 55 | 100%(n=10) | 60%(n=10) | 38%(n=8) | 止步第3层 |
|
||||
| 第40局 | 血12/攻3/甲4 | 16 | 100%(n=10) | 80%(n=10) | 40%(n=10) | 止步第3层 |
|
||||
| 第43局 | 血12/攻4/甲4 | 99 | 100%(n=10) | 90%(n=10) | 60%(n=10) | 通关 |
|
||||
| 第46局 | 血12/攻4/甲5 | 94 | 100%(n=10) | 90%(n=10) | 70%(n=10) | 止步第3层 |
|
||||
| 第49局 | 血15/攻4/甲5 | 2 | 100%(n=10) | 90%(n=10) | 80%(n=10) | 通关 |
|
||||
| 第52局 | 血15/攻5/甲5 | 97 | 100%(n=10) | 100%(n=10) | 80%(n=10) | 止步第3层 |
|
||||
| 第55局 | 血15/攻5/甲6 | 42 | 100%(n=10) | 100%(n=10) | 70%(n=10) | 止步第3层 |
|
||||
| 第58局 | 血15/攻5/甲6 | 0 | 100%(n=10) | 100%(n=10) | 80%(n=10) | 通关 |
|
||||
|
||||
### 完美档 · 护甲优先（60 局战役）
|
||||
|
||||
- 钥石：全程入账 1674 · 终态余额 213 · 锻造终态 = 生命+18/攻击+6/护甲+7
|
||||
- 道具工坊解锁时点（魔法道具面，局内效果未实装只报不判）：显影尘 第 1 局、工兵令 第 1 局、探宝罗盘 第 2 局、探巢摆钟 第 2 局、地穴全图卷 第 3 局、爆破工兵包 第 3 局
|
||||
|
||||
- 判据：累计通过第一层 5 次后，第二层条件通关率（滑窗 10 局）——带未定（只测不判）（触发时注入 = 生命+3/攻击+0/护甲+2，表值平移 +8.0 点——带重锚后随平移判）
|
||||
- 判据：累计通过第二层 5 次后，第三层条件通关率（滑窗 10 局）——带未定（只测不判）（触发时注入 = 生命+9/攻击+3/护甲+3，表值平移 +48.0 点——带重锚后随平移判）
|
||||
|
||||
| 局 | 注入(flat) | 钥石 | 第1层率(窗) | 第2层率(窗) | 第3层率(窗) | 终局 |
|
||||
|--------|--------------|------|-------------|-------------|-------------|-----------|
|
||||
| 第1局 | 血0/攻0/甲0 | 15 | 100%(n=1) | 0%(n=1) | — | 止步第2层 |
|
||||
| 第4局 | 血0/攻0/甲1 | 8 | 100%(n=4) | 0%(n=4) | — | 止步第2层 |
|
||||
| 第7局 | 血3/攻0/甲2 | 9 | 100%(n=7) | 14%(n=7) | — | 止步第2层 |
|
||||
| 第10局 | 血6/攻1/甲2 | 12 | 100%(n=10) | 10%(n=10) | — | 止步第2层 |
|
||||
| 第13局 | 血6/攻2/甲2 | 16 | 100%(n=10) | 30%(n=10) | 33%(n=3) | 通关 |
|
||||
| 第16局 | 血6/攻2/甲3 | 4 | 100%(n=10) | 20%(n=10) | — | 止步第2层 |
|
||||
| 第19局 | 血9/攻3/甲3 | 41 | 100%(n=10) | 50%(n=10) | 33%(n=6) | 通关 |
|
||||
| 第22局 | 血9/攻3/甲4 | 44 | 100%(n=10) | 60%(n=10) | 38%(n=8) | 止步第3层 |
|
||||
| 第25局 | 血12/攻3/甲4 | 46 | 100%(n=10) | 80%(n=10) | 30%(n=10) | 止步第3层 |
|
||||
| 第28局 | 血12/攻4/甲4 | 87 | 100%(n=10) | 90%(n=10) | 50%(n=10) | 通关 |
|
||||
| 第31局 | 血12/攻4/甲5 | 82 | 100%(n=10) | 100%(n=10) | 50%(n=10) | 通关 |
|
||||
| 第34局 | 血15/攻4/甲5 | 65 | 100%(n=10) | 90%(n=10) | 70%(n=10) | 通关 |
|
||||
| 第37局 | 血15/攻5/甲5 | 73 | 100%(n=10) | 90%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第40局 | 血15/攻5/甲5 | 31 | 100%(n=10) | 90%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第43局 | 血15/攻5/甲6 | 126 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 止步第3层 |
|
||||
| 第46局 | 血18/攻5/甲6 | 84 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第49局 | 血18/攻6/甲6 | 42 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第52局 | 血18/攻6/甲6 | 150 | 100%(n=10) | 100%(n=10) | 90%(n=10) | 通关 |
|
||||
| 第55局 | 血18/攻6/甲6 | 33 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
| 第58局 | 血18/攻6/甲7 | 141 | 100%(n=10) | 100%(n=10) | 100%(n=10) | 通关 |
|
||||
|
||||
## ④ 换算率标定（OFAT 注入档 vs 白板，同种子配对逐关条件通关率差）
|
||||
|
||||
### 生命上限（每级 flat +3）
|
||||
|
||||
| 注入档 | 画像 | 层 | 配对局数 | 条件率 白板→档 | 差(点) | 折每级(点/级) |
|
||||
|------------|--------|--------|----------|----------------|-------------|---------------|
|
||||
| +3（1 级） | 普通档 | 第一层 | 100 | 53.0→60.0 | +7.0 ±2.6 | +7.0 ±2.6 |
|
||||
| +3（1 级） | 普通档 | 第二层 | 100 | 1.9→6.7 | +4.8 ±2.8 | +4.8 ±2.8 |
|
||||
| +3（1 级） | 普通档 | 第三层 | 100 | 0.0→25.0 | +25.0 ±18.4 | +25.0 ±18.4 |
|
||||
| +3（1 级） | 完美档 | 第一层 | 100 | 86.0→90.0 | +4.0 ±2.0 | +4.0 ±2.0 |
|
||||
| +3（1 级） | 完美档 | 第二层 | 100 | 17.4→26.7 | +9.2 ±3.2 | +9.2 ±3.2 |
|
||||
| +3（1 级） | 完美档 | 第三层 | 100 | 0.0→12.5 | +12.5 ±6.7 | +12.5 ±6.7 |
|
||||
| +6（2 级） | 普通档 | 第一层 | 100 | 53.0→65.0 | +12.0 ±3.2 | +6.0 ±1.6 |
|
||||
| +6（2 级） | 普通档 | 第二层 | 100 | 1.9→20.0 | +18.1 ±4.9 | +9.1 ±2.4 |
|
||||
| +6（2 级） | 普通档 | 第三层 | 100 | 0.0→7.7 | +7.7 ±7.1 | +3.8 ±3.6 |
|
||||
| +6（2 级） | 完美档 | 第一层 | 100 | 86.0→94.0 | +8.0 ±2.7 | +4.0 ±1.3 |
|
||||
| +6（2 级） | 完美档 | 第二层 | 100 | 17.4→34.0 | +16.6 ±3.9 | +8.3 ±2.0 |
|
||||
| +6（2 级） | 完美档 | 第三层 | 100 | 0.0→18.8 | +18.8 ±7.1 | +9.4 ±3.5 |
|
||||
|
||||
### 基础攻击（每级 flat +1）
|
||||
|
||||
| 注入档 | 画像 | 层 | 配对局数 | 条件率 白板→档 | 差(点) | 折每级(点/级) |
|
||||
|------------|--------|--------|----------|----------------|-------------|---------------|
|
||||
| +1（1 级） | 普通档 | 第一层 | 100 | 53.0→68.0 | +15.0 ±3.9 | +15.0 ±3.9 |
|
||||
| +1（1 级） | 普通档 | 第二层 | 100 | 1.9→16.2 | +14.3 ±4.3 | +14.3 ±4.3 |
|
||||
| +1（1 级） | 普通档 | 第三层 | 100 | 0.0→18.2 | +18.2 ±11.5 | +18.2 ±11.5 |
|
||||
| +1（1 级） | 完美档 | 第一层 | 100 | 86.0→88.0 | +2.0 ±2.8 | +2.0 ±2.8 |
|
||||
| +1（1 级） | 完美档 | 第二层 | 100 | 17.4→30.7 | +13.2 ±4.5 | +13.2 ±4.5 |
|
||||
| +1（1 级） | 完美档 | 第三层 | 100 | 0.0→22.2 | +22.2 ±8.2 | +22.2 ±8.2 |
|
||||
| +2（2 级） | 普通档 | 第一层 | 100 | 53.0→84.0 | +31.0 ±4.8 | +15.5 ±2.4 |
|
||||
| +2（2 级） | 普通档 | 第二层 | 100 | 1.9→21.4 | +19.5 ±4.4 | +9.8 ±2.2 |
|
||||
| +2（2 级） | 普通档 | 第三层 | 100 | 0.0→16.7 | +16.7 ±8.6 | +8.3 ±4.3 |
|
||||
| +2（2 级） | 完美档 | 第一层 | 100 | 86.0→95.0 | +9.0 ±2.8 | +4.5 ±1.4 |
|
||||
| +2（2 级） | 完美档 | 第二层 | 100 | 17.4→40.0 | +22.6 ±4.8 | +11.3 ±2.4 |
|
||||
| +2（2 级） | 完美档 | 第三层 | 100 | 0.0→18.4 | +18.4 ±6.2 | +9.2 ±3.1 |
|
||||
|
||||
### 护甲等级（每级 flat +1）
|
||||
|
||||
| 注入档 | 画像 | 层 | 配对局数 | 条件率 白板→档 | 差(点) | 折每级(点/级) |
|
||||
|------------|--------|--------|----------|----------------|-----------|---------------|
|
||||
| +1（1 级） | 普通档 | 第一层 | 100 | 53.0→53.0 | +0.0 ±0.0 | +0.0 |
|
||||
| +1（1 级） | 普通档 | 第二层 | 100 | 1.9→1.9 | +0.0 ±0.0 | +0.0 |
|
||||
| +1（1 级） | 普通档 | 第三层 | 100 | 0.0→0.0 | +0.0 ±0.0 | +0.0 |
|
||||
| +1（1 级） | 完美档 | 第一层 | 100 | 86.0→89.0 | +3.0 ±1.7 | +3.0 ±1.7 |
|
||||
| +1（1 级） | 完美档 | 第二层 | 100 | 17.4→18.0 | +0.5 ±1.2 | +0.5 ±1.2 |
|
||||
| +1（1 级） | 完美档 | 第三层 | 100 | 0.0→0.0 | +0.0 ±0.0 | +0.0 |
|
||||
| +2（2 级） | 普通档 | 第一层 | 100 | 53.0→55.0 | +2.0 ±1.4 | +1.0 ±0.7 |
|
||||
| +2（2 级） | 普通档 | 第二层 | 100 | 1.9→3.6 | +1.7 ±1.8 | +0.9 ±0.9 |
|
||||
| +2（2 级） | 普通档 | 第三层 | 100 | 0.0→0.0 | +0.0 ±0.0 | +0.0 |
|
||||
| +2（2 级） | 完美档 | 第一层 | 100 | 86.0→89.0 | +3.0 ±1.7 | +1.5 ±0.9 |
|
||||
| +2（2 级） | 完美档 | 第二层 | 100 | 17.4→20.2 | +2.8 ±2.0 | +1.4 ±1.0 |
|
||||
| +2（2 级） | 完美档 | 第三层 | 100 | 0.0→0.0 | +0.0 ±0.0 | +0.0 |
|
||||
|
||||
### 三行汇总与建议投值
|
||||
|
||||
| 属性 | 现行表值(点/级) | 实测每级(点/级, 合并) | 建议投值 | 状态 |
|
||||
|----------|-----------------|-----------------------|----------|--------------|
|
||||
| 生命上限 | 6 | +6.0 ±0.7 | 6 | 与表值一致 ✓ |
|
||||
| 基础攻击 | 9 | +8.8 ±0.8 | 9 | 与表值一致 ✓ |
|
||||
| 护甲等级 | 1 | +1.2 ±0.4 | 1 | 与表值一致 ✓ |
|
||||
- 折算语义：每级该属性强化 ≈ 通关率带平移量（百分点）——配对同种子读数，护甲行即解锁后实测（强条目）
|
||||
- 合并口径：逆方差加权跨（档位×画像×层，配对 bootstrap SE）；带平移为线性单值近似——近带顶/带底的读数受天花板压缩，判读看 ④ 明细表
|
||||
@@ -0,0 +1,39 @@
|
||||
#!/bin/bash
|
||||
# 换算率标定批·全量采集脚本（2026-09-23）
|
||||
# 10 次采集顺序执行：7 个 OFAT 注入档直入口（n=100×双画像×两层，同 seed0 配对）
|
||||
# + 3 个花费序战役（k=60×双画像）。产物 = production/qa/conversion-calibration/ 下
|
||||
# 各档 .log/.vjson + 合并 calibration.raw.jsonl（判定端 --from-raw 消费）。
|
||||
set -u
|
||||
GODOT=/d/code/godot/Godot_v4.7.2-stable_win64_console.exe
|
||||
SLICE=/d/code/g-plan2-conversion-calibration/game
|
||||
QA=/d/code/g-plan2-conversion-calibration/production/qa/conversion-calibration
|
||||
mkdir -p "$QA"
|
||||
cd "$SLICE" || exit 1
|
||||
|
||||
run() {
|
||||
local name=$1; shift
|
||||
local t0=$(date +%s)
|
||||
"$GODOT" --headless --path . --script res://smoke/verifier_batch.gd -- "$@" > "$QA/$name.log" 2>&1
|
||||
local rc=$?
|
||||
grep '^VJSON ' "$QA/$name.log" > "$QA/$name.vjson"
|
||||
local rows=$(wc -l < "$QA/$name.vjson")
|
||||
local errs=$(grep -cE 'SCRIPT ERROR|Parse Error' "$QA/$name.log")
|
||||
echo "[$(date +%H:%M:%S)] done $name rc=$rc rows=$rows errs=$errs $(( $(date +%s) - t0 ))s"
|
||||
}
|
||||
|
||||
echo "=== 换算率标定采集开跑 $(date +%F' '%H:%M:%S) ==="
|
||||
run base n=100 levels=1,2 only=level seed0=8000
|
||||
run hp3 n=100 levels=1,2 only=level seed0=8000 inject=max_hp:3
|
||||
run hp6 n=100 levels=1,2 only=level seed0=8000 inject=max_hp:6
|
||||
run atk1 n=100 levels=1,2 only=level seed0=8000 inject=atk:1
|
||||
run atk2 n=100 levels=1,2 only=level seed0=8000 inject=atk:2
|
||||
run ac1 n=100 levels=1,2 only=level seed0=8000 inject=armor_class:1
|
||||
run ac2 n=100 levels=1,2 only=level seed0=8000 inject=armor_class:2
|
||||
run camp_hp k=60 only=campaign seed0=8000 spend=hp_first
|
||||
run camp_atk k=60 only=campaign seed0=8000 spend=atk_first
|
||||
run camp_ac k=60 only=campaign seed0=8000 spend=armor_first
|
||||
|
||||
cat "$QA"/base.vjson "$QA"/hp3.vjson "$QA"/hp6.vjson "$QA"/atk1.vjson "$QA"/atk2.vjson \
|
||||
"$QA"/ac1.vjson "$QA"/ac2.vjson "$QA"/camp_hp.vjson "$QA"/camp_atk.vjson "$QA"/camp_ac.vjson \
|
||||
| sed 's/^VJSON //' > "$QA/calibration.raw.jsonl"
|
||||
echo "=== 合并完成：$(wc -l < "$QA/calibration.raw.jsonl") 局 → $QA/calibration.raw.jsonl ==="
|
||||
@@ -0,0 +1,40 @@
|
||||
#!/bin/bash
|
||||
# 换算率标定批·新口径重测采集脚本（2026-09-23）
|
||||
# 前提：单关直入口口径退役 + 冒险条件口径生效 + L2 收紧/关间大奖励 10→5 已落 master——
|
||||
# 首轮（直入口面、旧数值）读数作废，本脚本在冒险条件口径上全量重测。
|
||||
# 10 次采集顺序执行：白板 + 6 个 OFAT 注入档冒险（na=100×双画像，同 seed0 配对）
|
||||
# + 3 个花费序战役（k=60×双画像）。产物合并 calibration.raw.jsonl（判定端 --from-raw 消费）。
|
||||
set -u
|
||||
GODOT=/d/code/godot/Godot_v4.7.2-stable_win64_console.exe
|
||||
SLICE=/d/code/g-plan2-conversion-calibration/game
|
||||
QA=/d/code/g-plan2-conversion-calibration/production/qa/conversion-calibration
|
||||
mkdir -p "$QA"
|
||||
cd "$SLICE" || exit 1
|
||||
|
||||
run() {
|
||||
local name=$1; shift
|
||||
local t0=$(date +%s)
|
||||
"$GODOT" --headless --path . --script res://smoke/verifier_batch.gd -- "$@" > "$QA/$name.log" 2>&1
|
||||
local rc=$?
|
||||
grep '^VJSON ' "$QA/$name.log" > "$QA/$name.vjson"
|
||||
local rows=$(wc -l < "$QA/$name.vjson")
|
||||
local errs=$(grep -cE 'SCRIPT ERROR|Parse Error' "$QA/$name.log")
|
||||
echo "[$(date +%H:%M:%S)] done $name rc=$rc rows=$rows errs=$errs $(( $(date +%s) - t0 ))s"
|
||||
}
|
||||
|
||||
echo "=== 新口径重测开跑 $(date +%F' '%H:%M:%S) ==="
|
||||
run adv_base na=100 only=adventure seed0=8000
|
||||
run adv_hp3 na=100 only=adventure seed0=8000 inject=max_hp:3
|
||||
run adv_hp6 na=100 only=adventure seed0=8000 inject=max_hp:6
|
||||
run adv_atk1 na=100 only=adventure seed0=8000 inject=atk:1
|
||||
run adv_atk2 na=100 only=adventure seed0=8000 inject=atk:2
|
||||
run adv_ac1 na=100 only=adventure seed0=8000 inject=armor_class:1
|
||||
run adv_ac2 na=100 only=adventure seed0=8000 inject=armor_class:2
|
||||
run camp_hp k=60 only=campaign seed0=8000 spend=hp_first
|
||||
run camp_atk k=60 only=campaign seed0=8000 spend=atk_first
|
||||
run camp_ac k=60 only=campaign seed0=8000 spend=armor_first
|
||||
|
||||
cat "$QA"/adv_base.vjson "$QA"/adv_hp3.vjson "$QA"/adv_hp6.vjson "$QA"/adv_atk1.vjson "$QA"/adv_atk2.vjson \
|
||||
"$QA"/adv_ac1.vjson "$QA"/adv_ac2.vjson "$QA"/camp_hp.vjson "$QA"/camp_atk.vjson "$QA"/camp_ac.vjson \
|
||||
| sed 's/^VJSON //' > "$QA/calibration.raw.jsonl"
|
||||
echo "=== 合并完成：$(wc -l < "$QA/calibration.raw.jsonl") 局 → $QA/calibration.raw.jsonl ==="
|
||||
@@ -0,0 +1,33 @@
|
||||
#!/bin/bash
|
||||
# 换算率标定批·修复后重采（2026-09-23）
|
||||
# _defender_ac 护甲断链接线修复后，护甲注入两档与三条战役轨迹（甲轴购买后段生效）需重采；
|
||||
# base/hp3/hp6/atk1/atk2 五档注入甲=0、修复逐位不变，沿用首轮产物。
|
||||
set -u
|
||||
GODOT=/d/code/godot/Godot_v4.7.2-stable_win64_console.exe
|
||||
SLICE=/d/code/g-plan2-conversion-calibration/game
|
||||
QA=/d/code/g-plan2-conversion-calibration/production/qa/conversion-calibration
|
||||
mkdir -p "$QA"
|
||||
cd "$SLICE" || exit 1
|
||||
|
||||
run() {
|
||||
local name=$1; shift
|
||||
local t0=$(date +%s)
|
||||
"$GODOT" --headless --path . --script res://smoke/verifier_batch.gd -- "$@" > "$QA/$name.log" 2>&1
|
||||
local rc=$?
|
||||
grep '^VJSON ' "$QA/$name.log" > "$QA/$name.vjson"
|
||||
local rows=$(wc -l < "$QA/$name.vjson")
|
||||
local errs=$(grep -cE 'SCRIPT ERROR|Parse Error' "$QA/$name.log")
|
||||
echo "[$(date +%H:%M:%S)] done $name rc=$rc rows=$rows errs=$errs $(( $(date +%s) - t0 ))s"
|
||||
}
|
||||
|
||||
echo "=== 修复后重采开跑 $(date +%F' '%H:%M:%S) ==="
|
||||
run ac1 n=100 levels=1,2 only=level seed0=8000 inject=armor_class:1
|
||||
run ac2 n=100 levels=1,2 only=level seed0=8000 inject=armor_class:2
|
||||
run camp_hp k=60 only=campaign seed0=8000 spend=hp_first
|
||||
run camp_atk k=60 only=campaign seed0=8000 spend=atk_first
|
||||
run camp_ac k=60 only=campaign seed0=8000 spend=armor_first
|
||||
|
||||
cat "$QA"/base.vjson "$QA"/hp3.vjson "$QA"/hp6.vjson "$QA"/atk1.vjson "$QA"/atk2.vjson \
|
||||
"$QA"/ac1.vjson "$QA"/ac2.vjson "$QA"/camp_hp.vjson "$QA"/camp_atk.vjson "$QA"/camp_ac.vjson \
|
||||
| sed 's/^VJSON //' > "$QA/calibration.raw.jsonl"
|
||||
echo "=== 合并完成：$(wc -l < "$QA/calibration.raw.jsonl") 局 → $QA/calibration.raw.jsonl ==="
|
||||
@@ -0,0 +1,35 @@
|
||||
# MC 重投基线报告（2026-09-20）
|
||||
|
||||
> 触发：主角增益续时批（台账 102）+ 伏击退役/警觉 + 行动点第八型 + 伤害下限 [1,+∞)（台账 100/101）四批行为变更后，验收重测批旧读数全部失效，按「先有数据→再分析→再方案→再决定」流程重投基线。
|
||||
> 工具：`smoke/level_monte_carlo.gd`（本批新增第 6 参 `baseline`——只跑 atk0/hp0 基线格，大样本精度成本可控）。
|
||||
> 口径：N=300/画像/关 · 逐局独立种子（unique，seed0=7000）· R3 随机流 · 双关双画像。±值为 95% 置信区间。
|
||||
|
||||
## 读数
|
||||
|
||||
| 指标 | 第 1 关 | 第 2 关 | 目标带 | 判定 |
|
||||
|---|---|---|---|---|
|
||||
| 完美档通关率 | 55.7%（±5.6） | 39.7%（±5.5） | [35, 65]（不变） | ✅ 双关带内 |
|
||||
| 普通档通关率 | 46.7%（±5.6） | 34.3%（±5.4） | **本批新带 L1 [35,55] / L2 [25,45]** | ✅ 双关带内（旧带 [10,25] 下双越上界） |
|
||||
| 整关承伤均 / p90（普通档） | 15.8 / 21.0 | 13.6 / 20.0 | — | — |
|
||||
| Boss 场承伤%（普通档） | 47.7% | 49.7% | ≤50%（F4） | ✅ 带内贴缘 |
|
||||
| Boss 场承伤%（完美档） | 49.2% | **51.6%** | ≤50%（F4） | ⚠️ L2 带缘微越 1.6 点 |
|
||||
| 平均轮数（完美档） | 14.8 | 11.4 | — | — |
|
||||
|
||||
确定性重放校验：两次独立运行（间隔重跑）通关率逐位一致（47/56/34/40），unique 序列确定性成立。
|
||||
|
||||
## 判读
|
||||
|
||||
1. **完美档通关率双关落带**：改革前 70-100% 越带（mc-scan-2026-09-18、地形变异批 70%/60%）被三批行为变更（地形变异加难、伏击退役+警觉、主角增益削半）合力压回带内。台阶方向理顺（L1 55.7% > L2 39.7%，不再倒挂）。
|
||||
2. **普通档落带靠新带**：旧带 [10,25] 锚定随机点击画像，普通画像换装基础定式后失锚（用户 2026-09-20 拍板分带 L1 [35,55] / L2 [25,45]，推导链 = 真人体验换算：模拟 47%/34% 对应真人新手约六成/五成通关率，元进度驱动力保留——新手仍约四成局会输）。
|
||||
3. **残留越带唯一项：L2 完美 Boss 承伤 51.6%**（较地形变异批 55.8% 收敛）。L2 完美档死亡 94% 集中 Boss 战（170/181）——Boss 场仍是第一杠杆位，微调即可入带，归曲线调参批。
|
||||
4. **结构杠杆否决维持**：算术核验（17 血尺度下百分比硬地板 <6% ≡ 平铺下限 1，台账 100 已落 [1,+∞) 下限）+ 通关率落带双重印证——「承伤硬地板」类新机制无立项必要。
|
||||
|
||||
## 逐局死亡分布（完美档）
|
||||
|
||||
- L1：132 败 = 6.boss×85（64%）+ 4.battle×41（31%）+ 3.battle×6
|
||||
- L2：181 败 = 8.boss×170（94%）+ 1.battle×10 + 6.battle×1
|
||||
|
||||
## 工具改动（随批）
|
||||
|
||||
- `level_monte_carlo.gd`：第 6 参 `baseline`（只扫 atk0/hp0 基线格）；脚注 F5 带文字随新带同步。
|
||||
- 旧读数处置：地形变异批读数（普通 43/60、完美 70/60）由本批读数取代；两份 JSONL 日志（playtest_7000_20260920T043531/044638）为本次基线原始数据。
|
||||
@@ -0,0 +1,65 @@
|
||||
# Playtest Report — Dungeon Sweeper 战斗阶段垂直切片
|
||||
|
||||
> 判定：**INCOMPLETE**（两次中断的试玩尝试，定性反馈未采集）· Review mode: lean（CD-PLAYTEST skipped — Lean mode）
|
||||
> 技能：/playtest-report（analyze 模式，原始素材 = 本会话用户反馈 + 崩溃日志 + 仪器数据）
|
||||
|
||||
## Session Info
|
||||
- **Date**: 2026-09-10 ~ 2026-09-11（两次中断的试玩尝试）
|
||||
- **Build**: 垂直切片（拍板①–④落地版：atk=6 先手 / 两级奖励 / 库存关内延续 / 窗口单件）
|
||||
- **Duration**: 未完成一场完整战斗（两次均在循环中途中断）
|
||||
- **Tester**: 用户（设计师本人，唯一测试者）
|
||||
- **Platform**: PC · KB+M
|
||||
- **Session Type**: First time ×2（均为中断重试）
|
||||
|
||||
## Test Focus
|
||||
战斗阶段完整循环：开战 → 挖掘/旗/停手 → 七段结算逐行兑现 → 胜负；含 2026-09-11 新机制（主角先手、即时奖励、库存延续）。
|
||||
|
||||
## First Impressions
|
||||
- **未采集**——两次均未撑到可评估的时长。唯一间接信号：用户问"是否有图像"（程序化色块+文字的观感被注意到，属预期内的占位表现）。
|
||||
|
||||
## Gameplay Flow
|
||||
### What worked well
|
||||
- 核心循环链路本身可走通：挖掘、插旗、结算弹出、道具窗口、关卡过渡（第二场试玩已推进到"胜利→库存/HP 带入下一层"节点才崩溃）。
|
||||
- 结算明细逐行输出正常工作（崩溃均发生在呈现层读数，流水内容无恙）。
|
||||
|
||||
### Pain points
|
||||
- **崩溃 #1（High）**：第一轮结算弹道具窗口即假死——窗口数据缺 `round_index` 字段，弹窗构建崩溃但输入锁已上，游戏无声冻结。用户被迫中止。
|
||||
- **崩溃 #2（High）**：胜利/关卡过渡时再次报错——`battle_finished` 信号发出前 `hero` 已被销毁，UI 读 `hp` 崩溃，结算覆盖层未显示。
|
||||
|
||||
### Confusion points
|
||||
- 用户问"是不是设置了断点"——假死无任何提示，玩家无法区分"卡了"与"在等输入"。（呈现层崩溃静默锁输入 = 设计缺陷级体验问题，不只是代码 bug。）
|
||||
|
||||
### Moments of delight
|
||||
- 未采集。
|
||||
|
||||
## Bugs Encountered
|
||||
| # | 描述 | 严重度 | 可复现 | 状态 |
|
||||
|---|---|---|---|---|
|
||||
| 1 | 道具窗口数据缺 `round_index`，弹窗构建崩溃→输入锁死 | High | 是（固定流程必现） | ✅ 当日修复+字段契约断言入冒烟 |
|
||||
| 2 | `battle_finished` 载荷缺 hero 状态（despawn 先于信号），胜利过渡崩溃 | High | 是（打到胜利必现） | ✅ 当日修复（载荷销毁前捕获）+冒烟适配 |
|
||||
|
||||
**共性根因**：呈现层与核心间"信号载荷/时序"契约未成文；GDScript 编译不查这两类错；冒烟从未执行 main.gd。防复发已登记为 D1 GDD 三条硬性要求（载荷 schema 成文 / 场景级 headless 测试 / 状态可见性规则）。
|
||||
|
||||
## Feature-Specific Feedback
|
||||
### 全部新机制（先手攻击/两级奖励/库存延续/单件窗口）
|
||||
- **未采集**——机制是否"可感受、可归因、有趣"没有任何用户输入。
|
||||
|
||||
## Quantitative Data（注意：来自自动玩家，非人类试玩）
|
||||
- 蒙特卡洛 60 场（30 种子 × L1/L2，理性政策）：胜轮均值 1.80、每轮承伤均值 2.1–2.7（max_hp=50 的 0–16%）、每场恰清图 1 次、败北 0。
|
||||
- 与设计意图冲突：**多轮结算仪式感 / RAP 取舍 / 囤刀时机未获得发生空间**（B4 失衡预警⑥定量坐实）。
|
||||
|
||||
## Overall Assessment
|
||||
- **Would play again**: 未采集（用户实际行为 = 两次遇崩即报，信任受影响——"写代码没检查依赖吗"）
|
||||
- **Difficulty / Pacing**: 未采集（人类视角）；仪器视角 = 过易、过快
|
||||
- **本轮试玩判定：INCOMPLETE**——循环完整性与 P2 归因（"这个结果是我哪步扫雷带来的"）这两个切片核心验证问题均未得到回答
|
||||
|
||||
## Top 3 Priorities
|
||||
1. **修复后完整重跑一次试玩**（当前 build 冒烟 43/43）——采集首轮真正的定性反馈：归因清晰度、结算节奏、新机制手感
|
||||
2. **难度带拍板**（C3 域）：以期望表为靶（期望胜轮带/承伤占比），用 monte_carlo.gd 验算 knob 方案
|
||||
3. **headless UI 冒烟**：真实实例化 main 场景跑完整对局——把"呈现层从未被执行"的盲区关死
|
||||
|
||||
## Action Routing（Phase 3）
|
||||
- Bug ×2：已修复；如需正式追踪 → /bug-report 建档
|
||||
- 平衡项（预警⑥）→ /balance-check + C3 期望表
|
||||
- 设计变更：暂无（人类定性反馈为零）
|
||||
- Polish：占位视觉 → 格子样张测试（art-bible 既有任务）
|
||||
@@ -0,0 +1,93 @@
|
||||
# Playtest Report — Dungeon Sweeper 战斗阶段垂直切片（第 2 次）
|
||||
|
||||
> 判定：**COMPLETE**（首次完整通关的真人局，定性反馈两条，均有遥测坐实）· Review mode: solo（CD-PLAYTEST skipped — Solo mode）
|
||||
> 技能：/playtest-report（analyze 模式，原始素材 = 本会话用户口述 + playtest JSONL 遥测 + 代码/数据核对）
|
||||
|
||||
## Session Info
|
||||
- **Date**: 2026-09-12 20:13（主分析局）；20:41 辅助局（调参面板加成后）
|
||||
- **Build**: 垂直切片 · 2026-09-12 五区改造批 + BUG-0001 修复前；数据 = v3 调参批（enemy.tres 18:05：atk 7/5/9/6/9、Boss 150）
|
||||
- **Duration**: 完整一关（7 节点：battle×2 → reward → battle×2 → rest → boss，12 个结算轮）
|
||||
- **Tester**: 用户（设计师本人，唯一测试者）
|
||||
- **Platform**: PC · Win10 · Godot 4.7.2 · seed 42（固定种子）
|
||||
- **Session Type**: Returning（第 3 次尝试，首次跑通全程——09-11 两局均被崩溃阻断）
|
||||
|
||||
## Test Focus
|
||||
两条旧问题的复核：① 道具获取（治疗稀缺性 / 伤害:治疗 9:1 体感）；② 难度曲线（到 Boss 房前满血）。
|
||||
|
||||
## First Impressions
|
||||
- 未单独采集（用户直接进入两条旧问题反馈）。
|
||||
|
||||
## Gameplay Flow
|
||||
|
||||
### What worked well
|
||||
- **核心循环首次完整走通**：挖掘 → 结算七段 → 道具窗口 → 关卡节点（reward/rest）→ Boss → level_end victory，全程无崩溃。09-11 报告的两个 High 崩溃与 BUG-0001 软锁家族未复现（BUG-0001 修复批 20:23 落地，主分析局在其之前——悬停路径未触发，属幸存而非验证）。
|
||||
- 窗口 usable_now 投影工作正常：满血下治疗包全程禁选（usable_now:false），玩家实际行为 = 连续 skip，机制按设计执行。
|
||||
|
||||
### Pain points
|
||||
- **P1（旧问题②）：全关零承伤**——12 个结算快照 hero hp 恒 50/50，Boss 房前满血、Boss 战后仍满血。对照 C3 F4 目标带（普通场承伤 ≤20%、Boss 场 ≤50%）：实测 0%，越带。详见「根因分析」。
|
||||
- **P2（旧问题①）：治疗包体感过剩**——Boss 战结束时库存 3 件治疗道具 + 已用 1 把小刀；用户体感"9:1 完全反过来"。实现核对结论：**9:1 配比实现正确，体感由三个结构性放大器制造**（见根因分析）。
|
||||
|
||||
### Confusion points
|
||||
- 未采集。
|
||||
|
||||
### Moments of delight
|
||||
- 未采集。
|
||||
|
||||
## Bugs Encountered
|
||||
| # | 描述 | 严重度 | 可复现 | 状态 |
|
||||
|---|---|---|---|---|
|
||||
| 1 | **浅深度战斗零敌人**：两场真人局中 d0 战斗（20:13 还含 d1）`unit_count=0`、round 1 即 victory——遭遇骰/spawn 路径疑似缺陷（C3 Rule 8 区间 [unit_count, unit_count_max] 最小值 1，不应掷出 0） | Medium | 两次真人局均现（d0 100%） | 待查——建议 /bug-report 建档 |
|
||||
| 2 | **Boss 攻击拍零兑现**：ogre_chief（pattern [attack, attack, charge, heavy]）在两局中共 7 个存活结算轮，快照 beat 轮转正常（advance 在跑）但英雄血量纹丝不动——攻击链对该敌未生效（普通敌在 20:41 局 fresh 池轮正常承伤：d1 r1 −34、d3 r1 −9， ambush 乘区算术精确吻合） | High | 两局均现 | 待查——与下条根因共用一个探针 |
|
||||
| 3 | （轻微）`grant_node_active` 直调 stock、不经 `_supply.notify_granted()`——节点奖励完全绕开供给控制器计数，关卡级供给总量失控的结构性漏洞之一 | Low | 结构性 | 待登记 |
|
||||
|
||||
## 根因分析（本次报告核心增量）
|
||||
|
||||
### 问题②难度：v3 调参为何无效
|
||||
- **防御墙机制**：defense_up = stack 策略 × magnitude −50 × max_stack 2，池 clamp [−100, +100]（settlement.tres）→ **同轮叠两层 = 100% 免伤**。它在**授予段生效、先于战斗段**——当轮挖到的减伤当轮即全额兑现。
|
||||
- defense_up 权重 24/75 = 安全格池**最高**单行（32%/grant），每轮 7–14 安全格 × ~44% 授予率 ≈ 3–6 次 grant → 单轮叠满两层的概率常在 25–50% 区间；20:13 主分析局 12/12 轮零承伤。
|
||||
- **结论**：v3 批选的主杠杆"atk +50%"是**乘在 ×0 上的调参**——墙不拆，任何 atk 曲线都无效。C3 F4 的 E[减伤] 估算（0.44 × 50% ≈ 22%）严重低估了 stack-to-clamp 的实际行为（实测 ≈100%）。
|
||||
- **未闭合点**：20:41 辅助局 fresh 池轮普通敌正常承伤（−34/−9 精确吻合 ambush 算术），但 Boss 轮 fresh 池仍零承伤——"防御墙"与"Boss 攻击链缺陷"两嫌疑并存，**一次 instrumented headless 探针即可分割**（逐结算行打印 beat/atk.total/pool/d_tick）。
|
||||
|
||||
### 问题①道具获取：9:1 没有反，但体感是真的
|
||||
- **配比核对（三路径全部正确）**：active_inject 池 knife_t1 60 / knife_adv 30 / heal_pack 10 = 9:1（reward.tres 89–93 行注释明示"治疗资源宝贵"）；grant_node_active 同池同比；B1 分流正确（即时类当场兑付、道具类入库）。
|
||||
- **本局实测**：4 次可选类获取 = 3 治疗包 + 1 小刀（Boss r6 用刀后剩 3 治疗包——与用户口述完全吻合）。按 9:1 单次 10% 治疗率，该组合概率 ≈ 0.4%——但 **seed 42 固定**，这条 RNG 轨迹每次重开都原样重放，"反过来"的体感被逐次确认。
|
||||
- **三个结构性放大器**（配比正确也挡不住）：
|
||||
1. **供给量**：09-11 供给控制器批把可选类从格子权重池改为"每战斗首件保证 + 指数递减"——每关 4 战斗 × 首件保证 + 1 奖励节点 + 递减重注 ≈ 4–5 件/关（P(≥1 治疗包) ≈ 40%），且节点奖励绕开控制器（Bug #3）再放大；
|
||||
2. **满血累积**：难度零压力 → heal_pack 永远 usable_now=false → 只进不出堆在库存里，显著度极高；
|
||||
3. **固定种子**：seed 42 让坏抽变成"每次都一样的坏抽"。
|
||||
- **耦合结论**：问题①与问题②**互为放大器**——20:41 辅助局（有承伤）里奖励节点的治疗包在 70/100 时被立即使用。难度修好后治疗包消耗通道自然打开，体感问题预计大半自行消解。
|
||||
|
||||
## Feature-Specific Feedback
|
||||
### 可选类供给控制器（09-11 批）
|
||||
- 机制按设计运转（首件保证/递减/永不绝育均可在遥测中辨认）；但"每战斗"首件保证在 4 战斗关卡结构下的总供给量是否偏离"治疗是稀缺奖励"的原始意图，**归 C3 重新拍板**（候选：首件保证升到关卡域、或 inject 池治疗行单独降权）。
|
||||
|
||||
### 难度（v3 调参批后复测）
|
||||
- 承伤 0% vs 目标带 ≤20%/≤50%：**严重越带**；通关率 100% vs F5 基线带 40–60%：越带。与 enemy.tres v3 注释自认的"难度严重不足"一致——**调参后未复测即判定"已处理"是本问题拖延三轮的直接流程原因**。
|
||||
|
||||
## Quantitative Data（遥测实测，playtest_42_20260912T201317.jsonl）
|
||||
- 12 结算轮 / 7 节点 / level_end victory；hero hp 全程 50/50；ambush_layers 恒 0；buffs[] 恒空。
|
||||
- 敌情：d0/d1 空场；d2 bugbear 40hp（2 轮）；d3 bugbear 18hp（2 轮）；boss ogre 150hp（6 轮，beat 轮转 attack→attack→charge→heavy→attack，兑付伤害 0）。
|
||||
- 输出侧：charge_dmg_a 7–14/轮（快照键现名 charge_counts/charge_points——2026-09-15 两批（命名统一 → 抽象分离）；本行保留当时观测键名），boss 逐轮 −21/−16/−53(含 clear_blast 40)/−16/−24/−20——**英雄输出正常，Boss 3–6 轮内可斩**。
|
||||
- 可选类供给：4 获取（3 heal_pack + 1 knife_t1）/ 1 消耗 / 3 库存残留。
|
||||
- 20:41 辅助局（调参面板 max_hp 100 + atk 加成）：普通敌承伤正常（−34/−9），Boss 仍零承伤；治疗包在缺血时正常消耗。证明消耗通道与攻击链在普通敌上健康，Boss 路径存疑。
|
||||
|
||||
## Overall Assessment
|
||||
- **Would play again**: 未采集（用户两轮即时反馈 = 高关注信号）
|
||||
- **Difficulty**: 严重不足（0% 承伤，越带）——**非数值问题，机制性免伤墙 + 疑似 Boss 攻击缺陷**
|
||||
- **Pacing**: Boss 战 6 轮偏拖（输出侧正常但无压力回报）
|
||||
- **本轮判定：COMPLETE**——两个旧问题本轮均拿到机理级解释，不再停留在"感觉不对"
|
||||
|
||||
## Top 3 Priorities
|
||||
1. **一次 instrumented 探针分割零承伤根因**：headless 逐结算行打印 beat / atk.total / hero_defense 池值 / d_tick——区分"defense_up 叠满墙"（设计变更）与"Boss/敌攻击链缺陷"（bug 修复）。**这是两问题的共同前置。**
|
||||
2. **拆墙后重调难度带**：多种子 level_monte_carlo 对 C3 F4/F5 期望表复算（承伤 ≤20%/≤50%、通关率 40–60%），禁止单种子判定；v3 的 atk 值此时才第一次真正参与计算。
|
||||
3. **供给量重拍板 + 节点奖励纳入控制器**：C3 裁决"每战斗首件保证"的总量语义（候选：关卡域首件）；grant_node_active 补 notify_granted 上报；评估用种子轮换（seed 42 单轨迹不能作为平衡证据）。
|
||||
|
||||
## Action Routing（Phase 3）
|
||||
- **设计变更**（防御墙语义：stack×2→clamp −100 = 免伤；候选改法：clamp 收紧至 −60/−70、乘法衰减、重击拍穿防）→ `/propagate-design-change design/gdd/b3-status-effect.md`（连带 B1 池 clamp 语义 + C3 F4 估算式修正）
|
||||
- **平衡调整**（墙拆除后：atk 曲线/Boss hp/供给量对 F4/F5 期望表复算）→ `/balance-check`
|
||||
- **Bug**（浅深度空遭遇 #1；Boss 攻击零兑现 #2；节点奖励绕过供给计数 #3）→ `/bug-report` 正式建档
|
||||
- **Polish/观测**：治疗包满血堆积的呈现（现有 usable_now 禁选已正确，难度修复后观测残留量）→ 记入失衡预警②仪表（短缺半）
|
||||
|
||||
## 与既往报告的追踪关系
|
||||
- playtest-2026-09-11（INCOMPLETE）：Top2"难度带拍板"→ v3 批（09-12 18:05）只调了 atk、**未复测**→ 本轮证实无效 + 根因前置（防御墙）。状态：**未解决，根因收窄**。
|
||||
- 治疗稀缺化（09-11 两级奖励批）：配比 6%→inject 池 10%（9:1）**实现正确**；本轮体感失效根因 = 供给量 + 满血累积 + 固定种子，非配比。状态：**配比已解决，体感未解决，路径已明确**。
|
||||
@@ -0,0 +1,65 @@
|
||||
# Architecture Registry — Dungeon Sweeper
|
||||
# 生成：2026-09-12（/architecture-decision solo 批：ADR-0001~0004；用户授权代决）
|
||||
# 规则：只增不改；立场变更 = 旧条目标 status: superseded_by + 新增条目（永改既有条目）
|
||||
# 命名注记（2026-09-15）：A1–D6 系统代号已清偿为中文规范名（对照表见 design/gdd/02-系统清单.md）；interfaces 两条目键名同批改领域命名（a2_event_surface→minesweeper_event_surface、b1_settlement_trigger→settlement_trigger）。
|
||||
# 设计层立场（状态归属/接口契约/锚验收）登记在 design/registry/entities.yaml——本文件只登记实现级架构立场
|
||||
|
||||
interfaces:
|
||||
- name: minesweeper_event_surface
|
||||
adr: ADR-0001
|
||||
signals: [cell_revealed, flag_judged, round_end_board]
|
||||
note: GDD 概念名 round_end 的 排雷玩法 实现实名 = round_end_board；行动经济 直发 = round_end_stopped（payload 同构）
|
||||
- name: settlement_trigger
|
||||
adr: ADR-0001
|
||||
contract: 战斗结算 订阅 行动经济 相位→Waiting 触发结算；只读 last_round_end + 相位观测量；不依赖事件到达序
|
||||
- name: presentation_subscription_rule
|
||||
adr: ADR-0001
|
||||
contract: 呈现层永不直接订阅 排雷玩法/行动经济——只订 战斗结算 步骤流 / level_runner（切片缺陷②教训固化）
|
||||
|
||||
api_decisions:
|
||||
- name: renderer
|
||||
adr: ADR-0002
|
||||
decision: gl_compatibility（Forward+ 否决——D3D12 新驱动线降险；战斗表现 出现 HDR 2D 需求时复议）
|
||||
- name: window_base
|
||||
adr: ADR-0002
|
||||
decision: 1280×800 基座 + stretch canvas_items + aspect expand（全部键显式落盘，防引擎默认漂移）
|
||||
- name: autoload_set
|
||||
adr: ADR-0003
|
||||
decision: 仅 {ConfigDB, RngService}（定名锁定）；战斗编排器等核心类由组合根按局实例化，非 autoload
|
||||
- name: board_rendering
|
||||
adr: ADR-0003
|
||||
decision: MVP 沿用切片 GridContainer + 逐格控件形态（探针耦合事实）；_draw() 迁移 = HUD框架 正式化候选工作项（含三探针改造 + push_input 端到端探针 + 命中测试自建）
|
||||
- name: cjk_font
|
||||
adr: ADR-0003
|
||||
decision: CJK 字体随包发行并设 theme 默认字体（运行时默认字体无 CJK 字形）——HUD框架 正式化硬性前置 + 导出 checklist 项
|
||||
- name: test_carrier
|
||||
adr: ADR-0004
|
||||
decision: 双载体（--headless --script 逻辑冒烟 + headless 场景探针）+ 静态扫描域 S1–S8 + CI 外部 wall-clock 超时；gdUnit4 deferred（数据配置 OQ1 关闭形态）
|
||||
- name: save_contract
|
||||
adr: ADR-0005
|
||||
decision: SCHEMA_VERSION 比较逻辑归 存档序列化（存档版本 > 当前 = 拒读）；RNG 快照 = master_seed + 各流 scope 计数器 + 意图/窗口选择序列，切出须在 scope 事件边界外（无在飞 open_stream 实例——战斗结算 编排保证）
|
||||
|
||||
forbidden_patterns:
|
||||
- pattern: autoload_global_event_bus
|
||||
adr: ADR-0001
|
||||
detail: 否决中心事件总线——组合根直连 signal 接线
|
||||
- pattern: lambda_capture_self_cross_lifetime
|
||||
adr: ADR-0001
|
||||
detail: core↔core 信号连接只许方法 Callable；发射者禁持有订阅者反向引用（防循环引用/生命周期延长）
|
||||
- pattern: bare_autoload_global_identifier_in_core
|
||||
adr: ADR-0004
|
||||
detail: core/ 禁裸引用 ConfigDB/RngService 全局标识符（--script 模式不注册——parse error；构造注入 only）
|
||||
- pattern: global_rand_functions_in_gameplay
|
||||
adr: ADR-0004
|
||||
detail: randi()/randf()/randf_range() 与 randomize() 同禁（全局 RNG 绕开 RngService——数据配置 Rule 5 补全）
|
||||
- pattern: core_extends_control_or_tscn_preload
|
||||
adr: ADR-0004
|
||||
detail: core/ 禁 extends Control/Node2D、禁 .tscn preload（数据配置 Rule 7）
|
||||
- pattern: second_caller_of_battle_domain_apis
|
||||
adr: ADR-0004
|
||||
detail: 敌人系统/增益状态/地图战斗资源 战斗域 API 唯一调用方 = 战斗结算；排雷玩法/增益状态/地图战斗资源 零相互直调（静态扫描 S7——战斗结算 AC-43）
|
||||
|
||||
- name: hero_override_parameter_passing
|
||||
adr: ADR-0009（候选——切片机制正式化批）
|
||||
decision: 主角加成值经 encounter 显式参数传入（begin_battle 增 hero_atk/hero_max_hp 字段；敌人系统.spawn 增 atk_override/max_hp_override 参数，-1 = 表值兜底）——db.hero 表值运行期只读（切片原表写通道 _apply_hero_override/runner 写表废除）
|
||||
note: 2026-09-13 E4 收口；接口漂移 = 敌人系统.spawn 签名 +2 参数、战斗结算 encounter +2 字段（正式侧 战斗结算/敌人系统 GDD 修订随 ADR-0009 批）；ui_tune_probe ⑦⑧ 为表不可变 + 单次加成的回归断言载体
|
||||
@@ -0,0 +1,169 @@
|
||||
# AP6+AC 合并批验收判读口径
|
||||
|
||||
> 一句话：行动点压速批（每轮 8→6）与护甲等级批（d20 掷点折扣）合并落地后的验收判读标准——三个数据源（MC 双档 / 真人基线 / 日志分析器）、两段制判读、一条四级调参阶梯。
|
||||
> 状态：**定稿 v1.0（2026-09-16）**——决策点 a–i 经两轮拍板全部落定，记录见 §4；后续修订走版本历史。
|
||||
> 口径裁定前提（2026-09-16 测量口径裁定，已拍板）：蒙特卡洛 normal 档 = 盲挖策略 = "不会扫雷的玩家"下界，不承载难度语义；perfect 档（零盲挖/全标旗）≈ 真人水平，是强度上界。
|
||||
> 本文档独立成文，不改任何既有文件；落批后的登记义务见 §5。
|
||||
|
||||
## 0. 设计前提：基线是生死带，天赋是出路（2026-09-16 用户拍板）
|
||||
|
||||
第一关在**基础数值、零永久天赋加成**时，整关承伤分布必须**跨过主角生命上限（50）**：最坏情况承伤 > 50（会死），最好情况 < 50（能活）——即第一关对零加成的合格玩家有实质失败概率（完美档通关率 gate [35%, 65%]）。玩家经多次循环解锁永久天赋获得属性加成后，承伤范围整体下移、生命上限也可能提高，关卡变得可通。**这个"基线生死带 → 天赋解锁 → 压力回落"的落差，就是驱动循环游玩的困难设限点。**
|
||||
|
||||
工具映射：MC 的 atk%/hp% 网格即模拟天赋加成轴——基线格 atk+0%/hp+0% = 零加成生死带（阶段二主判据格），满配格 atk+100%/hp+100% = 天赋养成后的成人态（F4 舒适带复验格）。
|
||||
|
||||
## 1. 验收前置条件
|
||||
|
||||
全部满足才可开跑。任何一条不满足 = 本批未落批，禁止启动验收；也禁止在 AC 批在飞期间预跑——半成品读数会污染同种子历史可比性。
|
||||
|
||||
| # | 条件 | 判据 |
|
||||
|---|---|---|
|
||||
| 1 | AC 批 smoke 全绿 | `smoke_all.gd` 零失败（AC 批会话交付后执行） |
|
||||
| 2 | 日志分析器可用 | `game/tools/log_analysis.py` 可运行；对 AC 落批日志能激活掷点面（FIELD_CANDIDATES 命中，或按其数据质量观测面补一行字段适配） |
|
||||
| 3 | MC 双档可跑 | `smoke/level_monte_carlo.gd` 以策略 both 跑通零报错；完美档零踩雷构造断言通过 |
|
||||
| 4 | 工作区无半成品 | git status 干净（`core/rng_service.gd` 等在飞改动已收编提交） |
|
||||
|
||||
## 2. 验收运行配置
|
||||
|
||||
三个数据源全部跑完再判读，禁止用单一数据源下结论。
|
||||
|
||||
### 2.1 模拟批（主数据源）
|
||||
|
||||
- 工具：`game/smoke/level_monte_carlo.gd`
|
||||
- 配置：N=30、种子 4200+30（4200–4229，逐局 seed0+i）、策略 both（normal + perfect 双档一次跑齐）——与 2026-09-16 历史坐标同种子同口径。
|
||||
- 阶段一读数格：基线格 atk+0%/hp+0%（零天赋，生死带判据格）。
|
||||
- 阶段二加跑满配格 atk+100%/hp+100%（天赋成人态；F4 复验格，已拍板 i①）。
|
||||
- 消费读数行：整关承伤均/p90、通关率、通关剩余 HP 均（胜）、进 Boss HP 均、平均轮数、普通承伤/场%、Boss 承伤%、踩雷/局、刷新/局。
|
||||
|
||||
### 2.2 真人批（修正锚）
|
||||
|
||||
- 基线档试玩 3–5 局（已拍板 d=① 方向哨），记录每局种子；每局记整关掉血、零承伤轮、通关与否、体感异常。
|
||||
- 用途：真人修正系数 k 观测；只登记不回调，不用真人局判 gate。
|
||||
|
||||
### 2.3 日志批（机制正确性数据源）
|
||||
|
||||
- 工具：`tools/log_analysis.py <logs 目录>` 跑验收期产生的全部 JSONL（建议加 `--per-run`）。
|
||||
- 消费面：零承伤轮（窄/宽口径）、掷点直方图 / 档位占比 / nat20 率 / EV 减免（按方向）、战斗级承伤带对照、增益战斗期复原、数据质量面。
|
||||
|
||||
## 3. 指标判读表
|
||||
|
||||
gate = 不满足即该阶段验收失败（按 §4e 阶梯回滚或登记 06-待办清单，禁静默出带）；observe = 记录与对照，不判生死。
|
||||
|
||||
**两段制（已拍板 h①）**：**阶段一 = 机制验收**——AC 批落批判据（掷点面 / 零承伤轮 / 数据质量等，与压力目标解耦，机制对即闭批）；**阶段二 = 压力验收**——调参收敛判据（承伤跨线带 / 通关率 / 通关余量 / F4@满配格），允许经 §4e 阶梯多轮"测–调–重测"直至落带。
|
||||
|
||||
| 指标 | 口径（档位/数据源） | 期望带 | 判读 | 段 |
|
||||
|---|---|---|---|---|
|
||||
| 完美档整关承伤分布 | MC perfect 基线格，p10 / p90 | **p10 ∈ [35, 45] 且 p90 ∈ [55, 65]**（已拍板 b=B1；蕴含 p10 < 50 < p90 跨线断言，[40,60]/50 形式化） | gate | 二 |
|
||||
| 完美档通关率 | MC perfect 基线格 | **[35%, 65%]**（已拍板 g=独立 gate）；偏差归因规则见下方注 | gate | 二 |
|
||||
| 完美档 Boss 场承伤占比 | MC perfect 基线格，Boss 战承伤 ÷ 生效 max_hp | observe（生死带的组成部分，可超 50%）；单场绝对天花板 ≤100% 生命上限 | observe | 二 |
|
||||
| 完美档普通场承伤占比 | MC perfect 基线格，逐普通战承伤 ÷ 生效 max_hp | observe；单场绝对天花板 ≤100% 生命上限 | observe | 二 |
|
||||
| 盲挖档通关率 | MC normal | 无 gate、无触发动作，纯记录（已拍板 c=①；基线生死带下 0% 为预期态，见 §0） | observe | 二 |
|
||||
| 通关余量（完美档通关者剩余 HP 的 p90/p10） | MC perfect 基线格 | p90 ≤ 13 且 p10 ≥ 3（旧带保留：新设计下幸存者恰为"承伤 <50"的局，余量天然回落该语义域）；阶段二收敛复验，收敛前 observe | gate（收敛后） | 二 |
|
||||
| 平均轮数（完美档） | MC perfect 基线格 | observe，带值待压力收敛后按新基线回填（旧带 [14,17] 绑定旧压力水平，不适用） | observe | 二 |
|
||||
| 满配格承伤占比（F4 复验） | MC perfect 满配格 atk+100%/hp+100% | 普通场 ≤20% / Boss 场 ≤50% 生效 max_hp（原值，已拍板 i① 改挂满配格——基线=生死带、加成=舒适带，两带各司其职） | gate | 二 |
|
||||
| 零承伤轮（窄口径） | 日志分析器：有攻击落地且承伤 0 的轮 | 0（AC 伤害全局下限 1 后构造趋零） | gate | 一 |
|
||||
| 零掉血轮（宽口径） | 日志分析器：有敌人轮 HP 不降 | observe；真人对照旧读数 8/11、8/10，应显著下行 | observe | 一 |
|
||||
| nat20 暴击率 | 日志分析器掷点面（双向合并） | 5% ± 2pp（工具 CRIT_TOLERANCE 既有口径） | gate | 一 |
|
||||
| 档位分布 vs 理论（敌→主角） | 日志分析器 by_dir，vs 主角 AC10 | 全额 55% / ×0.75 15% / ×0.5 20% / ×0.25 10%，各 ±2σ 二项（按实际 n 重算；n≈700 预估时约 ±3–4pp） | gate | 一 |
|
||||
| 玩家侧全额率（主角→敌） | 日志分析器 by_dir，敌 AC 首关 0 | 全额 100%（出现任何非全额档 = 掷点实现缺陷） | gate | 一 |
|
||||
| EV 减免（敌→主角） | 日志分析器 by_dir，口径 = 仅档位乘数、不含 nat20 暴击倍率（与工具一致） | 21.25% ± 2pp（n≈700 预估口径，按实际 n 重算） | gate | 一 |
|
||||
| Boss 血量锚 | 敌人表 / registry 表值断言（非运行读数） | r_boss = 150 ÷ 153.5 ≈ 0.98，带 [0.5, 1.1] 内，本批不动；走廊 [1.1, 1.35] 为行值加难级（已拍板 f①）的候选杠杆，启用即越现行带、须走越带登记 | gate（表值断言） | 一 |
|
||||
| 增益战斗期复原 | 日志分析器 effect 行复原面 | 增伤/削弱/减伤三类可复原；快照 buffs 恒空盲区口径不破（非空计数 = 0） | observe | 一 |
|
||||
| 真人修正系数 k | 真人批 ÷ MC perfect（整关承伤中位比） | observe；预警线 k < 0.3 连续两批（已拍板 d=①） | observe | 二 |
|
||||
| 数据质量面 | 日志分析器 | 解析失败行 0；未配对 battle_end 0；step 未知键仅限 AC 掷点新增字段 | gate | 一 |
|
||||
|
||||
**通关率与承伤分布双 gate 的偏差归因规则（g 拍板附则）**：承伤带过 + 通关率 > 65% → 治疗供给超标，动恢复点收益/治疗量侧，不动敌方输出行值；承伤带过 + 通关率 < 35% → 先查形态带与红档（是否存在不可控死法）；承伤带不过 → 敌方输出侧走 §4e 阶梯。两 gate 同时成立才算阶段二落带。
|
||||
|
||||
理论参照（判读表数字来源，AC10）：读数 ≥10 全额（55%，含 nat20）；缺口 1–3 → ×0.75（15%）；缺口 4–7 → ×0.5（20%）；缺口 8+ → ×0.25（10%）；EV = 0.7875（减免 21.25%）。nat20 = 5% 双方同规暴击 ×2；主角→敌方向敌 AC 首关 0 → 恒全额。
|
||||
|
||||
## 4. 决策记录（2026-09-16，两轮拍板）
|
||||
|
||||
### a. 旧通关率带 [30%, 50%]（基线档）——拍板：① 退役重标
|
||||
|
||||
旧带退役，不另立通关率口径带；新带族 = b 的承伤跨线分布 + g 的通关率 gate，收编批改写期望值带章节时注明退役原因（2026-09-16 测量口径裁定）。未采：完美档单带重定（完美档通关率恒 100% 无分辨力）、双判据（被"退役重标 + 独立通关率 gate"组合取代）。
|
||||
联动：06-待办清单「基线通关率越带，加难杠杆扫描未执行」改写——"越带"失义，加难扫描义务升级为 f① 行值加难批的执行义务；冒险结构「大奖励数值随难度曲线联动」复验基准同步换锚。
|
||||
|
||||
### b. "压力足"主判据——拍板：承伤分布跨生命上限 + B1 分位带
|
||||
|
||||
方向：基础数值、零永久天赋时，第一关整关承伤最大值 > 主角生命上限 50、最小值 < 50，第一关很有可能无法通关；天赋加成后承伤范围整体下移、生命上限提高，关卡变可通——落差即循环驱动的困难设限点（成文于 §0）。
|
||||
判据：**完美档基线格整关承伤 p10 ∈ [35, 45] 且 p90 ∈ [55, 65]**（[40,60]/50 的形式化，分位带对 30 局极值噪声稳健）。未采：极值带（min/max 字面口径，死亡率 ≥3% 即几乎必过，区分度弱）、纯通关率带（治疗供给混入判据，与天赋叙事脱节）。
|
||||
可达性事实：新带中位 ~50 是 AC 落地预估落点（~17.6）的近 3 倍，AC+行动点旋钮量程上限 ~43——由此产生 f 的行值加难级。
|
||||
|
||||
### c. 盲挖档地板观察线——拍板：① 不设线
|
||||
|
||||
盲挖档为纯观察口径，读多少（含 0%）都只记录、无触发动作；基线生死带下 0% 为预期态（§0），文档自身即留痕。未采：登记线、硬 gate（与 b 矛盾）。
|
||||
|
||||
### d. 真人修正系数标定——拍板：① 方向哨
|
||||
|
||||
每批真人 3–5 局；日志分析器产出 k = 真人整关承伤中位 ÷ MC 完美档整关承伤中位；只登记 + 预警线（k < 0.3 连续两批 → 触发 b 带复议），不折算 gate 数字。硬折算升级条件（备查）：累计 ≥8 局且相邻两批 k 波动 < 20%，届时再拍板是否冻结。
|
||||
|
||||
### e. 越带回滚阶梯——拍板：四级阶梯（含 f①）+ 四条边界
|
||||
|
||||
**AC 档位边界 → AC 档位值 → 难度曲线行值加难 → 行动点 6→4**（粒度细→粗、爆炸半径小→大；双向可用：承伤偏低加深压力、承伤偏高放宽折扣）。四条边界：
|
||||
|
||||
1. "承伤偏高（减免过度）"败向先查实现缺陷（双重乘算、档位映射反向），对照掷点面 EV 减免读数定位，再谈调参。
|
||||
2. 动用行值级或行动点级均使同种子历史坐标整体作废，须重立基线、另起验收批。
|
||||
3. 敌方 AC 正式值（首关 0）不进本链——归怪物设定批。
|
||||
4. 每次调参后全量重跑本验收，并在调参日志留联动检算记录（禁独立调参网络纪律）。
|
||||
|
||||
### f. 阶梯第四级"难度曲线行值加难"——拍板：f① 加入
|
||||
|
||||
行值是量程最大、归因最直接的杠杆（AC+行动点两级量程上限 ~43，够不着中位 50）。候选杠杆（06-待办已登记）：敌方攻击基线与群战数量上探、Boss 血量锚走廊 [1.1, 1.35]（启用即越现行带，须走越带登记）、注入衰减 0.5 → 0.6。行值批自带联动对账义务（关级恒等式 / 挖掘风险不等式 / 清图支配性重跑），与已排期的难度曲线调参批合流——先义务后回退，不动摇刚落地的压速批。未采：不加级（目标形同虚设）、行动点提前（先推翻压速批，无好处）。
|
||||
|
||||
### g. 完美档通关率独立 gate——拍板：要，[35%, 65%]
|
||||
|
||||
独立于承伤分布的第二道阶段二 gate（两道须同时成立）。偏差归因规则见 §3 附则：双 gate 打架时按偏差方向归因到治疗供给侧或形态带，不互相覆盖。未采：只 observe（用户要双保险）。
|
||||
|
||||
### h. 两段制——拍板：h①
|
||||
|
||||
阶段一 = 机制验收（AC 批落批判据）；阶段二 = 压力验收（调参收敛判据，允许多轮迭代）。避免 AC 批在压力收敛前无法闭批、批次边界糊掉。未采：单段制。
|
||||
|
||||
### i. F4 期望承伤占比带归属格——拍板：i① 改挂满配格
|
||||
|
||||
F4 原值（普通 ≤20% / Boss ≤50% 生效 max_hp）复验改在满配格 atk+100%/hp+100% 执行，与 GDD 翻倍档 ≥95% 通关率带同格互证；基线格逐场上界降为 observe（单场绝对天花板 ≤100% 生命上限）。基线 = 生死带（b/g 管），加成 = 舒适带（F4 管）。未采：基线格放宽数值（惨烈场贴线误伤）、F4 退役（丢掉唯一单场天花板）。
|
||||
|
||||
## 5. 与既有验收体系的衔接
|
||||
|
||||
### 5.1 旧带处置映射
|
||||
|
||||
| 旧带 / 注记（难度曲线与Boss 期望值带章节） | 处置 | 说明与去向 |
|
||||
|---|---|---|
|
||||
| 第一关通关率带 基线档 [30%, 50%] | **退役（a）** | 收编批改写期望值带章节，注明退役原因；新带族 = b 承伤跨线分布 + g 通关率 gate |
|
||||
| "现行扫描读数 60% 越上界"注记 + 06-待办清单「基线通关率越带」 | 退役 / 改写 | 旧带退役则"越带"失义；加难扫描义务升级为 f① 行值加难批执行义务 |
|
||||
| 通关余量带 p90 ≤ 13 / p10 ≥ 3 | **保留** | 新设计（承伤跨 50）下幸存者余量天然落回该语义域，旧值重新成立；阶段二收敛复验，收敛前 observe |
|
||||
| 形态带（教学绿 / 中段黄 / Boss 黄不红）与零红档 | 不动 | 口径不变，与"整关生死带"不冲突（教学位绿档 = 第一战必胜，整关仍可死）；AC 落批激活"区间带宽补扫"义务（v0.4 既有成文），落收编后的调参批执行 |
|
||||
| 期望承伤占比带 普通 ≤20% / Boss ≤50%（provisional，F4） | **归属格改挂满配格（i①）** | 基线格惨烈是设计态，F4 原值在基线格必破带；满配格复验与翻倍档通关率带同格互证 |
|
||||
| Boss 血量锚 r_boss = 0.98 | 本批不动 | gate = 表值断言；走廊 [1.1,1.35] 为 f① 候选杠杆，启用即越现行带、须越带登记 |
|
||||
| 恒等式奖励输出占比 [15%, 40%] | 不动 | 复测安排见 5.2 |
|
||||
| 状态强度 / 克制矩阵 / 充能投桶等表值 | 不动 | 本批唯一新数值层 = AC 掷点 |
|
||||
|
||||
### 5.2 恒等式奖励占比复测安排
|
||||
|
||||
- 时点：AC 批落批 + 阶段一机制验收通过之后、压力收敛过程中随行值/行动点调参批一并执行（本清单不跑恒等式对账——level_monte_carlo 不产输出侧占比读数）。
|
||||
- 方向预判：敌 AC 首关 0 → 玩家侧基础攻击输出仅因 nat20 暴击 +~5%；奖励侧输出不变 → 占比分母微涨、占比微降，原读数处 15% 下沿则须盯穿带风险。行值加难（f①）同步抬高敌方总生命，恒等式必须联合检算——这正是其禁独立调参联动条款。
|
||||
- 义务落点：难度曲线与Boss「验收标准—恒等式闭合」条目不变；复测结论记入调参日志（联动可审计纪律）。
|
||||
|
||||
### 5.3 登记义务落点（本文档零改动既有文件；以下为落批后的收编义务）
|
||||
|
||||
- **难度曲线与Boss「期望值带」章节**：收编新带族（§0 生死带前提、b 分位带、g 通关率 gate、c 盲挖不设线、通关余量带保留注记、F4 满配格归属、f① 四级阶梯），注明"等 AC 批落批后收编"。同批改写 v0.4 掷点带宽段的"EV 中性引入"口径——实际落地规格（AC10 → 敌方输出 EV −21.25%）非 EV 中性，两口径冲突须以落批实现为准。
|
||||
- **06-待办清单.md**：①「护甲等级掷点形式与数值域」「护甲等级掷点的随机流归属」「护甲等级（armor_class）行值未定」→ 已收口：2026-09-16 AC 批裁决成文于战斗结算 v0.10 与 registry settlement_table 条目，原 06 清单三条件目已按「解决即移除」口径删除（2026-09-19 清理批）；②「基线通关率越带」按 a 改写，同时升级为 f① 行值加难批的执行义务；③「真人通关率标定」接 d=① 管道；④「完美策略档的结构性加难杠杆」重估——b 的新带下"承伤带对完美档无分辨力"的前提已反转，该条目大概率转已解决/失义。
|
||||
- **registry entities.yaml**：AC 行值与档位参数由 AC 批会话收编，非本清单义务，仅衔接注记。
|
||||
- 附带发现（不修，随收编批一并处理）：难度曲线与Boss 的「待拍板」存根链接指向 `06-待拍板清单.md`，实际文件已更名 `06-待办清单.md`，断链。
|
||||
|
||||
## 6. 附录：历史实测坐标（对照基线）
|
||||
|
||||
| 坐标 | 完美档整关承伤 | 普通场占比 | Boss 场占比 | 平均轮数 | 通关率（完美） | 盲挖通关率 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| 行动点 8 时代 | 13.1/关 | 2.1% | 18.9% | 13.4 | 100% | 20% |
|
||||
| 行动点 6 现行（AC 未落地） | 22.4/关 | 4.2% | 29.8% | 15.3 | 100% | 7%（仅下界观察） |
|
||||
| AC 落地预估（非 gate 数字） | 17–20 | ~3.3% | 23–25% | ≈15 | 100% | 上行方向 |
|
||||
| **新目标带（定稿）** | p10 ∈ [35,45] / p90 ∈ [55,65] | observe（单场 ≤100% 天花板） | observe（可超 50%） | 待新基线回填 | **[35%, 65%]（gate）** | 预期 0%（设计态，不设线） |
|
||||
|
||||
真人锚：基线通关局两份（种子 5678/1234）整关掉血 6/12 点，零承伤轮 8/11 与 8/10——"回合无伤"是待修的退化解；更早试玩批次实测真人显著强于当时模拟者（真人 100% vs 模拟 80%）。N=30 同种子（4200+30）各代读数逐局可比。**注：新目标带确立后，上表历史坐标属"低压区读数"，只作机制面对照；压力对照以收敛后的新基线批为准。**
|
||||
|
||||
## 版本历史
|
||||
|
||||
| 版本 | 日期 | 改动 |
|
||||
|---|---|---|
|
||||
| v0.1 | 2026-09-16 | 草案建账：前置条件 / 运行配置 / 判读表 / 决策点 a–e / 衔接映射 / 历史坐标附录 |
|
||||
| v0.2 | 2026-09-16 | 第二轮拍板回填：a=①、d=①、e 确认+四条边界；b 方向改判"承伤分布跨生命上限"（§0 新增设计前提）；c 概念解释重写；新增决策点 f/g/h/i；判读表改两段制、通关余量带改判保留、F4 归属格待拍 |
|
||||
| v1.0 | 2026-09-16 | **定稿**：b=B1 分位带（p10∈[35,45] / p90∈[55,65]）、c=① 不设线、f=f① 行值加难入阶梯（四级阶梯成文）、g=通关率独立 gate [35%,65%]（附双 gate 偏差归因规则）、h=h① 两段制、i=i① F4 改挂满配格；§4 改为决策记录，全表与衔接章节按拍板结果收口 |
|
||||
@@ -0,0 +1,81 @@
|
||||
# Alpha 验收清单 · 战斗屏（初稿）
|
||||
|
||||
> 状态：**初稿成文于循环 1（2026-09-26，战斗舞台 Node2D 迁移批 T0）**。本文件 = Alpha 验收批（三段式程序第三段）的销项底单；循环 1 只成文不销项，随批更新状态列。
|
||||
> 来源拼装（六源）：① `design/gdd/ux/battle.md` AC 与 §13 上游义务对照表 ② `design/gdd/systems/表现与支撑/HUD框架.md` 验收标准与基线表 ③ `design/art/art-bible.md` 美术判据（§1.4/§2/§4.5/§8）④ `design/gdd/07-体验验证清单.md` §⑨ 真人试玩指引 ⑤ `design/gdd/06-待办清单.md` 挂 Alpha 条目 ⑥ 工程回归面（冒烟/五探针/文档三闸/MC）。
|
||||
> 验法分档：**[headless]** = 场景探针或脚本可自动判定；**[真机渲染]** = 开窗口跑游戏读日志/截图测量（draw calls、灰度、帧率类，agent 可窗口化自动测大半）；**[人]** = 用户目检或真人试玩，agent 只备料。
|
||||
> 数值带（ap6-ac 阶段二压力验收）**不在本清单**——归调参批（2026-09-26 裁决⑦）。
|
||||
|
||||
## A. 布局与性能（源② + 源①）
|
||||
|
||||
| # | 判据 | 验法 | 状态 |
|
||||
|---|---|---|---|
|
||||
| A1 | 三区无遮挡、无重叠、无内容裁切（棋盘全部格子与数字完整可见）；分区尺寸与 battle.md 布局表一致 | [headless] ui_layout_probe + [人] 双分辨率目检 | 待验收 |
|
||||
| A2 | 1280×800 与 1920×1080 两档均成立（1920 档换算值表现层升级批成文后此项才可销） | [人] 全屏目检两档 | 待验收（1920 档参数未成文） |
|
||||
| A3 | 同屏 draw calls < 200 | [真机渲染] RenderingServer 调试读数（迁移批 T7 附首读数） | 待测（基线读数见循环 1 T7 交付） |
|
||||
| A4 | 进入战斗屏 500ms 内首格可点 | [headless] ui_click_probe 首格可点计时 AC | 待验收 |
|
||||
| A5 | B 区战斗舞台 = Node2D 舞台半区 + Control 文本半区（ADR-0006 分工表）；站桩载体 Button/GridContainer/HBox 计数 = 0 | [headless] 场景树 dump 取证探针（迁移批 T5① 已实证 PASS——探针按台账 152 先例跑完即删，复跑件归呈现层测试分级批周期化时重建） | **已实证（循环 1 T5，2026-09-26）——周期化复跑件待建** |
|
||||
|
||||
## B. 可读性与色彩（源②基线表 + 源③）
|
||||
|
||||
| # | 判据 | 验法 | 状态 |
|
||||
|---|---|---|---|
|
||||
| B1 | 全部数字对格底对比 ≥4.5:1 | [真机渲染] 截图采样明度计算 | 待验收 |
|
||||
| B2 | 已开/未开格态灰度截图下可逐格分类；变异格纹带灰度可辨 | [真机渲染] 灰度转换截图 + 逐格分类脚本 | 待验收 |
|
||||
| B3 | 无信息仅靠色相承载（色弱安全，art-bible §4.5 清单） | [真机渲染] 灰度截图复核 + [人] 抽检 | 待验收 |
|
||||
| B4 | 字号下限：棋盘数字 ≥18px、明细正文 ≥14px、tooltip ≥13px（1280×800 基座） | [headless] 布局探针读值 | 待验收 |
|
||||
| B5 | 中文字体随包内置并设默认，运行时中文渲染无缺字 | [headless] 注入字体非空 + has_char + 宽度 >0（C6 判据）+ [人] 目检光栅 | 待验收（当前=引擎回退字体，CJK 随包未落） |
|
||||
| B6 | 按钮文案 ≤4 汉字宽度；译西文不破版 | [人] 目检 | 待验收（本地化专项前置） |
|
||||
|
||||
## C. 呈现义务（源① AC + 源② 验收标准）
|
||||
|
||||
| # | 判据 | 验法 | 状态 |
|
||||
|---|---|---|---|
|
||||
| C1 | 悬停光标三语义（移动/挖/旗）随目标切换并高亮目标格；悬停已开格画合法路径；可挖域常驻呼吸微光 | [headless] ui_input_probe case①②③ | 待验收 |
|
||||
| C2 | 一帧内意图整批到达，停手点击终结当帧收集；每次拒绝可感知（棋盘/资源/相位三面，前两类可区分；双通道反馈） | [headless] ui_probe 拒绝面断言 + [人] 目检 | 待验收 |
|
||||
| C3 | 敌人站桩呈现：意图占位（普攻零表示/特殊技类型级提示，不预告名与数值）且挖掘期全程可见、映射跨局恒定、顺位可读、血量可读、敌方共享层数各立绘同值 | [headless] ui_probe 站桩断言 + [人] 目检 | 待验收 |
|
||||
| C4 | 死亡灰化加碎裂退场（禁瞬消）且就地更新不丢灰化态 | [headless] 探针灰化态断言 + [人] 目检节奏 | 待验收 |
|
||||
| C5 | 受击闪白、血条直角递减、结算弹道落点贴站桩中心 | [headless] 等价探针 + [人] 目检 | 待验收 |
|
||||
| C6 | 状态槽：图标+层数+剩余结算次数，悬停见来源+语义+剩余；空态整排隐藏；战斗结束全清有微文案 | [headless] ui_probe BUG-0001 回归段 + ui_click_probe tooltip 段 + [人] 目检 | 待验收 |
|
||||
| C7 | 结算逐行实时滚出带来源标注；未生效类行聚合计数带形状冗余；零值行不吞；高光三档不打空兑现 | [headless] ui_probe 结算段 + [人] 目检 | 待验收 |
|
||||
| C8 | 终局：胜利金蜡封、失败暮蓝氛围层（明度不变）；两反馈不合并、时序不倒挂 | [headless] 探针 + [人] 目检 | 待验收 |
|
||||
| C9 | 任一模态打开时遮挡物隐藏或输入锁定、关闭逐层恢复；tooltip/明细行固定槽高不推挤布局 | [headless] ui_click_probe 回看段 | 待验收 |
|
||||
| C10 | 终局呈现只消费流水与快照（零生命周期回读）；重放渲染与实时渲染一致；载荷逐字段断言 | [headless] MC/冒烟既有断言 | 待验收 |
|
||||
|
||||
## D. 可访问性与输入（源②基线表）
|
||||
|
||||
| # | 判据 | 验法 | 状态 |
|
||||
|---|---|---|---|
|
||||
| D1 | 无每秒超三次闪烁 | [真机渲染] 帧序列采样 | 待验收 |
|
||||
| D2 | 减动效开关：时长减半或跳终态（结算兑现可加速不可跳过） | [headless] 开关态探针 + [人] 目检 | 待验收（开关本身未立项，先挂起） |
|
||||
| D3 | 全程纯鼠标可玩 | [headless] ui_click_probe 全链 | 待验收 |
|
||||
| D4 | 切片临时名零残留；呈现层零随机调用 | [headless] static_scan + grep | 待验收 |
|
||||
|
||||
## E. 真人试玩面（源④ 07§⑨ + 源① OQ）
|
||||
|
||||
| # | 判据 | 验法 | 状态 |
|
||||
|---|---|---|---|
|
||||
| E1 | 照 07§⑨ 指引真人试玩 3–5 局（零天赋基线档），局中体感对号 ①–⑧ 观测项，局后一句话记录 | [人] 用户一次真人试玩（裁决⑦） | 待验收 |
|
||||
| E2 | 样张 v1 终审（视觉语言冻结为换皮批输入） | [人] 用户看图 | 循环 1 异步触点，不阻塞 |
|
||||
| E3 | 表现遗留收口复核（循环 2 交付后）：敌人立绘/接触带微光/封印特效/原型件退役/C 区美化 | [人] 目检 + [headless] 回归闸 | 待循环 2 |
|
||||
|
||||
## F. 工程回归面（源⑥，每批常态闸）
|
||||
|
||||
| # | 判据 | 验法 | 状态 |
|
||||
|---|---|---|---|
|
||||
| F1 | run_smoke 全绿（当轮基线零失败） | [headless] `python tools/run_smoke.py` | 循环 1 基线 557/0 绿，迁移批 T0–T5 每轮复跑全绿（2026-09-26） |
|
||||
| F2 | 五探针全绿：ui_probe / ui_click_probe(SEED=7) / ui_layout_probe / ui_tune_probe / ui_input_probe 十一断言 | [headless] 场景探针 | 循环 1 基线全绿；迁移批每轮复跑全绿（ui_probe 敌站桩断言已随批等价改写为本体探针出口——台账 171） |
|
||||
| F3 | 文档三闸对基线零新增 | [headless] doc_link_audit / doc_term_audit / gdd_lint 对基线快照 diff | 循环 1 基线已存档 |
|
||||
| F4 | MC 12 局 RUNSUM 与基线逐位一致（核心层零漂移证据） | [headless] adventure_monte_carlo | 循环 1 基线采集于 T0（24 行 RUNSUM 存档），T7 对拍 |
|
||||
|
||||
## G. 源⑤ 06 挂 Alpha 条目涉战斗屏者（销项时逐条对表）
|
||||
|
||||
- Alpha：全怪物技能池数值验证与合理性设计（归难度曲线与 Boss 主责，非本清单销项——录以备查）。
|
||||
- 雷格与安全格的资源分布差异化（Alpha 批，结构修订）——非战斗屏呈现面，录以备查。
|
||||
- 表现层测试分级与 UI 驱动夹具周期化（06 台账 160-164 批登记）——夹具周期化落地时本清单 A5 取证件转正式回归件。
|
||||
|
||||
## 修订记录
|
||||
|
||||
| 日期 | 改动 |
|
||||
|---|---|
|
||||
| 2026-09-26 | 初稿成文（循环 1 T0，六源拼装；销项归 Alpha 验收批） |
|
||||
| 2026-09-26 | T5/T6 状态列更新（A5 已实证/ F1、F2 迁移批全绿注记/F4 待 T7 对拍；B 区站桩断言改判注记） |
|
||||
@@ -4,7 +4,7 @@
|
||||
**性质**：只读对账作业——履行 06 待办「清图支配性保守地板缺口」的对账义务（用户指令：从难度曲线调参批提前执行）。本报告不动任何数值；调参建议仅呈报，拍板归用户。
|
||||
**判式权威**：[registry entities.yaml `clause5_dominance`](../registry/entities.yaml)（挖穿残余池计价，模型本体不变）
|
||||
**配套工具**：`tools/clear_dominance_audit.py`（重算器，判式全参数可配——难度曲线调参批的常设重跑入口）＋ `game/smoke/board_stat_probe.gd`（实测板形统计探针）
|
||||
**归属**：[难度曲线与Boss](../gdd/systems/冒险循环/难度曲线与Boss.md)（裁决方）× [地图战斗资源](../gdd/systems/战斗循环/地图战斗资源.md)（清图奖励供给方）× [行动经济](../gdd/systems/排雷循环/行动经济.md)（契约本体）× [战斗结算](../gdd/systems/战斗循环/战斗结算.md)（对账责任方）
|
||||
**归属**：[难度曲线与Boss](../gdd/systems/冒险循环/难度曲线与Boss.md)（裁决方）× [地图战斗资源](../gdd/systems/战斗循环/地图战斗资源.md)（清图奖励供给方）× [行动经济](../gdd/systems/排雷循环/行动经济.md)（契约本体）× [战斗结算](../systems/战斗循环/战斗结算.md)（对账责任方）
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,70 @@
|
||||
# Gate Check 报告：Concept → Systems Design（重审）
|
||||
|
||||
- **日期**：2026-09-07
|
||||
- **执行**：gate-check 技能 · 评审模式 lean（`production/review-mode.txt` 不存在，取默认）
|
||||
- **背景**：上一轮（2026-09-06）四总监 CONCERNS（流程债 FAIL）。本轮为流程债清偿后的重审。
|
||||
- **Verdict: CONCERNS**（无阻塞项，遗留项均为登记级文档修正）
|
||||
|
||||
## 必备物证：3/3 通过
|
||||
|
||||
- ✅ `design/gdd/game-concept.md` — 有实质内容（受众/术语/循环/难度分层/待定问题）
|
||||
- ✅ 游戏支柱 — `game-pillars.md`，4 条支柱各带裁剪判据
|
||||
- ✅ Visual Identity Anchor — game-concept.md:13，1 句总规则 + 4 条支撑原则
|
||||
- ✅ （推荐项）概念原型 REPORT — `prototypes/minesweeper-battle-concept/REPORT.md`，Verdict: PROCEED，CONFIRMED（核心）
|
||||
|
||||
## 质量检查：4/4 通过（1 项注明）
|
||||
|
||||
- ✅ 核心循环已描述且文档间一致
|
||||
- ✅ 目标受众已定稿（game-concept.md:6）
|
||||
- ✅ VIA 含一句规则 + ≥2 支撑原则（实为 4 条）
|
||||
- ✅ 概念已评审 — 无独立 `/design-review` 报告文件，由两轮四总监门禁评审代行，无 MAJOR REVISION 级判定
|
||||
|
||||
## 总监评审
|
||||
|
||||
### Creative Director — CONCERNS
|
||||
1. 流程债四项验证属实清偿；情绪核心与支柱全文档一致
|
||||
2. 验证证据质量：CONFIRMED 依据为开发者自测主观反馈，预注册验证信号未逐条记录 → 垂直切片前补一次按信号记录的正式 playtest（可与标错惩罚实测合并）
|
||||
3. 未登记创意风险：安全格奖励**可预期性**无文档承载（P2 规划前提）→ 进 GDD 前登记，B4/A4 落实奖励可见性/探测
|
||||
4. 未登记创意风险："我算对了"缺高光兑现节点（如全图标中/零误标加倍结算）→ 进 GDD 前登记，B1/B4 设计
|
||||
|
||||
### Technical Director — CONCERNS
|
||||
1. 四项已登记技术风险（双舞台管线、可回放结算、headless 可测、RNG 归 D2）核实；依赖无环，前 10 GDD 满足拓扑序
|
||||
2. systems-index:55 依赖笔误：`A5 ← B2,A4` 应为 `A5 ← A2,A4`（奖励侧挂 B4 未入箭头）→ 进 GDD 前修正
|
||||
3. C3 口径不一：:62 称"C3 消费 B1 输出"但 :56 依赖表为 C3 ← D2,B2 → C3 GDD 内定稿回写，可延后
|
||||
4. stage.txt 未写入（门禁关闭动作）；两条未登记工程约束（headless 测试载体、事件总线载体）归 D2/B1 GDD 章节
|
||||
|
||||
### Producer — CONCERNS
|
||||
1. **流程债四项逐项验证 ✓ 全部清偿**（支柱/受众/VIA/REPORT 均非占位、有定稿日期）
|
||||
2. 里程碑分层与 GDD 设计顺序可执行；待定问题均有归属
|
||||
3. 两条跨系统前置未登记进 systems-index：标错惩罚实测（A2 GDD 前）、格子样张测试/art-bible 排期（game-concept:24 指向不存在的"art-bible 任务"）→ A2 前补齐；**前 5 份 GDD（D2/A3/A4/B3/A1）无未清前置，可立即开写**
|
||||
4. active.md 轻微失真："v1→v3 验证完成"应为"v2 核心假设 CONFIRMED，v3 待终验"
|
||||
|
||||
### Art Director — CONCERNS（代评）
|
||||
|
||||
> 注：AD 代理派单连续 4 次失败（基础设施错误），本项由主会话按已读文档代行评审；如需独立评审可重跑 `/gate-check systems-design`。
|
||||
|
||||
1. VIA 足以支撑后续美术工作（色弱双通道、绘制优先级、调色板交换均到位）；三项美术风险均已登记
|
||||
2. art-bible 未创建且未排期：不阻塞进入 Systems Design，但最晚须在 **D1 GDD（设计顺序第 10 位）前**、至迟垂直切片前存在（含格子样张测试）
|
||||
3. 格子样张测试归属模糊；战斗表现美术测试（B5 GDD 前一屏样张）已登记清晰
|
||||
4. D1 行未登记"移动路径预览"归属（game-concept:25 有）
|
||||
|
||||
## 阻塞项
|
||||
|
||||
无。
|
||||
|
||||
## 建议（按优先级）
|
||||
|
||||
1. 补 systems-index 登记：标错惩罚实测（A2 前）、art-bible + 格子样张（D1 GDD 前最晚）、B4"使用时机"字段、D1"移动路径预览"
|
||||
2. 修 systems-index:55 依赖箭头（A5 ← A2,A4,B4）
|
||||
3. 修 active.md 失真（v3 待终验）+ README 标题 v2→v3 + game-concept:121 拆分停手(×2)/清图(×1)
|
||||
4. 登记 CD 两条创意风险（奖励可预期性、"我算对了"高光节点）
|
||||
5. 垂直切片前：按预注册信号做一次正式 playtest（与标错惩罚补丁实测合并）
|
||||
|
||||
## Chain-of-Verification
|
||||
|
||||
5 问核验，结论不变。工具实证：VIA 节（grep game-concept.md:13）、支柱裁剪判据数 = 4、REPORT PROCEED 行、stage.txt 确认不存在、design/gdd/ 仅 3 文件。无 CONCERN 可升级为阻塞；上轮 FAIL 项经文件证据逐项确认清偿。
|
||||
|
||||
## 阶段处置
|
||||
|
||||
- **stage.txt 未写入**（判定 CONCERNS，且技能要求阶段变更须用户明确确认）
|
||||
- 门禁实质通过；用户确认推进后执行：`production/stage.txt` ← `Systems Design`，并同步 active.md 阶段字段
|
||||
@@ -0,0 +1,311 @@
|
||||
# B1 战斗结算规则（lean 格式样例）
|
||||
|
||||
> **状态**：格式样例——用新格式重排现有 `b1-settlement.md` 的内容域，供评审，非生效文档（行协议计数等现行口径以 `design/gdd/systems/战斗循环/战斗结算.md` 为准）
|
||||
> **版本**：lean-sample · 2026-09-13 · 作者：user + agents
|
||||
> **一句话**：B1 把每轮扫雷的结果逐行兑现为战斗结果，并判定胜负。
|
||||
|
||||
## 速览
|
||||
|
||||
| 关键问题 | 答案 |
|
||||
|---|---|
|
||||
| 定位 | 战斗域编排与结算中枢；轮次生命周期唯一 owner |
|
||||
| 拥有 | 段序、判定时机、伤害消费侧语义、明细流水协议、上游义务账本（B3×8 / B2×6 / A2×3 / B4×6） |
|
||||
| 不拥有 | 单位状态（B2）· 状态实例（B3）· 奖励内容（B4）· 行动价目（A3）· 棋盘规则（A1/A2）· 呈现（D1/B5） |
|
||||
| 上游输入 | A2 三事件流 · A3 相位观测量 · 各表值快照 |
|
||||
| 下游输出 | 结算步骤流（D1/B5/D4 消费）· 条款③⑤对账结论（C3 约束输入） |
|
||||
| 硬约束 | 零随机 · 零 UI 依赖 · 结算禁 await——同种子同输入 ⇒ 步骤流逐行相同 |
|
||||
|
||||
## 体验锚点
|
||||
|
||||
| 支柱 | 关键词 | 机制承诺 |
|
||||
|---|---|---|
|
||||
| P2 因果归因 | "都是我算出来的" | 每行明细携带来源标注；无来源行 = 断言失败（AC-42） |
|
||||
| P1 掌控感 | "挖下去值得" | 条款③不等式由本系统闭合签字 |
|
||||
| P3 雷的两面 | "赌桌不是陷阱" | 敌方伏击行与标中旗削弱行同框、同呈现语言 |
|
||||
| 高光节拍 | "完美被加倍兑现" | 完美排雷双份兑付 + 标中旗行高光 |
|
||||
|
||||
## 全局流程
|
||||
|
||||
### 战斗开始
|
||||
|
||||
```
|
||||
begin_battle(encounter)
|
||||
│ ① set_reload_gate(true) [D2] 调试门置位
|
||||
│ ② notify_battle_start() [B3] 容器开域
|
||||
│ ③ spawn(L, D, hero_hp) [B2] 行值快照实例化
|
||||
│ ④ install_board + roll_board [A2/B4] 恰一次；资格格清单 = S ∖ R₀
|
||||
│ ⑤ notify_round_start() [A3] → Active
|
||||
▼
|
||||
RoundActive（挖掘期，B1 只缓冲事件流）
|
||||
```
|
||||
|
||||
### 每轮结算（七段骨架，全序执行、段序结构冻结）
|
||||
|
||||
```
|
||||
轮末触发：Waiting 相位编排点（只读 A3 相位观测量，不依赖事件到达序）
|
||||
│
|
||||
▼
|
||||
①授予段 ──── cell_revealed 批 → flag_judged 批 → 清图奖励（仅 cleared 轮）
|
||||
│ （转化规则见下方两表）
|
||||
▼
|
||||
②道具使用窗口 ─ 玩家至多选一件或跳过（全流程唯一玩家输入点）
|
||||
│ 满血禁选治疗包；空库存可整体不弹窗
|
||||
▼
|
||||
③增益/减益段 ─ query_active 双侧读值 → SettlementTable 语义映射 → 效果明细行
|
||||
│
|
||||
▼
|
||||
④道具段 ───── 伤害道具：恒定表值打 default_target；治疗包：clamp 回复
|
||||
│ 施加时无存活敌 → 照常消耗 + "已消耗未生效"行
|
||||
▼
|
||||
⑤战斗段 ───── 主角先手攻击（D_hero = atk ×（1+attack_up））
|
||||
│ → 逐存活敌（行主序）：query_attack → apply_damage → advance
|
||||
│ ※ hero hp=0 → 立即短路，剩余敌不作用，直入 ⑦
|
||||
▼
|
||||
⑥衰减段 ───── decay_round() 恰一次（含末轮；先兑付后衰减的时序契约）
|
||||
│
|
||||
▼
|
||||
⑦判定段 ───── hero hp=0 → 失败 │ 存活敌=∅ → 胜利 │ 否则 → 下一轮
|
||||
```
|
||||
|
||||
### 出口分发
|
||||
|
||||
| 结局 | 触发 | 动作序列 | 约束 |
|
||||
|---|---|---|---|
|
||||
| 继续 | 判定=下一轮 | `notify_settlement_done(same_board)` → `notify_round_start()` | 同图续轮 |
|
||||
| 换图 | cleared 轮 | `retire_board` → `retire_mapping` → A1 `generate` → `install_board` → `roll_board` 恰一次 → `notify_settlement_done(new_board)` → `notify_round_start()` | stopped/ap_exhausted 恒 same_board，违约 fail-fast |
|
||||
| 挖掘期刷新 | 玩家经 D1 发起 | A3 `request_refresh` 扣费 → 换图全序（无结算段、无 round_end、轮次不终结） | RAP 不足→拒绝上抛；每图 cap 2；刷新图无清图奖励 |
|
||||
| 战斗结束 | 判定=胜/负 | `retire_mapping` → `despawn_all` → `notify_battle_end` → `notify_combat_end` → `set_reload_gate(false)` | 库存不清（关内延续） |
|
||||
| 关卡结束 | 上层显式调用 | `clear_inventory()` 恰一次，清空前快照计数返回 | victory/defeat 皆然 |
|
||||
|
||||
## 核心规则
|
||||
|
||||
| # | 规则 | 要点 |
|
||||
|---|---|---|
|
||||
| 1 | 编排唯一性 | B1 是战斗域全部跨系统调用的唯一发起方；B2/B3/B4 零相互直调 |
|
||||
| 2 | 结算触发 | Waiting 相位编排点；不依赖事件到达序 |
|
||||
| 3 | facts 缓冲 | 按轮缓冲事件、轮末统一转化；事实→授予恰一次（B4 幂等仅兜底） |
|
||||
| 4 | 段序骨架 | 七段全序（见上图）；修订走 GDD 流程，非调参 |
|
||||
| 5 | 授予段 | 三批转化，见下两表 |
|
||||
| 6 | 伏击转化 | `ambush_grant_plan(mines_r, cap)`；前 granted_r 颗逐颗授予；池 L side 共享、dur=1 轮末清零 |
|
||||
| 7 | 道具窗口 | B4 `query_inventory` 投影 + B1 守卫预判；至多一件；选择序列入回放 |
|
||||
| 8 | 增益/减益 | 读值→语义映射→池合成（F2）；明细按授予流水逐条标注来源 |
|
||||
| 9 | 道具段 | 伤害恒定表值不吃修正；满血守卫拒治疗；零效果判定读 B2 存活集 |
|
||||
| 10 | 战斗段 | 主角先手攻击 + 逐敌循环（调用序钉死）；死亡即不动手；hero 死亡短路 |
|
||||
| 11 | 衰减段 | 恰一次、恒执行、含末轮 |
|
||||
| 12 | 判定段 | hero 先判（防御性优先级）；胜负明细行 |
|
||||
| 13 | 高光节点 | #2 完美排雷=清图奖励双份兑付；#3 标中旗=行字段 highlight（见枚举表） |
|
||||
| 14 | 明细流水协议 | 13 类行封闭枚举 + 公共字段（见枚举表）——D1/B5/D4 的统一数据源契约 |
|
||||
| 15 | 可回放性 | 零随机 + 确定性输入 + 表值快照 ⇒ 同种子同输入步骤流逐行相同 |
|
||||
| 16 | 数值承载 | 全部数值在 D2 SettlementTable；B1 代码零数值字面量；战斗中热重载被门拒绝 |
|
||||
|
||||
### 授予段：三批转化
|
||||
|
||||
| 批 | 输入 | 转化 | 产出 |
|
||||
|---|---|---|---|
|
||||
| cell_revealed | `kind=mine` | 调 `ambush_grant_plan`，事件规范序逐颗 `apply_effect(ambush)` | 伏击池 L；溢出产"溢出未生效"行 |
|
||||
| cell_revealed | `kind=safe ∧ reward_eligible` | 按 category 分流（见下表） | 每格受理恰一次 |
|
||||
| flag_judged | `hit=true` 且资格未消费 | `apply_effect(weaken)` + 资格消费 | 标中旗行（highlight=`flag_hit`） |
|
||||
| flag_judged | `hit=true` 且资格已消费 | 去重跳过（每雷实例一次） | 零新增行 |
|
||||
| flag_judged | `hit=false` | 零兑付 | "标旗未中"零值行（highlight=`perfect_broken`） |
|
||||
| cleared 轮 | — | `grant_clear()` 恰一次；完美板（零误标 ∧ ≥1 标中）追加第二份同身份兑付 | 清图奖励行；完美高光行 |
|
||||
|
||||
### 授予段：奖励分流
|
||||
|
||||
| category | 兑付方式 | 拒绝语义 |
|
||||
|---|---|---|
|
||||
| buff | `apply_effect`（入池，结算段生效） | 满层 → "奖励未生效"行，无折算 |
|
||||
| instant_aoe | 全体存活敌各 `power` 点（逐个 apply_damage） | 当场兑付，不进库存 |
|
||||
| instant_heal | 主角回复 `power`（clamp） | 满血 → "奖励未生效"行 |
|
||||
| damage_item / heal_pack | `stock()` 入关卡域库存 | 窗口选用时兑付 |
|
||||
|
||||
## 枚举
|
||||
|
||||
### 明细行类型（封闭枚举，13 类）
|
||||
|
||||
| 行类型 | 特有字段 | 产出点 | 说明 |
|
||||
|---|---|---|---|
|
||||
| 效果行 | `effect_id` `pool_value` | 增益/减益段 | value=该次授予贡献值；pool_value=池合成值（防 −130%×2 行误读为 −260%） |
|
||||
| 伤害行 | `target` | 道具段 / 战斗段 | 分量二元组 + 减伤终值 + 击杀标记 |
|
||||
| 治疗行 | — | 道具段 | clamp 后真实回复量 |
|
||||
| 道具行 | `target` | 授予段 / 道具段 | 入库 / 生效 / 语境注记 |
|
||||
| 奖励未生效行 | 聚合计数 | 授予段 | 满层拒绝、满血、雾板等合法例外 |
|
||||
| 已消耗未生效行 | — | 道具段 | 施加时已无存活敌（Used 不可逆） |
|
||||
| 使用被拒行 | — | 道具段 | 满血治疗包守卫 |
|
||||
| 溢出未生效行 | — | 授予段 | 伏击/奖励族同名协议 |
|
||||
| 标旗未中行 | highlight=`perfect_broken` | 授予段 | 零值归因行；每雷实例一次去重 |
|
||||
| 蓄力行 | — | 战斗段 | charge 拍零作用 |
|
||||
| 衰减行 | — | 衰减段 | 移除数 k（呈现聚合归 D1） |
|
||||
| 判定行 | — | 判定段 | 胜负 / 继续 |
|
||||
| 高光行 | — | 授予段（清图） | 完美排雷；value=实际有效兑付，禁记名义值 |
|
||||
|
||||
**公共字段**（13 类全必有）：`type` `source_class` `origin_cell`（板级行可空）`round_index` `display_name` `value` `highlight?`
|
||||
**断言**：无来源行 = 失败（AC-42）。
|
||||
|
||||
### source_class（封闭枚举）
|
||||
|
||||
| 值 | 来源 |
|
||||
|---|---|
|
||||
| safe_cell / flag_hit / mine_hit / clear_default | B3 既有四源 |
|
||||
| 道具/判定扩展 | B4 交付语义 |
|
||||
| enemy_action | 敌方行动行（伤害/蓄力） |
|
||||
| flag_miss | 标旗未中零值行 |
|
||||
| hero_attack | 主角先手攻击伤害行 |
|
||||
|
||||
新增值 = 接口漂移，须同步 `source_label_map` 键集。
|
||||
|
||||
### highlight（可空枚举）
|
||||
|
||||
| 值 | 含义 |
|
||||
|---|---|
|
||||
| `flag_hit` | 标中旗削弱兑付行强调 |
|
||||
| `clear_reward_h2` | 清图奖励行强调 |
|
||||
| `perfect_broken` | 本板完美谓词已破的归因锚 |
|
||||
|
||||
## 数值结论与推导
|
||||
|
||||
> 章节纪律：**结论先行**（加粗一行），下接「推导」小标题给公式与验算表。F1 对照表 / F3 伤害合成迁移时同模式展开（Variables 表 + Example 一行）。
|
||||
|
||||
### F0 当量归一口径（weaken 锚裁决）
|
||||
|
||||
**结论**：采用"每结算瞬时当量"口径；m_w 值域 [60, 85]、默认 −65；地板交叉层数 = 2；B3/B4 零接口修订（值变更走 registry 回写）。
|
||||
|
||||
#### 推导
|
||||
|
||||
- **同分母性**：weaken 与 defense_up 作用于同一伤害流，"严格大于"在百分点读法与 HP 读法下等价，锚判定无量纲歧义。
|
||||
- **机制同构**：B3 本就按结算逐次兑付，瞬时口径是容器原生口径；"每 AP 总暴露"需跨结算累计账本，与已锁的"单结算自然边界"冲突。
|
||||
- **schema 禁止**：总暴露口径需 m_w > 100，越出 percent ∈ [−100, 100] 域，改域 = 三侧换算连锁，成本不成比例。
|
||||
|
||||
### F2 乘区合成
|
||||
|
||||
**结论**：池内加算 → 每池独立 clamp [−100, +100] → 池间乘算 → floor 单一取整；免伤轮（D'=0）是合法设计态，产零值伤害行、不调 apply_damage。
|
||||
|
||||
#### 公式
|
||||
|
||||
```
|
||||
P_pool = Σ(同池实例 L×m) 池内加算
|
||||
P_pool ← clamp(P_pool, −100, +100) 每池独立地板
|
||||
M_pool = 1 + P_pool ÷ 100 域 [0, 2]
|
||||
D' = floor(D_raw × M_hero × M_enemy) 池间乘算，单一取整
|
||||
```
|
||||
|
||||
例：D_raw=20、weaken L=2 → P=−130 → clamp −100 → M=0 → D'=0（零值伤害行）。
|
||||
|
||||
### F4 条款③挖掘风险不等式
|
||||
|
||||
**结论**：默认行值通过（锚行口径 L1≈2.0× / L2≈2.6×；跨行期望口径 1.2× / 1.5×，二元结论一致）；满配 unit_count=3 破线 → 登记 C3 调参约束。actuals p10 交付后强制重跑。
|
||||
|
||||
#### 公式与验算
|
||||
|
||||
```
|
||||
主式：P(安全) × V_safe > P(雷) × V_mine （决策单位=单格挖掘；评估点=残余盲猜端最坏点）
|
||||
P(雷) = |M| ÷ (|M| + (1−ι)×|S|) （残余盲猜端上界）
|
||||
V_safe = D_ref（锚行满寿命恒等式）；V_mine = unit_count × m_amb
|
||||
域守卫：(1−ι)×|S| < 1 ⇒ 主式不评估，信息端平凡腿接管
|
||||
```
|
||||
|
||||
| 板形 | P(雷) | 左臂 | 右臂 | 裕度 | 判定 |
|
||||
|---|---|---|---|---|---|
|
||||
| L1（\|M\|=9，\|S\|=91，ι=0.95） | 0.664 | 4.03 | 1.99 | ≈2.0× | ✓ |
|
||||
| L2（\|M\|=16，\|S\|=128，ι=0.92） | 0.610 | 4.68 | 1.83 | ≈2.6× | ✓ |
|
||||
| 满配（unit_count=3，V_mine=9） | 0.664 | 4.03 | 5.98 | <1 | ✗ 破线 → C3 约束 |
|
||||
|
||||
注：C3 不得以锚行读数（2.0×/2.6×）作为 unit_count=2 的放行依据。
|
||||
|
||||
### F5 条款⑤清图支配性
|
||||
|
||||
**结论**：**未闭合**（挖穿残余池计价，两态为负）→ C3/B4 约束包：C 量级上调，或裁"清图非严格支配"为设计态，二选一归 C3。
|
||||
|
||||
#### 公式
|
||||
|
||||
```
|
||||
Δ_clear = [R_res + C_eff] − [X_res + Δr × s_ref] （主判式，≥0 为闭合）
|
||||
E[踩雷] = |M| × n_s ÷ (n_s + 1) （挖穿残余池期望，均匀交错模型）
|
||||
```
|
||||
|
||||
### 边界参数总表
|
||||
|
||||
| 参数 | 边界 | 默认 | 出处 |
|
||||
|---|---|---|---|
|
||||
| percent 池 clamp | [−100, +100] pp，每池独立收口 | — | F2 |
|
||||
| 池乘数域 | [0, 2]（= 1 + pp/100） | — | F2 |
|
||||
| m_w（weaken 行值） | [60, 85] | −65 | F0 裁决（瞬时当量口径） |
|
||||
| 地板交叉层数 | ⌈100/m_w⌉ = 2（值域内恒 2） | — | F0 |
|
||||
| P_perfect 载体域 | **{100, 200}**，域外加载致命 | 200（×2 双份交付） | Core Rule 13 |
|
||||
| D_ref（当量参考敞口） | [1, 999] | 12 | SettlementTable |
|
||||
| HeroTable.atk | [1, 999]，0 加载拒绝 | 6 | 2026-09-11 拍板 |
|
||||
| 伤害 D' | 整数 [0, ∞)，零负值分支 | — | F3 |
|
||||
| D' = 0 | **不调** apply_damage，产零值伤害行 | — | 负值分支禁令 |
|
||||
| 取整 | floor，单一规则（结构性，非 knob） | — | F2 |
|
||||
| 溢杀 | 丢弃，不转移、无负 hp 态 | — | F3 |
|
||||
| 治疗 | hp' = min(hp + power, max_hp) | — | F3 |
|
||||
|
||||
### SettlementTable schema（单行全局，B1 回填 owner）
|
||||
|
||||
| 字段 | 类型/域 | 默认 | knob |
|
||||
|---|---|---|---|
|
||||
| equivalence_ref_damage（D_ref） | int [1,999] | 12 | ✓（变更触发全对账重跑） |
|
||||
| p_perfect | percent {100, 200} | 200 | ✓ |
|
||||
| effect_pool_map | effect_id → {hero_offense, hero_defense, enemy_output, flat_attach} | — | ✗ |
|
||||
| rounding_direction | floor（结构性） | floor | ✗ |
|
||||
| pool_clamp_lo / pool_clamp_hi | int | −100 / +100 | ✗ |
|
||||
| source_label_map | 键集 = source_class 全集 | — | 随接口漂移 |
|
||||
|
||||
## 状态
|
||||
|
||||
| 状态 | 进入条件 | 行为/出口 |
|
||||
|---|---|---|
|
||||
| Uninit | 冷启动 / 清理完成 | 唯一出口 `begin_battle` |
|
||||
| BattleSetup | `begin_battle` 受理 | 战斗开始序列；任一步拒绝 = fail-fast 上抛 |
|
||||
| RoundActive | `notify_round_start` | 不干预挖掘，只缓冲事件流 |
|
||||
| RoundWaiting | 轮次结束事务达成 | 执行七段结算；窗口段为唯一玩家输入点 |
|
||||
| BattleOver | 判定段产胜负 | 战斗结束序列 → Uninit |
|
||||
|
||||
不变式：同时刻至多一个结算事务在飞；段序恒全序（短路是段内规则非跳段）；跨系统调用集中在 B1。
|
||||
|
||||
## 边界情况
|
||||
|
||||
| 条件 | 行为 | 依据 |
|
||||
|---|---|---|
|
||||
| 末图清图即胜利 | 清图奖励先兑付 → 窗口可选用 → 战斗段空转 → 衰减 → 判胜 | B4 E15 |
|
||||
| 战斗段 hero hp=0 | 立即短路，剩余敌不作用不产行 | 用户拍板 |
|
||||
| 判定时敌我双 hp=0 | 结构不可达；防御规则 hero 先判 | Core Rule 12 |
|
||||
| 合成后 D'=0 | 不调 apply_damage，产零值伤害行 | 负值分支禁令 |
|
||||
| 伤害溢出 | 溢出丢弃；行 value=D'、击杀布尔，不记溢出量 | F3 |
|
||||
| charge 拍本轮踩雷 | 伏击授予照常；战斗段零伤害，池 dur=1 蒸发 | B2 EC8 |
|
||||
| 全体存活敌同拍 charge | N 行蓄力行、零伤害——合法状态 | B2 EC |
|
||||
| 伏击池 L=0 时敌攻击 | D_raw=纯基线 atk，自然读值非缺失分支 | B2 F2 |
|
||||
| 刀施加时已无存活敌 | 照常消耗 + "已消耗未生效"行 | B4 E10 |
|
||||
| 窗口打开时库存空 | 跳过合法；D1 可不弹窗；段序零停顿 | B4 E8 |
|
||||
| 挖掘期刷新 RAP 不足 | `request_refresh` 返回 false，原样上抛拒绝 | A3 EC13 |
|
||||
| 同轮多次刷新（cap 内） | 每次独立走换图全序，取新 scope | A3 EC15 |
|
||||
| 清图槽 buff 且满层 | 零兑付 + "奖励未生效"行；完美高光降级不发 | B4 E11 |
|
||||
| 完美谓词在刷新图上 | 刷新图无兑付点，不触发；flag 计数随 install 重置 | Core Rule 13 |
|
||||
| 板内既有标中又有误标 | 完美不成立；首个误标产"标旗未中"行（perfect_broken） | 单档完美，两档扩展被否 |
|
||||
| 多敌同结算攻击 | 行主序逐敌、共享 L；任一作用后 hero 死 → 短路 | Core Rule 10 |
|
||||
| battle_over 清理中被拒 | 诊断 + 幂等兜底；清理序列必须完成 | 防半清理态泄漏 |
|
||||
| 战斗中热重载请求 | 门已置位 → D2 拒绝返回 false | D2 EC8 |
|
||||
|
||||
## 依赖
|
||||
|
||||
**上游**（除 C1/C2 外全部 Approved——B1 是首个上游全就绪的系统）：
|
||||
|
||||
| 系统 | 性质 | 接口要点 |
|
||||
|---|---|---|
|
||||
| D2 | hard | SettlementTable（B1 回填）+ `set_reload_gate` 唯一调用方 |
|
||||
| A3 | hard | 五条款下游契约（B1 为①②③⑤闭合 owner）+ 结算回发 + `last_round_end` |
|
||||
| A2 | hard（订阅） | 三事件流 + `install_board`/`retire_board` + Waiting 观测量 |
|
||||
| B2 / B3 / B4 | hard | 全调用面 + 各自义务清单（义务明细在 registry，不在本文） |
|
||||
| A1 | 间接 hard | `generate` 换图 + actuals p10 对账输入 |
|
||||
| C1/C2 | provisional（未设计） | encounter 上下文由 `begin_battle` 入参封装隔离 |
|
||||
|
||||
**下游**：D1（明细流水=统一数据源契约，呈现义务台账在 registry）· B5（步骤流=动画回放脚本源）· D4/D5（音频/教学事件源）· C3（对账结论=调参约束）。
|
||||
|
||||
## 版本历史
|
||||
|
||||
| 版本 | 日期 | 改动 |
|
||||
|---|---|---|
|
||||
| lean-sample | 2026-09-13 | 格式重排样例：修订注记出正文→版本表；规则/枚举/边界/边界情况转表格；流程转字符图。语义与 b1-settlement.md Rev 1 对齐，未改任何现行规则 |
|
||||
| Rev 1 | 2026-09-10 | design-review 8 项 blocking 核销（完美排雷双份载体、条款⑤计价模型重推、流水协议分层、hit=false 零值行、P_perfect 换算成文等）——明细见 review log |
|
||||
| v1 | 2026-09-10 | 一次会话定稿（F0–F5 + 43 条 AC + 23 条上游义务落位） |
|
||||
| D4 修订 | 2026-09-12 | 刷新决策前移挖掘期：新增"挖掘期刷新"出口行，作废原 Waiting 期代理调用 |
|
||||
| 2026-09-11 拍板批 | 2026-09-11 | 主角先手攻击（hero_attack 来源）、两级奖励、窗口单件制、库存关内延续 |
|
||||
@@ -0,0 +1,22 @@
|
||||
# 试玩问题记录
|
||||
|
||||
## 垂直切片 v1
|
||||
|
||||
### 核心循环
|
||||
|
||||
1. 减伤太多；
|
||||
- 不要固定值，换成百分比，需要有百分比上限；或者固定上限
|
||||
2. 增伤也太多了；
|
||||
- 考虑替换安全格的奖励占比，增加一种冒险内的累计资源（比如：金币，只能用于冒险内购买道具；）
|
||||
3. 玩家攻击和怪物攻击不对等
|
||||
- 考虑引入命中（AC like），但是造成伤害的方式要区分开；
|
||||
4. 每次开图就是开了片面积；
|
||||
- 是否有生成图计算如此？
|
||||
5. 现在还是不能开已经被标记为雷的安全格,或者说不能开被标记的格子这跟我们之前的设定是相悖的.你有个会话说是已经修复了,但其实并没有修复.你并没有对应的测试,我需要你补全对应的测试,并且修复这个 bug; 不要把原本的扫雷的规则观念带进来,我们这里是有魔改的
|
||||
|
||||
6. 第二关显示时，棋盘最底下会有一点显示不出来，也就是最下面一排的格子不是一个完整的正方形，会缺失 1/6 的高度。
|
||||
你可以把棋盘下面预留一定的空间，大概是 1/4 方格的空间或者是一个固定的值，让棋盘的最底下不要贴着游戏的边框。
|
||||
|
||||
# 想法
|
||||
|
||||
1. 是否有可能将AP改成时间制? 但是这会让单回合上限无限拔高, 有点变态了
|
||||
@@ -0,0 +1,260 @@
|
||||
# 敌人技能池出招系统提案
|
||||
|
||||
> 一句话：废除确定性行为环，改用"技能池 + 开轮摇号"决定敌方每次行动——本文收拢全部拍板记录、逐维度设计、登记约束回应与实施批切分。
|
||||
> 状态：已定稿（2026-09-16 全部决策点拍板收口）
|
||||
> 性质：提案/评审件，不在 GDD 规范树内；本文不改任何既有文件，所登记的修订面随实施批落进各系统文档（见 §7）
|
||||
> 前置：实施批排在 AC 掷点批落批之后（该批文件集 `core/`、`enemy.tres`、结算文档冻结中）
|
||||
|
||||
## 1. 方向复述与拍板记录
|
||||
|
||||
已拍板方向：废除现行确定性行为环（地精单拍环、熊地精三拍环、食人魔酋长四拍 Boss 环、全场同种锁步同拍、死亡冻结指针），改为技能池——每个敌种一张技能池，池元素是带出招权重的技能行，每一拍从池中摇一个技能执行，出招序列不再固定；蓄力不再绑死重击前奏；质感目标 = 动作游戏怪物 AI：以普通攻击为基底，随机时机出特殊技。
|
||||
|
||||
对话裁决全记录（均为 2026-09-16；"纠偏"= 用户对早期口径的修正，一律以纠偏后为准）：
|
||||
|
||||
| # | 决策点 | 定稿口径 |
|
||||
|---|---|---|
|
||||
| 方向 | 出招系统 | 每敌种一张技能池（带权重技能行），每拍摇号出招；固定出招剧本废除 |
|
||||
| D1 | 抽取机制 | 权重份额归一 + 双闸；纠偏后闸形态 = 全技能各自冷却 + 保底；条件触发器后置 |
|
||||
| D2 | 数据结构 | 池模板内嵌敌行 + 技能定义独立技能表（skill_id 引用共享） |
|
||||
| D3 | 蓄力处置 | 蓄力 = 独立的 0 伤害增益技；原子连招技否决；前摇属性不引入 |
|
||||
| D4/D5 | 可见性 | 池与权重不公开、不做技能池界面；特殊技开轮类型级技能动画（纯提醒）；普通攻击零表示 |
|
||||
| D6 | 随机流 | behavior_roll 主流 + 每敌按生成序派生独立子流 |
|
||||
| D7 | 新技扩展 | 每敌种 +1 新技位；敌方防御池进切片（硬化技） |
|
||||
| D8 | 伤害公式 | 三乘法链落战斗结算（§6） |
|
||||
| D9 | 实现纪律 | 封装对象、高内聚低耦合、禁一次性脚本（§2.2） |
|
||||
| 纠偏一 | 冷却模型 | **所有技能各带冷却字段**（普通攻击冷却恒 0）；技能冷却与增益持续是两个计时器；保底保留。早期"冷却只锁高伤技"口径作废 |
|
||||
| 纠偏二 | 蓄力语义 | **蓄力 = 纯"攻击力增加"增益技，与重击无任何组合语义**——旧环"蓄力→猛击"是哥布林弹珠的拷贝，观念与相关文档表述一并清除；增益与倍率同拍只是两层乘法共存 |
|
||||
| 纠偏三 | 增益纪律 | **每池增益类技能 ≤1**——非 RPG，怪物连出不同增益显得呆 |
|
||||
| 纠偏四 | 概念区分 | 行动轮概念**完全退役**；nat20 暴击（掷点层）≠ 技能重击（池技能），两层严格区分 |
|
||||
| A | 同种多敌 | 一份池模板 + 每实例自己的实例池（快照 + 冷却状态），独立摇号；轨迹分歧是涌现，开战分配机制不存在；个体化变体池标 P1 |
|
||||
| B | 摇号时点 | **开轮摇号**：技能选择前置到轮次开始，数值计算留在结算段 |
|
||||
|
||||
## 2. 逐维度设计
|
||||
|
||||
### 2.1 抽取机制：权重份额归一 + 全技能各自冷却 + 保底
|
||||
|
||||
每个敌实例每一拍做什么，由一次摇号决定：把它实例池里冷却中的技能排除，剩下的技能按权重份额归一摇一个。**中签率 = 该技能权重 ÷ 当前可摇技能权重合计**——权重是份额不是固定百分比，排除谁，谁的份额按比例摊给其余技能。
|
||||
|
||||
示例（熊地精池：基础攻击 6 · 蓄力 2 · 重击 2）：
|
||||
|
||||
| 回合 | 可摇集合 | 基础攻击 | 蓄力 | 重击 |
|
||||
|---|---|---|---|---|
|
||||
| 第 1 拍 | 全部（合计 10） | 60% | 20% | 20% |
|
||||
| 第 2 拍（第 1 拍摇中重击，重击冷却 3 拍） | 普攻+蓄力（合计 8） | 75% | 25% | 0%（冷却中） |
|
||||
| 第 3 拍（第 2 拍若摇中蓄力） | 仅普攻 | 100% | 0%（冷却中） | 0%（冷却中） |
|
||||
|
||||
开轮摇号时序（共识点 B 定稿）：
|
||||
|
||||
```
|
||||
开轮（轮次开始）：每实例 冷却递减 → 排除冷却中技能 → 按行序逐敌摇定本拍行动（behavior_roll 各敌子流）
|
||||
挖掘期：按摇定结果播动画（特殊技 = 技能动画，普通攻击 = 零表示）
|
||||
结算段：按技能行兑现——AC 掷点、三乘法链、增益挂接、明细落行（与现行完全相同）
|
||||
判定段之后进入下一轮开轮……
|
||||
```
|
||||
|
||||
时点细则：首轮同样开轮摇号；每轮恰摇一次，挖掘期中途刷新换图不重摇；摇定后、兑现前死亡（主角先手 / 授予段直伤）→ 本拍技能作废、不动手（死亡即不动手，与现行同构）。
|
||||
|
||||
两道闸：
|
||||
|
||||
| 闸 | 语义 | 建议值（provisional，归难度曲线） |
|
||||
|---|---|---|
|
||||
| 技能冷却 | 每技能行带冷却拍数；施放后连续 N 拍不可摇中；普通攻击恒 0 | 普攻 0 · 突刺 2 · 蓄力 3 · 重击 3 · 硬化 4 |
|
||||
| 保底 | 连续 M 拍执行的都是普通攻击 → 下一拍必出特殊技（特殊技内按权重，不受冷却限制） | M = 4 |
|
||||
|
||||
结构保证与校验：普通攻击冷却恒 0 → 池恒非空，最坏情况（全部特殊技同时进冷却）怪物平砍等待，那是玩家的反打窗口而非死拍。加载期校验兜底：每池恰一行普通攻击、增益技 ≤1、池条目 skill_id 悬空致命、权重 > 0、冷却 ≥ 0，违规拒绝入表。
|
||||
|
||||
连发账：同一技能连发不可能（自身冷却杜绝）；异名特殊技背靠背可能但概率低（上例 ≈14%，任意两拍"特殊→特殊" ≈3.6%），是变化不是失控。不建议全局特殊间隔闸——它会把节奏变成可背诵的"特殊→N 平砍→特殊"，标 P1 备用旋钮。
|
||||
|
||||
摇号只决定"做什么"；伤害多少由三乘法链在结算段算（§6）。
|
||||
|
||||
### 2.2 数据结构与封装切分
|
||||
|
||||
三层对象，模板与实例分离（共识点 A 定稿）：
|
||||
|
||||
| 层 | 对象 | 载体 | 职责 |
|
||||
|---|---|---|---|
|
||||
| 定义层 | 技能行 | 独立技能表（数据配置承载、敌人系统回填） | 技能是什么：类型、倍率、冷却、效果引用——多敌种共享 |
|
||||
| 定义层 | 池模板 | 内嵌敌行 pool 数组：{skill_id, weight} | 敌种用什么、多常用——难度曲线的调参单点 |
|
||||
| 实例层 | 实例池 | 单位实例（开战把模板快照一份） | 这一只在什么状态：各技能冷却剩余、活跃增益、摇号轨迹 |
|
||||
|
||||
生成流程：开战 → 读敌行池模板 → 每实例快照出自己的实例池（冷却全零）→ 此后各自独立摇号、互不干涉。怪物 1 的猛击在冷却里不影响怪物 2。与现行"生成拿到当时的表值快照、之后改表不影响已生成单位"同一条快照纪律，池纳入快照范围。
|
||||
|
||||
技能行字段词汇表：
|
||||
|
||||
| 字段 | 适用类型 | 说明 |
|
||||
|---|---|---|
|
||||
| skill_id | 全部 | 主键，池条目引用键 |
|
||||
| display_name | 全部 | 玩家可见名（明细行与动画共用） |
|
||||
| type | 全部 | 封闭枚举 {普通攻击, 伤害, 增益}；新类型走文档修订（同现行行为拍枚举纪律） |
|
||||
| damage_mult | 仅伤害 | 伤害倍率；域 [1.1, 16] provisional。普通攻击恒 1、不可配 |
|
||||
| cooldown_beats | 全部 | 施放后连续 N 拍不可摇中；普通攻击恒 0、不可配 |
|
||||
| buff_ref | 仅增益 | 效果引用，指向既有状态效果行（现有效应词汇） |
|
||||
| buff_duration | 仅增益 | 增益持续回合数（结算数） |
|
||||
| P1 字段位 | — | 触发条件、命中段数、目标数、固定值分量——随对应后置批加列 |
|
||||
|
||||
普通攻击也是一行技能行（type=普通攻击），两条域校验锁死它的特殊性：倍率恒 1、冷却恒 0——想配倍率或冷却的就不是普攻，是伤害技。
|
||||
|
||||
技能伤害存倍率、不存固定值：伤害 = 施放者攻击基线 × 技能倍率（§6 第一乘）。同一行"猛击"，地精用是 7×2=14，熊地精用是 9×2=18，深层强化行自动缩放——这是共享技能表成立的前提；固定值分量若将来需要，是加字段的事（P1）。增益技带效果引用与持续回合，百分比天然按施放者生效，无缩放问题。
|
||||
|
||||
封装纪律（D9）：抽签器是独立服务类（输入实例池与随机子流、输出技能 id，不碰血量不碰表）；战斗段只做编排；单位容器保持零随机零事件——摇号的执行方是战斗结算换算层，单位收到的是确定结果（与 armor_roll 先例同构）。禁止一次性强耦合脚本。
|
||||
|
||||
### 2.3 蓄力与旧概念清除
|
||||
|
||||
蓄力不是重击前奏：它是一行增益技——0 伤害动作，施加"攻击×2"状态，持续 1 结算（provisional）。旧环"蓄力→猛击"的固定配对是哥布林弹珠的拷贝（给玩家输出窗口用的），随行为环一并退役；蓄力与重击之间**没有任何组合语义**——增益与技能倍率恰好同拍只是两层乘法共存（×2 遇 ×2 = ×4），蓄力后摇中普通攻击则是基线×2 的加成平砍，两者同为平常事，不是设计的连招。
|
||||
|
||||
两个计时器严格分账：**技能冷却**（几拍内不能再摇中，技能行属性）与**增益持续**（状态挂几回合，状态行属性）互不相干。
|
||||
|
||||
增益纪律（纠偏三）：每池增益类技能 ≤1。结构红利：增益存续期内下一拍必是伤害技（池里其余全是伤害技、增益自身还在冷却），**增益不可能白白过期**——"连出不同增益显得呆"的场景被池构成纪律结构消除。
|
||||
|
||||
敌方增益走既有增益状态容器（新状态行入状态表、新池映射随批登记 registry）。旧蓄力拍"零兑付、不读伏击"的语义由增益技继承：0 伤害技能不兑付伏击——"本轮喂的伏击若逢增益拍不兑现"的读怪奖励保留。
|
||||
|
||||
前摇（telegraph）不作为技能属性引入（D3 显式裁决）：规划窗口由开轮摇号 + 类型级动画承担（§2.4），旧"蓄力拍 = 规划窗口"的职责由它替代。
|
||||
|
||||
Boss 专属身份 = 专属池承载：独占技能 + 权重轮廓（现行建议：酋长池含独占增益技"硬化"）。旧"专属四拍环且含蓄力拍"约定随批改写（§7）。
|
||||
|
||||
### 2.4 可见性
|
||||
|
||||
池与权重不公开、无技能池界面（D4/D5 裁决）。摇号结果的信息面分三档：
|
||||
|
||||
| 摇中 | 挖掘期呈现 | 结算揭示 |
|
||||
|---|---|---|
|
||||
| 普通攻击 | 普通动画，零特殊表示 | 明细行"普通攻击（暴击/被压制）" |
|
||||
| 特殊技 | 技能动画（攻击系/防御系不同）——纯动画提醒，无额外语义 | 明细行具名技能 + 数值 |
|
||||
| nat20 暴击 | 无前置动画（掷点层，与技能重击严格区分） | 明细行"（暴击）"标注 |
|
||||
|
||||
即：普攻完全不可预测；特殊技有一次类型级预告，不可撤销，但给"继续挖还是停手"的决策依据。信息量比旧环少（不预告技能名与数值）、比全隐藏多，落在动作游戏怪物 AI 的纹理上。
|
||||
|
||||
HUD 替代位（ring_size/ring_index 环点行拆除）：敌人卡意图徽标语义改为"本拍摇定结果的动画占位"；具体视觉规格归战斗表现与 HUD 框架批。
|
||||
|
||||
### 2.5 切片范围与建议池内容
|
||||
|
||||
切片做：三敌种池化（EV 中性锚定）+ 敌方防御池新词汇 + behavior_roll 子流 + HUD 替代位 + 开轮摇号编排 + 文档与 registry 修订清单落地（§7/§8）。后置项见 §9。
|
||||
|
||||
建议池内容（全部 provisional，投值归难度曲线）：
|
||||
|
||||
| 敌种 | 池（权重） | 每拍 EV | 相对现行环 |
|
||||
|---|---|---|---|
|
||||
| 地精 | 普攻 9 · 突刺 1（新行：伤害 ×1.5，冷却 2） | 1.05 | +5%，显式登记 |
|
||||
| 熊地精 | 普攻 6 · 蓄力 2 · 重击 2 | 1.00 | 中性 |
|
||||
| 食人魔酋长 | 普攻 6 · 重击 2 · 硬化 2（新行：自防增益，敌方防御池词汇载体；旧蓄力拍退役、不进 Boss 池——增益 ≤1 纪律） | 1.00 | 中性 |
|
||||
|
||||
EV 锚定说明：含 0 伤害技能的池要保 EV=1.0，伤害技权重须抵偿增益权重份额（例：重击权重 = 硬化权重恰好中性）；像突刺这种倍率 >1 的新技必然抬 EV（正权重配不平），偏移量显式登记难度曲线、不硬凑。EV 锚按含闸长期速率在实施批复核。熊地精若复用突刺行，即共享技能表的活证明（候选）。
|
||||
|
||||
## 3. 现行环 → 技能池对照表
|
||||
|
||||
| 面 | 现行行为环 | 技能池（本提案定稿） |
|
||||
|---|---|---|
|
||||
| 出招决定 | 环序列 + 指针，步数取模，零随机 | 实例池权重摇号（开轮时点） |
|
||||
| 同步性 | 同种永远同拍（锁步） | 各实例独立摇号、独立冷却 |
|
||||
| 蓄力 | 重击前奏空拍（固定配对） | 攻击增益技（1 结算过期），无组合语义 |
|
||||
| 死亡 | 轮到前被杀，指针冻结 | 摇定技作废、不动手（死亡即不动手不变） |
|
||||
| 可见性 | 下一拍全程亮出（意图徽标 + 环点） | 特殊技开轮类型级动画、普攻零表示、池与权重不公开 |
|
||||
| 随机 | 系统零随机 | behavior_roll 封闭流、每敌子流、可回放 |
|
||||
| 表结构 | pattern 环数组（拍枚举封闭） | 技能表 + 敌行池模板 + 实例池 |
|
||||
| 调参 | 环读数、倍率 | 池 EV、权重/冷却/保底（难度曲线） |
|
||||
| 拍结构 | 每结算各行动一次、行序、先作用后推进 | **不变** |
|
||||
|
||||
## 4. 七条登记约束的逐条回应
|
||||
|
||||
**约束一（随机价值观兑现）**：进回合内的随机共两源——技能身份摇号（离散、具名、开轮时点）与 AC 掷点（数值、结算段）。固定出招剧本废除即本方向的兑现；"每拍数值抖动"的口子不开：每个技能实例的伤害由基线×倍率确定，随机器只决定技能身份与 AC 判断值。摇号时点前置到开轮是动画呈现诉求的代价，可回放契约不破（约束二）。
|
||||
|
||||
**约束二（零随机纪律修订面）**：敌人系统自身语义零随机不变（收到确定结果）；随机消费在战斗结算换算层新开封闭流 behavior_roll——STREAM_NAMES 增名、计数器、registry salt、derive 向量（armor_roll 先例同构）；每敌按生成序派生子流，单敌出招轨迹可独立复放、互不穿插。文档修订面：敌人系统结构冻结清单"零随机"注记随行为环退役改写；战斗结算随机消费清单两处 → 三处（开战掷骰 = 初始化随机；技能摇号 = 回合内、开轮时点、结算步骤流之外；AC 掷点 = 回合内、步骤流之内）；可回放契约扩写为"三处皆封闭流，同种子同输入逐位复现"。
|
||||
|
||||
**约束三（数字可读性锚）**：技能抽取 ≠ 数值抖动——抽的是离散具名的动作，明细行带技能名与倍率，数字仍由基线×倍率确定。"下一拍出什么"的可见性方案 = §2.4 三档；HUD ring_size/ring_index 显示位拆除，替代 = 摇定结果动画位 + 具名明细行。
|
||||
|
||||
**约束四（蓄力拍退役与前摇）**：删行为环时固定蓄力拍自动退役（登记收口）；前摇 telegraph 显式裁决为**不引入**——规划窗口职责由开轮预告承担；蓄力改为增益技（§2.3）。
|
||||
|
||||
**约束五（AC 掷点批耦合）**：判定对象措辞随池化改述，四处对照见 §6；暴击（nat20 ×2）、折扣档位（下限 ×0.25）、伤害下限 max(1,·) 全部挂在伤害实例上、语义不变；伏击附加必中全额、后置加法不进乘区。落批后随技能池实施批收编，AC 批落批前不动。
|
||||
|
||||
**约束六（难度曲线纪律联动改写）**："每关至少投放一项新内容（新敌种或既有敌种新行为环段）"→"新敌种或既有池新技能"；"保持行为环读数不变、数量优先"→"保持技能池 EV 读数不变（权重即旋钮、投值归难度曲线）"；Boss 约定"专属四拍环且含蓄力拍"→"专属池（独占技 + 权重轮廓）"；调参表 pattern 列改池列，新增权重、冷却、保底投值域；生存链区间模型的受伤峰值/谷值构成按含闸长期速率复核，EV 中性锚定、现行行值不重调。
|
||||
|
||||
**约束七（方差预算）**：见 §5。
|
||||
|
||||
## 5. 熵预算与方差对照
|
||||
|
||||
| 随机源 | 时点 | 每次熵 |
|
||||
|---|---|---|
|
||||
| d20 AC 掷点（既有） | 结算段，每伤害实例 | log2(20) ≈ 4.32 bit |
|
||||
| 技能摇号（新增） | 开轮，每实例 | 0.47–1.37 bit（建议池）；四技均分上限 2 bit |
|
||||
| 开战掷骰（既有） | 初始化 | 不变 |
|
||||
|
||||
技能摇号与单次 d20 同量级或更小，且承载的是结构多样性（出哪个动作）而非数值噪声——离散、具名、可归因。
|
||||
|
||||
锁步峰值的新形态（旧 D3 三敌同轮重击 12–54 问题的账）：
|
||||
|
||||
- 旧环：同步轮转定理 → 每 3 拍**必然**全体重击（概率 100% 的结构性峰值，周期可背诵）。
|
||||
- 池化（建议权重 6/2/2，EV 中性）：单敌重击率 20%，三敌同拍全重击 ≈ 0.8%/拍；长期输出速率由 EV 锚定不变；冷却闸削簇（同敌重击后必隔数拍），保底闸削旱季。峰值从"必然周期"变"低概率事故"，分布形状（重击频率）是难度曲线的自由调参维度——想要更高频重击就抬权重，EV 随之重锚。
|
||||
|
||||
## 6. AC 规格修订措辞建议
|
||||
|
||||
**三乘法链**（结论先行：技能倍率乘在最前，AC 判断值与甲效依次乘上去，其后既有链一字不动）：
|
||||
|
||||
```
|
||||
① 攻击伤害值 A = 攻击基线 × 技能伤害倍率 （普通攻击倍率恒 1；主角侧恒 1）
|
||||
② AC 判断值 a：d20 vs 防守方护甲等级
|
||||
掷点 < AC → 档位折扣（量程下限 ×0.25）；nat20 → 暴击 ×2（量程上限）
|
||||
③ 命中伤害 H = (A × a) × 甲效倍率 （克制 1.5 / 中性 1.0 / 被克 0.5；敌打主角无甲轴恒中性）
|
||||
── 以下既有链不动 ──
|
||||
增益池乘区（含新敌方防御池）→ 伏击附加（后置加法、必中全额、不吃 AC）→ 向下取整 → 伤害下限 max(1,·)
|
||||
```
|
||||
|
||||
判定对象措辞修订（落点 = 战斗结算.md，伤害合成链的 owner；敌人系统只供技能行数据）：
|
||||
|
||||
| 位置 | 现行措辞 | 建议措辞 |
|
||||
|---|---|---|
|
||||
| 战斗段正文 | 敌方攻击拍与重击拍的基线伤害（基线 × 重击倍率） | 敌方技能的基础伤害分量（= 攻击基线 × 技能伤害倍率）；无伤害分量的技能（增益类）不掷不折 |
|
||||
| 公式行 | 吃掷点分量 = 主角普通分量 / 敌方攻击拍与重击拍基线 | 吃掷点分量 = 主角普通分量 / 敌方技能基础伤害分量 |
|
||||
| 调参表边界行 | （主角普通分量、敌方攻击/重击拍基线） | （主角普通分量、敌方技能基础伤害分量） |
|
||||
| 验收标准 | 敌方攻击/重击拍基线 | 敌方技能基础伤害分量 |
|
||||
|
||||
不变项：nat20 ×2、档位折扣、伤害下限、伏击必中后置、逐次掷逐次取号（未来多段命中 = 每段一掷，P1 预留）。
|
||||
|
||||
## 7. 修订面清单（按文档）
|
||||
|
||||
跨三个循环 + 两个横切件；排雷循环零触及（挖掘期、行动经济、棋盘、道具、变异全不碰）。跨循环不是范围蔓延——按引用纪律的删除概念流程查"行为环"反向边，其读数本被织入曲线纪律与呈现义务，影响面即下表。
|
||||
|
||||
| 循环 | 文档 | 修订面 | 深度 |
|
||||
|---|---|---|---|
|
||||
| 战斗循环 | [敌人系统](../design/gdd/systems/战斗循环/敌人系统.md) | 主 owner：行为环章节退役，技能池/技能行/实例池/冷却/开轮摇号语义成文，蓄力语义改写（清"重击前奏"表述），敌人表 schema（pattern → 池），结构冻结清单与验收标准重写 | 重 |
|
||||
| 战斗循环 | [战斗结算](../design/gdd/systems/战斗循环/战斗结算.md) | 开轮摇号时点与随机口径三处、三乘法链、AC 措辞四处（§6）、行型改型（蓄力行 → 施放行）、敌方防御池、可回放契约扩写 | 重 |
|
||||
| 战斗循环 | [战斗表现](../design/gdd/systems/战斗循环/战斗表现.md) | 敌种姿态数据面（普攻零表示、特殊技攻/防系动画映射）、样张验收联动 | 中 |
|
||||
| 战斗循环 | [增益状态](../design/gdd/systems/战斗循环/增益状态.md) | 敌方增益状态行挂载、敌方防御池容器语义延伸 | 轻 |
|
||||
| 冒险循环 | [难度曲线与Boss](../design/gdd/systems/冒险循环/难度曲线与Boss.md) | 曲线纪律改写、Boss 约定、调参表（池列 + 权重/冷却/保底投值域）、区间模型口径 | 中 |
|
||||
| 表现与支撑 | [HUD 框架](../design/gdd/systems/表现与支撑/HUD框架.md) | 敌人卡义务改写（意图徽标语义、环点拆除）、验收条目 | 中 |
|
||||
| 横切 | registry entities.yaml | enemy / rng_service / settlement / status_effect 条目 + §10 术语 | 必 |
|
||||
| 横切 | [06-待办清单](../design/gdd/06-待办清单.md) | 旧条目收编关闭（如"删行为环取消蓄力拍"、"单拍行为环体验验证"改型）+ §9 登记 | 必 |
|
||||
|
||||
数据与代码（实施批范围，非文档修订面）：`enemy.tres` 与新技能表、schemas、`core/`（unit_container / battle_orchestrator / rng_service）、`presentation/`（enemy_card_view / battle_log_view / status_slot_row）、smoke。
|
||||
|
||||
## 8. 实施批切分
|
||||
|
||||
前置门：AC 掷点批收编提交（工作区干净、smoke 全绿）后才开工；本提案自身零代码、零表改、不改任何既有文档。
|
||||
|
||||
| 批 | 范围 | 交付与验收 |
|
||||
|---|---|---|
|
||||
| 批 1 核心机制 | 技能表 schema 与数据、敌表池字段、单位容器实例池与冷却、编排器开轮摇号与战斗段兑现、随机服务 behavior_roll 与每敌子流、建议池行值 | smoke 全绿，含：同种子回放逐位复现、单敌轨迹独立复放、EV 抽样对锚、死亡打断前摇作废、空池不可能、加载校验拒绝 |
|
||||
| 批 2 呈现替代 | 敌人卡摇定动画位、结算明细技能具名行、状态槽敌方增益显示 | 呈现只读面字段同步、行格式化同步 |
|
||||
| 批 3 文档与 registry | §7 全表落文、06 待办登记、registry salt 与术语 | 死链检查全绿 |
|
||||
|
||||
批间纪律：并行批用互斥文件集、批末跑全量验证（既有批处理纪律）。
|
||||
|
||||
## 9. 后置登记位（P1/P2）
|
||||
|
||||
| 优先级 | 项 | 说明 |
|
||||
|---|---|---|
|
||||
| P1 | 情境条件触发器 | 低血触发防御、玩家停手时的偷袭技等；载体 = 技能行触发条件字段 |
|
||||
| P1 | 个体化变体池 | A 型好斗/B 型守势、精英专属池（共识点 A 的 A2 案） |
|
||||
| P1 | 全局特殊间隔旋钮 | 特殊技背靠背实测仍嫌时的备用闸 |
|
||||
| P1 | 新效应词汇批 | 妨害技（对主角施减益）、固定值分量、多段命中（每段一掷） |
|
||||
| P1 | 第二关池与投放 | 归难度曲线内容批 |
|
||||
| P2 | 敌方技能图鉴/学习呈现 | 玩家侧技能知识系统 |
|
||||
|
||||
## 10. 术语候选（registry 术语条目登记用，随批定稿）
|
||||
|
||||
技能池（池模板）· 实例池 · 技能行 · 开轮摇号 · 保底 · 技能冷却 · 施放行（行型）
|
||||
|
||||
## 版本历史
|
||||
|
||||
| 版本 | 日期 | 改动 |
|
||||
|---|---|---|
|
||||
| v1.0 | 2026-09-16 | 首版定稿：方向复述与拍板记录（D1–D9 + 四点纠偏 + 共识点 A/B）、五维度设计、七条约束回应、对照表、熵预算、AC 措辞、修订面清单、实施批切分 |
|
||||
@@ -0,0 +1,86 @@
|
||||
# proposal-status-vocabulary（技能池新效应词汇批——设计权威）
|
||||
|
||||
- 版本：v1.0（2026-09-19 用户拍板定稿）
|
||||
- 设计权威地位：同 docs/proposal-skill-pool.md v1.0 先例——本文档为技能行「妨害类型 + 必中附加分量」的语义权威；GDD（敌人系统 / 战斗结算 / 增益状态）与 registry / 切片实现以本文为锚同步。
|
||||
- 上位纪律：小整数加法核（01-核心循环 数值语言条款）；技能基线倍率 = 合法乘法位（台账 79 登记义务随批兑现）。
|
||||
|
||||
## 0. 三词收敛为两词（用户拍板 2026-09-19）
|
||||
|
||||
原登记三类新效应词汇，经对答会话逐项裁决：
|
||||
|
||||
| 原词汇 | 裁决 | 去向 |
|
||||
|---|---|---|
|
||||
| 妨害技（对主角施减益） | ✅ 立项 | 新增第四技能类型，见 §1 |
|
||||
| 固定值伤害分量 | ✅ 改形立项 | **必中附加分量**（§2）——"固定值不通用/跨关稀释"析出此改形：固定值不随攻击基线缩放，与共享技能表"行值随敌种缩放"前提冲突（Brotato 稀释教训镜像）；真正的设计需求是"躲不掉的稳定伤害"，由必中小倍率承载 |
|
||||
| 多段命中（每段一掷） | ❌ 退役 | 用户拍板：本作无防御磨损体系，多段失去"打高甲更疼"的对照机制，不实装；P1 字段位「命中段数」保留以防将来复活 |
|
||||
|
||||
实装面收窄（用户拍板）：**仅第二关 Boss 蛛化卓尔精灵（drider）**——毒爆挂必中毒分量 + 新妨害技；其余敌种不动。
|
||||
|
||||
## 1. 妨害技（debuff）
|
||||
|
||||
### 1.1 语义
|
||||
|
||||
敌方对**主角**施加负面状态的特殊技。执行形态与增益技同族：**0 伤害施放行**（cast）——不掷不折、不兑付伏击（"本轮喂的伏击逢施放拍不兑现"的读怪奖励保留）；状态授予经唯一进货口进容器，**落点由状态行 `target_side` 路由**（妨害技引用 hero 侧行 → 自动落在主角），容器语义零改动。
|
||||
|
||||
### 1.2 字段与校验
|
||||
|
||||
- 技能类型枚举 {普通攻击 basic, 伤害 damage, 增益 buff} **+ 妨害 debuff**（封闭枚举修订——敌人系统结构冻结项，本批即修订批）。
|
||||
- 字段复用 `buff_ref` / `buff_duration`（效果引用 + 施放持续回合；技能冷却与增益持续两计时器分账的既有口径不变）。适用面措辞从"仅增益"扩为"增益与妨害"。
|
||||
- 域校验：妨害技禁配 damage_mult / rider_mult；必带 buff_ref；buff_duration ∈ [1,99]。
|
||||
- 跨表校验（ConfigDB）：buff 行的引用必须指向 **enemy 侧**状态行；debuff 行的引用必须指向 **hero 侧**状态行（side 守卫，防反向挂接）。
|
||||
- 池构成纪律 +1：**每池妨害技 ≤1**（与"每池增益 ≤1"同构——非 RPG，怪物连出不同妨害显得呆）。
|
||||
- 妨害技是特殊技：进保底闸（M 拍普攻必出特殊技）、受冷却闸管辖（既有两闸零改动）。
|
||||
|
||||
### 1.3 载荷词汇（复用既有主角侧减益行，零新状态行）
|
||||
|
||||
| 词汇 | 状态行 | 轴 | 现有来源 | 妨害技引用 |
|
||||
|---|---|---|---|---|
|
||||
| 失衡 | off_guard | AC 轴（掷点阈值下调） | 标空旗反噬 | ✅ **首发**（用户拍板） |
|
||||
| 乏力 | sapped | hero_offense 池（输出打折） | 雷格负向 | 第二词汇（暂不实装） |
|
||||
|
||||
首发 = **失衡**：蛛网束缚的"被缠住、破绽百出"读法与 AC 轴联动（更易被护甲骰全额命中），与必中毒分量的"躲不掉"构成 Boss 战的压制组合。
|
||||
|
||||
### 1.4 意图呈现
|
||||
|
||||
特殊技类型级预告从两族扩三族：攻击系 ⚔（朱红）/ 增益系 ✦（蓝）/**妨害系 ☠（紫）**。终稿动画归表现层样张后（美术清单 §2.3 同批口径），本批为占位符号。
|
||||
|
||||
## 2. 必中附加分量（rider）
|
||||
|
||||
### 2.1 语义
|
||||
|
||||
伤害技可携带的第二伤害分量：**必中全额**——不吃护甲骰（无折扣无暴击）、后置加法（伏击附加同族：不进乘区）。
|
||||
|
||||
### 2.2 字段与数值
|
||||
|
||||
- 伤害技新字段 `rider_mult`，域 (0, 1]，缺省无（无字段 = 无附加分量）。非伤害类型禁配。
|
||||
- 分量值 = `max(damage_floor, floor(施放者攻击基线 × rider_mult))`——随施放者攻击基线缩放（共享技能表前提保持），下限保底防 atk=1 出零点哑弹。
|
||||
- **价位锚（用户质询后修正）**：rider_mult = **0.75**，锚定 AC 折扣档表最轻档——"永远不会掉档的稳定伤害"。可掷分量期望对表：主角 AC10 ≈ 0.80、AC12 ≈ 0.76；必中 0.75 ≈ 中甲期望命中质量，天然克制堆护甲但不构成无脑溢价。×0.5 案（永久第三档）经用户质询否决。
|
||||
|
||||
### 2.3 结算位置与明细
|
||||
|
||||
```
|
||||
敌方伤害技终值 = max(damage_floor, 主分量链结果) + rider
|
||||
主分量链结果 = 现行三乘法链（基线×倍率 → AC 掷点折扣/暴击 → +克制点数〔敌方恒中性〕 → 伏击附加 → 池乘区 → floor）
|
||||
rider = max(damage_floor, floor(atk × rider_mult))——必中、必全额、不进乘区、不出暴击
|
||||
```
|
||||
|
||||
明细：零新行型——rider 随该技能的**伤害行**留档（payload `rider` 键），行文本后缀「＋附加N（必中）」。
|
||||
|
||||
### 2.4 首实装
|
||||
|
||||
毒爆 venom_burst（蛛化卓尔精灵独占）：damage_mult 2.5 不变，`rider_mult = 0.75`——atk 3 时毒分量 = 2 点（atk 区间 2–4 → 毒 1–3 点随开战掷定值缩放）。
|
||||
|
||||
## 3. 卓尔内容行（全部 provisional，投值归 难度曲线与Boss）
|
||||
|
||||
| 项 | 值 | 说明 |
|
||||
|---|---|---|
|
||||
| 毒爆 venom_burst | + rider_mult 0.75 | §2.4 |
|
||||
| 蛛网束缚 web_snare（新行） | type debuff · buff_ref off_guard · buff_duration 2 · 冷却 4 | duration 2 = 1 个有效结算（empower/fortify 先兑付后衰减含施放当轮口径）；失衡幅度沿用 off_guard 行值（AC 轴 −2，provisional） |
|
||||
| 卓尔池 | 普攻 6 / 重击 2 / 毒爆 2 / **蛛网束缚 2** | 权重 provisional；主分量 EV 权重期望 1.67 → 1.25，加蛛网束缚的零伤害拍与毒分量后待抽样复核 |
|
||||
|
||||
## 4. 验收要点
|
||||
|
||||
- 妨害技施放行落行、off_guard 落主角（投掷阈值 10 → 8 随行可读）；冷却/保底/死亡作废三既有闸对妨害技无一例外。
|
||||
- 毒爆伤害行 rider 键随行；停手轮（零池零伏击）下终值 = max(1, 掷点档位主分量) + rider 逐拍精确复算。
|
||||
- 加载校验拒绝：池妨害 >1 / 妨害缺 buff_ref / rider_mult 越域 / 非伤害技带 rider_mult / 妨害引用 enemy 侧状态。
|
||||
- 冒烟全绿 + 四探针 PASS；≥20 遍模拟试玩 + 日志数据分析（用户验收标准）；L2 Boss 行为变更并入验收读数重测批变量清单（07 头注）。
|
||||
@@ -0,0 +1,45 @@
|
||||
# 概念原型报告：扫雷 × 自动战斗
|
||||
|
||||
- **原型位置**：`prototypes/minesweeper-battle-concept/`（Godot 4.x，Engine 路径）
|
||||
- **日期**：2026-09-06 · 迭代 v1 → v3
|
||||
- **可证伪假设**：如果玩家通过扫雷决策为自动战斗获取道具，他们会感受到"每一步排雷都在影响战斗结果"的策略联动感。（验证信号：扫雷阶段主动规划目标；主动想进入下一轮）
|
||||
|
||||
## 假设判定：CONFIRMED（核心） / 部分确认（表现层）
|
||||
|
||||
用户（唯一测试者）在 v2 后反馈："**目前整体轮次的玩法是没有问题的**"，且确认小人边缘探索"更像地牢探险，氛围上 OK"。三层联动（挖雷→攒道具→结算兑现）作为循环骨架被接受并持续投入迭代——没有出现"战斗是过场"的否定信号。表现层（逐行结算文字）被判定"无所谓"（正式版将替换为战斗动画），兑现的**情绪强化**仍有待战斗动画验证。
|
||||
|
||||
## 迭代记录
|
||||
|
||||
| 版本 | 内容 | 用户反馈 |
|
||||
|---|---|---|
|
||||
| v1 | 全图点击挖雷，AP 12，逐格即时奖励 | AP 太多；想要小人控制；开/未开格难分辨；结算应统一画面而非即时生效 |
|
||||
| v2 | 小人控制（参考 MS Minesweeper Adventure 模式）、初始 3×3 安全区、AP 8、统一战斗结算画面、色块区分 | 地牢氛围 OK；结算画面无所谓（正式版上战斗动画）；**整体轮次玩法没有问题** |
|
||||
| v3 | 行动经济统一（插旗 1AP+1旗）、标雷判定（标中+5 拆弹奖励/标错无惩罚）、修延续图旗子重置 bug | 待终验 |
|
||||
|
||||
## 最好时刻
|
||||
|
||||
小人控制上线后循环"活"了：从"选格子"变成"走位规划"，挖/旗被锁定在小人相邻——位置本身成为资源（用户认可地牢探险感）。
|
||||
|
||||
## 最糟时刻 / 已修复问题
|
||||
|
||||
- v1 的 12 AP 节奏拖沓 → v2 降到 8 并引入走位成本
|
||||
- v1 奖励即时生效导致"点一格就像结算一次" → v2 改为统一入库、轮末结算
|
||||
- v3 前的 bug：延续图上旗子未随轮次重置（旗子资源凭空变多）→ 已修
|
||||
|
||||
## 意外发现
|
||||
|
||||
- 标雷判定把"插旗"从记账动作变成了**赌注式动作**——风险与收益同源原则（P3）的雏形在测试中自然浮现
|
||||
- 用户主动要求的"小人控制"与 Microsoft Minesweeper Adventure 模式高度吻合，验证了参考方向的合理性
|
||||
|
||||
## 遗留验证点（下阶段处理，不阻塞 PROCEED）
|
||||
|
||||
1. 标雷"赌注式动作"的实际使用率与手感（v3 终验）
|
||||
2. 标错惩罚是否需要（候选方案已登记，A2 GDD 前用小补丁实测）
|
||||
3. 停手折算比例（×2）的数值合理性（A3 GDD 定稿）
|
||||
4. 兑现的情绪强化（战斗动画）——垂直切片的 B5 验证
|
||||
|
||||
## Verdict: **PROCEED**
|
||||
|
||||
核心假设成立：扫雷决策与战斗结果的联动被测试者确认，循环骨架定稿并全部落入系统索引。下一步进入正式系统设计（GDD），用原型结论作为 Tuning Knobs 素材。
|
||||
|
||||
**PIVOT 记录**：无 PIVOT 链。原型代码不进生产（生产实现按 GDD 从零写，原型仅作参数与规则参考）。
|
||||
Reference in new issue
Block a user