improve-threejs
Skill540 starsChanged 3 months agoMITView on GitHub
Audit and fix Three.js and React Three Fiber apps for frame-loop performance, GPU memory leaks, scene-graph correctness, and visual defects like z-fighting, shadow acne, wrong color space, and broken resize handling. Uses React Doctor as the scanning engine plus a visual rubric checked against rendered output. Use when the user asks to improve, audit, scan, or clean up a Three.js, R3F, react-three-fiber, drei, or WebGL app, or types `/improve-threejs`.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- millionco/react-doctorword for word, first seen Oct 8, 2026
Other versions1 project uses a version of this.
Word for word · 1
- millionco/react-doctor★ 15k100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository9 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- public/llms-full.txtllms.txt
- public/llms.txtllms.txt
- api-skillSkill
- server-skillSkill
- claude-of-tanks-skillSkill
- src-skillSkill
- tools-skillSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 22
Run React Doctor read-only to collect structured evidence:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Improve Three.js
Audits a Three.js or React Three Fiber (R3F) codebase and fixes what hurts most: work that runs every frame, GPU resources that never get disposed, scene-graph objects rebuilt on every render, and visual defects the user can see. React Doctor supplies the machine-verified code scan; this skill supplies the frame-loop judgment and the visual inspection a general React scanner lacks.
The core principle: severity follows the render loop. Code inside useFrame or a requestAnimationFrame callback runs 60 times per second, so a minor inefficiency there outweighs a major one in a settings panel. Rank every finding by where it runs, not by the rule's default severity.
Workflow
Step 1: Recon
Identify the stack before scanning: plain Three.js or R3F, which helper libraries are in use (drei, postprocessing, rapier), and where the render loop lives (useFrame hooks, requestAnimationFrame, the <Canvas frameloop> setting).
Build a hot-path map: every useFrame body, every RAF callback, every pointer-move handler. These files get the strictest review in Step 3.
Step 2: Scan
Run React Doctor read-only to collect structured evidence:
npx react-doctor@latest --verboseFor a regression check after making changes, run with --scope changed and confirm the score did not drop.
Step 3: Triage by frame-loop leverage
Re-rank the scanner's findings using the hot-path map, then hunt for the Three.js-specific problems the scanner cannot see. Confirm every finding at its file:line before reporting it.
HIGH severity, runs every frame or leaks GPU memory:
- Allocation inside
useFrame:new Vector3(),new Color(), or fresh arrays passed to Three.js APIs each frame. Fix: hoist a scratch object to module scope oruseMemo, then mutate it in place setStateinsideuseFrame: re-renders the React tree on every frame. Fix: mutate refs directly; reserve state for discrete changes like selection or visibility- Missing disposal: geometries, materials, textures, or render targets created imperatively and never disposed. Fix: call
dispose()in the cleanup function, or move the object into R3F's declarative tree so it owns the lifecycle - Object reconstruction in render: geometry or material instances created without
useMemo, or inlineargsarrays whose identity changes each render, forcing R3F to rebuild the underlying object
MEDIUM severity, per-render or per-interaction waste:
- Unstable scene-graph props: inline
new THREE.Vector3()or fresh material objects as props (plain arrays likeposition={[x, y, z]}are fine; R3F handles them) - Missing instancing: hundreds of identical meshes rendered individually instead of through
<Instances>orInstancedMesh - Wasted frames:
frameloop="always"on a scene that only changes on interaction. Fix:frameloop="demand"plusinvalidate() - Uncached asset loading: textures and models loaded outside
useLoader,useTexture, oruseGLTF, losing caching and Suspense integration
LOW severity, hygiene: React Doctor findings on non-canvas UI code, missing <Preload>, oversized textures.
Step 4: Visual audit
Inspect what the scene actually renders. Every visual finding needs evidence: a screenshot, a frame capture, or a reproduced observation, never a guess from reading source. When a dev server and browser are available, load the app, capture the first stable frame, then capture again after moving the camera and interacting. When no browser is available, check the code-level causes listed below and label each finding as inferred from source.
Apply the mini rubric. A row fails only when the evidence shows the failure condition:
| Area | Check | Fail when |
| Render sanity | The scene reaches a stable frame after load | Black canvas, WebGL context errors, or content that never appears |
| Geometry | Move the camera along seams, edges, and boundaries | Gaps, missing faces, visible backfaces, or two surfaces flickering at the same depth (z-fighting) |
| Transparency and depth | Cross depth-order boundaries with overlapping or transmissive surfaces | Wrong sort order, halos, opaque surfaces that should transmit, or flicker at grazing angles |
| Textures | View mapped surfaces close, far, and at grazing angles | Missing textures, stretching, seams, moiré, shimmer, or washed-out colors from a wrong color space |
| Materials and lighting | Change light and view direction on lit surfaces | Surfaces that ignore light direction, or reflective metals with no environment to reflect |
| Shadows | Move casters, receivers, and the light through their range | Acne, detached or floating shadows, flicker at rest, or shadows that outlive their caster |
| Camera | Follow the primary subject through movement and transitions | Subject leaves frame, camera clips into geometry, or foreground blocks the play area |
| Scale and contact | Compare object scale and resting contact against surroundings | Objects float above, sink into, or intersect their support surface, or sit at implausible scale |
| Image stability | Pan the camera slowly at supported resolutions | Silhouettes, thin geometry, or highlights that crawl, sparkle, or ghost |
| Resize and DPR | Change viewport size, zoom, and device pixel ratio | Distortion, blur, stretched output, or content leaving the viewport |
Each rubric row has a small set of usual code-level causes. Check these first when a row fails:
- Washed-out or too-dark colors:
renderer.outputColorSpacenot set toSRGBColorSpace, color textures missingtexture.colorSpace = SRGBColorSpace, or a data texture (normal, roughness) wrongly marked sRGB - Z-fighting: coplanar geometry needing
polygonOffsetor a position nudge, or a near plane set far too small for the scene scale - Shadow acne or floating shadows:
shadow.biasandshadow.normalBiasuntuned, or a shadow camera frustum far larger than the scene - Blurry or stretched canvas: renderer size not synced to canvas CSS size,
setPixelRationever called, or a resize handler that forgetscamera.updateProjectionMatrix() - Black metals:
metalness: 1with noscene.environmentset - Transparency sorting glitches: large transparent meshes needing
depthWrite: false, manualrenderOrder, or a split into smaller meshes - Shimmer and crawl: missing texture anisotropy, antialiasing disabled, or thin geometry needing thicker forms
Step 5: Fix
Fix in severity order: HIGH performance findings and failed visual rows first. When a finding maps to a React Doctor rule, fetch the canonical recipe instead of improvising:
https://www.react.doctor/prompts/rules/<plugin>/<rule>.mdFor Three.js-specific findings, apply the fix named in the triage list or the cause list above.
Step 6: Validate
Run npx react-doctor@latest --verbose --scope changed and confirm the score did not regress. Re-check every visual rubric row that failed, using the same viewpoint and interaction as the original evidence, and confirm it now passes. Then verify behavior: the scene renders, animations play, and interactions respond. If browser dev tools are available, watch the memory profile while orbiting an idle scene; a rising heap during idle means a disposal leak survived.
Checks the scanner always misses
Review these by hand on every audit:
dispose()coverage for every imperatively created GPU resource- Allocations and
setStateinsideuseFrameand RAF callbacks - Event listeners and
ResizeObservers on the canvas or window without cleanup - Raycasting against the full scene on every pointer move instead of a filtered target list
- Shadows or postprocessing enabled globally when one part of the scene needs them
- Color space configuration on the renderer and every color texture
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

