anchi-kit 1.2.3 → 1.2.6

package/.antigravity/skills/threejs/references/02-loaders.md

@@ -0,0 +1,169 @@
+# Asset Loading
+
+Load 3D models, textures, and other assets.
+
+## Loading Manager
+
+Coordinate multiple loads, track progress:
+
+```javascript
+const manager = new THREE.LoadingManager();
+manager.onStart = (url, loaded, total) => console.log('Loading:', url);
+manager.onProgress = (url, loaded, total) => console.log(`${loaded}/${total}`);
+manager.onLoad = () => console.log('Complete');
+manager.onError = (url) => console.error('Error:', url);
+
+const loader = new THREE.TextureLoader(manager);
+```
+
+## GLTF Loader (Recommended Format)
+
+Industry standard, supports PBR materials, animations, bones:
+
+```javascript
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+
+const loader = new GLTFLoader();
+loader.load(
+  'model.gltf',
+  (gltf) => {
+    scene.add(gltf.scene);
+
+    // Access animations
+    const mixer = new THREE.AnimationMixer(gltf.scene);
+    gltf.animations.forEach((clip) => mixer.clipAction(clip).play());
+  },
+  (xhr) => console.log((xhr.loaded / xhr.total * 100) + '% loaded'),
+  (error) => console.error(error)
+);
+```
+
+## FBX Loader
+
+Autodesk format, common in game dev:
+
+```javascript
+import { FBXLoader } from 'three/addons/loaders/FBXLoader.js';
+
+const loader = new FBXLoader();
+loader.load('model.fbx', (object) => {
+  scene.add(object);
+});
+```
+
+## OBJ Loader
+
+Simple geometry format:
+
+```javascript
+import { OBJLoader } from 'three/addons/loaders/OBJLoader.js';
+
+const loader = new OBJLoader();
+loader.load('model.obj', (object) => {
+  scene.add(object);
+});
+
+// With MTL (material library)
+import { MTLLoader } from 'three/addons/loaders/MTLLoader.js';
+
+const mtlLoader = new MTLLoader();
+mtlLoader.load('model.mtl', (materials) => {
+  materials.preload();
+  const objLoader = new OBJLoader();
+  objLoader.setMaterials(materials);
+  objLoader.load('model.obj', (object) => scene.add(object));
+});
+```
+
+## Texture Loader
+
+Load images as textures:
+
+```javascript
+const textureLoader = new THREE.TextureLoader();
+const texture = textureLoader.load('texture.jpg');
+
+// Use in material
+const material = new THREE.MeshStandardMaterial({ map: texture });
+
+// Load with callback
+textureLoader.load(
+  'texture.jpg',
+  (texture) => {
+    material.map = texture;
+    material.needsUpdate = true;
+  },
+  (xhr) => console.log((xhr.loaded / xhr.total * 100) + '% loaded'),
+  (error) => console.error(error)
+);
+```
+
+## Cube Texture Loader
+
+Load environment maps (skybox):
+
+```javascript
+const cubeLoader = new THREE.CubeTextureLoader();
+const envMap = cubeLoader.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.background = envMap;
+material.envMap = envMap;
+```
+
+## DRACO Compressed Models
+
+Smaller file sizes for GLTF:
+
+```javascript
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
+
+const dracoLoader = new DRACOLoader();
+dracoLoader.setDecoderPath('path/to/draco/');
+
+const loader = new GLTFLoader();
+loader.setDRACOLoader(dracoLoader);
+loader.load('compressed.gltf', (gltf) => scene.add(gltf.scene));
+```
+
+## KTX2 Compressed Textures
+
+GPU-optimized texture compression:
+
+```javascript
+import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
+
+const ktx2Loader = new KTX2Loader();
+ktx2Loader.setTranscoderPath('path/to/basis/');
+ktx2Loader.detectSupport(renderer);
+ktx2Loader.load('texture.ktx2', (texture) => {
+  material.map = texture;
+  material.needsUpdate = true;
+});
+```
+
+## Common Other Loaders
+
+```javascript
+// STL (3D printing)
+import { STLLoader } from 'three/addons/loaders/STLLoader.js';
+
+// Collada (.dae)
+import { ColladaLoader } from 'three/addons/loaders/ColladaLoader.js';
+
+// 3DS Max
+import { TDSLoader } from 'three/addons/loaders/TDSLoader.js';
+```
+
+## Best Practices
+
+- Use GLTF/GLB for web (best compression, features)
+- Compress with DRACO for large models
+- Use KTX2 for textures (GPU-friendly)
+- Enable caching: `THREE.Cache.enabled = true;`
+- Show loading progress to users
+- Handle errors gracefully

