anchi-toolkit 1.0.0

package/.cursor/skills/threejs/references/13-node-materials.md

@@ -0,0 +1,298 @@
+# Node Materials (TSL - Three Shading Language)
+
+Modern node-based material system for creating custom shaders visually.
+
+## What is TSL?
+
+Three Shading Language (TSL) is a node-based system for creating materials and shaders:
+- Functional approach to shader composition
+- Type-safe node graph
+- Unified GLSL/WGSL output (WebGL & WebGPU)
+- No manual shader code required
+
+## Basic Node Material
+
+```javascript
+import * as THREE from 'three/webgpu';
+import { color, texture, normalMap, MeshStandardNodeMaterial } from 'three/nodes';
+
+const material = new MeshStandardNodeMaterial();
+
+// Set base color node
+material.colorNode = color(0xff0000);
+
+// Or use texture
+material.colorNode = texture(colorTexture);
+
+// Combine nodes
+material.colorNode = texture(colorTexture).mul(color(0xffffff));
+
+// Normal mapping
+material.normalNode = normalMap(normalTexture);
+```
+
+## Node Types
+
+### Input Nodes
+
+```javascript
+import {
+  attribute,
+  uniform,
+  texture,
+  cubeTexture,
+  instancedArray,
+  storage
+} from 'three/nodes';
+
+// Geometry attributes
+const positionNode = attribute('position');
+const normalNode = attribute('normal');
+const uvNode = attribute('uv');
+
+// Uniforms
+const timeNode = uniform(0); // value
+
+// Textures
+const colorNode = texture(diffuseTexture);
+const envNode = cubeTexture(cubeMapTexture);
+
+// Instanced data
+const instanceColorNode = instancedArray('instanceColor');
+
+// Storage buffers (compute)
+const storageNode = storage(buffer, 'vec4', count);
+```
+
+### Math Nodes
+
+```javascript
+import { add, sub, mul, div, pow, sin, cos, length, normalize } from 'three/nodes';
+
+// Basic operations
+const result = add(a, b);     // a + b
+const result = sub(a, b);     // a - b
+const result = mul(a, b);     // a * b
+const result = div(a, b);     // a / b
+
+// Trigonometry
+const result = sin(angle);
+const result = cos(angle);
+
+// Vector operations
+const result = length(vector);
+const result = normalize(vector);
+
+// Chaining
+const result = mul(texture(tex), color(0xff0000));
+```
+
+### Procedural Nodes
+
+```javascript
+import { checker, dots, noise, voronoi } from 'three/nodes';
+
+// Checker pattern
+material.colorNode = checker(uvNode.mul(10));
+
+// Noise
+material.colorNode = noise(uvNode.mul(5));
+
+// Voronoi cells
+material.colorNode = voronoi(uvNode.mul(3));
+```
+
+## Custom Shader Function
+
+```javascript
+import { Fn, vec3, float } from 'three/nodes';
+
+// Define custom function
+const customColor = Fn(([uv, time]) => {
+  const r = sin(uv.x.mul(10).add(time));
+  const g = cos(uv.y.mul(10).add(time));
+  const b = float(0.5);
+  return vec3(r, g, b);
+});
+
+// Use in material
+material.colorNode = customColor(uvNode, timeNode);
+```
+
+## Animation with Nodes
+
+```javascript
+import { uniform, oscSine, timerLocal } from 'three/nodes';
+
+// Oscillating value
+const oscillator = oscSine(timerLocal(0.5)); // frequency = 0.5
+
+// Pulsing color
+material.colorNode = color(0xff0000).mul(oscillator.add(0.5));
+
+// Rotating UV
+const rotatedUV = uvNode.rotateUV(timerLocal());
+material.colorNode = texture(tex, rotatedUV);
+```
+
+## Advanced Effects
+
+### Fresnel Effect
+
+```javascript
+import { normalView, positionView, dot, pow } from 'three/nodes';
+
+const fresnel = pow(
+  float(1).sub(dot(normalView, positionView.normalize())),
+  3
+);
+
+material.colorNode = mix(baseColor, edgeColor, fresnel);
+```
+
+### Vertex Displacement
+
+```javascript
+import { positionLocal, normalLocal, timerLocal, sin } from 'three/nodes';
+
+// Displace vertices along normal
+const displacement = sin(positionLocal.y.add(timerLocal())).mul(0.5);
+material.positionNode = positionLocal.add(normalLocal.mul(displacement));
+```
+
+### Custom Normal Mapping
+
+```javascript
+import { normalMap, normalView, TBNViewMatrix } from 'three/nodes';
+
+const normalMapNode = normalMap(normalTexture);
+const transformedNormal = TBNViewMatrix.mul(normalMapNode);
+material.normalNode = transformedNormal;
+```
+
+## Compute Shaders (WebGPU)
+
+```javascript
+import { compute, uniform, storage, Fn } from 'three/nodes';
+
+// Define compute shader
+const computeShader = Fn(() => {
+  const storageBuffer = storage(buffer, 'vec4', count);
+  const index = instanceIndex; // built-in
+
+  // Modify buffer
+  const value = storageBuffer.element(index);
+  storageBuffer.element(index).assign(value.mul(2));
+})();
+
+// Create compute node
+const computeNode = compute(computeShader, 256); // workgroup size
+
+// Execute
+renderer.compute(computeNode);
+```
+
+## Node Material Types
+
+```javascript
+import {
+  MeshStandardNodeMaterial,
+  MeshPhysicalNodeMaterial,
+  MeshBasicNodeMaterial,
+  PointsNodeMaterial,
+  LineBasicNodeMaterial,
+  SpriteNodeMaterial
+} from 'three/nodes';
+
+// Standard PBR
+const material = new MeshStandardNodeMaterial();
+material.colorNode = colorNode;
+material.roughnessNode = roughnessNode;
+material.metalnessNode = metalnessNode;
+
+// Physical (clearcoat, transmission, etc.)
+const material = new MeshPhysicalNodeMaterial();
+material.clearcoatNode = clearcoatNode;
+material.transmissionNode = transmissionNode;
+```
+
+## Post-Processing with Nodes
+
+```javascript
+import { pass, PassNode } from 'three/nodes';
+
+// Custom post-processing pass
+const customPass = new PassNode('customPass', (input, output) => {
+  // input: previous pass texture
+  // output: render target
+
+  // Apply effect
+  const modifiedColor = input.mul(color(1, 0.5, 0.5));
+  output.assign(modifiedColor);
+});
+
+// Add to post-processing chain
+postProcessing.addPass(customPass);
+```
+
+## Practical Example: Animated Material
+
+```javascript
+import * as THREE from 'three/webgpu';
+import {
+  MeshStandardNodeMaterial,
+  texture,
+  uniform,
+  timerLocal,
+  sin,
+  cos,
+  vec2
+} from 'three/nodes';
+
+const material = new MeshStandardNodeMaterial();
+
+// Animated UV scroll
+const time = timerLocal();
+const scrollSpeed = uniform(0.1);
+const uvOffset = vec2(
+  time.mul(scrollSpeed),
+  sin(time).mul(0.1)
+);
+const scrolledUV = uv().add(uvOffset);
+
+// Apply to color
+material.colorNode = texture(diffuseTexture, scrolledUV);
+
+// Animated emission
+const pulseSpeed = uniform(2);
+const emission = sin(time.mul(pulseSpeed)).mul(0.5).add(0.5);
+material.emissiveNode = color(1, 0.5, 0).mul(emission);
+```
+
+## Migration from ShaderMaterial
+
+```javascript
+// Old way (ShaderMaterial)
+const material = new THREE.ShaderMaterial({
+  uniforms: {
+    time: { value: 0 }
+  },
+  vertexShader: `...`,
+  fragmentShader: `...`
+});
+
+// New way (Node Material)
+const material = new MeshStandardNodeMaterial();
+material.colorNode = customFunction(timerLocal());
+// Much cleaner, type-safe, and reusable
+```
+
+## When to Use Node Materials
+
+- Creating complex procedural materials
+- Need both WebGL and WebGPU support
+- Want visual/functional shader composition
+- Reusable shader components
+- Compute shader integration (WebGPU only)
+
+**Note**: Node materials require WebGPU renderer for full features. Some features work with WebGL backend but compute shaders require WebGPU.

