opencode-skills-collection 4.0.53 → 4.0.55

package/bundled-skills/threejs-skills/references/detailed-guide.md

@@ -0,0 +1,693 @@
+# Three.js Skills - Detailed Guide
+
+> This file contains the detailed procedure and reference material extracted from `SKILL.md` for focused loading. The root skill defines activation, examples, safety constraints, and limitations.
+
+## Core Setup Pattern
+
+### 1. Essential Three.js Imports
+
+Use ES module import maps for modern Three.js (r183+):
+
+```html
+<script type="importmap">
+{
+  "imports": {
+    "three": "https://cdn.jsdelivr.net/npm/three@0.183.0/build/three.module.js",
+    "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.183.0/examples/jsm/"
+  }
+}
+</script>
+<script type="module">
+import * as THREE from "three";
+import { OrbitControls } from "three/addons/controls/OrbitControls.js";
+</script>
+```
+
+For production with npm/vite/webpack:
+
+```javascript
+import * as THREE from "three";
+import { OrbitControls } from "three/addons/controls/OrbitControls.js";
+```
+
+### 2. Scene Initialization
+
+Every Three.js artifact needs these core components:
+
+```javascript
+// Scene - contains all 3D objects
+const scene = new THREE.Scene();
+
+// Camera - defines viewing perspective
+const camera = new THREE.PerspectiveCamera(
+  75, // Field of view
+  window.innerWidth / window.innerHeight, // Aspect ratio
+  0.1, // Near clipping plane
+  1000, // Far clipping plane
+);
+camera.position.z = 5;
+
+// Renderer - draws the scene
+const renderer = new THREE.WebGLRenderer({ antialias: true });
+renderer.setSize(window.innerWidth, window.innerHeight);
+document.body.appendChild(renderer.domElement);
+```
+
+### 3. Animation Loop
+
+Use `renderer.setAnimationLoop()` (preferred) or `requestAnimationFrame`:
+
+```javascript
+// Preferred: setAnimationLoop (handles WebXR compatibility)
+renderer.setAnimationLoop(() => {
+  mesh.rotation.x += 0.01;
+  mesh.rotation.y += 0.01;
+  renderer.render(scene, camera);
+});
+
+// Alternative: manual requestAnimationFrame
+function animate() {
+  requestAnimationFrame(animate);
+  mesh.rotation.x += 0.01;
+  mesh.rotation.y += 0.01;
+  renderer.render(scene, camera);
+}
+animate();
+```
+
+
+## Systematic Development Process
+
+### 1. Define the Scene
+
+Start by identifying:
+
+- **What objects** need to be rendered
+- **Camera position** and field of view
+- **Lighting setup** required
+- **Interaction model** (static, rotating, user-controlled)
+
+### 2. Build Geometry
+
+Choose appropriate geometry types:
+
+**Basic Shapes:**
+
+- `BoxGeometry` - cubes, rectangular prisms
+- `SphereGeometry` - spheres, planets
+- `CylinderGeometry` - cylinders, tubes
+- `PlaneGeometry` - flat surfaces, ground planes
+- `TorusGeometry` - donuts, rings
+
+**CapsuleGeometry** is available (stable since r142):
+
+```javascript
+new THREE.CapsuleGeometry(0.5, 1, 4, 8); // radius, length, capSegments, radialSegments
+```
+
+### 3. Apply Materials
+
+Choose materials based on visual needs:
+
+**Common Materials:**
+
+- `MeshBasicMaterial` - unlit, flat colors (no lighting needed)
+- `MeshStandardMaterial` - physically-based, realistic (needs lighting)
+- `MeshPhongMaterial` - shiny surfaces with specular highlights
+- `MeshLambertMaterial` - matte surfaces, diffuse reflection
+
+```javascript
+const material = new THREE.MeshStandardMaterial({
+  color: 0x00ff00,
+  metalness: 0.5,
+  roughness: 0.5,
+});
+```
+
+### 4. Add Lighting
+
+**If using lit materials** (Standard, Phong, Lambert), add lights:
+
+```javascript
+// Ambient light - general illumination
+const ambientLight = new THREE.AmbientLight(0xffffff, 0.5);
+scene.add(ambientLight);
+
+// Directional light - like sunlight
+const directionalLight = new THREE.DirectionalLight(0xffffff, 0.8);
+directionalLight.position.set(5, 5, 5);
+scene.add(directionalLight);
+```
+
+**Skip lighting** if using `MeshBasicMaterial` - it's unlit by design.
+
+### 5. Handle Responsiveness
+
+Always add window resize handling:
+
+```javascript
+window.addEventListener("resize", () => {
+  camera.aspect = window.innerWidth / window.innerHeight;
+  camera.updateProjectionMatrix();
+  renderer.setSize(window.innerWidth, window.innerHeight);
+});
+```
+
+
+## Common Patterns
+
+### Rotating Object
+
+```javascript
+function animate() {
+  requestAnimationFrame(animate);
+  mesh.rotation.x += 0.01;
+  mesh.rotation.y += 0.01;
+  renderer.render(scene, camera);
+}
+```
+
+### OrbitControls
+
+With import maps or build tools, OrbitControls works directly:
+
+```javascript
+import { OrbitControls } from "three/addons/controls/OrbitControls.js";
+
+const controls = new OrbitControls(camera, renderer.domElement);
+controls.enableDamping = true;
+
+// Update in animation loop
+renderer.setAnimationLoop(() => {
+  controls.update();
+  renderer.render(scene, camera);
+});
+```
+
+### Custom Camera Controls (Alternative)
+
+For lightweight custom controls without importing OrbitControls:
+
+```javascript
+let isDragging = false;
+let previousMousePosition = { x: 0, y: 0 };
+
+renderer.domElement.addEventListener("mousedown", () => {
+  isDragging = true;
+});
+
+renderer.domElement.addEventListener("mouseup", () => {
+  isDragging = false;
+});
+
+renderer.domElement.addEventListener("mousemove", (event) => {
+  if (isDragging) {
+    const deltaX = event.clientX - previousMousePosition.x;
+    const deltaY = event.clientY - previousMousePosition.y;
+
+    // Rotate camera around scene
+    const rotationSpeed = 0.005;
+    camera.position.x += deltaX * rotationSpeed;
+    camera.position.y -= deltaY * rotationSpeed;
+    camera.lookAt(scene.position);
+  }
+
+  previousMousePosition = { x: event.clientX, y: event.clientY };
+});
+
+// Zoom with mouse wheel
+renderer.domElement.addEventListener("wheel", (event) => {
+  event.preventDefault();
+  camera.position.z += event.deltaY * 0.01;
+  camera.position.z = Math.max(2, Math.min(20, camera.position.z)); // Clamp
+});
+```
+
+### Raycasting for Object Selection
+
+Detect mouse clicks and hovers on 3D objects:
+
+```javascript
+const raycaster = new THREE.Raycaster();
+const mouse = new THREE.Vector2();
+const clickableObjects = []; // Array of meshes that can be clicked
+
+// Update mouse position
+window.addEventListener("mousemove", (event) => {
+  mouse.x = (event.clientX / window.innerWidth) * 2 - 1;
+  mouse.y = -(event.clientY / window.innerHeight) * 2 + 1;
+});
+
+// Detect clicks
+window.addEventListener("click", () => {
+  raycaster.setFromCamera(mouse, camera);
+  const intersects = raycaster.intersectObjects(clickableObjects);
+
+  if (intersects.length > 0) {
+    const clickedObject = intersects[0].object;
+    // Handle click - change color, scale, etc.
+    clickedObject.material.color.set(0xff0000);
+  }
+});
+
+// Hover effect in animation loop
+function animate() {
+  requestAnimationFrame(animate);
+
+  raycaster.setFromCamera(mouse, camera);
+  const intersects = raycaster.intersectObjects(clickableObjects);
+
+  // Reset all objects
+  clickableObjects.forEach((obj) => {
+    obj.scale.set(1, 1, 1);
+  });
+
+  // Highlight hovered object
+  if (intersects.length > 0) {
+    intersects[0].object.scale.set(1.2, 1.2, 1.2);
+    document.body.style.cursor = "pointer";
+  } else {
+    document.body.style.cursor = "default";
+  }
+
+  renderer.render(scene, camera);
+}
+```
+
+### Particle System
+
+```javascript
+const particlesGeometry = new THREE.BufferGeometry();
+const particlesCount = 1000;
+const posArray = new Float32Array(particlesCount * 3);
+
+for (let i = 0; i < particlesCount * 3; i++) {
+  posArray[i] = (Math.random() - 0.5) * 10;
+}
+
+particlesGeometry.setAttribute(
+  "position",
+  new THREE.BufferAttribute(posArray, 3),
+);
+
+const particlesMaterial = new THREE.PointsMaterial({
+  size: 0.02,
+  color: 0xffffff,
+});
+
+const particlesMesh = new THREE.Points(particlesGeometry, particlesMaterial);
+scene.add(particlesMesh);
+```
+
+### User Interaction (Mouse Movement)
+
+```javascript
+let mouseX = 0;
+let mouseY = 0;
+
+document.addEventListener("mousemove", (event) => {
+  mouseX = (event.clientX / window.innerWidth) * 2 - 1;
+  mouseY = -(event.clientY / window.innerHeight) * 2 + 1;
+});
+
+function animate() {
+  requestAnimationFrame(animate);
+  camera.position.x = mouseX * 2;
+  camera.position.y = mouseY * 2;
+  camera.lookAt(scene.position);
+  renderer.render(scene, camera);
+}
+```
+
+### Loading Textures
+
+```javascript
+const textureLoader = new THREE.TextureLoader();
+const texture = textureLoader.load("texture-url.jpg");
+
+const material = new THREE.MeshStandardMaterial({
+  map: texture,
+});
+```
+
+
+## Best Practices
+
+### Performance
+
+- **Reuse geometries and materials** when creating multiple similar objects
+- **Use `BufferGeometry`** for custom shapes (more efficient)
+- **Limit particle counts** to maintain 60fps (start with 1000-5000)
+- **Dispose of resources** when removing objects:
+  ```javascript
+  geometry.dispose();
+  material.dispose();
+  texture.dispose();
+  ```
+
+### Visual Quality
+
+- Always set `antialias: true` on renderer for smooth edges
+- Use appropriate camera FOV (45-75 degrees typical)
+- Position lights thoughtfully - avoid overlapping multiple bright lights
+- Add ambient + directional lighting for realistic scenes
+
+### Code Organization
+
+- Initialize scene, camera, renderer at the top
+- Group related objects (e.g., all particles in one group)
+- Keep animation logic in the animate function
+- Separate object creation into functions for complex scenes
+
+### Common Pitfalls to Avoid
+
+- ❌ Using `outputEncoding` instead of `outputColorSpace` (renamed in r152)
+- ❌ Forgetting to add objects to scene with `scene.add()`
+- ❌ Using lit materials without adding lights
+- ❌ Not handling window resize
+- ❌ Forgetting to call `renderer.render()` in animation loop
+- ❌ Using `THREE.Clock` without considering `THREE.Timer` (recommended in r183)
+
+
+## Troubleshooting
+
+**Black screen / Nothing renders:**
+
+- Check if objects added to scene
+- Verify camera position isn't inside objects
+- Ensure renderer.render() is called
+- Add lights if using lit materials
+
+**Poor performance:**
+
+- Reduce particle count
+- Lower geometry detail (segments)
+- Reuse materials/geometries
+- Check browser console for errors
+
+**Objects not visible:**
+
+- Check object position vs camera position
+- Verify material has visible color/properties
+- Ensure camera far plane includes objects
+- Add lighting if needed
+
+
+## Advanced Techniques
+
+### Visual Polish for Portfolio-Grade Rendering
+
+**Shadows:**
+
+```javascript
+// Enable shadows on renderer
+renderer.shadowMap.enabled = true;
+renderer.shadowMap.type = THREE.PCFSoftShadowMap; // Soft shadows
+
+// Light that casts shadows
+const directionalLight = new THREE.DirectionalLight(0xffffff, 1);
+directionalLight.position.set(5, 10, 5);
+directionalLight.castShadow = true;
+
+// Configure shadow quality
+directionalLight.shadow.mapSize.width = 2048;
+directionalLight.shadow.mapSize.height = 2048;
+directionalLight.shadow.camera.near = 0.5;
+directionalLight.shadow.camera.far = 50;
+
+scene.add(directionalLight);
+
+// Objects cast and receive shadows
+mesh.castShadow = true;
+mesh.receiveShadow = true;
+
+// Ground plane receives shadows
+const groundGeometry = new THREE.PlaneGeometry(20, 20);
+const groundMaterial = new THREE.MeshStandardMaterial({ color: 0x808080 });
+const ground = new THREE.Mesh(groundGeometry, groundMaterial);
+ground.rotation.x = -Math.PI / 2;
+ground.receiveShadow = true;
+scene.add(ground);
+```
+
+**Environment Maps & Reflections:**
+
+```javascript
+// Create environment map from cubemap
+const loader = new THREE.CubeTextureLoader();
+const envMap = loader.load([
+  "px.jpg",
+  "nx.jpg", // positive x, negative x
+  "py.jpg",
+  "ny.jpg", // positive y, negative y
+  "pz.jpg",
+  "nz.jpg", // positive z, negative z
+]);
+
+scene.environment = envMap; // Affects all PBR materials
+scene.background = envMap; // Optional: use as skybox
+
+// Or apply to specific materials
+const material = new THREE.MeshStandardMaterial({
+  metalness: 1.0,
+  roughness: 0.1,
+  envMap: envMap,
+});
+```
+
+**Tone Mapping & Output Encoding:**
+
+```javascript
+// Improve color accuracy and HDR rendering
+renderer.toneMapping = THREE.ACESFilmicToneMapping;
+renderer.toneMappingExposure = 1.0;
+renderer.outputColorSpace = THREE.SRGBColorSpace; // Was outputEncoding in older versions
+
+// Makes colors more vibrant and realistic
+```
+
+**Fog for Depth:**
+
+```javascript
+// Linear fog
+scene.fog = new THREE.Fog(0xcccccc, 10, 50); // color, near, far
+
+// Or exponential fog (more realistic)
+scene.fog = new THREE.FogExp2(0xcccccc, 0.02); // color, density
+```
+
+### Custom Geometry from Vertices
+
+```javascript
+const geometry = new THREE.BufferGeometry();
+const vertices = new Float32Array([-1, -1, 0, 1, -1, 0, 1, 1, 0]);
+geometry.setAttribute("position", new THREE.BufferAttribute(vertices, 3));
+```
+
+### Post-Processing Effects
+
+Post-processing effects are available via import maps or build tools. See `threejs-postprocessing` skill for EffectComposer, bloom, DOF, and more.
+
+### Group Objects
+
+```javascript
+const group = new THREE.Group();
+group.add(mesh1);
+group.add(mesh2);
+group.rotation.y = Math.PI / 4;
+scene.add(group);
+```
+
+
+## Summary
+
+Three.js artifacts require systematic setup:
+
+1. Import Three.js via import maps or build tools
+2. Initialize scene, camera, renderer
+3. Create geometry + material = mesh
+4. Add lighting if using lit materials
+5. Implement animation loop (prefer `setAnimationLoop`)
+6. Handle window resize
+7. Set `renderer.outputColorSpace = THREE.SRGBColorSpace`
+
+Follow these patterns for reliable, performant 3D experiences.
+
+
+## Modern Three.js Practices (r183)
+
+### Modular Imports
+
+```javascript
+// With npm/vite/webpack:
+import * as THREE from "three";
+import { OrbitControls } from "three/addons/controls/OrbitControls.js";
+import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
+import { EffectComposer } from "three/addons/postprocessing/EffectComposer.js";
+```
+
+### WebGPU Renderer (Alternative)
+
+Three.js r183 includes a WebGPU renderer as an alternative to WebGL:
+
+```javascript
+import { WebGPURenderer } from "three/addons/renderers/webgpu/WebGPURenderer.js";
+
+const renderer = new WebGPURenderer({ antialias: true });
+await renderer.init();
+renderer.setSize(window.innerWidth, window.innerHeight);
+```
+
+WebGPU uses TSL (Three.js Shading Language) instead of GLSL for custom shaders. See `threejs-shaders` for details.
+
+### Timer (r183 Recommended)
+
+`THREE.Timer` is recommended over `THREE.Clock` as of r183:
+
+```javascript
+const timer = new THREE.Timer();
+
+renderer.setAnimationLoop(() => {
+  timer.update();
+  const delta = timer.getDelta();
+  const elapsed = timer.getElapsed();
+
+  mesh.rotation.y += delta;
+  renderer.render(scene, camera);
+});
+```
+
+**Benefits over Clock:**
+
+- Not affected by page visibility (pauses when tab is hidden)
+- Cleaner API design
+- Better integration with `setAnimationLoop`
+
+### Animation Libraries (GSAP Integration)
+
+```javascript
+// Smooth timeline-based animations
+import gsap from "gsap";
+
+// Instead of manual animation loops:
+gsap.to(mesh.position, {
+  x: 5,
+  duration: 2,
+  ease: "power2.inOut",
+});
+
+// Complex sequences:
+const timeline = gsap.timeline();
+timeline
+  .to(mesh.rotation, { y: Math.PI * 2, duration: 2 })
+  .to(mesh.scale, { x: 2, y: 2, z: 2, duration: 1 }, "-=1");
+```
+
+**Why GSAP:**
+
+- Professional easing functions
+- Timeline control (pause, reverse, scrub)
+- Better than manual lerping for complex animations
+
+### Scroll-Based Interactions
+
+```javascript
+// Sync 3D animations with page scroll
+let scrollY = window.scrollY;
+
+window.addEventListener("scroll", () => {
+  scrollY = window.scrollY;
+});
+
+function animate() {
+  requestAnimationFrame(animate);
+
+  // Rotate based on scroll position
+  mesh.rotation.y = scrollY * 0.001;
+
+  // Move camera through scene
+  camera.position.y = -(scrollY / window.innerHeight) * 10;
+
+  renderer.render(scene, camera);
+}
+```
+
+**Advanced scroll libraries:**
+
+- ScrollTrigger (GSAP plugin)
+- Locomotive Scroll
+- Lenis smooth scroll
+
+### Performance Optimization in Production
+
+```javascript
+// Level of Detail (LOD)
+const lod = new THREE.LOD();
+lod.addLevel(highDetailMesh, 0); // Close up
+lod.addLevel(mediumDetailMesh, 10); // Medium distance
+lod.addLevel(lowDetailMesh, 50); // Far away
+scene.add(lod);
+
+// Instanced meshes for many identical objects
+const geometry = new THREE.BoxGeometry();
+const material = new THREE.MeshStandardMaterial();
+const instancedMesh = new THREE.InstancedMesh(geometry, material, 1000);
+
+// Set transforms for each instance
+const matrix = new THREE.Matrix4();
+for (let i = 0; i < 1000; i++) {
+  matrix.setPosition(
+    Math.random() * 100,
+    Math.random() * 100,
+    Math.random() * 100,
+  );
+  instancedMesh.setMatrixAt(i, matrix);
+}
+```
+
+### Modern Loading Patterns
+
+```javascript
+// In production, load 3D models:
+import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader";
+
+const loader = new GLTFLoader();
+loader.load("model.gltf", (gltf) => {
+  scene.add(gltf.scene);
+
+  // Traverse and setup materials
+  gltf.scene.traverse((child) => {
+    if (child.isMesh) {
+      child.castShadow = true;
+      child.receiveShadow = true;
+    }
+  });
+});
+```
+
+### When to Use What
+
+**Import Map Approach:**
+
+- Quick prototypes and demos
+- Educational content
+- Artifacts and embedded experiences
+- No build step required
+
+**Production Build Approach:**
+
+- Client projects and portfolios
+- Complex applications
+- Performance-critical applications
+- Team collaboration with version control
+
+### Recommended Production Stack
+
+```
+Three.js r183 + Vite
+├── GSAP (animations)
+├── React Three Fiber (optional - React integration)
+├── Drei (helper components)
+├── Leva (debug GUI)
+└── Post-processing effects
+```