anchi-kit 1.2.3 → 1.2.6

package/.cursor/skills/threejs/references/10-controls.md

@@ -0,0 +1,259 @@
+# Camera Controls (Addons)
+
+Interactive camera navigation systems.
+
+## OrbitControls (Most Common)
+
+Orbit camera around a target:
+
+```javascript
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+
+const controls = new OrbitControls(camera, renderer.domElement);
+
+// Target point
+controls.target.set(0, 0, 0);
+
+// Damping (smooth motion)
+controls.enableDamping = true;
+controls.dampingFactor = 0.05;
+
+// Zoom limits
+controls.minDistance = 5;
+controls.maxDistance = 50;
+
+// Rotation limits
+controls.minPolarAngle = 0;                // radians
+controls.maxPolarAngle = Math.PI / 2;      // prevent going below ground
+controls.minAzimuthAngle = -Math.PI / 4;   // horizontal limit
+controls.maxAzimuthAngle = Math.PI / 4;
+
+// Behavior
+controls.enablePan = true;
+controls.enableZoom = true;
+controls.enableRotate = true;
+controls.autoRotate = true;
+controls.autoRotateSpeed = 2.0;
+
+// Mouse buttons
+controls.mouseButtons = {
+  LEFT: THREE.MOUSE.ROTATE,
+  MIDDLE: THREE.MOUSE.DOLLY,
+  RIGHT: THREE.MOUSE.PAN
+};
+
+// In animation loop (required if damping enabled)
+function animate() {
+  controls.update();
+  renderer.render(scene, camera);
+  requestAnimationFrame(animate);
+}
+
+// Events
+controls.addEventListener('change', () => {
+  renderer.render(scene, camera);
+});
+```
+
+## MapControls
+
+Bird's-eye map navigation (like OrbitControls but different mouse behavior):
+
+```javascript
+import { MapControls } from 'three/addons/controls/MapControls.js';
+
+const controls = new MapControls(camera, renderer.domElement);
+controls.enableDamping = true;
+controls.screenSpacePanning = false;
+controls.maxPolarAngle = Math.PI / 2;
+
+// Mouse buttons
+controls.mouseButtons = {
+  LEFT: THREE.MOUSE.PAN,
+  MIDDLE: THREE.MOUSE.DOLLY,
+  RIGHT: THREE.MOUSE.ROTATE
+};
+```
+
+## FirstPersonControls
+
+FPS-style camera movement:
+
+```javascript
+import { FirstPersonControls } from 'three/addons/controls/FirstPersonControls.js';
+
+const controls = new FirstPersonControls(camera, renderer.domElement);
+
+controls.movementSpeed = 10;
+controls.lookSpeed = 0.1;
+controls.lookVertical = true;
+controls.constrainVertical = true;
+controls.verticalMin = 1.0;
+controls.verticalMax = 2.0;
+
+// Requires delta time
+const clock = new THREE.Clock();
+function animate() {
+  const delta = clock.getDelta();
+  controls.update(delta);
+  renderer.render(scene, camera);
+  requestAnimationFrame(animate);
+}
+```
+
+## FlyControls
+
+Free-form flying navigation:
+
+```javascript
+import { FlyControls } from 'three/addons/controls/FlyControls.js';
+
+const controls = new FlyControls(camera, renderer.domElement);
+
+controls.movementSpeed = 10;
+controls.rollSpeed = Math.PI / 24;
+controls.autoForward = false;
+controls.dragToLook = false;
+
+const clock = new THREE.Clock();
+function animate() {
+  const delta = clock.getDelta();
+  controls.update(delta);
+  renderer.render(scene, camera);
+  requestAnimationFrame(animate);
+}
+```
+
+## PointerLockControls
+
+Locked pointer FPS controls:
+
+```javascript
+import { PointerLockControls } from 'three/addons/controls/PointerLockControls.js';
+
+const controls = new PointerLockControls(camera, renderer.domElement);
+
+// Lock pointer on click
+renderer.domElement.addEventListener('click', () => {
+  controls.lock();
+});
+
+controls.addEventListener('lock', () => {
+  console.log('Locked');
+});
+
+controls.addEventListener('unlock', () => {
+  console.log('Unlocked');
+});
+
+// Movement
+const velocity = new THREE.Vector3();
+const direction = new THREE.Vector3();
+
+window.addEventListener('keydown', (event) => {
+  switch (event.code) {
+    case 'KeyW': moveForward = true; break;
+    case 'KeyS': moveBackward = true; break;
+    case 'KeyA': moveLeft = true; break;
+    case 'KeyD': moveRight = true; break;
+  }
+});
+
+function animate() {
+  if (controls.isLocked) {
+    // Calculate movement
+    direction.z = Number(moveForward) - Number(moveBackward);
+    direction.x = Number(moveRight) - Number(moveLeft);
+    direction.normalize();
+
+    controls.moveForward(direction.z * 10);
+    controls.moveRight(direction.x * 10);
+  }
+  renderer.render(scene, camera);
+  requestAnimationFrame(animate);
+}
+```
+
+## TrackballControls
+
+Intuitive rotation (no gimbal lock):
+
+```javascript
+import { TrackballControls } from 'three/addons/controls/TrackballControls.js';
+
+const controls = new TrackballControls(camera, renderer.domElement);
+
+controls.rotateSpeed = 1.0;
+controls.zoomSpeed = 1.2;
+controls.panSpeed = 0.8;
+controls.staticMoving = true;
+controls.dynamicDampingFactor = 0.3;
+
+function animate() {
+  controls.update();
+  renderer.render(scene, camera);
+  requestAnimationFrame(animate);
+}
+```
+
+## ArcballControls
+
+3D rotation with virtual ball metaphor:
+
+```javascript
+import { ArcballControls } from 'three/addons/controls/ArcballControls.js';
+
+const controls = new ArcballControls(camera, renderer.domElement, scene);
+
+controls.enablePan = true;
+controls.enableZoom = true;
+controls.enableRotate = true;
+controls.cursorZoom = true;
+
+function animate() {
+  controls.update();
+  renderer.render(scene, camera);
+  requestAnimationFrame(animate);
+}
+```
+
+## Controls Comparison
+
+**OrbitControls**: Product viewers, 3D models, general use
+**MapControls**: Top-down maps, strategy games
+**FirstPersonControls**: Architectural walkthroughs
+**FlyControls**: Space navigation, creative tools
+**PointerLockControls**: FPS games
+**TrackballControls**: CAD applications
+**ArcballControls**: Scientific visualization
+
+## Common Patterns
+
+```javascript
+// Disable controls during UI interaction
+transformControls.addEventListener('dragging-changed', (event) => {
+  orbitControls.enabled = !event.value;
+});
+
+// Reset camera position
+function resetCamera() {
+  controls.reset();
+}
+
+// Animate camera to position
+function moveCameraTo(position, target) {
+  gsap.to(camera.position, {
+    duration: 1,
+    x: position.x,
+    y: position.y,
+    z: position.z,
+    onUpdate: () => controls.update()
+  });
+  gsap.to(controls.target, {
+    duration: 1,
+    x: target.x,
+    y: target.y,
+    z: target.z
+  });
+}
+```

