@hienlh/ppm 0.9.81 → 0.9.83

package/.opencode/skills/threejs/references/11-materials.md

@@ -1,519 +0,0 @@
-# Three.js Materials
-
-## Overview
-
-Three.js materials - PBR, basic, phong, shader materials, material properties. Use when styling meshes, working with textures, creating custom shaders, or optimizing material performance.
-
-## Quick Start
-
-```javascript
-import * as THREE from "three";
-
-// PBR material (recommended for realistic rendering)
-const material = new THREE.MeshStandardMaterial({
-  color: 0x00ff00,
-  roughness: 0.5,
-  metalness: 0.5,
-});
-
-const mesh = new THREE.Mesh(geometry, material);
-```
-
-## Material Types Overview
-
-| Material             | Use Case                              | Lighting           |
-| -------------------- | ------------------------------------- | ------------------ |
-| MeshBasicMaterial    | Unlit, flat colors, wireframes        | No                 |
-| MeshLambertMaterial  | Matte surfaces, performance           | Yes (diffuse only) |
-| MeshPhongMaterial    | Shiny surfaces, specular highlights   | Yes                |
-| MeshStandardMaterial | PBR, realistic materials              | Yes (PBR)          |
-| MeshPhysicalMaterial | Advanced PBR, clearcoat, transmission | Yes (PBR+)         |
-| MeshToonMaterial     | Cel-shaded, cartoon look              | Yes (toon)         |
-| MeshNormalMaterial   | Debug normals                         | No                 |
-| MeshDepthMaterial    | Depth visualization                   | No                 |
-| ShaderMaterial       | Custom GLSL shaders                   | Custom             |
-| RawShaderMaterial    | Full shader control                   | Custom             |
-
-## MeshBasicMaterial
-
-No lighting calculations. Fast, always visible.
-
-```javascript
-const material = new THREE.MeshBasicMaterial({
-  color: 0xff0000,
-  transparent: true,
-  opacity: 0.5,
-  side: THREE.DoubleSide, // FrontSide, BackSide, DoubleSide
-  wireframe: false,
-  map: texture, // Color/diffuse texture
-  alphaMap: alphaTexture, // Transparency texture
-  envMap: envTexture, // Reflection texture
-  reflectivity: 1, // Env map intensity
-  fog: true, // Affected by scene fog
-});
-```
-
-## MeshLambertMaterial
-
-Diffuse-only lighting. Fast, no specular highlights.
-
-```javascript
-const material = new THREE.MeshLambertMaterial({
-  color: 0x00ff00,
-  emissive: 0x111111, // Self-illumination color
-  emissiveIntensity: 1,
-  map: texture,
-  emissiveMap: emissiveTexture,
-  envMap: envTexture,
-  reflectivity: 0.5,
-});
-```
-
-## MeshPhongMaterial
-
-Specular highlights. Good for shiny, plastic-like surfaces.
-
-```javascript
-const material = new THREE.MeshPhongMaterial({
-  color: 0x0000ff,
-  specular: 0xffffff, // Highlight color
-  shininess: 100, // Highlight sharpness (0-1000)
-  emissive: 0x000000,
-  flatShading: false, // Flat vs smooth shading
-  map: texture,
-  specularMap: specTexture, // Per-pixel shininess
-  normalMap: normalTexture,
-  normalScale: new THREE.Vector2(1, 1),
-  bumpMap: bumpTexture,
-  bumpScale: 1,
-  displacementMap: dispTexture,
-  displacementScale: 1,
-});
-```
-
-## MeshStandardMaterial (PBR)
-
-Physically-based rendering. Recommended for realistic results.
-
-```javascript
-const material = new THREE.MeshStandardMaterial({
-  color: 0xffffff,
-  roughness: 0.5, // 0 = mirror, 1 = diffuse
-  metalness: 0.0, // 0 = dielectric, 1 = metal
-
-  // Textures
-  map: colorTexture, // Albedo/base color
-  roughnessMap: roughTexture, // Per-pixel roughness
-  metalnessMap: metalTexture, // Per-pixel metalness
-  normalMap: normalTexture, // Surface detail
-  normalScale: new THREE.Vector2(1, 1),
-  aoMap: aoTexture, // Ambient occlusion (uses uv2!)
-  aoMapIntensity: 1,
-  displacementMap: dispTexture, // Vertex displacement
-  displacementScale: 0.1,
-  displacementBias: 0,
-
-  // Emissive
-  emissive: 0x000000,
-  emissiveIntensity: 1,
-  emissiveMap: emissiveTexture,
-
-  // Environment
-  envMap: envTexture,
-  envMapIntensity: 1,
-
-  // Other
-  flatShading: false,
-  wireframe: false,
-  fog: true,
-});
-
-// Note: aoMap requires second UV channel
-geometry.setAttribute("uv2", geometry.attributes.uv);
-```
-
-## MeshPhysicalMaterial (Advanced PBR)
-
-Extends MeshStandardMaterial with advanced features.
-
-```javascript
-const material = new THREE.MeshPhysicalMaterial({
-  // All MeshStandardMaterial properties plus:
-
-  // Clearcoat (car paint, lacquer)
-  clearcoat: 1.0, // 0-1 clearcoat layer strength
-  clearcoatRoughness: 0.1,
-  clearcoatMap: ccTexture,
-  clearcoatRoughnessMap: ccrTexture,
-  clearcoatNormalMap: ccnTexture,
-  clearcoatNormalScale: new THREE.Vector2(1, 1),
-
-  // Transmission (glass, water)
-  transmission: 1.0, // 0 = opaque, 1 = fully transparent
-  transmissionMap: transTexture,
-  thickness: 0.5, // Volume thickness for refraction
-  thicknessMap: thickTexture,
-  attenuationDistance: 1, // Absorption distance
-  attenuationColor: new THREE.Color(0xffffff),
-
-  // Refraction
-  ior: 1.5, // Index of refraction (1-2.333)
-
-  // Sheen (fabric, velvet)
-  sheen: 1.0,
-  sheenRoughness: 0.5,
-  sheenColor: new THREE.Color(0xffffff),
-  sheenColorMap: sheenTexture,
-  sheenRoughnessMap: sheenRoughTexture,
-
-  // Iridescence (soap bubbles, oil slicks)
-  iridescence: 1.0,
-  iridescenceIOR: 1.3,
-  iridescenceThicknessRange: [100, 400],
-  iridescenceMap: iridTexture,
-  iridescenceThicknessMap: iridThickTexture,
-
-  // Anisotropy (brushed metal)
-  anisotropy: 1.0,
-  anisotropyRotation: 0,
-  anisotropyMap: anisoTexture,
-
-  // Specular
-  specularIntensity: 1,
-  specularColor: new THREE.Color(0xffffff),
-  specularIntensityMap: specIntTexture,
-  specularColorMap: specColorTexture,
-});
-```
-
-### Glass Material Example
-
-```javascript
-const glass = new THREE.MeshPhysicalMaterial({
-  color: 0xffffff,
-  metalness: 0,
-  roughness: 0,
-  transmission: 1,
-  thickness: 0.5,
-  ior: 1.5,
-  envMapIntensity: 1,
-});
-```
-
-### Car Paint Example
-
-```javascript
-const carPaint = new THREE.MeshPhysicalMaterial({
-  color: 0xff0000,
-  metalness: 0.9,
-  roughness: 0.5,
-  clearcoat: 1,
-  clearcoatRoughness: 0.1,
-});
-```
-
-## MeshToonMaterial
-
-Cel-shaded cartoon look.
-
-```javascript
-const material = new THREE.MeshToonMaterial({
-  color: 0x00ff00,
-  gradientMap: gradientTexture, // Optional: custom shading gradient
-});
-
-// Create step gradient texture
-const colors = new Uint8Array([0, 128, 255]);
-const gradientMap = new THREE.DataTexture(colors, 3, 1, THREE.RedFormat);
-gradientMap.minFilter = THREE.NearestFilter;
-gradientMap.magFilter = THREE.NearestFilter;
-gradientMap.needsUpdate = true;
-```
-
-## MeshNormalMaterial
-
-Visualize surface normals. Useful for debugging.
-
-```javascript
-const material = new THREE.MeshNormalMaterial({
-  flatShading: false,
-  wireframe: false,
-});
-```
-
-## MeshDepthMaterial
-
-Render depth values. Used for shadow maps, DOF effects.
-
-```javascript
-const material = new THREE.MeshDepthMaterial({
-  depthPacking: THREE.RGBADepthPacking,
-});
-```
-
-## PointsMaterial
-
-For point clouds.
-
-```javascript
-const material = new THREE.PointsMaterial({
-  color: 0xffffff,
-  size: 0.1,
-  sizeAttenuation: true, // Scale with distance
-  map: pointTexture,
-  alphaMap: alphaTexture,
-  transparent: true,
-  alphaTest: 0.5, // Discard pixels below threshold
-  vertexColors: true, // Use per-vertex colors
-});
-
-const points = new THREE.Points(geometry, material);
-```
-
-## LineBasicMaterial & LineDashedMaterial
-
-```javascript
-// Solid lines
-const lineMaterial = new THREE.LineBasicMaterial({
-  color: 0xffffff,
-  linewidth: 1, // Note: >1 only works on some systems
-  linecap: "round",
-  linejoin: "round",
-});
-
-// Dashed lines
-const dashedMaterial = new THREE.LineDashedMaterial({
-  color: 0xffffff,
-  dashSize: 0.5,
-  gapSize: 0.25,
-  scale: 1,
-});
-
-// Required for dashed lines
-const line = new THREE.Line(geometry, dashedMaterial);
-line.computeLineDistances();
-```
-
-## ShaderMaterial
-
-Custom GLSL shaders with Three.js uniforms.
-
-```javascript
-const material = new THREE.ShaderMaterial({
-  uniforms: {
-    time: { value: 0 },
-    color: { value: new THREE.Color(0xff0000) },
-    texture1: { value: texture },
-  },
-  vertexShader: `
-    varying vec2 vUv;
-    uniform float time;
-
-    void main() {
-      vUv = uv;
-      vec3 pos = position;
-      pos.z += sin(pos.x * 10.0 + time) * 0.1;
-      gl_Position = projectionMatrix * modelViewMatrix * vec4(pos, 1.0);
-    }
-  `,
-  fragmentShader: `
-    varying vec2 vUv;
-    uniform vec3 color;
-    uniform sampler2D texture1;
-
-    void main() {
-      // Use texture2D() for GLSL 1.0, texture() for GLSL 3.0 (glslVersion: THREE.GLSL3)
-      vec4 texColor = texture2D(texture1, vUv);
-      gl_FragColor = vec4(color * texColor.rgb, 1.0);
-    }
-  `,
-  transparent: true,
-  side: THREE.DoubleSide,
-});
-
-// Update uniform in animation loop
-material.uniforms.time.value = clock.getElapsedTime();
-```
-
-### Built-in Uniforms (auto-provided)
-
-```glsl
-// Vertex shader
-uniform mat4 modelMatrix;         // Object to world
-uniform mat4 modelViewMatrix;     // Object to camera
-uniform mat4 projectionMatrix;    // Camera projection
-uniform mat4 viewMatrix;          // World to camera
-uniform mat3 normalMatrix;        // For transforming normals
-uniform vec3 cameraPosition;      // Camera world position
-
-// Attributes
-attribute vec3 position;
-attribute vec3 normal;
-attribute vec2 uv;
-```
-
-## RawShaderMaterial
-
-Full control - no built-in uniforms/attributes.
-
-```javascript
-const material = new THREE.RawShaderMaterial({
-  uniforms: {
-    projectionMatrix: { value: camera.projectionMatrix },
-    modelViewMatrix: { value: new THREE.Matrix4() },
-  },
-  vertexShader: `
-    precision highp float;
-    attribute vec3 position;
-    uniform mat4 projectionMatrix;
-    uniform mat4 modelViewMatrix;
-
-    void main() {
-      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
-    }
-  `,
-  fragmentShader: `
-    precision highp float;
-
-    void main() {
-      gl_FragColor = vec4(1.0, 0.0, 0.0, 1.0);
-    }
-  `,
-});
-```
-
-## Common Material Properties
-
-All materials share these base properties:
-
-```javascript
-// Visibility
-material.visible = true;
-material.transparent = false;
-material.opacity = 1.0;
-material.alphaTest = 0; // Discard pixels with alpha < value
-
-// Rendering
-material.side = THREE.FrontSide; // FrontSide, BackSide, DoubleSide
-material.depthTest = true;
-material.depthWrite = true;
-material.colorWrite = true;
-
-// Blending
-material.blending = THREE.NormalBlending;
-// NormalBlending, AdditiveBlending, SubtractiveBlending, MultiplyBlending, CustomBlending
-
-// Stencil
-material.stencilWrite = false;
-material.stencilFunc = THREE.AlwaysStencilFunc;
-material.stencilRef = 0;
-material.stencilMask = 0xff;
-
-// Polygon offset (z-fighting fix)
-material.polygonOffset = false;
-material.polygonOffsetFactor = 0;
-material.polygonOffsetUnits = 0;
-
-// Misc
-material.dithering = false;
-material.toneMapped = true;
-```
-
-## Multiple Materials
-
-```javascript
-// Assign different materials to geometry groups
-const geometry = new THREE.BoxGeometry(1, 1, 1);
-const materials = [
-  new THREE.MeshBasicMaterial({ color: 0xff0000 }), // right
-  new THREE.MeshBasicMaterial({ color: 0x00ff00 }), // left
-  new THREE.MeshBasicMaterial({ color: 0x0000ff }), // top
-  new THREE.MeshBasicMaterial({ color: 0xffff00 }), // bottom
-  new THREE.MeshBasicMaterial({ color: 0xff00ff }), // front
-  new THREE.MeshBasicMaterial({ color: 0x00ffff }), // back
-];
-const mesh = new THREE.Mesh(geometry, materials);
-
-// Custom groups
-geometry.clearGroups();
-geometry.addGroup(0, 6, 0); // start, count, materialIndex
-geometry.addGroup(6, 6, 1);
-```
-
-## Environment Maps
-
-```javascript
-// Load cube texture
-const cubeLoader = new THREE.CubeTextureLoader();
-const envMap = cubeLoader.load([
-  "px.jpg",
-  "nx.jpg", // positive/negative X
-  "py.jpg",
-  "ny.jpg", // positive/negative Y
-  "pz.jpg",
-  "nz.jpg", // positive/negative Z
-]);
-
-// Apply to material
-material.envMap = envMap;
-material.envMapIntensity = 1;
-
-// Or set as scene environment (affects all PBR materials)
-scene.environment = envMap;
-
-// HDR environment (recommended)
-import { RGBELoader } from "three/examples/jsm/loaders/RGBELoader.js";
-const rgbeLoader = new RGBELoader();
-rgbeLoader.load("environment.hdr", (texture) => {
-  texture.mapping = THREE.EquirectangularReflectionMapping;
-  scene.environment = texture;
-  scene.background = texture;
-});
-```
-
-## Material Cloning and Modification
-
-```javascript
-// Clone material
-const clone = material.clone();
-clone.color.set(0x00ff00);
-
-// Modify at runtime
-material.color.set(0xff0000);
-material.needsUpdate = true; // Only needed for some changes
-
-// When needsUpdate is required:
-// - Changing flat shading
-// - Changing texture
-// - Changing transparent
-// - Custom shader code changes
-```
-
-## Performance Tips
-
-1. **Reuse materials**: Same material = batched draw calls
-2. **Avoid transparent when possible**: Transparent materials require sorting
-3. **Use alphaTest instead of transparency**: When applicable, faster
-4. **Choose simpler materials**: Basic > Lambert > Phong > Standard > Physical
-5. **Limit active lights**: Each light adds shader complexity
-
-```javascript
-// Material pooling
-const materialCache = new Map();
-function getMaterial(color) {
-  const key = color.toString(16);
-  if (!materialCache.has(key)) {
-    materialCache.set(key, new THREE.MeshStandardMaterial({ color }));
-  }
-  return materialCache.get(key);
-}
-
-// Dispose when done
-material.dispose();
-```
-
-## See Also
-
-- `threejs-textures` - Texture loading and configuration
-- `threejs-shaders` - Custom shader development
-- `threejs-lighting` - Light interaction with materials