浏览器与自动化
renderer
Build, debug, or review WebGPU renderer work — three.js/TSL scene layers, node materials, or raw WGSL passes and compute. Use when changing GPU resource layouts, render or compute passes, node materials, bind groups, buffers, shaders, frame orchestration, depth/overlay composition, capability handling, performance, or browser-verified renderer visuals.
dzhng · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add dzhng/skills --skill renderer技能说明
name: renderer description: Build, debug, or review WebGPU renderer work — three.js/TSL scene layers, node materials, or raw WGSL passes and compute. Use when changing GPU resource layouts, render or compute passes, node materials, bind groups, buffers, shaders, frame orchestration, depth/overlay composition, capability handling, performance, or browser-verified renderer visuals.
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
- Inspect the existing device/shell, pass graph, bind group layouts, shader contracts, and validation routes before adding a pipeline or buffer.
- Define resources first: buffers, textures, uniforms, storage layouts, bind groups, ownership, update frequency, read/write access, and lifetime.
- 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.
- 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.
- 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.
- Validate in the browser. Run the narrowest scenario that exercises the
changed pass, open the produced PNG, and use
compare-screenshotswhen 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, andwrite; 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=readworld 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=0can 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