docs(arch): 棋盘迁移文档修订——战斗屏进度条退场裁定落文（战后回关卡画面，进度只留关卡画面；退场落地随停点前移批，用户裁定 2026-09-23）
This commit is contained in:
DKChan committed
1 parent
00108b13c5
commit
b1756d2de0
2 files changed
+14
-10
No files matched your search
@@ -33,7 +33,7 @@ Accepted（2026-09-23 用户拍板方向；本 ADR 落文。Phase A 棋盘实施
|
||||
ADR-0003 Decision 3 将棋盘渲染冻结为「GridContainer + 逐格常驻控件」，并登记 _draw/自绘迁移为 D1 正式化候选、迁移前禁盲目动手（探针耦合是登记成本）。2026-09-23 用户拍板：表现层走 Node2D 重构，**只迁战斗棋盘**，开始菜单（ui_assembler build_start_overlay）与各覆盖层保持 Control——分工不是替换。原「禁盲目迁移」条款与现行裁决冲突，需要新 ADR 定向解禁并落分工边界。
|
||||
|
||||
### Constraints
|
||||
- 战斗屏四区布局与分区尺寸是 HUD框架 结构冻结项——本迁移只换渲染技术，四区结构、双舞台常驻、尺寸表零改动
|
||||
- 战斗屏四区布局与分区尺寸是 HUD框架 结构冻结项——本迁移只换渲染技术，四区结构、双舞台常驻、尺寸表零改动（战斗屏进度条退场与四区→三区重排由停点前移批按文档修订流程另行落地，与本批解耦）
|
||||
- 组合根纪律（ADR-0001）：核心写调用唯一落点不变；BoardView 信号外发 + 只读注入模式不变
|
||||
- 性能预算（HUD框架 引用值）：同屏 draw calls < 200；进入战斗屏 500ms 内首格可点
|
||||
- 美术终稿资产全部缺位（样张批未跑）——迁移必须以程序化占位服役为前提，不新增素材前置
|
||||
@@ -48,11 +48,11 @@ ADR-0003 Decision 3 将棋盘渲染冻结为「GridContainer + 逐格常驻控
|
||||
|
||||
**1. D 区棋盘本体迁 Node2D 渲染，BoardView 类名与公共面契约保持不变。**
|
||||
|
||||
BoardView（`presentation/views/board_view.gd`，现 extends Control + 内部 GridContainer）重构为：Control 壳参与四区布局不变，壳内经 **SubViewportContainer + SubViewport + Node2D 世界**（BoardWorld）渲染棋盘。对外契约逐项保持：
|
||||
BoardView（`presentation/views/board_view.gd`，现 extends Control + 内部 GridContainer）重构为：Control 壳参与屏幕栅格布局不变，壳内经 **SubViewportContainer + SubViewport + Node2D 世界**（BoardWorld）渲染棋盘。对外契约逐项保持：
|
||||
|
||||
| 契约面 | 消费方 | 保持方式 |
|
||||
|---|---|---|
|
||||
| 类名 `BoardView` / extends Control | ui_assembler 组装、四区布局 | 不变 |
|
||||
| 类名 `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 |
|
||||
@@ -61,13 +61,13 @@ BoardView（`presentation/views/board_view.gd`，现 extends Control + 内部 Gr
|
||||
|
||||
**2. 渲染技术分工表（本 ADR 核心裁决——「三块模型」）。**
|
||||
|
||||
战斗屏渲染技术按内容形态切分，与四区布局正交：
|
||||
战斗屏渲染技术按内容形态切分，与屏幕布局正交。**战斗屏目标形态 = B/C/D 三区**（2026-09-23 用户裁定：战斗画面不再保留关卡进度条——战斗结束后返回关卡画面，节点链进度只留关卡画面）：
|
||||
|
||||
| 内容 | 渲染技术 | 批次 |
|
||||
|---|---|---|
|
||||
| D 区棋盘本体（格面/数字/旗/徽章/变异纹带/高亮/微光） | **Node2D**（本 ADR） | Phase A（本批立项） |
|
||||
| B 区战斗舞台（主角/敌人站桩、意图三档动画、受击/死亡演出、FX） | **Node2D** | Phase B（后续批，本 ADR 只定分工） |
|
||||
| A 区关卡进度条 | Control | 不动 |
|
||||
| A 区关卡进度条 | Control | **战斗屏退场**（裁定见上；退场落地随停点前移批——流程未倒置前 A 区仍是战斗中唯一节点链可视面，先删致盲，本批不动其现状） |
|
||||
| C 区角色信息（数据框/状态槽/立绘） | Control | 不动 |
|
||||
| D 区 AP 条、按钮组、toast 槽 | Control | 不动 |
|
||||
| B 区结算明细带、回合阶段指示、战斗日志 | Control（文本件） | 不动（Phase B 时留 B 区 Control 半区） |
|
||||
@@ -93,7 +93,7 @@ Phase B 届时将 BattleStageView 同构改造（PanelContainer → Control 壳
|
||||
|
||||
### Alternative 2: 直挂 Node2D（Control 壳内手挂 Node2D，无 SubViewport）
|
||||
- **Cons**: 屏幕坐标↔棋盘坐标换算、缩放纪律、两档分辨率适配全部自建；布局联动手工维护。
|
||||
- **Rejection Reason**: SubViewportContainer 是 Control——四区容器布局引擎原生参与，鼠标坐标引擎换算，内部分辨率固定使像素缩放纪律有单点可管。
|
||||
- **Rejection Reason**: SubViewportContainer 是 Control——容器栅格布局引擎原生参与，鼠标坐标引擎换算，内部分辨率固定使像素缩放纪律有单点可管。
|
||||
|
||||
### Alternative 3: 逐格 Area2D 承载命中
|
||||
- **Cons**: 144 个 Area2D 节点开销与信号接线量；命中语义（相邻约束/chord/长按）仍要自建。
|
||||
@@ -124,7 +124,7 @@ Phase B 届时将 BattleStageView 同构改造（PanelContainer → Control 壳
|
||||
- 输入路径改 `_gui_input` 后现探针全走 `click_cell` 直调，公式换算无自动化覆盖 → 缓解：实施批增补 push_input 端到端输入探针（ADR-0003 已登记项，本批转义务）
|
||||
|
||||
## Migration Plan
|
||||
Phase A（棋盘，实施另批）：BoardView 内部重构 + 探针增补 + 冒烟全量回归 + 文档随批（HUD框架渲染注记/battle.md 实现注记/architecture.md 模块归属行）。Phase B（B 区舞台，后续批）：同构复制 + 站桩精灵迁移 + 意图动画承载；开工前置 = 样张批冻结剪影与动画方案。工程细节见同目录 `board-node2d-migration-plan.md`。
|
||||
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）绿
|
||||
|
||||
@@ -10,11 +10,10 @@
|
||||
|
||||
## 1. 目标形态（已与用户确认的三块模型）
|
||||
|
||||
战斗屏 = 两块 Node2D 舞台 + 一层 Control 面板。术语校准：Godot 没有「Canvas」节点——面板层是 Control 树（常驻顶层与弹层经 CanvasLayer，现状已如此）；Node2D 不参与 Control 容器布局，所以每块舞台包一个 Control 壳（SubViewportContainer）参与四区栅格，壳内才是 Node2D 世界。
|
||||
战斗屏 = 两块 Node2D 舞台 + 一层 Control 面板。术语校准：Godot 没有「Canvas」节点——面板层是 Control 树（常驻顶层与弹层经 CanvasLayer，现状已如此）；Node2D 不参与 Control 容器布局，所以每块舞台包一个 Control 壳（SubViewportContainer）参与屏幕栅格布局，壳内才是 Node2D 世界。
|
||||
|
||||
```
|
||||
BattleScreen（Control 四区栅格，结构冻结不动）
|
||||
├── A 关卡进度条 ................ Control（不动）
|
||||
BattleScreen（Control 栅格；目标形态 = B/C/D 三区——进度条退场裁定见下）
|
||||
├── B 战斗画面（Phase B 改造，本批不动）
|
||||
│ ├── Node2D 舞台壳：主角/敌人站桩、意图动画、演出（后续批）
|
||||
│ └── Control 半区：结算明细带、回合指示、战斗日志（永久 Control）
|
||||
@@ -28,6 +27,11 @@ BattleScreen（Control 四区栅格，结构冻结不动）
|
||||
└── CellUnit × N（Node2D，每格一个）
|
||||
```
|
||||
|
||||
**进度条退场裁定（2026-09-23 用户）**：战斗画面不再有关卡进度条——战斗结束后返回关卡画面，节点链进度只留关卡画面。两点排程事实：
|
||||
|
||||
1. **A 区现状代码继续服役**：当前流程尚未倒置（冒险开局直进战斗，节点图是战后弹层），A 区顶栏是战斗过程中唯一的节点链可视面——先删会致盲。退场落地 = 停点前移批（关卡画面成为常驻枢纽、战后返回），届时本图删 A 行、四区→三区。
|
||||
2. **该批的 GDD 修订面**：HUD框架.md 四区结构表（含 B/C/D 是否重新编字母）、关卡节点地图.md 节点链常显条款（常显载体随进度条迁回关卡画面）、battle.md 像素布局表（28px 纵向空间再分配）。三项都随停点前移批走文档修订，不随本批。
|
||||
|
||||
## 2. Phase A 范围（本批做）
|
||||
|
||||
1. **BoardView 内部重构**（`presentation/views/board_view.gd`）：
|
||||
|
||||
Reference in new issue
Block a user