120 lines
6.2 KiB
Markdown
120 lines
6.2 KiB
Markdown
# 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（新项目默认值差异）
|