package/.antigravity/skills/threejs/references/03-textures.md

@@ -0,0 +1,170 @@
+# Textures
+
+Map images and data onto 3D surfaces.
+
+## Texture Types
+
+### Standard 2D Texture
+```javascript
+const texture = new THREE.Texture(image);
+texture.needsUpdate = true; // required after manual creation
+
+// Or use loader (auto-updates)
+const texture = new THREE.TextureLoader().load('image.jpg');
+```
+
+### Canvas Texture
+```javascript
+const canvas = document.createElement('canvas');
+const ctx = canvas.getContext('2d');
+// Draw on canvas...
+const texture = new THREE.CanvasTexture(canvas);
+```
+
+### Video Texture
+```javascript
+const video = document.createElement('video');
+video.src = 'video.mp4';
+video.play();
+const texture = new THREE.VideoTexture(video);
+```
+
+### Data Texture
+```javascript
+const size = 512;
+const data = new Uint8Array(size * size * 4);
+// Fill data with RGBA values...
+const texture = new THREE.DataTexture(data, size, size);
+texture.needsUpdate = true;
+```
+
+### Cube Texture (Environment/Skybox)
+```javascript
+const loader = new THREE.CubeTextureLoader();
+const texture = loader.load(['px.jpg', 'nx.jpg', 'py.jpg', 'ny.jpg', 'pz.jpg', 'nz.jpg']);
+```
+
+## Material Maps
+
+Multiple texture types for different effects:
+
+```javascript
+const material = new THREE.MeshStandardMaterial({
+  map: diffuseTexture,           // base color
+  normalMap: normalTexture,       // surface detail
+  roughnessMap: roughnessTexture, // surface roughness variation
+  metalnessMap: metalnessTexture, // metallic areas
+  aoMap: aoTexture,               // ambient occlusion
+  emissiveMap: emissiveTexture,   // glow areas
+  alphaMap: alphaTexture,         // transparency
+  bumpMap: bumpTexture,           // height variation
+  displacementMap: dispTexture    // vertex displacement
+});
+
+// AO map requires second UV set
+geometry.setAttribute('uv2', geometry.attributes.uv);
+```
+
+## Wrapping Modes
+
+Control texture repeat behavior:
+
+```javascript
+texture.wrapS = THREE.RepeatWrapping;      // horizontal
+texture.wrapT = THREE.RepeatWrapping;      // vertical
+
+// Options:
+// THREE.RepeatWrapping - tile infinitely
+// THREE.ClampToEdgeWrapping - stretch edge pixels
+// THREE.MirroredRepeatWrapping - mirror on each repeat
+
+// Set repeat count
+texture.repeat.set(4, 4);
+
+// Offset texture
+texture.offset.set(0.5, 0.5);
+```
+
+## Filtering
+
+Control texture sampling quality:
+
+```javascript
+// Magnification (when texel < pixel)
+texture.magFilter = THREE.LinearFilter; // smooth
+// or THREE.NearestFilter // pixelated
+
+// Minification (when texel > pixel)
+texture.minFilter = THREE.LinearMipmapLinearFilter; // best quality
+// Options:
+// THREE.NearestFilter
+// THREE.LinearFilter
+// THREE.NearestMipmapNearestFilter
+// THREE.NearestMipmapLinearFilter
+// THREE.LinearMipmapNearestFilter
+// THREE.LinearMipmapLinearFilter
+
+// Anisotropic filtering (better at angles)
+texture.anisotropy = renderer.capabilities.getMaxAnisotropy();
+```
+
+## UV Mapping
+
+Control how texture is mapped to geometry:
+
+```javascript
+// Flip texture vertically
+texture.flipY = false;
+
+// Rotate texture
+texture.rotation = Math.PI / 4; // 45 degrees
+texture.center.set(0.5, 0.5); // rotation center
+
+// Transform UV coordinates
+const uvAttribute = geometry.attributes.uv;
+for (let i = 0; i < uvAttribute.count; i++) {
+  let u = uvAttribute.getX(i);
+  let v = uvAttribute.getY(i);
+  uvAttribute.setXY(i, u * 2, v * 2); // scale UVs
+}
+uvAttribute.needsUpdate = true;
+```
+
+## Color Space
+
+Handle color space correctly:
+
+```javascript
+// For color data (diffuse, emissive)
+texture.colorSpace = THREE.SRGBColorSpace;
+
+// For non-color data (normal, roughness, etc.)
+texture.colorSpace = THREE.NoColorSpace; // or LinearSRGBColorSpace
+```
+
+## Performance Optimization
+
+```javascript
+// Use mipmaps (auto-generated by default)
+texture.generateMipmaps = true;
+
+// Dispose when done
+texture.dispose();
+
+// Compress textures (use KTX2Loader for .ktx2 files)
+// Reduce resolution for distant objects
+// Use texture atlases to reduce draw calls
+```
+
+## Advanced Textures
+
+```javascript
+// 3D Texture (volumetric)
+const texture3d = new THREE.Data3DTexture(data, width, height, depth);
+
+// Depth Texture (for advanced effects)
+const depthTexture = new THREE.DepthTexture(width, height);
+
+// Compressed Texture
+const compressedTexture = new THREE.CompressedTexture(...);
+```

