# 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（新项目默认值差异）