Mode d’emploi
- Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
- Consultez le document original pour les outils, identifiants et environnements requis.
- Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill threejs-scene-setupAvant de commencer
- L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
- Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.
three.js scene setup
Builds the base every three.js game needs: module loading, the scene, camera and renderer, one render loop, resize handling, and a resolution budget. Patterns target r187. Read the installed three version first; addons, defaults and deprecations move every release.
When to use
- Bootstrapping a three.js scene, fixing a black or blank canvas, making the canvas
responsive, setting up the loop, adding OrbitControls, or choosing between WebGLRenderer and WebGPURenderer.
package.jsondepends onthree, or code doesimport * as THREE from 'three'.- Not for models and animation (
threejs-gltf-loading), surface look, lights and shadows
(threejs-materials-lighting), or React Three Fiber (@react-three/fiber) components, whose <Canvas> owns the renderer and loop. For 2D, use pixijs-rendering or Phaser.
Workflow
- Read `three` from `package.json` or the import map. An existing project keeps its
release unless the user asks to upgrade.
- Resolve `three` and `three/addons/` with a bundler or an import map; addons live under
three/addons/....
- Create the scene, camera and renderer, with the camera moved back from the origin and
the pixel ratio capped (Pattern 2).
- Prove the pipeline with an unlit mesh first (
MeshNormalMaterial). Only then switch
to lit materials and add lights.
- Drive everything from `renderer.setAnimationLoop` with a
Timerand a clamped delta.
Keep game state in plain objects and copy it onto meshes each frame. Meshes then stay a view, and state can be saved and tested without a GPU.
- Handle resize (aspect, projection matrix, renderer size) and add
OrbitControls
while developing.
- Verify with Verify.
Patterns
1. Import map (no bundler)
<canvas id="c"></canvas>
<script type="importmap">
{
"imports": {
"three": "https://cdn.jsdelivr.net/npm/three@0.187.0/build/three.module.js",
"three/addons/": "https://cdn.jsdelivr.net/npm/three@0.187.0/examples/jsm/"
}
}
</script>
<script type="module" src="./main.js"></script>With Vite or webpack, npm i three and the same imports resolve without a map.
2. Scene, camera and renderer
import * as THREE from 'three';
const canvas = document.querySelector('#c');
const renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 1.5)); // starting budget; profile on target hardware
renderer.setSize(window.innerWidth, window.innerHeight);
const scene = new THREE.Scene();
scene.background = new THREE.Color(0x101018);
const camera = new THREE.PerspectiveCamera(60, window.innerWidth / window.innerHeight, 0.1, 100);
camera.position.set(3, 2, 5);
camera.lookAt(0, 0, 0);
const cube = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1), new THREE.MeshNormalMaterial());
scene.add(cube);
Object.assign(window, { renderer, scene }); // for the smoke check and console debugging3. Render loop with Timer
const timer = new THREE.Timer(); // replaces the deprecated THREE.Clock (r183+)
timer.connect(document); // optional: no huge delta after a hidden tab
renderer.setAnimationLoop(() => {
timer.update(); // use performance.now(), like visibility reset
const dt = Math.min(Math.max(timer.getDelta(), 0), 0.1); // seconds; bound stalls and negative deltas
cube.rotation.x += dt; // frame-rate independent
cube.rotation.y += dt * 0.7;
renderer.render(scene, camera);
});
// renderer.setAnimationLoop(null); // stop the loop
// timer.dispose(); // remove visibility listener when tearing downCall update() with no argument when the timer is connected. Visibility reset samples performance.now(), so passing the loop's timestamp can produce a negative delta right after a hidden tab returns. The clamp also protects a fixed-step accumulator; the 0.1 s upper bound drops time after a stall on purpose, so tune it to the game's catch-up policy.
4. Resize
window.addEventListener('resize', () => {
camera.aspect = window.innerWidth / window.innerHeight;
camera.updateProjectionMatrix(); // required after changing aspect
renderer.setSize(window.innerWidth, window.innerHeight);
});5. OrbitControls
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
const controls = new OrbitControls(camera, renderer.domElement);
controls.enableDamping = true;
// In the loop, before render: controls.update(); (required every frame with damping)6. WebGPURenderer, only when needed
Stay on WebGLRenderer by default. Switch when the project needs TSL node materials or compute shaders; WebGPURenderer falls back to a WebGL 2 backend where WebGPU is missing.
// Official WebGPU examples map both "three" and "three/webgpu" to
// build/three.webgpu.js, plus "three/tsl" to build/three.tsl.js.
import * as THREE from 'three/webgpu';
const renderer = new THREE.WebGPURenderer({ antialias: true });
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 1.5)); // starting budget; profile on target hardware
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);
await renderer.init(); // required before direct render()/compute()
renderer.setAnimationLoop(() => renderer.render(scene, camera));Scenes, cameras, built-in Mesh*Materials and most addons carry over. Custom GLSL (ShaderMaterial, onBeforeCompile) does not.
Verify
npm run build(ornpx tsc --noEmitwith@types/threematching thethreeversion)
passes.
- Smoke-test in a headless browser. With the dev server running and
window.renderer
exposed (Pattern 2), run node smoke.mjs <url> after npm i -D playwright and npx playwright install chromium. Without browser automation, ask the user to open the page, then report the console output and whether the cube is visible and turning.
// smoke.mjs: fails on page errors; checks that frames are drawn and survive a context loss.
import { chromium } from 'playwright';
const browser = await chromium.launch();
const page = await browser.newPage();
const errors = [];
page.on('pageerror', (e) => errors.push(e.message));
page.on('console', (m) => { if (m.type() === 'error') errors.push(m.text()); });
await page.goto(process.argv[2]);
await page.waitForFunction(() => window.renderer?.info.render.calls > 0, null, { timeout: 15000 });
const state = await page.evaluate(() => ({
drawCalls: window.renderer.info.render.calls,
triangles: window.renderer.info.render.triangles,
geometries: window.renderer.info.memory.geometries,
canvas: [window.renderer.domElement.width, window.renderer.domElement.height],
}));
await page.screenshot({ path: 'smoke.png' });
await page.evaluate(async () => { // WebGLRenderer only: lose and restore the context
if (!window.renderer.forceContextLoss) return;
window.renderer.forceContextLoss();
await new Promise((r) => setTimeout(r, 200));
window.renderer.forceContextRestore();
await new Promise((r) => setTimeout(r, 500));
});
await page.screenshot({ path: 'smoke-restored.png' });
await browser.close();
console.log(JSON.stringify({ ...state, errors }, null, 2));
process.exit(errors.length ? 1 : 0);Expect drawCalls above 0, a canvas size other than 0 × 0, and no errors. Open both screenshots: the second must still show the scene, or something holds GPU objects that the restore did not rebuild.
Gotchas
- `Failed to resolve module specifier "three"` → no import map or bundler. Map both
"three" and "three/addons/"; the addons entry must end with /.
- Black canvas, no errors → the camera sits inside or behind the object, or a lit
material has no light. Move the camera back and test with MeshNormalMaterial.
- Stretched view after resize → the renderer was resized but
camera.aspectand
updateProjectionMatrix() were not updated.
- Slow or hot on HiDPI and phones → a pixel ratio of 2 draws four times the pixels of 1,
so a cap of 2 does nothing on a 2× screen. Start at 1.25 to 1.5 and offer a resolution setting; adaptive resolution is in the reference.
- Simulation freezes after the tab returns → in r186 and r187 a loop timestamp passed to
timer.update(time) can precede the visibility reset and give a negative delta. Call update() with no argument and clamp as in Pattern 3.
- `THREE.Clock: This module has been deprecated` → since r183; use
THREE.Timer. - Old tutorials use `<script src="three.min.js">` or `examples/js/...` →
examples/jswas
removed in r148 and build/three.min.js in r161. Use modules and an import map.
- OrbitControls feel dead → with
enableDampingon,controls.update()must run every
frame.
- Canvas goes black after a GPU reset or many tabs → the WebGL context was lost.
WebGLRenderer handles webglcontextlost and rebuilds its own state on restore; code that keeps raw GL objects or skips the loop while lost does not recover. Test with forceContextLoss() / forceContextRestore() as in Verify.
- `.render() called before the backend is initialized` (WebGPURenderer) → `await
renderer.init() before a direct render()/compute(), or render only from setAnimationLoop`, which initialises first.
- `Material "ShaderMaterial" is not compatible`, or `onBeforeCompile` is ignored
(WebGPURenderer) → it renders node materials only. Port the effect to TSL or stay on WebGLRenderer.
References
- Read `references/scene-graph.md` for coordinate conventions,
parenting with Group, OrthographicCamera for 2.5D, disposing geometries, materials and textures between levels, stopping the loop, render-on-demand, and adaptive resolution.
Related skills
threejs-materials-lighting: lights, shadows, PBR and environment maps.threejs-gltf-loading: loading models and playing their animations.camera-systems: follow, orbit and first-person camera design.fps-shooter: a 3D genre that builds on these skills.
Version notes
Last verified: 2026-11-11 against three r187 (npm three@0.187.0, published 2026-10-30; @types/three@0.187.0).
Timer.update()is unchanged between r186 and r187, so the negative-delta note holds.- The r187 WebGPU examples still map
threeandthree/webgputobuild/three.webgpu.js. - Sources: r187 release notes,
Migration Guide, r187 Timer.js, r187 responsive rendering manual, WebGLRenderer.js context handling.