package/.cursor/skills/threejs/references/14-physics-vr.md

@@ -0,0 +1,304 @@
+# Physics & VR/XR
+
+Integrate physics simulations and virtual reality.
+
+## Physics Integration
+
+Three.js doesn't include physics - use external libraries:
+
+### Rapier Physics (Recommended)
+
+Rust-based, high-performance:
+
+```javascript
+import { RapierPhysics } from 'three/addons/physics/RapierPhysics.js';
+
+// Initialize
+const physics = await RapierPhysics();
+
+// Create physics body
+const box = new THREE.Mesh(
+  new THREE.BoxGeometry(),
+  new THREE.MeshStandardMaterial()
+);
+scene.add(box);
+
+// Add physics (mass > 0 = dynamic)
+physics.addMesh(box, 1); // mass = 1
+
+// Static ground
+const ground = new THREE.Mesh(
+  new THREE.BoxGeometry(10, 0.5, 10),
+  new THREE.MeshStandardMaterial()
+);
+ground.position.y = -2;
+scene.add(ground);
+physics.addMesh(ground); // no mass = static
+
+// Update in animation loop
+function animate() {
+  physics.step();
+  renderer.render(scene, camera);
+  requestAnimationFrame(animate);
+}
+```
+
+### Ammo Physics
+
+Port of Bullet physics engine:
+
+```javascript
+import { AmmoPhysics } from 'three/addons/physics/AmmoPhysics.js';
+
+const physics = await AmmoPhysics();
+
+// Same API as Rapier
+physics.addMesh(mesh, mass);
+
+function animate() {
+  physics.step();
+  renderer.render(scene, camera);
+  requestAnimationFrame(animate);
+}
+```
+
+### Jolt Physics
+
+High-performance alternative:
+
+```javascript
+import { JoltPhysics } from 'three/addons/physics/JoltPhysics.js';
+
+const physics = await JoltPhysics();
+physics.addMesh(mesh, mass);
+```
+
+### Physics Constraints
+
+```javascript
+// After initialization
+const physics = await RapierPhysics();
+
+// Point-to-point constraint
+physics.addConstraint(meshA, meshB, 'fixed');
+physics.addConstraint(meshA, meshB, 'spring', { stiffness: 100 });
+
+// Remove constraint
+physics.removeConstraint(constraint);
+```
+
+## VR/XR Setup
+
+### Basic WebXR
+
+```javascript
+import { VRButton } from 'three/addons/webxr/VRButton.js';
+
+// Enable XR
+renderer.xr.enabled = true;
+
+// Add VR button to page
+document.body.appendChild(VRButton.createButton(renderer));
+
+// Animation loop for VR
+renderer.setAnimationLoop(() => {
+  renderer.render(scene, camera);
+});
+
+// Stop using requestAnimationFrame, use setAnimationLoop instead
+```
+
+### AR Mode
+
+```javascript
+import { ARButton } from 'three/addons/webxr/ARButton.js';
+
+renderer.xr.enabled = true;
+document.body.appendChild(ARButton.createButton(renderer));
+
+// AR-specific features
+const session = renderer.xr.getSession();
+session.requestHitTestSource({ space: viewerSpace }).then((hitTestSource) => {
+  // Use hit testing for placing objects
+});
+```
+
+### VR Controllers
+
+```javascript
+// Get controllers
+const controller1 = renderer.xr.getController(0);
+const controller2 = renderer.xr.getController(1);
+
+scene.add(controller1);
+scene.add(controller2);
+
+// Controller events
+controller1.addEventListener('selectstart', () => {
+  console.log('Trigger pressed');
+});
+
+controller1.addEventListener('selectend', () => {
+  console.log('Trigger released');
+});
+
+// Add visual controller models
+import { XRControllerModelFactory } from 'three/addons/webxr/XRControllerModelFactory.js';
+
+const controllerModelFactory = new XRControllerModelFactory();
+
+const grip1 = renderer.xr.getControllerGrip(0);
+grip1.add(controllerModelFactory.createControllerModel(grip1));
+scene.add(grip1);
+
+const grip2 = renderer.xr.getControllerGrip(1);
+grip2.add(controllerModelFactory.createControllerModel(grip2));
+scene.add(grip2);
+```
+
+### Hand Tracking
+
+```javascript
+import { OculusHandModel } from 'three/addons/webxr/OculusHandModel.js';
+
+const hand1 = renderer.xr.getHand(0);
+const handModel1 = new OculusHandModel(hand1);
+hand1.add(handModel1);
+scene.add(hand1);
+
+const hand2 = renderer.xr.getHand(1);
+const handModel2 = new OculusHandModel(hand2);
+hand2.add(handModel2);
+scene.add(hand2);
+```
+
+### Teleportation
+
+```javascript
+const raycaster = new THREE.Raycaster();
+const tempMatrix = new THREE.Matrix4();
+
+function handleController(controller) {
+  const intersections = getIntersections(controller);
+
+  if (intersections.length > 0) {
+    const intersection = intersections[0];
+
+    // Teleport on button release
+    controller.addEventListener('selectend', () => {
+      const offset = intersection.point.y;
+      camera.position.y += offset;
+    });
+  }
+}
+
+function getIntersections(controller) {
+  tempMatrix.identity().extractRotation(controller.matrixWorld);
+  raycaster.ray.origin.setFromMatrixPosition(controller.matrixWorld);
+  raycaster.ray.direction.set(0, 0, -1).applyMatrix4(tempMatrix);
+  return raycaster.intersectObjects(scene.children, true);
+}
+```
+
+### Spatial Audio for VR
+
+```javascript
+const listener = new THREE.AudioListener();
+camera.add(listener);
+
+const sound = new THREE.PositionalAudio(listener);
+const audioLoader = new THREE.AudioLoader();
+
+audioLoader.load('sound.ogg', (buffer) => {
+  sound.setBuffer(buffer);
+  sound.setRefDistance(1);
+  sound.setLoop(true);
+  sound.play();
+});
+
+// Attach to object
+object.add(sound);
+
+// Update listener in VR
+renderer.setAnimationLoop(() => {
+  // Listener automatically updates with camera in VR
+  renderer.render(scene, camera);
+});
+```
+
+### Room-Scale VR
+
+```javascript
+// Request room-scale experience
+navigator.xr.requestSession('immersive-vr', {
+  requiredFeatures: ['local-floor']
+}).then((session) => {
+  // Session setup
+});
+
+// Get play area bounds
+session.requestReferenceSpace('bounded-floor').then((space) => {
+  const bounds = space.boundsGeometry;
+  // Create visual boundary
+});
+```
+
+### Performance Tips for VR
+
+- Target 90 FPS (11.1ms per frame)
+- Use lower polygon counts
+- Reduce shadow quality
+- Limit post-processing
+- Use instancing for repeated objects
+- Enable foveated rendering if available
+- Test on actual VR hardware
+
+```javascript
+// Foveated rendering (Quest 2+)
+const gl = renderer.getContext();
+const ext = gl.getExtension('WEBGL_foveated_rendering');
+if (ext) {
+  ext.foveatedRenderingModeWEBGL(gl.FOVEATED_RENDERING_MODE_ENABLE_WEBGL);
+}
+```
+
+## Mixed Reality (MR)
+
+```javascript
+import { XRButton } from 'three/addons/webxr/XRButton.js';
+
+// Request MR features
+document.body.appendChild(
+  XRButton.createButton(renderer, {
+    requiredFeatures: ['hand-tracking', 'layers'],
+    optionalFeatures: ['local-floor', 'bounded-floor']
+  })
+);
+
+// Passthrough mode (Quest Pro, etc.)
+const session = renderer.xr.getSession();
+const baseLayer = session.renderState.baseLayer;
+baseLayer.compositionDisabled = true; // enable passthrough
+```
+
+## Common VR Patterns
+
+```javascript
+// Detect if in VR
+if (renderer.xr.isPresenting) {
+  // In VR mode
+}
+
+// Get VR camera (for raycasting)
+const vrCamera = renderer.xr.getCamera(camera);
+
+// Different behavior for VR vs desktop
+renderer.setAnimationLoop(() => {
+  if (renderer.xr.isPresenting) {
+    // VR rendering logic
+  } else {
+    // Desktop rendering logic
+  }
+  renderer.render(scene, camera);
+});
+```