Find the owning cause or measured bottleneck before changing code.
Read references/debug-profile-checklists.md for the applicable render,
runtime, loading, mobile, audio, physics, or performance path.
Debug Workflow
- Reproduce in the correct build mode.
- Read the first console, page, and relevant network errors.
- Check canvas display/drawing-buffer size, renderer/context, and loop ownership.
- Check camera, clipping, lights, fog, materials, visibility, transforms, and scene contents.
- Check asset paths, loaders, CORS, base path, async ordering, and Mint artifact integration.
- Check delta units, update order, fixed timestep, bodies/colliders, listeners, pointer/touch behavior, resize, and audio unlock/decode.
- Fix the cause in the owning module.
- Retest the broken path plus screenshot, canvas pixels, and errors.
Performance Workflow
- Record target device, viewport, DPR, build mode, and worst-case scenario.
- Measure frame time/FPS, draw calls, triangles, resources, memory, bundle, and expensive shadows/shaders/post-processing.
- Identify CPU, GPU, memory, or network ownership.
- Change one bottleneck at a time using reuse, instancing, culling, LOD, pooling, disposal, DPR limits, or cheaper rendering.
- Re-measure the same scenario and verify playability and visuals.
Final Response
Lead with root cause or bottleneck. Report files changed, baseline/post metrics, commands, screenshots/artifacts, retested paths, and residual risks.