gplan-2/design/dev/architecture/adr-0002-renderer-and-window-config.md

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。

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