@genex-ai/cli-demo 0.6.0 → 0.6.2

package/templates/skills/genex-threejs-procedural-materials/references/material-systems.md

@@ -1,31 +1,198 @@
-# Material Systems
+# Procedural PBR material systems
 
-Use this reference when building procedural materials for Genex games.
+Use this reference for atlas filtering, shared shadow and light causes, planet-space material fields, wetness, per-instance dissolve, and authored physical-material identities.
 
-## PBR roles
+## Contents
 
-- Base color carries identity and broad variation.
-- Roughness controls highlight size and material age.
-- Metalness should usually be binary or near-binary by surface type.
-- Normals add shape detail but should not replace silhouette.
-- Emission should have a scene-relative intensity hierarchy.
+- atlas-based renderer block material
+- Atlas and minification response
+- Shared shadow/light causes
+- planet-space implementation planetary material
+- pooled VFX system terrain and debris
+- selective gallery pipeline authored PBR identities
+- Selection rules and limitations
+- Diagnostics
 
-## Filtering
 
-- Fade micro normals with distance.
-- Use mip-aware texture sampling for generated atlases.
-- Reduce specular aliasing on tiny bright details.
-- Avoid unbounded high-frequency noise in motion.
+## atlas-based renderer block material
 
-## Common masks
+The block material is a complete custom shader whose inputs include:
 
-- Wetness: driven by water height, splash, or exposed low points.
-- Wear: driven by edges, contact, pathing, or gameplay interaction.
-- Heat: driven by event timelines and cooling curves.
-- Dissolve: driven by a stable object-space or authored field.
-- Biome: driven by altitude, slope, latitude, moisture, or gameplay zones.
+```text
+atlas albedo and optional normal
+per-vertex AO/skylight/tint color
+sun direction/color
+four custom shadow cascades
+projected procedural cloud shadow
+environment cube
+roughness/metalness
+daylight and starlight factors
+```
 
-## Debug views
+Its useful material mechanisms are:
 
-Provide direct views of base color, roughness, normals, mask values, emission,
-and final lit material before post-processing.
+1. world position and view-space depth remain available for cascade choice;
+2. world-space shadow texel width scales bias and filter radius;
+3. cloud shadow projects a receiver point to a cloud plane along sun direction;
+4. normal derivatives increase effective roughness;
+5. atlas sampling clamps to the current tile interior;
+6. anisotropic minification chooses a major-axis multi-tap filter.
+
+Specular antialiasing:
+
+```text
+variance =
+  max(dot(dFdx(N), dFdx(N)),
+      dot(dFdy(N), dFdy(N)))
+
+filteredRoughness =
+  clamp(sqrt(roughness^2 + variance), 0, 1)
+```
+
+This is a practical filtering mechanism. It should still be compared against the
+renderer’s current physical-material and normal-filtering behavior before
+replacing built-in shading.
+
+## Atlas and minification response
+
+For an atlas with `atlasSize` tiles across and `tileSize` texels per tile:
+
+```text
+tile width = 1 / atlasSize
+horizontal inset = 0.5 / (atlasSize * tileSize)
+vertical inset = 0.5 / tileSize
+```
+
+Estimate the `dFdx/dFdy` footprint in texels. When minification grows, blend
+away from the base sample. If anisotropy exceeds `2`, sample `7` or `9` taps
+along the major axis.
+
+This avoids adjacent-tile bleed for direct taps, but shader clamping cannot fix
+atlas mip levels that were generated without duplicated tile borders. Require
+offline mip-safe padding when adopting this mechanism.
+
+## Shared shadow/light causes
+
+atlas-based renderer’s cloud shadow uses the same conceptual field as its visible cloud
+layer:
+
+```text
+project receiver to cloud altitude along sun direction
+advect by shared wind and time scale
+evaluate the same five-octave cloud field
+apply coverage and density shaping
+attenuate direct sunlight
+```
+
+The material does not darken emission or all ambient response with this term.
+Keep projected environmental shadows attached to direct-light ownership.
+
+## planet-space implementation planetary material
+
+planet-space implementation’s solid planets preserve an undeformed radial attribute and use it for
+all geological sampling. Camera-altitude weights reduce high-frequency bump
+and optical detail.
+
+For gas and ice giants, seam-free longitude is represented as:
+
+```text
+longitude = atan(z, x)
+longitude circle = (cos(longitude + advection), sin(longitude + advection))
+coordinate = (circle.x, circle.y, latitude01)
+```
+
+Latitude bands, seeded warp, turbulence, and storm masks share this coordinate.
+Roughness responds to the same final mask. Limb haze and wrapped diffuse
+lighting are added separately.
+
+For solid bodies, procedural bump normal is derived from screen derivatives of
+the height node and view position. This keeps the renderer’s material lighting
+path while changing only the normal input.
+
+The known debt is geometry/material field mismatch; see the planet and field
+references. Do not infer that close bump can substitute for silhouette parity.
+
+## pooled VFX system terrain and debris
+
+Terrain identity:
+
+```text
+grassness = smoothstep(0.01, 1, normalWorld.y^1.6)
+color = mix(shared-noise soil, shared-noise grass, grassness)
+roughness = blend(soil response, grass response, grassness) - wetness
+metalness = 0.2
+```
+
+Wetness comes from world height near the water plane and the broad noise field.
+It changes roughness and color together.
+
+Debris uses per-instance `isOrange` and `removalTimeSeconds`. Geometry-space
+noise controls discard as lifetime expires. Its color is reinforced at the rim
+through Fresnel and receives a small environment term of `0.05`.
+
+The reusable pattern is per-instance material state, not one cloned material
+per object.
+
+## selective gallery pipeline authored PBR identities
+
+The gallery defines distinct frame surfaces with real texture and response
+bundles:
+
+| Surface | Roughness | Metalness | Clearcoat | Clearcoat roughness | Bump |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| walnut | 0.42 | 0.04 | 0.62 | 0.28 | 0.022 |
+| antique gold | 0.24 | 0.78 | 0.24 | 0.20 | 0.012 |
+| ebony | 0.40 | 0.03 | 0.70 | 0.24 | 0.018 |
+
+Wall plaster stays near roughness `0.94–0.96`, floor `0.92`, and mat board
+`0.92`. These ranges preserve material separation before bloom.
+
+Chandelier bloom meshes intentionally use `MeshBasicMaterial`, with bulb and
+filament materials marked `toneMapped = false`. That is contribution ownership
+for a stylized light source, not a physically based metal recipe.
+
+## Selection rules and limitations
+
+Use the material mechanisms according to representation:
+
+```text
+atlas voxel surface -> atlas-based renderer filtering and custom shadow hooks
+planet surface -> planet-space implementation radial fields and altitude filtering
+terrain/wetness -> pooled VFX system world-height causal blend
+authored luxury material -> selective gallery pipeline response bundle
+pooled effect debris -> pooled VFX system per-instance attributes
+```
+
+Do not combine every mechanism into one universal material.
+
+Exact node/material extension hooks are version-sensitive. Inspect the
+installed renderer before porting atlas-based renderer's full custom shader or adapting
+planet-space implementation's node-material normal and emissive inputs.
+
+Observed limits:
+
+- atlas-based renderer replaces the full physical shader, increasing maintenance and making
+  backend migration harder.
+- Its custom lighting must be checked for energy consistency and environment
+  parity.
+- selective gallery pipeline’s chandelier basic materials rely on selective bloom and are not a
+  substitute for lit metal in non-emissive views.
+- pooled VFX system uses undefined reversed-edge `smoothstep` in wetness expressions; write
+  portable equivalent logic.
+- planet-space implementation has approximate rather than exact geometry/material field parity.
+
+## Diagnostics
+
+Expose:
+
+```text
+atlas tile and sample footprint
+roughness before/after specular AA
+cloud shadow field
+shadow cascade and world texel size
+planet coordinate, altitude weights, and material masks
+terrain grassness and wetness
+debris instance attributes and dissolve threshold
+base frame material without post
+raw emissive contribution for bloom-only materials
+```