package/.cursor/skills/threejs/references/11-materials-advanced.md

@@ -0,0 +1,270 @@
+# Advanced Materials
+
+PBR materials and custom shaders.
+
+## MeshStandardMaterial (PBR)
+
+Physically-based rendering with metallic/roughness workflow:
+
+```javascript
+const material = new THREE.MeshStandardMaterial({
+  color: 0xffffff,
+  metalness: 0.5,     // 0 = dielectric, 1 = metal
+  roughness: 0.5,     // 0 = smooth/shiny, 1 = rough/matte
+
+  map: colorTexture,          // base color
+  normalMap: normalTexture,   // surface detail
+  roughnessMap: roughnessTexture,
+  metalnessMap: metalnessTexture,
+  aoMap: aoTexture,           // ambient occlusion
+  emissive: 0xff0000,         // glow color
+  emissiveMap: emissiveTexture,
+  emissiveIntensity: 1.0,
+
+  envMap: environmentMap,     // reflections
+  envMapIntensity: 1.0,
+
+  alphaMap: alphaTexture,     // transparency control
+  transparent: true,
+  opacity: 1.0,
+
+  side: THREE.DoubleSide,     // render both sides
+  flatShading: false          // smooth normals
+});
+```
+
+## MeshPhysicalMaterial (Enhanced PBR)
+
+Extended PBR with clearcoat, transmission, sheen:
+
+```javascript
+const material = new THREE.MeshPhysicalMaterial({
+  // All MeshStandardMaterial properties plus:
+
+  // Clearcoat (protective layer)
+  clearcoat: 1.0,
+  clearcoatRoughness: 0.1,
+  clearcoatMap: clearcoatTexture,
+  clearcoatRoughnessMap: clearcoatRoughTexture,
+  clearcoatNormalMap: clearcoatNormalTexture,
+
+  // Transmission (transparency with refraction)
+  transmission: 1.0,          // 0-1, glass-like
+  thickness: 0.5,             // volumetric thickness
+  ior: 1.5,                   // index of refraction (glass = 1.5)
+
+  // Sheen (fabric-like edge glow)
+  sheen: 1.0,
+  sheenRoughness: 0.5,
+  sheenColor: new THREE.Color(0xffffff),
+
+  // Iridescence (rainbow effect)
+  iridescence: 1.0,
+  iridescenceIOR: 1.3,
+  iridescenceThicknessRange: [100, 400],
+
+  // Anisotropy (directional reflections)
+  anisotropy: 1.0,
+  anisotropyRotation: 0
+});
+```
+
+## ShaderMaterial (Custom Shaders)
+
+Full control over vertex and fragment shaders:
+
+```javascript
+const material = new THREE.ShaderMaterial({
+  uniforms: {
+    time: { value: 0.0 },
+    color: { value: new THREE.Color(0xff0000) },
+    texture1: { value: texture }
+  },
+
+  vertexShader: `
+    varying vec2 vUv;
+    varying vec3 vNormal;
+
+    void main() {
+      vUv = uv;
+      vNormal = normalize(normalMatrix * normal);
+      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+    }
+  `,
+
+  fragmentShader: `
+    uniform float time;
+    uniform vec3 color;
+    uniform sampler2D texture1;
+
+    varying vec2 vUv;
+    varying vec3 vNormal;
+
+    void main() {
+      vec4 texColor = texture2D(texture1, vUv);
+      vec3 light = vec3(0.5, 0.2, 1.0);
+      float dProd = max(0.0, dot(vNormal, light));
+
+      gl_FragColor = vec4(color * dProd * texColor.rgb, 1.0);
+    }
+  `,
+
+  transparent: true,
+  side: THREE.DoubleSide
+});
+
+// Update uniform in animation loop
+material.uniforms.time.value += 0.01;
+```
+
+## RawShaderMaterial
+
+Like ShaderMaterial but without Three.js shader injection:
+
+```javascript
+const material = new THREE.RawShaderMaterial({
+  uniforms: {
+    // ...
+  },
+  vertexShader: `
+    precision mediump float;
+    precision mediump int;
+
+    uniform mat4 modelViewMatrix;
+    uniform mat4 projectionMatrix;
+
+    attribute vec3 position;
+    attribute vec2 uv;
+
+    varying vec2 vUv;
+
+    void main() {
+      vUv = uv;
+      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+    }
+  `,
+  fragmentShader: `
+    precision mediump float;
+
+    varying vec2 vUv;
+
+    void main() {
+      gl_FragColor = vec4(vUv, 0.0, 1.0);
+    }
+  `
+});
+```
+
+## Common Shader Patterns
+
+### Fresnel Effect
+```glsl
+// In fragment shader
+float fresnel = pow(1.0 - dot(vNormal, vViewDirection), 3.0);
+gl_FragColor = vec4(mix(baseColor, edgeColor, fresnel), 1.0);
+```
+
+### Noise/Distortion
+```glsl
+// Simple noise function
+float noise(vec2 p) {
+  return fract(sin(dot(p, vec2(12.9898, 78.233))) * 43758.5453);
+}
+
+// UV distortion
+vec2 distortedUV = vUv + vec2(
+  noise(vUv + time) * 0.1,
+  noise(vUv.yx + time) * 0.1
+);
+```
+
+### Scrolling Texture
+```glsl
+uniform float time;
+varying vec2 vUv;
+
+vec2 scrollUV = vUv + vec2(time * 0.1, 0.0);
+vec4 color = texture2D(map, scrollUV);
+```
+
+## Material Blending
+
+```javascript
+material.blending = THREE.AdditiveBlending;
+// Options:
+// THREE.NoBlending
+// THREE.NormalBlending (default)
+// THREE.AdditiveBlending (glow/light effects)
+// THREE.SubtractiveBlending
+// THREE.MultiplyBlending
+
+// Custom blending
+material.blending = THREE.CustomBlending;
+material.blendEquation = THREE.AddEquation;
+material.blendSrc = THREE.SrcAlphaFactor;
+material.blendDst = THREE.OneMinusSrcAlphaFactor;
+```
+
+## Depth & Stencil
+
+```javascript
+// Depth testing
+material.depthTest = true;
+material.depthWrite = true;
+material.depthFunc = THREE.LessEqualDepth;
+
+// Alpha testing (discard transparent pixels)
+material.alphaTest = 0.5;
+
+// Render order
+mesh.renderOrder = 1; // higher renders later
+
+// Polygonoffset (prevent z-fighting)
+material.polygonOffset = true;
+material.polygonOffsetFactor = 1;
+material.polygonOffsetUnits = 1;
+```
+
+## Material Cloning & Disposal
+
+```javascript
+// Clone material
+const material2 = material.clone();
+
+// Dispose when done (free GPU memory)
+material.dispose();
+texture.dispose();
+geometry.dispose();
+```
+
+## Common Built-in Uniforms
+
+Available in ShaderMaterial (automatic):
+
+```glsl
+// Matrices
+uniform mat4 modelMatrix;
+uniform mat4 modelViewMatrix;
+uniform mat4 projectionMatrix;
+uniform mat4 viewMatrix;
+uniform mat3 normalMatrix;
+
+// Camera
+uniform vec3 cameraPosition;
+
+// Attributes (vertex shader)
+attribute vec3 position;
+attribute vec3 normal;
+attribute vec2 uv;
+attribute vec2 uv2;
+```
+
+## Performance Tips
+
+- Use MeshStandardMaterial for most cases (good balance)
+- MeshPhysicalMaterial is expensive (use sparingly)
+- ShaderMaterial requires GPU knowledge
+- Avoid transparent materials when possible
+- Use alphaTest instead of transparency for cutouts
+- Minimize uniform updates
+- Share materials between meshes