threejs-scene-setup

Q: How do I install threejs-scene-setup?

Run npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill threejs-scene-setup in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/threejs-scene-setup/ (personal) or .claude/skills/threejs-scene-setup/ (project).

by gamedev-skillsAI & Agents

Stand up a three.js scene: import maps and the three/addons path, the Scene/PerspectiveCamera/WebGLRenderer trio, the setAnimationLoop render loop, responsive resize, OrbitControls, and opting into WebGPURenderer. Use when starting or debugging a three.js app — when the user mentions three.js, THREE.Scene, WebGLRenderer, WebGPURenderer, PerspectiveCamera, the render loop, resizing, or OrbitControls. For models use threejs-gltf-loading; for materials/lights use threejs-materials-lighting.

Installs: 5.8K
Last 24h: +308
Trending rank: #943
Security: Pass

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill threejs-scene-setup

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads threejs-scene-setup automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

Security audits

Independent scans of the skill's instructions and bundled files.

Gen Agent Trust Hub PassSAFE ·This skill is a collection of templates and guidelines for setting up three.js 3D scenes. It follows modern web development best practices and uses a well-known CDN for loading the library.

Socket PassNo alerts

Snyk PassLOW ·Risk: LOW · No issues

SKILL.md

The instructions your agent reads when the skill is triggered.

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 r186. Read the installed three version before changing an existing project because examples and addons move across releases.

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.json depends on three and code does import * 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 r137 the bare specifier 'three' must be resolved by an import map (in HTML) or a bundler; map 'three/addons/' too. Addons (controls, loaders) live under three/addons/....
Create the trio. A Scene (root of the graph), a PerspectiveCamera(fov, aspect, near, far) moved back from the origin, and a WebGLRenderer whose domElement is in the DOM. Set size and pixelRatio.
Add a mesh. new Mesh(geometry, material) and scene.add(mesh). With a lit material you also need a light (see threejs-materials-lighting).
Drive a render loop with renderer.setAnimationLoop(fn). It's the modern, WebXR-/WebGPU-safe replacement for hand-rolled requestAnimationFrame. Use a Timer for delta time (Clock is deprecated since r183).
Handle resize so the camera aspect and renderer match the canvas; update camera.aspect, call updateProjectionMatrix(), and renderer.setSize(...).
Add OrbitControls for 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.186.1/build/three.module.js",
    "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.186.1/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 + 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((time) => {
  timer.update(time);                   // call once per frame, before getDelta()
  const dt = timer.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);
});

6. Opting into WebGPURenderer (only when you need it)

WebGLRenderer stays the default choice for compatibility. Switch to WebGPURenderer when the project needs TSL node materials or compute shaders; it falls back to a WebGL 2 backend where WebGPU is unavailable.

// 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, 2));
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.

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; use MeshNormalMaterial/MeshBasicMaterial to verify geometry first.
Nothing animates → you never called renderer.render inside the loop, or you call setAnimationLoop but 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 = true you must call controls.update() every frame.
Old tutorials use <script src="three.min.js"> or examples/js/... → examples/js was removed in r148 and build/three.min.js in r161; use type="module" + import maps.
.render() called before the backend is initialized (WebGPURenderer) → call await renderer.init() before any direct render()/compute(), or render only from setAnimationLoop, which initializes first.
Material "ShaderMaterial" is not compatible, or an onBeforeCompile patch is ignored (WebGPURenderer) → it renders node materials only; port the effect to TSL, or stay on WebGLRenderer.

References

For coordinate conventions, the scene-graph (Group, parent/child transforms, Object3D add/remove), OrthographicCamera for 2.5D, and disposing of geometries/materials/textures to avoid leaks, read references/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.

FAQ

What does the threejs-scene-setup skill do?

How do I install threejs-scene-setup?

Run npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill threejs-scene-setup in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/threejs-scene-setup/ (personal) or .claude/skills/threejs-scene-setup/ (project).

Which AI agents can use threejs-scene-setup?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is threejs-scene-setup safe to install?

Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk passed. As with any skill, read the SKILL.md and bundled scripts before installing.

Who maintains threejs-scene-setup?

It is published by gamedev-skills in gamedev-skills/awesome-gamedev-agent-skills. It has 5,826 recorded installs.