package/templates/skills/genex-threejs-procedural-planets/SKILL.md

@@ -5,26 +5,44 @@ description: Author procedural planets for Genex Three.js games. Use for spheric
 
 # Genex Three.js Procedural Planets
 
-Planets must hold up across extreme scale changes. Build shared terrain,
-material, atmosphere, and camera rules around one planet contract.
+Build a planet as a coupled field system evaluated on a unit direction. The same geological causes must drive geometry, color, roughness, normal, atmosphere handoff, and distance filtering.
 
-Read [references/planet-systems.md](references/planet-systems.md) for terrain
-fields, LOD, materials, and orbit-to-surface checks.
+## Required build order
 
-## Build order
+1. Establish planet-space direction, radius, sea level, and world-unit scale.
+2. Build macro silhouette fields before any surface material.
+3. Add named geological structures: continents, basins, ridges, craters, lava fields, or ice.
+4. Derive slope, cavity, altitude, latitude, exposure, and shoreline fields.
+5. Classify broad biomes from those causes.
+6. Derive displacement, color, roughness, and normal from the shared field bundle.
+7. Filter bands by represented mesh scale and camera altitude.
+8. Couple the material to atmosphere and lighting using the same planet transform.
 
-1. Define radius, gravity/up convention, playable altitude range, camera envelope,
-   and target quality tiers.
-2. Build low-frequency continent and elevation fields.
-3. Add ridges, craters, erosion bands, biome masks, and coastline rules.
-4. Derive normals, material masks, and gameplay zones from the same fields.
-5. Add atmosphere and clouds only after terrain readability is stable.
-6. Expose debug views for elevation, slope, biome, coast, normal, and LOD.
+Read [references/planet-systems.md](references/planet-systems.md) for terrain, biome, gas-giant, material, altitude-LOD, and atmosphere-handoff mechanisms, including a known CPU/GPU field-parity failure mode.
 
-## Rules
+## Non-negotiable constraints
 
-- Use planet-relative up vectors for cameras, actors, and placement.
-- Keep procedural detail stable between orbit and close approach.
-- Filter altitude detail by camera distance and surface scale.
-- Avoid unrelated noise layers that break geological cause.
-- Make spawn points, traversal zones, and hazards serializable by seed.
+- Domain-warp tangentially and renormalize; do not distort the sphere radially.
+- Craters need floor, wall, rim, and optional ejecta—not dark circles.
+- Continents and biomes must be region fields, not isolated threshold bubbles.
+- Geometry displacement and shader normals must describe the same height function.
+- Close detail may disappear with altitude; the macro silhouette may not.
+- Expose individual field views and a displacement exaggeration mode.
+
+## Completion test
+
+The body must remain intentional in:
+
+- unlit silhouette;
+- flat albedo with no atmosphere;
+- grazing directional light;
+- orbit view;
+- close approach;
+- biome-mask and normal-only views;
+- at least three seeds without losing the chosen planetary identity.
+
+## Routing boundary
+
+Use `$genex-threejs-procedural-fields` for a reusable field bundle without a complete
+body, and `$genex-threejs-atmosphere-aerial-perspective` for scattering independent
+of planet generation. This skill owns the coupled planetary surface.