Threejs Skills

1---
2name: threejs-skills
3description: Create 3D scenes, interactive experiences, and visual effects using Three.js. Use when user requests 3D graphics, WebGL experiences, 3D visualizations, animations, or interactive 3D elements.
4source: https://github.com/CloudAI-X/threejs-skills
5risk: safe
6---
7 
8# Three.js Skills
9 
10Systematically create high-quality 3D scenes and interactive experiences using Three.js best practices.
11 
12## When to Use
13 
14- Requests 3D visualizations or graphics ("create a 3D model", "show in 3D")
15- Wants interactive 3D experiences ("rotating cube", "explorable scene")
16- Needs WebGL or canvas-based rendering
17- Asks for animations, particles, or visual effects
18- Mentions Three.js, WebGL, or 3D rendering
19- Wants to visualize data in 3D space
20 
21## Core Setup Pattern
22 
23### 1. Essential Three.js Imports
24 
25Always use the correct CDN version (r128):
26 
27```javascript
28import * as THREE from "https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js";
29```
30 
31**CRITICAL**: Do NOT use example imports like `THREE.OrbitControls` - they won't work on the CDN.
32 
33### 2. Scene Initialization
34 
35Every Three.js artifact needs these core components:
36 
37```javascript
38// Scene - contains all 3D objects
39const scene = new THREE.Scene();
40 
41// Camera - defines viewing perspective
42const camera = new THREE.PerspectiveCamera(
43  75, // Field of view
44  window.innerWidth / window.innerHeight, // Aspect ratio
45  0.1, // Near clipping plane
46  1000, // Far clipping plane
47);
48camera.position.z = 5;
49 
50// Renderer - draws the scene
51const renderer = new THREE.WebGLRenderer({ antialias: true });
52renderer.setSize(window.innerWidth, window.innerHeight);
53document.body.appendChild(renderer.domElement);
54```
55 
56### 3. Animation Loop
57 
58Use requestAnimationFrame for smooth rendering:
59 
60```javascript
61function animate() {
62  requestAnimationFrame(animate);
63 
64  // Update object transformations here
65  mesh.rotation.x += 0.01;
66  mesh.rotation.y += 0.01;
67 
68  renderer.render(scene, camera);
69}
70animate();
71```
72 
73## Systematic Development Process
74 
75### 1. Define the Scene
76 
77Start by identifying:
78 
79- **What objects** need to be rendered
80- **Camera position** and field of view
81- **Lighting setup** required
82- **Interaction model** (static, rotating, user-controlled)
83 
84### 2. Build Geometry
85 
86Choose appropriate geometry types:
87 
88**Basic Shapes:**
89 
90- `BoxGeometry` - cubes, rectangular prisms
91- `SphereGeometry` - spheres, planets
92- `CylinderGeometry` - cylinders, tubes
93- `PlaneGeometry` - flat surfaces, ground planes
94- `TorusGeometry` - donuts, rings
95 
96**IMPORTANT**: Do NOT use `CapsuleGeometry` (introduced in r142, not available in r128)
97 
98**Alternatives for capsules:**
99 
100- Combine `CylinderGeometry` + 2 `SphereGeometry`
101- Use `SphereGeometry` with adjusted parameters
102- Create custom geometry with vertices
103 
104### 3. Apply Materials
105 
106Choose materials based on visual needs:
107 
108**Common Materials:**
109 
110- `MeshBasicMaterial` - unlit, flat colors (no lighting needed)
111- `MeshStandardMaterial` - physically-based, realistic (needs lighting)
112- `MeshPhongMaterial` - shiny surfaces with specular highlights
113- `MeshLambertMaterial` - matte surfaces, diffuse reflection
114 
115```javascript
116const material = new THREE.MeshStandardMaterial({
117  color: 0x00ff00,
118  metalness: 0.5,
119  roughness: 0.5,
120});
121```
122 
123### 4. Add Lighting
124 
125**If using lit materials** (Standard, Phong, Lambert), add lights:
126 
127```javascript
128// Ambient light - general illumination
129const ambientLight = new THREE.AmbientLight(0xffffff, 0.5);
130scene.add(ambientLight);
131 
132// Directional light - like sunlight
133const directionalLight = new THREE.DirectionalLight(0xffffff, 0.8);
134directionalLight.position.set(5, 5, 5);
135scene.add(directionalLight);
136```
137 
138**Skip lighting** if using `MeshBasicMaterial` - it's unlit by design.
139 
140### 5. Handle Responsiveness
141 
142Always add window resize handling:
143 
144```javascript
145window.addEventListener("resize", () => {
146  camera.aspect = window.innerWidth / window.innerHeight;
147  camera.updateProjectionMatrix();
148  renderer.setSize(window.innerWidth, window.innerHeight);
149});
150```
151 
152## Common Patterns
153 
154### Rotating Object
155 
156```javascript
157function animate() {
158  requestAnimationFrame(animate);
159  mesh.rotation.x += 0.01;
160  mesh.rotation.y += 0.01;
161  renderer.render(scene, camera);
162}
163```
164 
165### Custom Camera Controls (OrbitControls Alternative)
166 
167Since `THREE.OrbitControls` isn't available on CDN, implement custom controls:
168 
169```javascript
170let isDragging = false;
171let previousMousePosition = { x: 0, y: 0 };
172 
173renderer.domElement.addEventListener("mousedown", () => {
174  isDragging = true;
175});
176 
177renderer.domElement.addEventListener("mouseup", () => {
178  isDragging = false;
179});
180 
181renderer.domElement.addEventListener("mousemove", (event) => {
182  if (isDragging) {
183    const deltaX = event.clientX - previousMousePosition.x;
184    const deltaY = event.clientY - previousMousePosition.y;
185 
186    // Rotate camera around scene
187    const rotationSpeed = 0.005;
188    camera.position.x += deltaX * rotationSpeed;
189    camera.position.y -= deltaY * rotationSpeed;
190    camera.lookAt(scene.position);
191  }
192 
193  previousMousePosition = { x: event.clientX, y: event.clientY };
194});
195 
196// Zoom with mouse wheel
197renderer.domElement.addEventListener("wheel", (event) => {
198  event.preventDefault();
199  camera.position.z += event.deltaY * 0.01;
200  camera.position.z = Math.max(2, Math.min(20, camera.position.z)); // Clamp
201});
202```
203 
204### Raycasting for Object Selection
205 
206Detect mouse clicks and hovers on 3D objects:
207 
208```javascript
209const raycaster = new THREE.Raycaster();
210const mouse = new THREE.Vector2();
211const clickableObjects = []; // Array of meshes that can be clicked
212 
213// Update mouse position
214window.addEventListener("mousemove", (event) => {
215  mouse.x = (event.clientX / window.innerWidth) * 2 - 1;
216  mouse.y = -(event.clientY / window.innerHeight) * 2 + 1;
217});
218 
219// Detect clicks
220window.addEventListener("click", () => {
221  raycaster.setFromCamera(mouse, camera);
222  const intersects = raycaster.intersectObjects(clickableObjects);
223 
224  if (intersects.length > 0) {
225    const clickedObject = intersects[0].object;
226    // Handle click - change color, scale, etc.
227    clickedObject.material.color.set(0xff0000);
228  }
229});
230 
231// Hover effect in animation loop
232function animate() {
233  requestAnimationFrame(animate);
234 
235  raycaster.setFromCamera(mouse, camera);
236  const intersects = raycaster.intersectObjects(clickableObjects);
237 
238  // Reset all objects
239  clickableObjects.forEach((obj) => {
240    obj.scale.set(1, 1, 1);
241  });
242 
243  // Highlight hovered object
244  if (intersects.length > 0) {
245    intersects[0].object.scale.set(1.2, 1.2, 1.2);
246    document.body.style.cursor = "pointer";
247  } else {
248    document.body.style.cursor = "default";
249  }
250 
251  renderer.render(scene, camera);
252}
253```
254 
255### Particle System
256 
257```javascript
258const particlesGeometry = new THREE.BufferGeometry();
259const particlesCount = 1000;
260const posArray = new Float32Array(particlesCount * 3);
261 
262for (let i = 0; i < particlesCount * 3; i++) {
263  posArray[i] = (Math.random() - 0.5) * 10;
264}
265 
266particlesGeometry.setAttribute(
267  "position",
268  new THREE.BufferAttribute(posArray, 3),
269);
270 
271const particlesMaterial = new THREE.PointsMaterial({
272  size: 0.02,
273  color: 0xffffff,
274});
275 
276const particlesMesh = new THREE.Points(particlesGeometry, particlesMaterial);
277scene.add(particlesMesh);
278```
279 
280### User Interaction (Mouse Movement)
281 
282```javascript
283let mouseX = 0;
284let mouseY = 0;
285 
286document.addEventListener("mousemove", (event) => {
287  mouseX = (event.clientX / window.innerWidth) * 2 - 1;
288  mouseY = -(event.clientY / window.innerHeight) * 2 + 1;
289});
290 
291function animate() {
292  requestAnimationFrame(animate);
293  camera.position.x = mouseX * 2;
294  camera.position.y = mouseY * 2;
295  camera.lookAt(scene.position);
296  renderer.render(scene, camera);
297}
298```
299 
300### Loading Textures
301 
302```javascript
303const textureLoader = new THREE.TextureLoader();
304const texture = textureLoader.load("texture-url.jpg");
305 
306const material = new THREE.MeshStandardMaterial({
307  map: texture,
308});
309```
310 
311## Best Practices
312 
313### Performance
314 
315- **Reuse geometries and materials** when creating multiple similar objects
316- **Use `BufferGeometry`** for custom shapes (more efficient)
317- **Limit particle counts** to maintain 60fps (start with 1000-5000)
318- **Dispose of resources** when removing objects:
319  ```javascript
320  geometry.dispose();
321  material.dispose();
322  texture.dispose();
323  ```
324 
325### Visual Quality
326 
327- Always set `antialias: true` on renderer for smooth edges
328- Use appropriate camera FOV (45-75 degrees typical)
329- Position lights thoughtfully - avoid overlapping multiple bright lights
330- Add ambient + directional lighting for realistic scenes
331 
332### Code Organization
333 
334- Initialize scene, camera, renderer at the top
335- Group related objects (e.g., all particles in one group)
336- Keep animation logic in the animate function
337- Separate object creation into functions for complex scenes
338 
339### Common Pitfalls to Avoid
340 
341- ❌ Using `THREE.OrbitControls` - not available on CDN
342- ❌ Using `THREE.CapsuleGeometry` - requires r142+
343- ❌ Forgetting to add objects to scene with `scene.add()`
344- ❌ Using lit materials without adding lights
345- ❌ Not handling window resize
346- ❌ Forgetting to call `renderer.render()` in animation loop
347 
348## Example Workflow
349 
350User: "Create an interactive 3D sphere that responds to mouse movement"
351 
3521. **Setup**: Import Three.js (r128), create scene/camera/renderer
3532. **Geometry**: Create `SphereGeometry(1, 32, 32)` for smooth sphere
3543. **Material**: Use `MeshStandardMaterial` for realistic look
3554. **Lighting**: Add ambient + directional lights
3565. **Interaction**: Track mouse position, update camera
3576. **Animation**: Rotate sphere, render continuously
3587. **Responsive**: Add window resize handler
3598. **Result**: Smooth, interactive 3D sphere ✓
360 
361## Troubleshooting
362 
363**Black screen / Nothing renders:**
364 
365- Check if objects added to scene
366- Verify camera position isn't inside objects
367- Ensure renderer.render() is called
368- Add lights if using lit materials
369 
370**Poor performance:**
371 
372- Reduce particle count
373- Lower geometry detail (segments)
374- Reuse materials/geometries
375- Check browser console for errors
376 
377**Objects not visible:**
378 
379- Check object position vs camera position
380- Verify material has visible color/properties
381- Ensure camera far plane includes objects
382- Add lighting if needed
383 
384## Advanced Techniques
385 
386### Visual Polish for Portfolio-Grade Rendering
387 
388**Shadows:**
389 
390```javascript
391// Enable shadows on renderer
392renderer.shadowMap.enabled = true;
393renderer.shadowMap.type = THREE.PCFSoftShadowMap; // Soft shadows
394 
395// Light that casts shadows
396const directionalLight = new THREE.DirectionalLight(0xffffff, 1);
397directionalLight.position.set(5, 10, 5);
398directionalLight.castShadow = true;
399 
400// Configure shadow quality
401directionalLight.shadow.mapSize.width = 2048;
402directionalLight.shadow.mapSize.height = 2048;
403directionalLight.shadow.camera.near = 0.5;
404directionalLight.shadow.camera.far = 50;
405 
406scene.add(directionalLight);
407 
408// Objects cast and receive shadows
409mesh.castShadow = true;
410mesh.receiveShadow = true;
411 
412// Ground plane receives shadows
413const groundGeometry = new THREE.PlaneGeometry(20, 20);
414const groundMaterial = new THREE.MeshStandardMaterial({ color: 0x808080 });
415const ground = new THREE.Mesh(groundGeometry, groundMaterial);
416ground.rotation.x = -Math.PI / 2;
417ground.receiveShadow = true;
418scene.add(ground);
419```
420 
421**Environment Maps & Reflections:**
422 
423```javascript
424// Create environment map from cubemap
425const loader = new THREE.CubeTextureLoader();
426const envMap = loader.load([
427  "px.jpg",
428  "nx.jpg", // positive x, negative x
429  "py.jpg",
430  "ny.jpg", // positive y, negative y
431  "pz.jpg",
432  "nz.jpg", // positive z, negative z
433]);
434 
435scene.environment = envMap; // Affects all PBR materials
436scene.background = envMap; // Optional: use as skybox
437 
438// Or apply to specific materials
439const material = new THREE.MeshStandardMaterial({
440  metalness: 1.0,
441  roughness: 0.1,
442  envMap: envMap,
443});
444```
445 
446**Tone Mapping & Output Encoding:**
447 
448```javascript
449// Improve color accuracy and HDR rendering
450renderer.toneMapping = THREE.ACESFilmicToneMapping;
451renderer.toneMappingExposure = 1.0;
452renderer.outputEncoding = THREE.sRGBEncoding;
453 
454// Makes colors more vibrant and realistic
455```
456 
457**Fog for Depth:**
458 
459```javascript
460// Linear fog
461scene.fog = new THREE.Fog(0xcccccc, 10, 50); // color, near, far
462 
463// Or exponential fog (more realistic)
464scene.fog = new THREE.FogExp2(0xcccccc, 0.02); // color, density
465```
466 
467### Custom Geometry from Vertices
468 
469```javascript
470const geometry = new THREE.BufferGeometry();
471const vertices = new Float32Array([-1, -1, 0, 1, -1, 0, 1, 1, 0]);
472geometry.setAttribute("position", new THREE.BufferAttribute(vertices, 3));
473```
474 
475### Post-Processing Effects
476 
477While advanced post-processing may not be available in r128 CDN, basic effects can be achieved with shaders and render targets.
478 
479### Group Objects
480 
481```javascript
482const group = new THREE.Group();
483group.add(mesh1);
484group.add(mesh2);
485group.rotation.y = Math.PI / 4;
486scene.add(group);
487```
488 
489## Summary
490 
491Three.js artifacts require systematic setup:
492 
4931. Import correct CDN version (r128)
4942. Initialize scene, camera, renderer
4953. Create geometry + material = mesh
4964. Add lighting if using lit materials
4975. Implement animation loop
4986. Handle window resize
4997. Avoid r128 incompatible features
500 
501Follow these patterns for reliable, performant 3D experiences.
502 
503## Modern Three.js & Production Practices
504 
505While this skill focuses on CDN-based Three.js (r128) for artifact compatibility, here's what you'd do in production environments:
506 
507### Modular Imports with Build Tools
508 
509```javascript
510// In production with npm/vite/webpack:
511import * as THREE from "three";
512import { OrbitControls } from "three/examples/jsm/controls/OrbitControls";
513import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader";
514import { EffectComposer } from "three/examples/jsm/postprocessing/EffectComposer";
515```
516 
517**Benefits:**
518 
519- Tree-shaking (smaller bundle sizes)
520- Access to full example library (OrbitControls, loaders, etc.)
521- Latest Three.js features (r150+)
522- TypeScript support
523 
524### Animation Libraries (GSAP Integration)
525 
526```javascript
527// Smooth timeline-based animations
528import gsap from "gsap";
529 
530// Instead of manual animation loops:
531gsap.to(mesh.position, {
532  x: 5,
533  duration: 2,
534  ease: "power2.inOut",
535});
536 
537// Complex sequences:
538const timeline = gsap.timeline();
539timeline
540  .to(mesh.rotation, { y: Math.PI * 2, duration: 2 })
541  .to(mesh.scale, { x: 2, y: 2, z: 2, duration: 1 }, "-=1");
542```
543 
544**Why GSAP:**
545 
546- Professional easing functions
547- Timeline control (pause, reverse, scrub)
548- Better than manual lerping for complex animations
549 
550### Scroll-Based Interactions
551 
552```javascript
553// Sync 3D animations with page scroll
554let scrollY = window.scrollY;
555 
556window.addEventListener("scroll", () => {
557  scrollY = window.scrollY;
558});
559 
560function animate() {
561  requestAnimationFrame(animate);
562 
563  // Rotate based on scroll position
564  mesh.rotation.y = scrollY * 0.001;
565 
566  // Move camera through scene
567  camera.position.y = -(scrollY / window.innerHeight) * 10;
568 
569  renderer.render(scene, camera);
570}
571```
572 
573**Advanced scroll libraries:**
574 
575- ScrollTrigger (GSAP plugin)
576- Locomotive Scroll
577- Lenis smooth scroll
578 
579### Performance Optimization in Production
580 
581```javascript
582// Level of Detail (LOD)
583const lod = new THREE.LOD();
584lod.addLevel(highDetailMesh, 0); // Close up
585lod.addLevel(mediumDetailMesh, 10); // Medium distance
586lod.addLevel(lowDetailMesh, 50); // Far away
587scene.add(lod);
588 
589// Instanced meshes for many identical objects
590const geometry = new THREE.BoxGeometry();
591const material = new THREE.MeshStandardMaterial();
592const instancedMesh = new THREE.InstancedMesh(geometry, material, 1000);
593 
594// Set transforms for each instance
595const matrix = new THREE.Matrix4();
596for (let i = 0; i < 1000; i++) {
597  matrix.setPosition(
598    Math.random() * 100,
599    Math.random() * 100,
600    Math.random() * 100,
601  );
602  instancedMesh.setMatrixAt(i, matrix);
603}
604```
605 
606### Modern Loading Patterns
607 
608```javascript
609// In production, load 3D models:
610import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader";
611 
612const loader = new GLTFLoader();
613loader.load("model.gltf", (gltf) => {
614  scene.add(gltf.scene);
615 
616  // Traverse and setup materials
617  gltf.scene.traverse((child) => {
618    if (child.isMesh) {
619      child.castShadow = true;
620      child.receiveShadow = true;
621    }
622  });
623});
624```
625 
626### When to Use What
627 
628**CDN Approach (Current Skill):**
629 
630- Quick prototypes and demos
631- Educational content
632- Artifacts and embedded experiences
633- No build step required
634 
635**Production Build Approach:**
636 
637- Client projects and portfolios
638- Complex applications
639- Need latest features (r150+)
640- Performance-critical applications
641- Team collaboration with version control
642 
643### Recommended Production Stack
644 
645```
646Three.js (latest) + Vite/Webpack
647├── GSAP (animations)
648├── React Three Fiber (optional - React integration)
649├── Drei (helper components)
650├── Leva (debug GUI)
651└── Post-processing effects
652```
653 
654This skill provides CDN-compatible foundations. In production, you'd layer on these modern tools for professional results.
655