package/.antigravity/skills/threejs/references/04-cameras.md

@@ -0,0 +1,195 @@
+# Cameras
+
+Define viewpoint and projection for rendering.
+
+## Perspective Camera
+
+Realistic camera with field of view (most common):
+
+```javascript
+const camera = new THREE.PerspectiveCamera(
+  fov,    // field of view in degrees (typically 45-75)
+  aspect, // width / height
+  near,   // near clipping plane (typically 0.1)
+  far     // far clipping plane (typically 1000)
+);
+
+camera.position.set(0, 5, 10);
+camera.lookAt(0, 0, 0);
+
+// Update after changing parameters
+camera.fov = 60;
+camera.updateProjectionMatrix();
+```
+
+## Orthographic Camera
+
+No perspective distortion (parallel projection):
+
+```javascript
+const frustumSize = 10;
+const aspect = window.innerWidth / window.innerHeight;
+const camera = new THREE.OrthographicCamera(
+  frustumSize * aspect / -2, // left
+  frustumSize * aspect / 2,  // right
+  frustumSize / 2,           // top
+  frustumSize / -2,          // bottom
+  0.1,                       // near
+  1000                       // far
+);
+
+// Useful for: 2D games, CAD, isometric views
+```
+
+## Camera Controls (Addons)
+
+### OrbitControls (Most Common)
+```javascript
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+
+const controls = new OrbitControls(camera, renderer.domElement);
+controls.target.set(0, 0, 0);
+controls.enableDamping = true;   // smooth motion
+controls.dampingFactor = 0.05;
+controls.minDistance = 5;
+controls.maxDistance = 50;
+controls.maxPolarAngle = Math.PI / 2; // prevent going below ground
+
+// In animation loop
+function animate() {
+  controls.update(); // required if enableDamping = true
+  renderer.render(scene, camera);
+}
+```
+
+### FirstPersonControls
+```javascript
+import { FirstPersonControls } from 'three/addons/controls/FirstPersonControls.js';
+
+const controls = new FirstPersonControls(camera, renderer.domElement);
+controls.movementSpeed = 10;
+controls.lookSpeed = 0.1;
+
+const clock = new THREE.Clock();
+function animate() {
+  const delta = clock.getDelta();
+  controls.update(delta);
+  renderer.render(scene, camera);
+}
+```
+
+### FlyControls
+```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.dragToLook = true;
+```
+
+### TransformControls
+```javascript
+import { TransformControls } from 'three/addons/controls/TransformControls.js';
+
+const controls = new TransformControls(camera, renderer.domElement);
+controls.attach(mesh);
+scene.add(controls);
+
+// Switch modes
+controls.setMode('translate'); // or 'rotate', 'scale'
+
+// Events
+controls.addEventListener('change', () => renderer.render(scene, camera));
+controls.addEventListener('dragging-changed', (event) => {
+  orbitControls.enabled = !event.value;
+});
+```
+
+## Camera Methods
+
+```javascript
+// Position and orientation
+camera.position.set(x, y, z);
+camera.lookAt(x, y, z); // or lookAt(vector3) or lookAt(object.position)
+camera.up.set(0, 1, 0); // define "up" direction
+
+// Get world direction
+const direction = new THREE.Vector3();
+camera.getWorldDirection(direction);
+
+// Screen to world conversion
+const mouse = new THREE.Vector2(x, y); // normalized device coords (-1 to 1)
+const raycaster = new THREE.Raycaster();
+raycaster.setFromCamera(mouse, camera);
+
+// World to screen
+const vector = new THREE.Vector3(x, y, z);
+vector.project(camera); // now in normalized device coords
+```
+
+## Layers
+
+Selective rendering with layers:
+
+```javascript
+// Set object layers
+mesh.layers.set(1);
+
+// Set camera layers
+camera.layers.enable(0); // render layer 0
+camera.layers.enable(1); // render layer 1
+camera.layers.disable(2); // don't render layer 2
+
+// Objects on disabled layers won't be rendered
+```
+
+## Frustum Culling
+
+Automatic optimization (objects outside view are not rendered):
+
+```javascript
+// Manually check if object is in view
+const frustum = new THREE.Frustum();
+const matrix = new THREE.Matrix4().multiplyMatrices(
+  camera.projectionMatrix,
+  camera.matrixWorldInverse
+);
+frustum.setFromProjectionMatrix(matrix);
+
+if (frustum.containsPoint(object.position)) {
+  // Object is visible
+}
+```
+
+## Multiple Cameras
+
+```javascript
+const mainCamera = new THREE.PerspectiveCamera(...);
+const minimapCamera = new THREE.OrthographicCamera(...);
+
+// Render with different viewports
+renderer.setViewport(0, 0, width, height);
+renderer.render(scene, mainCamera);
+
+renderer.setViewport(width - 200, height - 200, 200, 200);
+renderer.render(scene, minimapCamera);
+```
+
+## Resize Handling
+
+```javascript
+window.addEventListener('resize', () => {
+  // Perspective camera
+  camera.aspect = window.innerWidth / window.innerHeight;
+  camera.updateProjectionMatrix();
+
+  // Orthographic camera
+  const aspect = window.innerWidth / window.innerHeight;
+  camera.left = -frustumSize * aspect / 2;
+  camera.right = frustumSize * aspect / 2;
+  camera.updateProjectionMatrix();
+
+  renderer.setSize(window.innerWidth, window.innerHeight);
+});
+```

