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

package/.codex-plugin/plugin.json

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

package/README.md

@@ -32,13 +32,14 @@ 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 and GPU-computed 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-precipitation-surfaces` | Falling snow and rain coupled to accumulation, snow caps, wet puddles, ripple normals, splashes, and shared weather envelopes. |
 | `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 +136,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,8 +1,8 @@
 {
   "name": "threejs-awesome-graphics-agent-skills",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Expert agent skills for creating exceptional Three.js graphics.",
-  "license": "MIT",
+  "license": "MIT AND GPL-3.0-only",
   "author": "Scott",
   "keywords": [
     "agent-skills",
@@ -31,6 +31,10 @@
     "bin/",
     "skills/",
     "LICENSE",
+    "source_materials/GPL-3.0.txt",
+    "source_materials/THIRD_PARTY_NOTICES.md",
+    "source_materials/trace-manifest.json",
+    "!source_materials/README.md",
     "README.md"
   ],
   "engines": {
@@ -41,7 +45,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",
     "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,7 +53,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:gallery": "node scripts/test-example-gallery.mjs",
+    "test:assets": "node scripts/test-example-asset-origins.mjs",
     "check:freshness": "node scripts/check-three-freshness.mjs",
     "test:all": "npm test && npm run check:freshness",
     "prepack": "npm run test:all",

package/skills/threejs-precipitation-surfaces/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: threejs-precipitation-surfaces
+description: Build coupled precipitation and affected surfaces in Three.js. Use for falling snow, snow accumulation, model snow caps, wet asphalt puddles, procedural ripple normals, splash flipbooks, rain streaks, shared weather envelopes, and surface wetness or coverage transitions.
+---
+
+# Precipitation Surfaces
+
+Treat weather as a coupled event, particle, and surface-response system. Do not
+add rain or snow particles that are visually disconnected from the ground.
+
+## Build order
+
+```text
+weather envelope
+  -> falling precipitation volume
+  -> world/object surface mask
+  -> displaced or optical surface response
+  -> impact residue and splashes
+  -> shared lighting/post presentation
+```
+
+Read [references/precipitation-surface-systems.md](references/precipitation-surface-systems.md)
+for snow accumulation, object capping, wrapped precipitation volumes, wet
+puddle masks, procedural ripple normals, splash placement, debug outputs, and
+licensing boundaries.
+
+Read the
+[snow accumulation implementation](examples/snow-accumulation/snow-system.js)
+for camera-wrapped snowfall, shared wind/time uniforms, world-space snow masks,
+single-source snow height and normals, model snow capping, and optional ice
+surface composition.
+
+Read the
+[wet puddle rain implementation](examples/wet-puddle-rain/rain-puddle-system.js)
+for rain-progress wetness, asphalt puddle masks, procedural ripple normals,
+instanced rain streaks, upward-surface splash sampling, and flipbook splashes.
+This example includes GPL-licensed source material;
+preserve its license boundary when copying or publishing it.
+
+## Required controls
+
+- precipitation density and speed;
+- wind direction and strength;
+- shared weather progress or coverage;
+- wetness, snow, or puddle mask threshold and softness;
+- ripple or drift normal strength;
+- surface roughness response;
+- particle/splash opacity;
+- debug modes for masks, normals, particles, and event progress.
+
+## Failure conditions
+
+- falling precipitation ignores the wind or timing used by surface response;
+- snow height and snow normals come from different fields;
+- model snow sticks to vertical faces without an upward-facing filter;
+- puddles only lower roughness without a mask, normal response, or ripples;
+- splashes appear on downward or hidden faces;
+- rain streaks allocate per drop or fail to wrap around the camera;
+- temporal wetness is faked with unrelated time noise;
+- the license boundary for GPL-derived rain code is removed or obscured.
+
+## Routing boundary
+
+Use `$threejs-water-optics` for bounded pool simulation, caustics, Fresnel,
+refraction, and Beer-Lambert water volumes. Use `$threejs-procedural-vfx` for
+general sparks, plasma, trails, and non-weather particles. Use
+`$threejs-temporal-surfaces` for screen-space touch history or frost clearing.
+This skill owns precipitation events and the surfaces they visibly alter.

package/skills/threejs-precipitation-surfaces/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Three.js Precipitation Surfaces"
+  short_description: "Coupled rain, snow, puddle, and wetness effects"
+  default_prompt: "Use $threejs-precipitation-surfaces when rain or snow must affect visible surfaces: falling precipitation, ground accumulation, wet puddle masks, ripple normals, splash flipbooks, shared wind/time envelopes, and material roughness or coverage transitions."

package/skills/threejs-precipitation-surfaces/assets/wet-puddle-rain/THIRD_PARTY_LICENSES.md

@@ -0,0 +1,10 @@
+# Third-Party Licenses
+
+This folder contains assets copied from a GPL-3.0 rain puddle reference
+implementation. The copied rain puddle implementation in
+`skills/threejs-precipitation-surfaces/examples/wet-puddle-rain/` preserves that
+GPL-3.0 boundary.
+
+See `source_materials/GPL-3.0.txt` and
+`source_materials/THIRD_PARTY_NOTICES.md` in the package for source attribution
+and license details.