anchi-kit 1.2.0 → 1.2.2

package/.antigravity/skills/threejs/references/12-performance.md

@@ -1,269 +0,0 @@
-# Performance Optimization
-
-Techniques for fast, smooth 3D experiences.
-
-## Instancing
-
-Render many copies of same geometry efficiently:
-
-```javascript
-// Instead of creating 10,000 individual meshes
-const geometry = new THREE.BoxGeometry(1, 1, 1);
-const material = new THREE.MeshStandardMaterial({ color: 0x00ff00 });
-const mesh = new THREE.InstancedMesh(geometry, material, 10000);
-
-// Set transforms for each instance
-const matrix = new THREE.Matrix4();
-const position = new THREE.Vector3();
-const rotation = new THREE.Euler();
-const quaternion = new THREE.Quaternion();
-const scale = new THREE.Vector3(1, 1, 1);
-
-for (let i = 0; i < 10000; i++) {
-  position.set(
-    Math.random() * 100 - 50,
-    Math.random() * 100 - 50,
-    Math.random() * 100 - 50
-  );
-
-  rotation.set(
-    Math.random() * Math.PI,
-    Math.random() * Math.PI,
-    Math.random() * Math.PI
-  );
-
-  quaternion.setFromEuler(rotation);
-  matrix.compose(position, quaternion, scale);
-  mesh.setMatrixAt(i, matrix);
-}
-
-mesh.instanceMatrix.needsUpdate = true;
-scene.add(mesh);
-
-// Per-instance colors
-mesh.instanceColor = new THREE.InstancedBufferAttribute(
-  new Float32Array(10000 * 3),
-  3
-);
-
-for (let i = 0; i < 10000; i++) {
-  mesh.setColorAt(i, new THREE.Color(Math.random(), Math.random(), Math.random()));
-}
-```
-
-## Level of Detail (LOD)
-
-Switch between detail levels based on distance:
-
-```javascript
-const lod = new THREE.LOD();
-
-// High detail (close)
-const geometryHigh = new THREE.IcosahedronGeometry(10, 4);
-const meshHigh = new THREE.Mesh(geometryHigh, material);
-lod.addLevel(meshHigh, 0);
-
-// Medium detail
-const geometryMed = new THREE.IcosahedronGeometry(10, 2);
-const meshMed = new THREE.Mesh(geometryMed, material);
-lod.addLevel(meshMed, 50);
-
-// Low detail (far)
-const geometryLow = new THREE.IcosahedronGeometry(10, 0);
-const meshLow = new THREE.Mesh(geometryLow, material);
-lod.addLevel(meshLow, 100);
-
-scene.add(lod);
-
-// Update LOD in animation loop
-function animate() {
-  lod.update(camera);
-  renderer.render(scene, camera);
-  requestAnimationFrame(animate);
-}
-```
-
-## Frustum Culling
-
-Automatic - objects outside camera view aren't rendered.
-
-```javascript
-// Force disable for specific object
-object.frustumCulled = false;
-
-// Manually test if in view
-const frustum = new THREE.Frustum();
-const cameraViewProjectionMatrix = new THREE.Matrix4();
-cameraViewProjectionMatrix.multiplyMatrices(
-  camera.projectionMatrix,
-  camera.matrixWorldInverse
-);
-frustum.setFromProjectionMatrix(cameraViewProjectionMatrix);
-
-if (frustum.intersectsObject(object)) {
-  // Object is visible
-}
-```
-
-## Geometry Optimization
-
-```javascript
-// Merge geometries (reduce draw calls)
-import { mergeGeometries } from 'three/addons/utils/BufferGeometryUtils.js';
-
-const geometries = [geom1, geom2, geom3];
-const mergedGeometry = mergeGeometries(geometries);
-const mesh = new THREE.Mesh(mergedGeometry, material);
-
-// Dispose old geometries
-geometries.forEach(g => g.dispose());
-
-// Simplify geometry
-import { SimplifyModifier } from 'three/addons/modifiers/SimplifyModifier.js';
-
-const modifier = new SimplifyModifier();
-const simplified = modifier.modify(geometry, Math.floor(geometry.attributes.position.count * 0.5));
-```
-
-## Texture Optimization
-
-```javascript
-// Use appropriate sizes (power of 2)
-// 512x512, 1024x1024, 2048x2048
-
-// Compress textures
-import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
-
-// Use mipmaps (auto-generated by default)
-texture.generateMipmaps = true;
-
-// Appropriate filtering
-texture.minFilter = THREE.LinearMipmapLinearFilter;
-texture.magFilter = THREE.LinearFilter;
-
-// Anisotropic filtering (balance quality/performance)
-texture.anisotropy = renderer.capabilities.getMaxAnisotropy();
-
-// Dispose unused textures
-texture.dispose();
-```
-
-## Material Sharing
-
-```javascript
-// Share materials between meshes (reduce memory)
-const sharedMaterial = new THREE.MeshStandardMaterial({ color: 0x00ff00 });
-
-const mesh1 = new THREE.Mesh(geometry1, sharedMaterial);
-const mesh2 = new THREE.Mesh(geometry2, sharedMaterial);
-const mesh3 = new THREE.Mesh(geometry3, sharedMaterial);
-```
-
-## Shadow Optimization
-
-```javascript
-// Reduce shadow map resolution
-light.shadow.mapSize.width = 1024;  // instead of 2048
-light.shadow.mapSize.height = 1024;
-
-// Limit shadow camera frustum
-light.shadow.camera.near = 0.5;
-light.shadow.camera.far = 50;  // only cast shadows within this range
-light.shadow.camera.left = -10;
-light.shadow.camera.right = 10;
-
-// Use fewer shadow-casting objects
-object.castShadow = false; // for distant/small objects
-object.receiveShadow = false; // for objects that don't need shadows
-
-// Cheaper shadow type
-renderer.shadowMap.type = THREE.PCFShadowMap; // instead of PCFSoftShadowMap
-```
-
-## Render Target Optimization
-
-```javascript
-// Lower resolution for post-processing
-const renderTarget = new THREE.WebGLRenderTarget(
-  window.innerWidth * 0.5,  // half resolution
-  window.innerHeight * 0.5
-);
-
-// Appropriate pixel format
-renderTarget.texture.format = THREE.RGBAFormat;
-renderTarget.texture.type = THREE.UnsignedByteType;
-
-// Dispose when done
-renderTarget.dispose();
-```
-
-## Object Pooling
-
-```javascript
-// Reuse objects instead of creating/destroying
-class ObjectPool {
-  constructor(factory, initialSize) {
-    this.factory = factory;
-    this.pool = [];
-    for (let i = 0; i < initialSize; i++) {
-      this.pool.push(factory());
-    }
-  }
-
-  get() {
-    return this.pool.length > 0 ? this.pool.pop() : this.factory();
-  }
-
-  release(obj) {
-    this.pool.push(obj);
-  }
-}
-
-const bulletPool = new ObjectPool(() => {
-  return new THREE.Mesh(bulletGeometry, bulletMaterial);
-}, 100);
-
-// Use
-const bullet = bulletPool.get();
-scene.add(bullet);
-
-// Return when done
-scene.remove(bullet);
-bulletPool.release(bullet);
-```
-
-## Monitoring Performance
-
-```javascript
-// FPS counter
-const stats = new Stats();
-document.body.appendChild(stats.dom);
-
-function animate() {
-  stats.begin();
-  // ... rendering
-  stats.end();
-  requestAnimationFrame(animate);
-}
-
-// Renderer info
-console.log(renderer.info);
-// Shows: geometries, textures, programs, calls, triangles, points, lines
-
-// GPU timing
-const query = renderer.extensions.get('EXT_disjoint_timer_query_webgl2');
-```
-
-## General Best Practices
-
-- Limit draw calls (merge geometries, use instancing)
-- Reduce polygon count (LOD, simplification)
-- Optimize textures (compression, appropriate sizes)
-- Share materials and geometries
-- Use frustum culling
-- Limit number of lights (3-5 max)
-- Avoid transparent materials when possible
-- Use object pooling for frequently created/destroyed objects
-- Profile with browser DevTools
-- Test on target devices
-- Use WebGL 2 features when available

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

@@ -1,298 +0,0 @@
-# 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.