From b1756d2de023984acdd341af7248e83e91167d45 Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Wed, 23 Sep 2026 20:07:26 +0800 Subject: [PATCH] =?UTF-8?q?docs(arch):=20=E6=A3=8B=E7=9B=98=E8=BF=81?= =?UTF-8?q?=E7=A7=BB=E6=96=87=E6=A1=A3=E4=BF=AE=E8=AE=A2=E2=80=94=E2=80=94?= =?UTF-8?q?=E6=88=98=E6=96=97=E5=B1=8F=E8=BF=9B=E5=BA=A6=E6=9D=A1=E9=80=80?= =?UTF-8?q?=E5=9C=BA=E8=A3=81=E5=AE=9A=E8=90=BD=E6=96=87=EF=BC=88=E6=88=98?= =?UTF-8?q?=E5=90=8E=E5=9B=9E=E5=85=B3=E5=8D=A1=E7=94=BB=E9=9D=A2=EF=BC=8C?= =?UTF-8?q?=E8=BF=9B=E5=BA=A6=E5=8F=AA=E7=95=99=E5=85=B3=E5=8D=A1=E7=94=BB?= =?UTF-8?q?=E9=9D=A2=EF=BC=9B=E9=80=80=E5=9C=BA=E8=90=BD=E5=9C=B0=E9=9A=8F?= =?UTF-8?q?=E5=81=9C=E7=82=B9=E5=89=8D=E7=A7=BB=E6=89=B9=EF=BC=8C=E7=94=A8?= =?UTF-8?q?=E6=88=B7=E8=A3=81=E5=AE=9A=202026-09-23=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../adr-0006-board-node2d-rendering.md | 14 +++++++------- docs/architecture/board-node2d-migration-plan.md | 10 +++++++--- 2 files changed, 14 insertions(+), 10 deletions(-) diff --git a/docs/architecture/adr-0006-board-node2d-rendering.md b/docs/architecture/adr-0006-board-node2d-rendering.md index c14e393b..227adc88 100644 --- a/docs/architecture/adr-0006-board-node2d-rendering.md +++ b/docs/architecture/adr-0006-board-node2d-rendering.md @@ -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）绿 diff --git a/docs/architecture/board-node2d-migration-plan.md b/docs/architecture/board-node2d-migration-plan.md index 4cc149b5..d0407261 100644 --- a/docs/architecture/board-node2d-migration-plan.md +++ b/docs/architecture/board-node2d-migration-plan.md @@ -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`）：