Home › Three.js › Three.js rules
Three.js rules
Cursor rules for Three.js (r17x, ES modules) web 3D and games: render loop, disposal, assets, and performance.
CursorThree.js
How to use
Save this as .cursor/rules/threejs.mdc in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.
.cursor/rules/threejs.mdcDownload ---
description: Three.js conventions
globs: ["src/**/*.{js,ts,jsx,tsx}"]
alwaysApply: false
---
# Three.js
- Import from `three` and addons from `three/addons/...` (ES modules). No global `THREE` or old `examples/js` files.
- One `WebGLRenderer` (`antialias: true`), set `renderer.setPixelRatio(Math.min(devicePixelRatio, 2))`, and handle resize by updating the camera aspect + `updateProjectionMatrix()`.
- Animate with `renderer.setAnimationLoop(tick)`; use a `THREE.Timer` or `Clock` delta for movement so speed is frame-rate independent.
- Color management: textures for color use `texture.colorSpace = THREE.SRGBColorSpace`. Keep the default output color space.
- Load models as glTF/GLB with `GLTFLoader` (+ `DRACOLoader`/`KTX2Loader` for compressed assets). Show loading progress via `LoadingManager`.
- Performance: reuse geometries and materials, use `InstancedMesh` for many copies, keep draw calls low, limit shadow-casting lights, and avoid creating objects (`new Vector3`) inside the loop; reuse scratch vectors.
- Dispose of what you remove: `geometry.dispose()`, `material.dispose()`, textures, and render targets.
- Keep game logic in plain classes/systems; the scene graph is for rendering.
- If the project uses React Three Fiber, follow its patterns (`useFrame`, declarative JSX) instead of imperative setup.
- WebGPU (`three/webgpu`) only if the project already opted in.
## Done when
No console errors, `renderer.info.render.calls` is reasonable for the scene, and `npm run build` passes.