ADR-003: WebGPU Rendering Strategy

Status: Accepted Date: 2026-01-25 Updated: 2026-02-19

Context

Web graphics APIs are evolving:

• WebGPU -- Modern GPU API with compute, storage buffers, and explicit resource control
• WebGL/WebGL2 -- Mature APIs with lower capability ceilings and significant implementation complexity for parity

The renderer originally shipped with a WebGPU-first + WebGL2 fallback model. Maintaining two rendering backends created substantial engineering overhead and delayed feature delivery.

Decision

Adopt a WebGPU-first strategy and standardize runtime rendering on WebGPU-only execution.

createDevice() remains the standard entry point:

const { device, backend } = await createDevice({
  canvas,
  preferredBackend: 'auto',
});

console.log(backend); // 'webgpu'

Consequences

Positive

• Single-backend maintenance -- Faster delivery and less duplicated infrastructure
• Consistent feature model -- Compute-dependent systems are first-class, not fallback-only
• Lower complexity -- Fewer backend-specific branches in renderer, tests, and docs
• Future-ready baseline -- Aligned with modern browser GPU capabilities

Negative

• WebGPU requirement -- Browser/runtime must support WebGPU
• No WebGL2 fallback -- Unsupported environments fail at device creation
• Migration burden -- Older docs/tests relying on WebGL2 assumptions must be updated

Alternatives Considered

• WebGL-only -- Maximum compatibility but leaves performance on the table. Rejected because WebGPU's benefits are too significant for a modern engine.
• WebGPU-first + WebGL2 fallback -- Kept temporarily during transition; later removed due maintenance cost and parity drag.
• Three.js abstraction -- Use Three.js for rendering. Rejected because we need lower-level control for ECS integration and custom render graphs.

Related

• Rendering Pipeline -- Full pipeline architecture