anchi-toolkit 1.0.0

package/.cursor/skills/threejs/references/09-postprocessing.md

@@ -0,0 +1,240 @@
+# Post-Processing
+
+Apply visual effects after rendering.
+
+## EffectComposer Setup
+
+Post-processing pipeline (addon):
+
+```javascript
+import { EffectComposer } from 'three/addons/postprocessing/EffectComposer.js';
+import { RenderPass } from 'three/addons/postprocessing/RenderPass.js';
+import { OutputPass } from 'three/addons/postprocessing/OutputPass.js';
+
+// Create composer
+const composer = new EffectComposer(renderer);
+
+// Add render pass (required first pass)
+const renderPass = new RenderPass(scene, camera);
+composer.addPass(renderPass);
+
+// Add effect passes
+// ... (see below)
+
+// Add output pass (required last pass)
+const outputPass = new OutputPass();
+composer.addPass(outputPass);
+
+// Render with composer instead of renderer
+function animate() {
+  requestAnimationFrame(animate);
+  composer.render();
+}
+
+// Handle resize
+window.addEventListener('resize', () => {
+  composer.setSize(window.innerWidth, window.innerHeight);
+});
+```
+
+## Bloom Effect
+
+Glow effect for bright areas:
+
+```javascript
+import { UnrealBloomPass } from 'three/addons/postprocessing/UnrealBloomPass.js';
+
+const bloomPass = new UnrealBloomPass(
+  new THREE.Vector2(window.innerWidth, window.innerHeight),
+  1.5,  // strength
+  0.4,  // radius
+  0.85  // threshold (brightness trigger)
+);
+composer.addPass(bloomPass);
+
+// Adjust parameters
+bloomPass.strength = 2.0;
+bloomPass.radius = 1.0;
+bloomPass.threshold = 0.5;
+```
+
+## SSAO (Screen Space Ambient Occlusion)
+
+Realistic shadowing in crevices:
+
+```javascript
+import { SSAOPass } from 'three/addons/postprocessing/SSAOPass.js';
+
+const ssaoPass = new SSAOPass(scene, camera, width, height);
+ssaoPass.kernelRadius = 16;
+ssaoPass.minDistance = 0.005;
+ssaoPass.maxDistance = 0.1;
+composer.addPass(ssaoPass);
+```
+
+## SSR (Screen Space Reflections)
+
+Real-time reflections:
+
+```javascript
+import { SSRPass } from 'three/addons/postprocessing/SSRPass.js';
+
+const ssrPass = new SSRPass({
+  renderer,
+  scene,
+  camera,
+  width: window.innerWidth,
+  height: window.innerHeight
+});
+
+ssrPass.opacity = 0.5;
+ssrPass.maxDistance = 0.1;
+composer.addPass(ssrPass);
+```
+
+## Depth of Field (Bokeh)
+
+Blur based on depth:
+
+```javascript
+import { BokehPass } from 'three/addons/postprocessing/BokehPass.js';
+
+const bokehPass = new BokehPass(scene, camera, {
+  focus: 10.0,      // focal distance
+  aperture: 0.025,  // blur amount
+  maxblur: 0.01     // max blur size
+});
+composer.addPass(bokehPass);
+```
+
+## FXAA (Anti-Aliasing)
+
+Smooth jagged edges:
+
+```javascript
+import { ShaderPass } from 'three/addons/postprocessing/ShaderPass.js';
+import { FXAAShader } from 'three/addons/shaders/FXAAShader.js';
+
+const fxaaPass = new ShaderPass(FXAAShader);
+fxaaPass.material.uniforms['resolution'].value.x = 1 / window.innerWidth;
+fxaaPass.material.uniforms['resolution'].value.y = 1 / window.innerHeight;
+composer.addPass(fxaaPass);
+```
+
+## Outline Pass
+
+Highlight selected objects:
+
+```javascript
+import { OutlinePass } from 'three/addons/postprocessing/OutlinePass.js';
+
+const outlinePass = new OutlinePass(
+  new THREE.Vector2(window.innerWidth, window.innerHeight),
+  scene,
+  camera
+);
+
+outlinePass.edgeStrength = 3;
+outlinePass.edgeGlow = 0.5;
+outlinePass.edgeThickness = 1;
+outlinePass.visibleEdgeColor.set('#ffffff');
+outlinePass.hiddenEdgeColor.set('#190a05');
+
+// Set objects to outline
+outlinePass.selectedObjects = [mesh1, mesh2];
+
+composer.addPass(outlinePass);
+```
+
+## Film/Grain Effect
+
+Add film grain and scanlines:
+
+```javascript
+import { FilmPass } from 'three/addons/postprocessing/FilmPass.js';
+
+const filmPass = new FilmPass(
+  0.35,  // noise intensity
+  0.5,   // scanline intensity
+  648,   // scanline count
+  false  // grayscale
+);
+composer.addPass(filmPass);
+```
+
+## Glitch Effect
+
+Digital glitch distortion:
+
+```javascript
+import { GlitchPass } from 'three/addons/postprocessing/GlitchPass.js';
+
+const glitchPass = new GlitchPass();
+composer.addPass(glitchPass);
+```
+
+## Custom Shader Pass
+
+Create custom effects:
+
+```javascript
+import { ShaderPass } from 'three/addons/postprocessing/ShaderPass.js';
+
+const customShader = {
+  uniforms: {
+    tDiffuse: { value: null },
+    amount: { value: 1.0 }
+  },
+  vertexShader: `
+    varying vec2 vUv;
+    void main() {
+      vUv = uv;
+      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+    }
+  `,
+  fragmentShader: `
+    uniform sampler2D tDiffuse;
+    uniform float amount;
+    varying vec2 vUv;
+
+    void main() {
+      vec4 color = texture2D(tDiffuse, vUv);
+      // Apply custom effect
+      color.r *= amount;
+      gl_FragColor = color;
+    }
+  `
+};
+
+const customPass = new ShaderPass(customShader);
+customPass.material.uniforms.amount.value = 1.5;
+composer.addPass(customPass);
+```
+
+## Common Pass Patterns
+
+```javascript
+// Combine multiple effects
+composer.addPass(renderPass);
+composer.addPass(ssaoPass);
+composer.addPass(bloomPass);
+composer.addPass(fxaaPass);
+composer.addPass(outputPass);
+
+// Selective rendering
+bloomPass.renderToScreen = false; // render to texture, not screen
+
+// Clear pass
+import { ClearPass } from 'three/addons/postprocessing/ClearPass.js';
+const clearPass = new ClearPass();
+composer.addPass(clearPass);
+```
+
+## Performance Tips
+
+- Post-processing is GPU-intensive
+- Use lower resolution for expensive effects (SSAO, SSR)
+- Limit number of passes (3-5 for good performance)
+- Disable passes when not needed
+- Use FXAA instead of MSAA (cheaper)
+- Test on target devices

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
+  });
+}
+```