threejs-awesome-graphics-agent-skills 0.1.2 → 0.2.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "threejs-awesome-graphics-agent-skills",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Expert agent skills for creating exceptional Three.js graphics.",
   "author": {
     "name": "Scott"

package/README.md

@@ -32,13 +32,13 @@ Every graphics system is expected to expose:
 | `threejs-camera-direction` | Authored lenses and shots, chase/side/orbit rigs, body-relative frames, handoffs, pointer look, floating origins. |
 | `threejs-procedural-animation` | Analytic timelines, gravity turns, staging, rotating-frame docking, springs, quaternion alignment, debris motion. |
 | `threejs-procedural-fields` | Shared scalar/vector fields, frequency bands, domain warping, causal masks, procedural normals. |
-| `threejs-procedural-materials` | Atlas filtering, specular AA, planetary materials, terrain wetness, frame PBR, per-instance dissolve. |
+| `threejs-procedural-materials` | Atlas filtering, specular AA, planetary materials, terrain wetness, lava/emissive surfaces, frame PBR, per-instance dissolve. |
 | `threejs-procedural-geometry` | Sculpted frame rails, branch rings, semantic mesh writers, UV density, material groups. |
-| `threejs-procedural-vegetation` | Growth hierarchies, branch-ring geometry, stratified children, foliage normals, wind. |
+| `threejs-procedural-vegetation` | Growth hierarchies, stylized grass, branch-ring geometry, stratified children, foliage normals, rooted wind. |
 | `threejs-procedural-architecture` | Massing and façade grammars, exposed-edge analysis, modules, material-slot compilation. |
 | `threejs-procedural-planets` | Spherical terrain, ridges, craters, biomes, procedural normals, altitude filtering. |
-| `threejs-spectral-ocean` | Validated FFT synthesis, spectral cascades, choppy derivatives, Jacobian foam, ocean shading. |
-| `threejs-water-optics` | Shared analytic waves/normals, heuristic refraction, fallback absorption, reflection, crest foam. |
+| `threejs-spectral-ocean` | Validated FFT synthesis, hybrid FFT/Gerstner water, stylized above/below ocean optics, spectral cascades, choppy derivatives, Jacobian foam, ocean shading. |
+| `threejs-water-optics` | Shared analytic waves/normals, bounded pool heightfields, object ripples, caustics, refraction, absorption, reflection. |
 | `threejs-atmosphere-aerial-perspective` | Shared Rayleigh/Mie atmosphere, sky, shell/post handoff, depth-based scattering. |
 | `threejs-volumetric-clouds` | Weather-shaped density, bounded raymarching, cloud lighting, history, cloud shadows. |
 | `threejs-raymarched-space-effects` | Curved-ray integration, black holes, accretion disks, wormholes, bounded quality. |
@@ -135,41 +135,6 @@ controls, pause/time controls, debug-mode routing, standalone launch, runtime
 metrics, and canvas capture. It is repository tooling and is not installed as
 an agent skill.
 
-Current accepted inspection surfaces:
-
-- [Atmosphere and aerial perspective](http://127.0.0.1:4173/?example=threejs-atmosphere-aerial-perspective%2Flut-aerial-perspective)
-  — precomputed sky radiance, sun transmittance, and depth-aware segment
-  scattering;
-- [Sculpted gallery frame](http://127.0.0.1:4173/?example=threejs-procedural-geometry%2Fsculpted-gallery-frame)
-  — profile-swept mesh, authored frame PBR, grazing lights, shadows, and
-  selective bloom;
-- [Ash growth system](http://127.0.0.1:4173/?example=threejs-procedural-vegetation%2Fstructured-ash-growth)
-  — species-specific hierarchy, branch geometry, foliage, wind, and meadow;
-- [Curved-ray accretion volume](http://127.0.0.1:4173/?example=threejs-raymarched-space-effects%2Fcurved-ray-accretion-volume)
-  — bounded ray steering, accretion density, transmittance, and bent
-  environment lookup;
-- [Spectral cascade ocean](http://127.0.0.1:4173/?example=threejs-spectral-ocean%2Fspectral-cascade-ocean)
-  — directional spectra, staged inverse FFT, choppy displacement, and
-  persistent Jacobian foam;
-- [Procedural planet surface](http://127.0.0.1:4173/?example=threejs-procedural-planets%2Fprocedural-planet-surface)
-  — coupled displacement, geological fields, biome masks, water, and
-  altitude-filtered material detail;
-- [Authored financial tower](http://127.0.0.1:4173/?example=threejs-procedural-architecture%2Fauthored-financial-tower)
-  — semantic massing, façade grammar, grouped mesh emission, and cached
-  clipmap shadows;
-- [Analytic wave optics](http://127.0.0.1:4173/?example=threejs-water-optics%2Fanalytic-wave-optics)
-  — shared displaced waves and normals, filtered microstructure, Fresnel,
-  refraction, absorption, and crest response;
-- [Weather volume clouds](http://127.0.0.1:4173/?example=threejs-volumetric-clouds%2Fweather-volume-clouds)
-  — packed weather channels, profile-shaped density, bounded integration,
-  directional lighting, and temporal reconstruction;
-- [Reentry plasma](http://127.0.0.1:4173/?example=threejs-procedural-vfx%2Freentry-plasma)
-  — closed layered wake shells, flow deformation, advected filaments, and
-  additive thermal emission;
-- [Touch-history frost](http://127.0.0.1:4173/?example=threejs-temporal-surfaces%2Ftouch-history-frost)
-  — persistent interaction history, static crystalline fields, reduced blur,
-  and two-scale refraction.
-
 Generate deterministic captures and a contact sheet:
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "threejs-awesome-graphics-agent-skills",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Expert agent skills for creating exceptional Three.js graphics.",
   "license": "MIT",
   "author": "Scott",
@@ -31,6 +31,9 @@
     "bin/",
     "skills/",
     "LICENSE",
+    "source_materials/THIRD_PARTY_NOTICES.md",
+    "source_materials/trace-manifest.json",
+    "!source_materials/README.md",
     "README.md"
   ],
   "engines": {
@@ -41,7 +44,7 @@
   },
   "scripts": {
     "validate": "node scripts/validate-pack.mjs",
-    "test": "npm run validate && npm run test:routing && npm run test:references && npm run test:installer && npm run test:gallery",
+    "test": "npm run validate && npm run test:routing && npm run test:references && npm run test:installer && npm run test:assets && npm run test:gallery",
     "dev:examples": "node dev/example-gallery/server.mjs --open",
     "dev:examples:no-open": "node dev/example-gallery/server.mjs",
     "dev:examples:fixture": "node dev/example-gallery/server.mjs --open --include-fixtures",
@@ -49,6 +52,7 @@
     "test:references": "node scripts/test-reference-examples.mjs",
     "test:routing": "node scripts/test-agent-routing.mjs",
     "test:installer": "node scripts/test-installer.mjs",
+    "test:assets": "node scripts/test-example-asset-origins.mjs",
     "test:gallery": "node scripts/test-example-gallery.mjs",
     "check:freshness": "node scripts/check-three-freshness.mjs",
     "test:all": "npm test && npm run check:freshness",

package/skills/threejs-procedural-materials/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: threejs-procedural-materials
-description: Author production procedural materials in Three.js. Use for atlas filtering and specular AA, planet-space material fields, terrain wetness, per-instance dissolve, authored PBR identities, derivative normals, and custom direct-light shadow modulation.
+description: Author production procedural materials in Three.js. Use for atlas filtering and specular AA, planet-space material fields, terrain wetness, lava and hot emissive procedural surfaces, raymarched material fields, per-instance dissolve, authored PBR identities, derivative normals, and custom direct-light shadow modulation.
 ---
 
 # Procedural Materials
@@ -38,6 +38,11 @@ Read the
 for coupled reflection, refraction, absorption, filtered microstructure,
 resolved crest response, and their diagnostic channels.
 
+Read the
+[lava flow surface material](examples/lava-flow-surface/lava-surface.js)
+for raymarched procedural height fields whose normals, rock/lava identity,
+emission, glow, embers, fog, and grain are coupled to one material cause stack.
+
 ## Required controls
 
 - real or perceptual texture scale;
@@ -47,6 +52,8 @@ resolved crest response, and their diagnostic channels.
 - distance/derivative filtering;
 - specular antialiasing;
 - channel and mask debug modes.
+- emissive-material debug modes when the material owns glow or volumetric
+  accumulation.
 
 ## Failure conditions
 

package/skills/threejs-procedural-materials/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Three.js Procedural Materials"
-  short_description: "Author coherent filtered procedural PBR surfaces"
-  default_prompt: "Use $threejs-procedural-materials to build a causal, multi-channel PBR surface with shared fields, derivative filtering, stable normals, and explicit channel diagnostics."
+  short_description: "Author coherent procedural PBR and emissive surfaces"
+  default_prompt: "Use $threejs-procedural-materials to build a causal procedural surface, including PBR or lava-like emissive materials, with shared fields, derivative normals, filtering, and explicit diagnostics."

package/skills/threejs-procedural-materials/examples/lava-flow-surface/lava-surface.js

@@ -0,0 +1,305 @@
+import * as THREE from "three";
+
+export const lavaFlowDebugModes = new Map([
+  ["final", 0],
+  ["height", 1],
+  ["normals", 2],
+  ["emission", 3],
+]);
+
+export function createLavaFlowMaterial({
+  cameraSpeed = 0.1,
+  flowSpeed = 0.1,
+  ridgeFrequency = 0.0,
+  pulseSpeed = 0.05,
+  amplitude = 0.4,
+  octaves = 7,
+  emberCount = 80,
+  filmNoise = 0.015,
+} = {}) {
+  return new THREE.ShaderMaterial({
+    uniforms: {
+      uTime: { value: 0 },
+      uResolution: { value: new THREE.Vector2(1, 1) },
+      uCameraPosition: { value: new THREE.Vector3(0, 0.2, 0) },
+      uCameraRight: { value: new THREE.Vector3(1, 0, 0) },
+      uCameraUp: { value: new THREE.Vector3(0, 1, 0) },
+      uCameraForward: { value: new THREE.Vector3(0, -0.35, 1).normalize() },
+      uVerticalTan: { value: Math.tan(THREE.MathUtils.degToRad(54) * 0.5) },
+      uDebugMode: { value: 0 },
+      uCameraSpeed: { value: cameraSpeed },
+      uFlowSpeed: { value: flowSpeed },
+      uRidgeFrequency: { value: ridgeFrequency },
+      uPulseSpeed: { value: pulseSpeed },
+      uAmplitude: { value: amplitude },
+      uOctaves: { value: octaves },
+      uEmberCount: { value: emberCount },
+      uFilmNoise: { value: filmNoise },
+      uLavaHot: { value: new THREE.Color(0xff1402) },
+      uLavaCool: { value: new THREE.Color(0xb20000) },
+      uEmberColor: { value: new THREE.Color(0xff5511) },
+    },
+    depthTest: false,
+    depthWrite: false,
+    vertexShader: `
+      varying vec2 vUv;
+
+      void main() {
+        vUv = uv;
+        gl_Position = vec4(position.xy, 0.0, 1.0);
+      }
+    `,
+    fragmentShader: `
+      precision highp float;
+
+      uniform float uTime;
+      uniform vec2 uResolution;
+      uniform vec3 uCameraPosition;
+      uniform vec3 uCameraRight;
+      uniform vec3 uCameraUp;
+      uniform vec3 uCameraForward;
+      uniform float uVerticalTan;
+      uniform int uDebugMode;
+      uniform float uCameraSpeed;
+      uniform float uFlowSpeed;
+      uniform float uRidgeFrequency;
+      uniform float uPulseSpeed;
+      uniform float uAmplitude;
+      uniform float uOctaves;
+      uniform float uEmberCount;
+      uniform float uFilmNoise;
+      uniform vec3 uLavaHot;
+      uniform vec3 uLavaCool;
+      uniform vec3 uEmberColor;
+      varying vec2 vUv;
+
+      float hash21(vec2 p) {
+        vec3 p3 = fract(vec3(p.xyx) * vec3(0.1031, 0.1030, 0.0973));
+        p3 += dot(p3, p3.yzx + 33.33);
+        return fract((p3.x + p3.y) * p3.z);
+      }
+
+      vec3 hash31(float p) {
+        vec3 p3 = fract(vec3(p) * vec3(0.1031, 0.1030, 0.0973));
+        p3 += dot(p3, p3.yzx + 33.33);
+        return fract((p3.xxy + p3.yzz) * p3.zyx);
+      }
+
+      float valueNoise(vec2 p) {
+        vec2 i = floor(p);
+        vec2 f = fract(p);
+        vec2 u = f * f * (3.0 - 2.0 * f);
+        return mix(
+          mix(hash21(i), hash21(i + vec2(1.0, 0.0)), u.x),
+          mix(hash21(i + vec2(0.0, 1.0)), hash21(i + vec2(1.0)), u.x),
+          u.y
+        );
+      }
+
+      float ridgeNoise(vec2 p, float octaveLimit) {
+        float h = 0.0;
+        float amp = 0.58;
+        mat2 rotation = mat2(0.8, -0.6, 0.6, 0.8);
+        for (int i = 0; i < 10; i++) {
+          if (float(i) >= octaveLimit) break;
+          float n = valueNoise(p);
+          h += amp * (1.0 - abs(n * 2.0 - 1.0));
+          p = rotation * p * 2.03;
+          amp *= 0.52;
+        }
+        return h;
+      }
+
+      float fbmHeight(vec2 p, float octaveLimit) {
+        float h = 0.0;
+        float amp = 0.8;
+        mat2 rotation = mat2(0.8, -0.6, 0.6, 0.8);
+        for (int i = 0; i < 10; i++) {
+          if (float(i) >= octaveLimit) break;
+          h += amp * valueNoise(p);
+          p = rotation * p * 2.1;
+          amp *= 0.5;
+        }
+        return h;
+      }
+
+      vec2 advectedDomain(vec2 p) {
+        p += vec2(1.0, 1.5) * uTime * uFlowSpeed;
+        vec2 curl = vec2(
+          sin(p.y * uRidgeFrequency + uTime * 0.42),
+          cos(p.x * uRidgeFrequency + uTime * 0.31)
+        ) * 0.2;
+        return p + curl;
+      }
+
+      float terrainHeight(vec2 p) {
+        float pulse = uAmplitude + sin(uTime * uPulseSpeed) * 0.06;
+        vec2 domain = advectedDomain(p);
+        float h = fbmHeight(domain, uOctaves);
+        return -0.9 + h * pulse;
+      }
+
+      float mapSurface(vec3 p) {
+        return (p.y - terrainHeight(p.xz)) * 0.52;
+      }
+
+      vec3 surfaceNormal(vec3 p) {
+        vec2 e = vec2(0.012, 0.0);
+        return normalize(vec3(
+          mapSurface(p + e.xyy) - mapSurface(p - e.xyy),
+          mapSurface(p + e.yxy) - mapSurface(p - e.yxy),
+          mapSurface(p + e.yyx) - mapSurface(p - e.yyx)
+        ));
+      }
+
+      float lavaMask(vec3 p) {
+        return clamp(1.0 - smoothstep(-0.7, -0.3, p.y), 0.0, 1.0);
+      }
+
+      float emberField(vec3 ro, vec3 rd, float surfaceT) {
+        float accum = 0.0;
+        for (float i = 0.0; i < 150.0; i++) {
+          if (i >= uEmberCount) break;
+          vec3 seed = hash31(i + 17.13);
+          float speed = 0.08 + seed.x * 0.13;
+          float life = fract(uTime * speed + seed.y);
+          vec3 ember = vec3(
+            (seed.x - 0.5) * 6.2,
+            mix(-0.86 + seed.z * 0.24, 0.85 + seed.x, pow(life, 1.35)),
+            ro.z + (seed.y - 0.5) * 5.2 + 3.2
+          );
+          float drift = uTime * (0.8 + seed.x * 0.45);
+          ember.x += (sin(drift * 2.1 + seed.z * 10.0) * 0.34 +
+            cos(drift * 4.7 + seed.y * 5.0) * 0.11) * life;
+          ember.z += (cos(drift * 2.4 + seed.x * 8.0) * 0.32 +
+            sin(drift * 5.2 + seed.z * 6.0) * 0.1) * life;
+
+          vec3 toEmber = ember - ro;
+          float projected = dot(toEmber, rd);
+          if (projected <= 0.0 || projected >= surfaceT) continue;
+          float distanceToRay = length(ro + rd * projected - ember);
+          float core = smoothstep(0.017, 0.001, distanceToRay);
+          float halo = 0.0000025 / (distanceToRay * distanceToRay + 0.0000015);
+          float fade =
+            smoothstep(0.0, 0.12, life) *
+            smoothstep(1.0, 0.68, life);
+          accum += (core * 1.1 + halo) * fade * (0.45 + seed.z * 0.7);
+        }
+        return accum;
+      }
+
+      void main() {
+        vec2 uv = (gl_FragCoord.xy - 0.5 * uResolution.xy) / uResolution.y;
+        vec3 ro = uCameraPosition + uCameraForward * uTime * uCameraSpeed;
+        vec3 rd = normalize(
+          uCameraForward +
+          uCameraRight * uv.x * 2.0 * uVerticalTan +
+          uCameraUp * uv.y * 2.0 * uVerticalTan
+        );
+
+        float t = 0.0;
+        float maxDistance = 15.0;
+        float glow = 0.0;
+        vec3 p = ro;
+        for (int i = 0; i < 84; i++) {
+          p = ro + rd * t;
+          float d = mapSurface(p);
+          if (d < 0.004 || t > maxDistance) break;
+          t += d;
+          float heat = smoothstep(-0.18, -0.86, p.y);
+          glow += exp(-d * 6.2) * heat * 0.055;
+        }
+
+        float horizonBand = exp(-abs(uv.y - 0.02) * 7.0);
+        vec3 background = mix(
+          vec3(0.00005, 0.00002, 0.00008),
+          vec3(0.16, 0.028, 0.015),
+          horizonBand
+        );
+        vec3 color = background;
+        float emissionMask = 0.0;
+        vec3 normal = vec3(0.0, 1.0, 0.0);
+        if (t < maxDistance) {
+          normal = surfaceNormal(p);
+          vec3 lightDirection = normalize(vec3(0.42, 0.92, -0.18));
+          float diffuse = max(dot(normal, lightDirection), 0.0);
+          float specular = pow(max(dot(reflect(-lightDirection, normal), -rd), 0.0), 12.0);
+          float ash = ridgeNoise(p.xz * 0.9 + vec2(3.0, -8.0), 4.0);
+          vec3 rock = mix(vec3(0.028, 0.018, 0.018), vec3(0.12, 0.09, 0.10), ash) *
+            (0.24 + diffuse * 0.62) +
+            vec3(0.12, 0.10, 0.12) * specular;
+          emissionMask = lavaMask(p);
+          float rockMask = smoothstep(-0.7, -0.3, p.y);
+          vec3 lava = mix(uLavaHot * 1.7, uLavaCool, smoothstep(-0.9, -0.6, p.y));
+          color = mix(lava, rock, rockMask);
+        }
+
+        float embers = emberField(ro, rd, min(t, maxDistance));
+        color += vec3(1.05, 0.11, 0.025) * glow;
+        color += uEmberColor * embers * 1.85;
+
+        float distanceFog = 1.0 - exp(-0.04 * min(t, maxDistance) * min(t, maxDistance));
+        float lowMist = t < maxDistance ? smoothstep(-0.25, -1.05, p.y) * 0.22 : 0.0;
+        vec3 fogColor = mix(
+          vec3(0.005, 0.002, 0.01),
+          vec3(0.44, 0.055, 0.02),
+          horizonBand
+        );
+        color = mix(color, fogColor, clamp(distanceFog + lowMist, 0.0, 0.82));
+
+        if (uDebugMode == 1) {
+          float heightValue = t < maxDistance ? clamp((p.y + 1.0) * 0.72, 0.0, 1.0) : 0.0;
+          color = mix(vec3(0.02, 0.0, 0.04), vec3(1.0, 0.18, 0.02), heightValue);
+        } else if (uDebugMode == 2) {
+          color = normal * 0.5 + 0.5;
+        } else if (uDebugMode == 3) {
+          color = vec3(glow * 1.7, emissionMask, embers * 0.08);
+        }
+
+        color *= 1.0 - 0.42 * length(uv);
+        color = pow(max(color, 0.0), vec3(0.4545));
+        float grain = hash21(gl_FragCoord.xy + vec2(fract(uTime * 0.123), fract(uTime * 0.321)) * 997.0);
+        color += (grain - 0.5) * uFilmNoise;
+        gl_FragColor = vec4(color, 1.0);
+      }
+    `,
+  });
+}
+
+export function createLavaFlowSurface(options = {}) {
+  const surface = new THREE.Mesh(
+    new THREE.PlaneGeometry(2, 2),
+    createLavaFlowMaterial(options),
+  );
+  surface.frustumCulled = false;
+  return surface;
+}
+
+const cameraForward = new THREE.Vector3();
+const cameraRight = new THREE.Vector3();
+const cameraUp = new THREE.Vector3();
+
+export function updateLavaFlowMaterial(material, {
+  elapsed,
+  width,
+  height,
+  camera,
+  debugMode = "final",
+}) {
+  material.uniforms.uTime.value = elapsed;
+  material.uniforms.uResolution.value.set(width, height);
+  material.uniforms.uDebugMode.value =
+    lavaFlowDebugModes.get(debugMode) ?? 0;
+  if (camera) {
+    camera.getWorldDirection(cameraForward);
+    const elements = camera.matrixWorld.elements;
+    cameraRight.set(elements[0], elements[1], elements[2]).normalize();
+    cameraUp.set(elements[4], elements[5], elements[6]).normalize();
+    material.uniforms.uCameraPosition.value.copy(camera.position);
+    material.uniforms.uCameraRight.value.copy(cameraRight);
+    material.uniforms.uCameraUp.value.copy(cameraUp);
+    material.uniforms.uCameraForward.value.copy(cameraForward);
+    material.uniforms.uVerticalTan.value =
+      Math.tan(THREE.MathUtils.degToRad(camera.fov ?? 54) * 0.5);
+  }
+}

package/skills/threejs-procedural-vegetation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: threejs-procedural-vegetation
-description: Generate authored procedural trees and vegetation in Three.js. Use for trunks, recursive branches, roots, canopies, leaf cards, species presets, growth forces, trellises, deterministic variation, and wind deformation.
+description: Generate authored procedural trees, grass, and vegetation in Three.js. Use for stylized meadow grass, trunks, recursive branches, roots, canopies, leaf cards, species presets, growth forces, trellises, deterministic variation, rooted blade/leaf wind, and wind deformation.
 ---
 
 # Procedural Vegetation
@@ -28,6 +28,13 @@ Read the [Ash Growth System implementation](examples/structured-ash-growth/tree-
 with its [authored preset](examples/structured-ash-growth/ash-preset.js) for a
 contract-accurate implementation and its diagnostic attributes.
 
+Read the
+[stylized meadow grass implementation](examples/stylized-meadow-grass/grass-system.js)
+for authored blade-cluster geometry with a procedural fallback, image-driven
+path masking, per-instance origin/facing attributes, circular-arc rooted wind,
+gust fronts, tip flutter, color clumps, macro variation, translucency, and rim
+diagnostics.
+
 ## Visual failure conditions
 
 - branches form visible helices;
@@ -43,4 +50,4 @@ contract-accurate implementation and its diagnostic attributes.
 
 Use `$threejs-procedural-geometry` for generic branch-ring emission without a
 growth model. This skill owns species tables, topology, child placement,
-foliage, roots, and hierarchical wind.
+foliage, grass fields, roots, and hierarchical/rooted wind.

package/skills/threejs-procedural-vegetation/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Three.js Procedural Vegetation"
-  short_description: "Generate trees, foliage, and organic growth"
-  default_prompt: "Use $threejs-procedural-vegetation to build this plant as a deterministic growth hierarchy."
+  short_description: "Generate trees, grass, foliage, and organic growth"
+  default_prompt: "Use $threejs-procedural-vegetation to build deterministic plant growth, authored foliage, or rooted stylized grass with coherent wind and diagnostics."