threejs-scene-setup
Stand up a three.js scene: import maps and the three/addons path, the Scene/PerspectiveCamera/WebGLRenderer trio, the setAnimationLoop render loop, responsive resize, and OrbitControls. Use when starting or debugging a three.js app — when the user mentions three.js, THREE.Scene, WebGLRenderer, PerspectiveCamera, the render loop, resizing, or OrbitControls. For models use threejs-gltf-loading; for materials/lights use threejs-materials-lighting.
- License 许可
- Apache-2.0
- 最近更新
- 2026-07-24
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- threejs-scene-setup
- license
- Apache-2.0
- metadata
- { "engine": "threejs", "category": "web-engines", "difficulty": "beginner" }
- description
- Stand up a three.js scene: import maps and the three/addons path, the Scene/PerspectiveCamera/WebGLRenderer trio, the setAnimationLoop render loop, responsive resize, and OrbitControls. Use when starting or debugging a three.js app — when the user mentions three.js, THREE.Scene, WebGLRenderer, PerspectiveCamera, the render loop, resizing, or OrbitControls. For models use threejs-gltf-loading; for materials/lights use threejs-materials-lighting.
- compatibility
- three.js r165+ (verified against r184; ES modules + import maps)
02 资源文件 1
- 参考文档references/scene-graph.md4.0 KB
03 SKILL.md 正文
three.js Scene Setup
Create the foundation of a three.js app: module loading, the scene/camera/renderer trio, the render loop, responsive resizing, and camera controls. Patterns target r165+ and are verified against r184.
When to use
- Use when bootstrapping a three.js scene, fixing a blank/black canvas, making the
canvas responsive, setting up the animation loop, or adding
OrbitControls. - Use when
package.jsondepends onthreeand code doesimport * as THREE from 'three'.
When not to use: loading .gltf/.glb models or skinned animation →
threejs-gltf-loading. Materials, lights, shadows, environment maps →
threejs-materials-lighting. 2D rendering → pixijs-rendering.
Core workflow
- Load three.js as an ES module with an import map. Since r147 the bare
specifier
'three'and'three/addons/'must be mapped (in HTML or by a bundler). Addons (controls, loaders) live underthree/addons/.... - Create the trio. A
Scene(root of the graph), aPerspectiveCamera(fov, aspect, near, far)moved back from the origin, and aWebGLRendererwhosedomElementis in the DOM. Set size andpixelRatio. - Add a mesh.
new Mesh(geometry, material)andscene.add(mesh). With a lit material you also need a light (seethreejs-materials-lighting). - Drive a render loop with
renderer.setAnimationLoop(fn). It's the modern, WebXR-/WebGPU-safe replacement for hand-rolledrequestAnimationFrame. Use aClockfor delta time. - Handle resize so the camera aspect and renderer match the canvas; update
camera.aspect, callupdateProjectionMatrix(), andrenderer.setSize(...). - Add
OrbitControlsfor orbit/pan/zoom while developing. Confirm something actually renders (a lit cube, the controls responding) before assuming success.
Patterns
1. HTML import map + module entry (no bundler)
<canvas id="c"></canvas>
<script type="importmap">
{
"imports": {
"three": "https://cdn.jsdelivr.net/npm/three@0.184.0/build/three.module.js",
"three/addons/": "https://cdn.jsdelivr.net/npm/three@0.184.0/examples/jsm/"
}
}
</script>
<script type="module" src="./main.js"></script>
With a bundler (Vite/webpack), skip the import map and just
npm i three; the same import statements resolve.
2. Scene + camera + renderer
// main.js
import * as THREE from 'three';
const canvas = document.querySelector('#c');
const renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2)); // cap for perf
renderer.setSize(window.innerWidth, window.innerHeight);
const scene = new THREE.Scene();
scene.background = new THREE.Color(0x101018);
const camera = new THREE.PerspectiveCamera(
60, // vertical field of view (degrees)
window.innerWidth / window.innerHeight, // aspect
0.1, // near
100 // far
);
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() // unlit; shows orientation without a light
);
scene.add(cube);
3. The render loop (setAnimationLoop + Clock)
const clock = new THREE.Clock();
renderer.setAnimationLoop(() => {
const dt = clock.getDelta(); // seconds since last frame
cube.rotation.x += dt; // frame-rate independent
cube.rotation.y += dt * 0.7;
renderer.render(scene, camera);
});
// renderer.setAnimationLoop(null); // stop the loop
4. Responsive resize
function onResize() {
const w = window.innerWidth, h = window.innerHeight;
camera.aspect = w / h;
camera.updateProjectionMatrix(); // required after changing aspect
renderer.setSize(w, h);
}
window.addEventListener('resize', onResize);
5. OrbitControls (orbit / pan / zoom)
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
const controls = new OrbitControls(camera, renderer.domElement);
controls.enableDamping = true; // inertial feel
controls.target.set(0, 0, 0);
renderer.setAnimationLoop(() => {
controls.update(); // needed every frame when damping is on
renderer.render(scene, camera);
});
Pitfalls
Failed to resolve module specifier "three"→ missing import map (or bundler config). Map both"three"and"three/addons/"; addon paths must end with/.- Black canvas, no errors → camera is at the origin (inside/behind the object),
or you used a lit material (
MeshStandardMaterial) with no light. Move the camera back; useMeshNormalMaterial/MeshBasicMaterialto verify geometry first. - Nothing animates → you never called
renderer.renderinside the loop, or you callsetAnimationLoopbut render outside it. - Stretched / squashed view on resize → you resized the renderer but didn't
update
camera.aspect+updateProjectionMatrix(). - Blurry or jagged on HiDPI → set
renderer.setPixelRatio(...); cap it (≈2) so 4K/retina screens don't tank performance. - OrbitControls feel dead → with
enableDamping = trueyou must callcontrols.update()every frame. - Old tutorials use
<script src="three.min.js">→ since r147 three.js ships ES modules only; usetype="module"+ import maps.
References
- For coordinate conventions, the scene-graph (
Group, parent/child transforms,Object3Dadd/remove),OrthographicCamerafor 2.5D, and disposing of geometries/materials/textures to avoid leaks, readreferences/scene-graph.md.
Related skills
threejs-materials-lighting— give surfaces a lit look (lights, shadows, PBR).threejs-gltf-loading— load 3D models and play their animations.pixijs-rendering— 2D rendering in the browser.fps-shooter— a 3D genre template that composes three.js skills.
04 同仓库更多 Skills
webapp-testing
Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
web-typography
Select, pair, and implement typefaces for web projects. Use when the user mentions "font pairing", "which typeface", "line height", "responsive typography", "web font loading", or "type hierarchy". Covers readability evaluation, CSS implementation, and performance optimization. For overall UI design systems, see refactoring-ui. For dramatic typographic experiences, see top-design.
web-haptics
Add haptic feedback to web apps using the web-haptics library. Use when building mobile-facing UIs that need tactile feedback on buttons, toggles, forms, pickers, and other interactive elements.
visual-novel
Build a visual novel: a branching script, character and background display, a text box with choices, save/load, backlog, and skip/auto. Use for a VN, dating sim, or branching story game.
ux-heuristics
Evaluate and improve interface usability using heuristic analysis. Use when the user mentions "usability audit", "UX review", "users are confused", "heuristic evaluation", "form usability", or "navigation problems". Covers Nielsen's 10 heuristics, severity ratings, and information architecture. For visual design fixes, see refactoring-ui. For conversion-focused audits, see cro-methodology.
unreal-packaging
Package and ship an Unreal Engine 5 project: the Platforms menu Package Project flow, build configurations (Development vs Shipping), cooking content, packaging settings and the Game Default Map, and command-line builds with RunUAT BuildCookRun. Use when packaging a build, making a shipping build, cooking content, configuring packaging settings, or when the user mentions package Unreal, cook content, shipping build, or BuildCookRun.