renderer

GPU renderer

Use this for WebGPU renderer work where correctness depends on GPU resource ownership, pass orchestration, shader/material layout, depth semantics, or browser-verified output. Find the current owners in the codebase — projection, depth convention, environment presets — before changing anything; do not assume this skill knows today's module layout.

Workflow

1. Inspect the existing device/shell, pass graph, bind group layouts, shader contracts, and validation routes before adding a pipeline or buffer.
2. Define resources first: buffers, textures, uniforms, storage layouts, bind groups, ownership, update frequency, read/write access, and lifetime.
3. Choose the phase deliberately:
   • Use compute for parallel preparation, simulation, reductions, texture or buffer transforms, and work-list construction.
   • Use render passes for rasterized output.
   • Use separate background, depth-tested world, transparent/effect, and UI overlay phases when visibility semantics differ.
4. Single-source shared contracts. Camera layouts, projection helpers, depth modes, frame phases, semantic roles, vertex strides, and bind group schemas should live in one canonical module/source and be imported by renderers, shaders, and verifiers.
5. Fight sediment. When a new requirement reveals that two passes own the same concept (lighting environment, haze, material palette, terrain projection, water mask), refactor to the shared primitive you would design from scratch. Do not bolt an adapter or alias beside the old owner unless it is a tiny temporary bridge with a named removal path.
6. Validate in the browser. Run the narrowest scenario that exercises the changed pass, open the produced PNG, and use compare-screenshots when a visual before/after needs telemetry.

Rules

• One projection owner, one depth convention, one environment owner — whatever modules currently own them. A camera is posed through the shared camera helper, never hand-rolled orbit math in a route or pass; a preset-dependent material knob lives on the environment owner, never in a pass.
• Prefer reverse-Z (near→1, far→0) on a float depth buffer for large outdoor depth ranges; whichever convention is in force, it is engine-wide — depth compare direction, clear value, and format move together or not at all.
• Renderer library upgrades are their own reviewed change with the full suite and perf gate as harness — never a ride-along on a feature commit.
• WGSL uniforms and storage structs must respect alignment. Pack scalar fields into obvious 16-byte slots when it reduces layout ambiguity.
• Treat depth as an access contract, not a boolean. Use explicit modes such as read, read-write, and write; make renderer stats and GPU pipeline state speak the same language.
• All pipelines in one render pass must be compatible with its attachments. Adding a depth attachment is a pass-wide change: update every pipeline in the pass, split the pass, or keep the pass depthless.
• Type buckets are batching details, not visibility policy. Sorting by mesh class, prop type, material, or instance bucket is valid only when the pass has the correct depth semantics for the world it draws.
• Do not mix alpha blending into depth-writing opaque geometry. Opaque/cutout world objects can write depth; translucent decals, shadows, selection rings, roads, and UI overlays need separate read-only depth or overlay phases.
• Treat read-only world decals as a one-way boundary inside a frame. Once ground cues, shadows, roads, or other depth=read world decals begin, no later world pass should write depth; otherwise the frame is relying on painter-order color overwrites instead of the depth buffer.
• World-space ground cues are not HUD overlays. If a marker belongs on terrain, submit it through the world camera and let real geometry occlude it; reserve screen overlays for labels, HUD, minimaps, debug UI, and deliberately non-world effects.
• Selection, order, targeting, and path cues should be verified by their semantic ground-cue/effect pass, not by an incidental terrain or mesh bucket. A correct cue can be a read-only world decal or tactical line without being part of the terrain geometry count.
• Ground decals on raised or tilted terrain need the same surface height as the world objects they mark. A selection ring, shadow, road, or footprint that assumes flat z=0 can disappear under the terrain or drift away from the model even when its x/y coordinates are correct.
• Continuous world paths should be continuous geometry. Do not create road, rail, river, or path continuity by cutting endpoint gaps around occluders; resample the path onto the canonical surface and let depth-tested world objects occlude it.
• Instanced world props need a base-elevation field when they live on raised terrain. An instance layout that carries only x/y/scale can look fine on a flat fixture while trees, rocks, crowds, or buildings float, sink, or lose depth ordering on the real map.
• Tilted world scenes need one canonical surface. If terrain, water, roads, labels, props, or hit tests must stay geographically aligned while the camera moves, project and draw them from the same 3D surface/height contract. A flat textured underlay plus separate raised world objects will drift under perspective even when the source coordinates are correct.
• Geographic effects need a canonical mask/projection owner. Water glints, coast foam, fog reveal, biome tints, and terrain overlays must sample or be generated from the same world-space mask that owns the gameplay geography; unmasked decorative quads/ellipses are only valid for non-geographic atmosphere and must not independently decide where land or water exists.
• Shared visual concepts are not pass-local knobs. If water, terrain, grass, sky, soldiers, or props all need the same weather, haze, palette, or light, make that a shared renderer contract and have every pass consume it. A wrapper that preserves old duplicated constants is still a failed architecture unless it is explicitly transitional and tracked.
• Secondary world views need the same contract as the primary view. Minimap, overview, reflection, shadow, and debug views should expose or consume canonical world-space anchors instead of carrying private scale/offset math; verifier tolerances should match the source grid resolution.
• Nested objects must be proven with hostile-order fixtures. Submit an occluder first, submit the nested/rear object later, then sample or crop pixels that prove depth, not painter order, owns visibility.
• Browser checks can pass while the canvas is visually wrong. Inspect actual PNGs after WGSL, pipeline, camera, pass-order, depth, or blend changes, and reject black frames, transparent canvases, flattened occlusion, or UI layered over world geometry by accident.
• A valid render is not necessarily a useful capture. Screenshot gates must prove the intended subject is framed: derive camera targets from live renderable bounds or explicit semantic anchors, and reject frames that show mostly empty terrain, sky, water, or one flat colour while entity stats look healthy.
• Treat GPU renderer validation warnings as failed renders. A bad pipeline can leave route stats and app hooks alive while command buffers are invalid and the canvas is black. Capture console warnings and fix the root contract, commonly vertex stride/attribute offsets, bind-group layout drift, attachment mismatch, or a depth mode that no longer matches the pass.
• WGSL let bindings are immutable. When staged shader values need overrides, use var; reassigned let expressions can invalidate the pipeline and leave JavaScript stats healthy while the actual canvas is black.
• Expose pass-level stats for render-affecting modes and resource contracts. If a shader path depends on a texture, mask, depth mode, or feature toggle, the route stats should say which path is active and what resource dimensions it consumed.
• Keep scenario assertions derived from the same contracts as renderer code. Hard-coded verifier copies of depth formats, phase names, role maps, or vertex strides drift into false confidence.
• Capability handling must match the product. An unsupported-GPU renderer path may show a clear failure/fallback UI, but it must not silently route production visuals through an unrelated renderer to hide missing GPU renderer behavior.
• Spatial budgets must not erase geography. If a map renderer caps mountains, forests, props, particles, or decals, reserve by canonical region/tile or connected feature before global sorting; batching and top-N selection are performance details, not permission to drop whole visible landforms.
• Stats that count submitted instances are not proof that the GPU rendered content. NaN instance fields, zero coverage, bad projection, or invalid shader state can leave counts healthy while pixels are blank; pair stats with crop/content probes for each visual class.