anchi-kit 1.2.3 → 1.2.6

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

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

@@ -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.