| name | world42-shader-terrain-lab |
| description | Evolve and debug World42 terrain and atmosphere shaders safely, including GLSL uniform contracts, Babylon ShaderMaterial bindings, shadow integration, and LOD/UV debug modes. Use when changing files under src/assets/shaders/, src/game_objects/planets/rocky_planet/terrains_shader.ts, atmospheric postprocess code, or when visual artifacts appear in terrain lighting, shadows, or debug LOD rendering. |
World42 Shader Terrain Lab
Work from contract to effect: keep GLSL declarations, TS uniform/sampler lists, and runtime set* bindings in sync before tuning visual output.
Workflow
1) Audit shader bindings
Run:
./.codex/skills/world42-shader-terrain-lab/scripts/audit-shader-bindings.ps1
Use it to detect:
- Uniforms declared in GLSL but not declared in TS material/postprocess lists
- Uniforms declared but never set
- Runtime
set* calls on names not declared in GLSL
- Sampler mismatches
2) Apply shader changes in lockstep
When adding/removing a uniform or sampler:
- Update GLSL declaration.
- Update TS
uniforms/samplers arrays.
- Update runtime
set* calls and default values.
Do this for both terrain shader and atmosphere postprocess paths.
3) Verify space assumptions
- Terrain shader local geometry logic remains planet-local (
vPosition, uPatchCenter).
- Shadow projection inputs stay render-space (
vWorldPosRender + lightMatrix).
- Lighting direction passed from chunk forge stays normalized and local as expected.
4) Validate visual debug modes
- Toggle
ChunkTree.debugLODEnabled path and confirm debugLOD branch.
- Keep
debugUV branch available for UV diagnostics.
- Recheck shadows after changing normal or world-position paths.
Use references/shader-uniform-contracts.md and references/shader-debug-playbook.md.
Resources
- Script:
scripts/audit-shader-bindings.ps1
- Reference:
references/shader-uniform-contracts.md
- Reference:
references/shader-debug-playbook.md
