threejs-debug-profiler

majidmanzarpour/threejs-game-skills

Debug and profile Three.js games: render bugs, asset loading, performance bottlenecks, and bundle size.

What is threejs-debug-profiler?

A diagnostic tool for Three.js browser games that helps identify and fix rendering issues, asset/audio loading problems, animation bugs, and performance bottlenecks. Use it when your game has blank canvases, runtime errors, or needs optimization across draw calls, memory, shaders, and post-processing.

Diagnose blank canvases and render failures
Trace asset and audio loading issues
Debug animation, physics, and input handling
Profile GPU metrics: draw calls, triangles, textures, memory usage
Measure shader and post-processing performance cost
Analyze bundle size and identify optimization targets

How to install threejs-debug-profiler

npx skills add https://github.com/majidmanzarpour/threejs-game-skills --skill threejs-debug-profiler

Claude Code

Cursor

Windsurf

Cline

How to use threejs-debug-profiler

1.Install the skill via the provided npx command.
2.Read `references/debug-playbook.md` for the ordered triage sequence and diagnostic shape.
3.Reproduce the issue using the same command and URL the user reported.
4.Follow the playbook's scope-based triage: check renderer, loop, camera, scene, assets, audio, input, physics, UI, and base path in order.
5.For performance issues, baseline one fixed scenario, classify the bottleneck type, change one variable, and re-measure the same scenario.
6.Report findings with root cause, files changed, baseline and post-fix metrics, and verification of the broken path.

Use cases

Good for

A Three.js game renders a blank canvas—use the playbook to systematically check renderer, scene, camera, and asset loading.
Performance drops during gameplay—baseline metrics, identify whether the bottleneck is CPU or GPU, then measure impact of each optimization.
Audio or assets fail to load—trace the loading path and verify the base path and network requests.
Game behaves differently on mobile—debug input handling and canvas resize behavior on target devices.

Who it's for

Three.js game developers
Performance engineers optimizing browser games
QA testers reproducing and verifying game bugs
Developers new to Three.js debugging workflows

threejs-debug-profiler FAQ

What should I do first when debugging a blank canvas?

Reproduce the issue with the exact command and URL, check the console and network tabs for errors, then follow the debug-playbook.md triage order starting with renderer, loop, camera, and scene setup.

How do I profile performance without breaking the game?

Profile the production preview in a fixed scenario, baseline key metrics (draw calls, triangles, memory, etc.), change one thing at a time, re-measure the same scenario, and confirm visuals and playability still work.

What metrics should I measure?

The playbook lists the metrics to baseline: draw calls, triangle count, texture memory, shader cost, post-processing overhead, and bundle size. Classify the bottleneck as CPU, GPU draw, fragment, vertex, memory, or network first.

When do I need broader testing after a fix?

A focused test of the fixed path is enough if only that path changed. Run broader testing if shared behavior was modified or if unresolved risks warrant it.

What is `__THREE_GAME_DIAGNOSTICS__`?

It is a diagnostic shape documented in the debug-playbook.md that provides structured access to game state and metrics for debugging and profiling.

Full instructions (SKILL.md)

Source of truth, from majidmanzarpour/threejs-game-skills.

name: threejs-debug-profiler description: "Debug and profile Three.js browser games: blank canvases, render and runtime bugs, asset and audio loading, animation, resize, mobile input, plus performance profiling of draw calls, triangles, textures, memory, shader and post-processing cost, and bundle size."

Three.js Debug Profiler

Find root causes and optimize measured bottlenecks without breaking playability.

Follow the changed behavior's scope. Reuse the lead's existing reproduction and evidence; verify the affected path after a fix. A passing focused check only needs broader testing when shared behavior changed or an unresolved risk warrants it. Return measurements and defects to the lead for the consolidated verification pass.

Reference

references/debug-playbook.md — ordered triage for blank canvas, asset and audio loading, loop/animation/physics, input and mobile, the profiling sequence, and the __THREE_GAME_DIAGNOSTICS__ shape. Read it when debugging or profiling anything non-obvious.

Debug

Reproduce first, with the same command and URL the user had, and read the console, page, and network errors. Find the module that owns the failure (renderer, loop, camera, scene, assets, audio, input, physics, UI, or base path), fix the root cause there, and retest the exact broken path. The playbook's triage order covers the common causes, such as more than one active loop, a canvas whose display size doesn't match its drawing buffer, and wrong delta units.

Profile

Profile the production preview when user-facing performance matters. Baseline one fixed scenario, classify the bottleneck (CPU, GPU draw, fragment, vertex, memory, or network), change one thing, and re-measure the same scenario, confirming visuals and playability held. The playbook lists the metrics to baseline and the optimizations in order of payoff.

Report

Lead with the root cause or the measured bottleneck. Then files changed, baseline and post metrics, commands, screenshots, the broken path retested, and residual risks.