anchi-kit 1.2.3 → 1.2.6

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

package/.cursor/skills/threejs/references/15-specialized-loaders.md

@@ -0,0 +1,333 @@
+# Specialized Loaders
+
+Domain-specific file format loaders.
+
+## SVG Loader
+
+Load and extrude SVG paths:
+
+```javascript
+import { SVGLoader } from 'three/addons/loaders/SVGLoader.js';
+
+const loader = new SVGLoader();
+loader.load('image.svg', (data) => {
+  const paths = data.paths;
+  const group = new THREE.Group();
+
+  paths.forEach((path) => {
+    const material = new THREE.MeshBasicMaterial({
+      color: path.color,
+      side: THREE.DoubleSide,
+      depthWrite: false
+    });
+
+    const shapes = SVGLoader.createShapes(path);
+    shapes.forEach((shape) => {
+      const geometry = new THREE.ShapeGeometry(shape);
+      const mesh = new THREE.Mesh(geometry, material);
+      group.add(mesh);
+    });
+  });
+
+  // Extrude SVG
+  paths.forEach((path) => {
+    const shapes = SVGLoader.createShapes(path);
+    const geometry = new THREE.ExtrudeGeometry(shapes, {
+      depth: 10,
+      bevelEnabled: false
+    });
+    const mesh = new THREE.Mesh(geometry, material);
+    group.add(mesh);
+  });
+
+  scene.add(group);
+});
+```
+
+## Collada (.dae) Loader
+
+XML-based format from Blender, SketchUp:
+
+```javascript
+import { ColladaLoader } from 'three/addons/loaders/ColladaLoader.js';
+
+const loader = new ColladaLoader();
+loader.load('model.dae', (collada) => {
+  const model = collada.scene;
+  scene.add(model);
+
+  // Access animations
+  const animations = collada.animations;
+  const mixer = new THREE.AnimationMixer(model);
+  animations.forEach(clip => mixer.clipAction(clip).play());
+});
+```
+
+## STL Loader
+
+3D printing format:
+
+```javascript
+import { STLLoader } from 'three/addons/loaders/STLLoader.js';
+
+const loader = new STLLoader();
+loader.load('model.stl', (geometry) => {
+  const material = new THREE.MeshPhongMaterial({ color: 0xff5533 });
+  const mesh = new THREE.Mesh(geometry, material);
+  scene.add(mesh);
+
+  // STL doesn't include normals, compute them
+  geometry.computeVertexNormals();
+});
+```
+
+## 3MF Loader
+
+Modern 3D printing format:
+
+```javascript
+import { 3MFLoader } from 'three/addons/loaders/3MFLoader.js';
+
+const loader = new 3MFLoader();
+loader.load('model.3mf', (object) => {
+  scene.add(object);
+});
+```
+
+## VRML/X3D Loader
+
+Virtual Reality Modeling Language:
+
+```javascript
+import { VRMLLoader } from 'three/addons/loaders/VRMLLoader.js';
+
+const loader = new VRMLLoader();
+loader.load('model.wrl', (object) => {
+  scene.add(object);
+});
+```
+
+## PDB Loader
+
+Protein Data Bank (chemistry/molecular):
+
+```javascript
+import { PDBLoader } from 'three/addons/loaders/PDBLoader.js';
+
+const loader = new PDBLoader();
+loader.load('molecule.pdb', (pdb) => {
+  const geometryAtoms = pdb.geometryAtoms;
+  const geometryBonds = pdb.geometryBonds;
+  const json = pdb.json;
+
+  // Render atoms as spheres
+  const material = new THREE.MeshPhongMaterial({ color: 0xffffff });
+  const atoms = new THREE.Mesh(geometryAtoms, material);
+  scene.add(atoms);
+
+  // Render bonds as cylinders
+  const bondMaterial = new THREE.MeshPhongMaterial({ color: 0xcccccc });
+  const bonds = new THREE.Mesh(geometryBonds, bondMaterial);
+  scene.add(bonds);
+});
+```
+
+## LDraw Loader
+
+LEGO models:
+
+```javascript
+import { LDrawLoader } from 'three/addons/loaders/LDrawLoader.js';
+
+const loader = new LDrawLoader();
+loader.setPath('ldraw/');
+
+loader.load('model.mpd', (group) => {
+  scene.add(group);
+
+  // Smooth LEGO bricks
+  group.traverse((child) => {
+    if (child.isMesh) {
+      child.material.flatShading = false;
+    }
+  });
+});
+```
+
+## VTK Loader
+
+Visualization Toolkit (scientific data):
+
+```javascript
+import { VTKLoader } from 'three/addons/loaders/VTKLoader.js';
+
+const loader = new VTKLoader();
+loader.load('model.vtk', (geometry) => {
+  geometry.computeVertexNormals();
+  const material = new THREE.MeshStandardMaterial();
+  const mesh = new THREE.Mesh(geometry, material);
+  scene.add(mesh);
+});
+```
+
+## PLY Loader
+
+Polygon file format (scanned 3D data):
+
+```javascript
+import { PLYLoader } from 'three/addons/loaders/PLYLoader.js';
+
+const loader = new PLYLoader();
+loader.load('model.ply', (geometry) => {
+  geometry.computeVertexNormals();
+
+  // Check if has vertex colors
+  const material = geometry.attributes.color ?
+    new THREE.MeshStandardMaterial({ vertexColors: true }) :
+    new THREE.MeshStandardMaterial({ color: 0x888888 });
+
+  const mesh = new THREE.Mesh(geometry, material);
+  scene.add(mesh);
+});
+```
+
+## 3DS Loader
+
+3DS Max format:
+
+```javascript
+import { TDSLoader } from 'three/addons/loaders/TDSLoader.js';
+
+const loader = new TDSLoader();
+loader.load('model.3ds', (object) => {
+  scene.add(object);
+});
+```
+
+## USDZ Loader/Exporter
+
+Apple's AR format:
+
+```javascript
+// Export to USDZ (for iOS AR)
+import { USDZExporter } from 'three/addons/exporters/USDZExporter.js';
+
+const exporter = new USDZExporter();
+const arraybuffer = await exporter.parse(scene);
+const blob = new Blob([arraybuffer], { type: 'application/octet-stream' });
+
+// Download or serve for AR Quick Look
+const link = document.createElement('a');
+link.href = URL.createObjectURL(blob);
+link.download = 'model.usdz';
+link.click();
+```
+
+## Font Loader (Text)
+
+Load fonts for 3D text:
+
+```javascript
+import { FontLoader } from 'three/addons/loaders/FontLoader.js';
+import { TextGeometry } from 'three/addons/geometries/TextGeometry.js';
+
+const fontLoader = new FontLoader();
+fontLoader.load('fonts/helvetiker_regular.typeface.json', (font) => {
+  const geometry = new TextGeometry('Hello World', {
+    font: font,
+    size: 80,
+    height: 5,
+    curveSegments: 12,
+    bevelEnabled: true,
+    bevelThickness: 10,
+    bevelSize: 8,
+    bevelSegments: 5
+  });
+
+  const material = new THREE.MeshPhongMaterial({ color: 0x00ff00 });
+  const mesh = new THREE.Mesh(geometry, material);
+  scene.add(mesh);
+});
+```
+
+## EXR Loader
+
+High dynamic range images:
+
+```javascript
+import { EXRLoader } from 'three/addons/loaders/EXRLoader.js';
+
+const loader = new EXRLoader();
+loader.load('env.exr', (texture) => {
+  texture.mapping = THREE.EquirectangularReflectionMapping;
+
+  scene.background = texture;
+  scene.environment = texture;
+});
+```
+
+## RGBE/HDR Loader
+
+HDR environment maps:
+
+```javascript
+import { RGBELoader } from 'three/addons/loaders/RGBELoader.js';
+
+const loader = new RGBELoader();
+loader.load('env.hdr', (texture) => {
+  texture.mapping = THREE.EquirectangularReflectionMapping;
+
+  scene.background = texture;
+  scene.environment = texture;
+
+  // Use with PMREM generator for better quality
+  const pmremGenerator = new THREE.PMREMGenerator(renderer);
+  const envMap = pmremGenerator.fromEquirectangular(texture).texture;
+  scene.environment = envMap;
+  texture.dispose();
+  pmremGenerator.dispose();
+});
+```
+
+## Basis/KTX2 Texture Loader
+
+GPU-optimized texture compression:
+
+```javascript
+import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
+
+const loader = new KTX2Loader();
+loader.setTranscoderPath('basis/');
+loader.detectSupport(renderer);
+
+loader.load('texture.ktx2', (texture) => {
+  material.map = texture;
+  material.needsUpdate = true;
+});
+```
+
+## Common Patterns
+
+```javascript
+// Load with progress
+loader.load(
+  'file.ext',
+  (result) => { /* success */ },
+  (xhr) => {
+    const percent = (xhr.loaded / xhr.total * 100);
+    console.log(`${percent}% loaded`);
+  },
+  (error) => { /* error */ }
+);
+
+// Center imported model
+const box = new THREE.Box3().setFromObject(model);
+const center = box.getCenter(new THREE.Vector3());
+model.position.sub(center);
+
+// Scale to fit
+const size = box.getSize(new THREE.Vector3());
+const maxDim = Math.max(size.x, size.y, size.z);
+const scale = 10 / maxDim;
+model.scale.setScalar(scale);
+```