Tom Boullay
134c0aecb7
Shadows occasionally failed to render on initial load and the Fabrik doorway sometimes blocked the player. Both issues are tracked down to geometry that mounts after Lighting: - Shadows: GLTFs and the merged static map mount imperatively after Lighting, so materials get compiled against a renderer state that pre-dates the final scene and bake a 'no shadow map' permutation, silently dropping shadows. A WebGL context-restore cycle fixes it, but is too invasive. New 'useShadowMapWarmup' hook replays it cheaply: once the scene mesh count has been stable for ~1s, it disposes the directional shadow map (three.js reallocates it on the next render) and marks every material 'needsUpdate' so shaders rebind to the freshly created shadow sampler. - Doorway: the door slab + its Solidify-modifier frame (children of the 'Thicken' parent in the LaFabrik GLTF) sat inside the doorway AABB and prevented the player from walking through. Stripped from the collision octree alongside the existing 'porte' slab; visual rendering is unaffected. Also: extract sun-relative-to-camera placement into a small helper, remove the temporary diagnostic logs, and document the shadow warmup in three-debugging.md.
3.7 KiB
Three Debugging
Use the dedicated debug mode when you need Chrome DevTools to step into Three.js internals.
npm run dev:three-debug
This mode aliases three to node_modules/three/src/Three.js and disables Vite dependency pre-bundling for Three. In DevTools, open node_modules/three/src/renderers/WebGLRenderer.js and place a breakpoint inside:
this.render = function (scene, camera) {
Reload the page or trigger a frame. When the breakpoint hits, inspect scene, camera, renderer state, visible objects, matrices, materials, and this.info.render.
If DevTools still opens a bundled file, stop the dev server, clear Vite's cached deps, and restart:
rm -rf node_modules/.vite
npm run dev:three-debug
Visual debug toggles
The Debug folder of the runtime debug GUI exposes inspection toggles backed by
src/managers/stores/useDebugVisualsStore.ts:
- Show Player Model — renders the main character GLTF in front of the
current camera (
src/components/debug/DebugPlayerModel.tsx). The model is positioned in camera-local space so it stays visible regardless of pitch. - Show Octree — overlays the collision octree as colored line segments,
one wireframe per spatial cell (
src/components/debug/DebugOctreeVisualization.tsx). Cells are colored by depth. Use it to inspect collision precision around doorways or passages. - Octree Max Depth — caps how deep the octree visualization recurses (default 6). Increase to see leaf-level subdivisions; decrease to keep the scene readable when the tree is large.
The octree visualization reads the live Octree instance from World. The
mesh uses depthTest: false and a high renderOrder, so cells stay visible
through opaque geometry.
Shadow rendering intermittence
Shadows occasionally failed to render on initial load and could disappear
mid-session even though the Lighting configuration ran to completion. The
fix has two layers:
Per-frame refresh (steady state)
The sun follows the camera, so its world matrix is dirty every frame. With
shadow.autoUpdate alone, three.js can skip the shadow map re-render on a
frame where the matrix update has happened but the renderer's internal dirty
tracking does not pick it up. To prevent that, Lighting.useFrame sets
sun.shadow.needsUpdate = true after the per-frame matrix updates. Shadow
config is centralized in src/data/world/lightingConfig.ts (bias=0,
normalBias=0, cameraSize=95).
Mount-time shadow map reallocation (useShadowMapWarmup)
The merged static map and other GLTFs mount imperatively after Lighting,
so the shadow render target ends up linked to a renderer state that pre-dates
the final scene. Materials compiled at that point bake a "no shadow map"
permutation into their shader program and silently fail to render shadows
until a WebGL context-restore cycle (the kind triggered by Chrome DevTools
in ?debug runs) reallocates everything.
src/hooks/three/useShadowMapWarmup.ts replays that cycle programmatically
without the cost of a full context loss. It runs a useFrame watchdog that
samples the scene mesh count every 6 frames; once the count has been stable
for ~1 s (or after a 5 s safety cap), it:
- Disposes the directional light shadow map and nulls it. three.js
reallocates the render target on the next render at the configured
mapSize. - Marks every material's
needsUpdate = true, forcing a shader recompile that rebinds every program to the freshly created shadow sampler. - Forces a single shadow pass and invalidates the renderer.
The watchdog runs once per mount and adds a single traversal every 6 frames during the warmup window, after which it self-terminates.