package/.antigravity/skills/threejs/references/05-lights.md

@@ -0,0 +1,183 @@
+# Lights
+
+Illuminate 3D scenes with various light types.
+
+## Ambient Light
+
+Global illumination affecting all objects equally:
+
+```javascript
+const light = new THREE.AmbientLight(0x404040); // soft white
+scene.add(light);
+
+// Often used as base illumination with other lights
+```
+
+## Directional Light
+
+Infinite distance light with parallel rays (sun-like):
+
+```javascript
+const light = new THREE.DirectionalLight(0xffffff, 1);
+light.position.set(10, 10, 5);
+light.target.position.set(0, 0, 0);
+scene.add(light);
+scene.add(light.target); // target must be in scene
+
+// With shadows
+light.castShadow = true;
+light.shadow.mapSize.width = 2048;
+light.shadow.mapSize.height = 2048;
+light.shadow.camera.near = 0.5;
+light.shadow.camera.far = 500;
+light.shadow.camera.left = -10;
+light.shadow.camera.right = 10;
+light.shadow.camera.top = 10;
+light.shadow.camera.bottom = -10;
+
+// Visualize shadow camera
+const helper = new THREE.CameraHelper(light.shadow.camera);
+scene.add(helper);
+```
+
+## Point Light
+
+Omnidirectional light from a point (lightbulb-like):
+
+```javascript
+const light = new THREE.PointLight(0xff0000, 1, 100, 2);
+// params: color, intensity, distance (0 = infinite), decay
+
+light.position.set(0, 10, 0);
+scene.add(light);
+
+// With shadows
+light.castShadow = true;
+light.shadow.mapSize.width = 1024;
+light.shadow.mapSize.height = 1024;
+light.shadow.camera.near = 0.5;
+light.shadow.camera.far = 100;
+```
+
+## Spot Light
+
+Cone-shaped light (spotlight-like):
+
+```javascript
+const light = new THREE.SpotLight(0xffffff, 1);
+light.position.set(0, 10, 0);
+light.target.position.set(0, 0, 0);
+scene.add(light);
+scene.add(light.target);
+
+// Cone parameters
+light.angle = Math.PI / 6; // cone angle
+light.penumbra = 0.1;      // edge softness (0-1)
+light.decay = 2;           // light falloff
+light.distance = 100;      // max range (0 = infinite)
+
+// With shadows
+light.castShadow = true;
+light.shadow.mapSize.width = 1024;
+light.shadow.mapSize.height = 1024;
+```
+
+## Hemisphere Light
+
+Sky/ground two-color lighting:
+
+```javascript
+const light = new THREE.HemisphereLight(
+  0x0000ff, // sky color (blue)
+  0x00ff00, // ground color (green)
+  0.6       // intensity
+);
+scene.add(light);
+
+// Good for outdoor scenes
+```
+
+## RectArea Light (Addon)
+
+Rectangular area light (realistic surface illumination):
+
+```javascript
+import { RectAreaLight } from 'three/addons/lights/RectAreaLight.js';
+
+const light = new RectAreaLight(0xffffff, 5, 10, 10);
+// params: color, intensity, width, height
+
+light.position.set(0, 5, 0);
+light.lookAt(0, 0, 0);
+scene.add(light);
+
+// Requires WebGL 2.0
+```
+
+## Shadow Configuration
+
+Global renderer settings:
+
+```javascript
+renderer.shadowMap.enabled = true;
+renderer.shadowMap.type = THREE.PCFSoftShadowMap; // soft shadows
+
+// Shadow types:
+// THREE.BasicShadowMap - fast, aliased
+// THREE.PCFShadowMap - smoother
+// THREE.PCFSoftShadowMap - softer (default)
+// THREE.VSMShadowMap - variance shadow maps
+
+// Objects must opt-in to shadows
+mesh.castShadow = true;    // object casts shadows
+mesh.receiveShadow = true; // object receives shadows
+```
+
+## Light Helpers
+
+Visualize light positions and directions:
+
+```javascript
+// Directional light
+const helper = new THREE.DirectionalLightHelper(light, 5);
+scene.add(helper);
+
+// Point light
+const helper = new THREE.PointLightHelper(light, 1);
+scene.add(helper);
+
+// Spot light
+const helper = new THREE.SpotLightHelper(light);
+scene.add(helper);
+
+// Hemisphere light
+const helper = new THREE.HemisphereLightHelper(light, 5);
+scene.add(helper);
+
+// RectArea light
+import { RectAreaLightHelper } from 'three/addons/helpers/RectAreaLightHelper.js';
+const helper = new RectAreaLightHelper(light);
+light.add(helper);
+```
+
+## Light Intensity & Units
+
+```javascript
+// Intensity values depend on physically-based rendering:
+// - Lower values (0.1-1) for ambient/hemisphere
+// - Higher values (1-10) for directional/point/spot
+// - Very high (10-100+) for small area lights
+
+// Physical light units (optional)
+renderer.physicallyCorrectLights = true; // deprecated in newer versions
+// Use intensity in candelas (cd) for point/spot lights
+```
+
+## Performance Tips
+
+- Limit number of lights (3-5 for good performance)
+- Use ambient + 1-2 directional lights for outdoor scenes
+- Bake lighting into textures for static scenes
+- Use lightmaps for complex static lighting
+- Shadows are expensive - use selectively
+- Lower shadow map resolution for better performance