@genex-ai/cli-demo 0.6.0 → 0.6.2

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

@@ -1,37 +1,314 @@
-# Vegetation Systems
+# Structured Ash growth system
 
-Use this reference for trees, plants, and grass in Genex games.
+Use this reference when the target is a natural deciduous Ash with a stable species identity. Preserve the species table, continuation model, branch geometry, foliage, rooted wind, and composition contracts before tuning.
 
-## Species definition
+## Contents
 
-Declare:
+1. Species table
+2. Continuation and child placement
+3. Branch growth and geometry
+4. Leaves and wind
+5. Bark, meadow, and scene composition
+6. Budgets, divergences, and diagnostics
 
-- height and width range;
-- trunk taper and bend;
-- branch count and angles;
-- canopy shape;
-- leaf size and clustering;
-- bark and leaf material identity;
-- wind response;
-- gameplay function such as cover, obstacle, collectible, or landmark.
+## 1. Preserve the exact species table before tuning
 
-## Branch hierarchy
+The Ash Medium species contract is:
 
-- Emit trunk first with a stable radius curve.
-- Spawn primary branches from height bands.
-- Spawn secondary branches from primary branch frames.
-- Align leaf clusters to branch direction and local light bias.
-- Keep branch rings oriented with a stable frame to avoid twisting.
+| Level | Length | Base radius factor | Sections | Radial segments | Child angle | Children | Child start | Gnarliness | Twist |
+| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| 0 trunk | 43.47 | 2.00 | 12 | 12 | — | 7 | — | 0.03 | 0.09 |
+| 1 primary | 27.14 | 0.63 | 8 | 6 | 48° | 4 | 0.23 | 0.25 | -0.07 |
+| 2 secondary | 9.51 | 0.76 | 6 | 4 | 75° | 3 | 0.33 | 0.20 | 0 |
+| 3 terminal | 4.60 | 0.70 | 4 | 3 | 60° | 0 | 0 | 0.09 | 0 |
 
-## Placement
+All levels use taper `0.7`. Growth force points up with strength `0.01`.
 
-- Use terrain slope, moisture, altitude, and gameplay zones as masks.
-- Leave readable paths and playable spaces.
-- Vary seed and scale without changing species identity.
+Leaves:
 
-## Wind
+```text
+type: ash
+count per terminal branch: 16
+start: 0
+angle: 55°
+double perpendicular cards
+size: 2.67
+size variance: ±0.72
+alpha test: 0.5
+rounded normals: enabled
+```
 
-- Drive wind from a shared vector field.
-- Use lower-frequency bend for trunk and branches.
-- Use higher-frequency flutter for leaves.
-- Keep wind amplitude within the silhouette promised by collision/proxy shapes.
+Do not replace this table with guessed “tree-like” ranges before the contract
+is reproduced. Species identity is encoded in the uneven angles, lengths,
+starts, and child counts.
+
+## 2. Match the branch continuation model
+
+The generator creates two types of descendants:
+
+1. stratified lateral children along the parent;
+2. one terminal continuation branch from the parent tip for every deciduous level until the final level.
+
+That continuation is essential to the sparse, irregular crown. A generator that creates only lateral children produces a candelabra or clipped crown.
+
+The terminal continuation inherits:
+
+```text
+origin = final parent section origin
+orientation = final parent section orientation
+radius = final parent section radius
+level = parent level + 1
+sections and radial segments = parent values
+length = next-level species length
+```
+
+The inherited section/segment counts differ from ordinary lateral children, which use the next level's table values.
+
+## 3. Match section evolution
+
+The implementation contains:
+
+```text
+sectionLength =
+  branchLength
+  / sectionCount
+  / (branchLevels - 1)
+```
+
+but guards the divisor with a comparison against the string `'Deciduous'`.
+The preset stores `'deciduous'`, so this build does **not** take that
+branch. Effective runtime behavior is:
+
+```text
+sectionLength = branchLength / sectionCount
+```
+
+For Ash Medium this doubles the height relative to the apparent intent. The
+complete build produces branch bounds reaching roughly `y=80.30` and leaf
+bounds reaching `y=83.69`. Preserve the actual runtime behavior.
+Do not infer behavior from one line without executing the complete growth path.
+
+At every section:
+
+1. emit an XZ ring through the current Euler orientation;
+2. store origin, orientation, and radius;
+3. advance along rotated local +Y;
+4. perturb Euler X/Z by seeded gnarliness;
+5. apply level twist around local Y;
+6. rotate the section toward world growth force.
+
+Gnarliness amplification:
+
+```text
+effectiveGnarliness =
+  max(1, 1 / sqrt(sectionRadius))
+  * levelGnarliness
+```
+
+The force angular step is:
+
+```text
+forceStrength / sectionRadius
+```
+
+clamped to the full angle between current local up and the target direction. Thin branches therefore respond more strongly than the trunk.
+
+## 4. Match taper and child radius semantics
+
+Deciduous taper:
+
+```text
+sectionRadius =
+  branchStartRadius
+  * (1 - levelTaper * sectionIndex / sectionCount)
+```
+
+The final section of the final level collapses to a near-zero radius.
+
+Lateral child radius is not simply the species radius:
+
+```text
+childRadius =
+  levelRadiusFactor
+  * interpolatedParentSectionRadius
+```
+
+This couples the child thickness to emergence height and parent taper.
+
+## 5. Match stratification and interpolation
+
+For both lateral children and leaves:
+
+```text
+along =
+  start
+  + (slotIndex + seededJitter)
+  * ((1 - start) / count)
+```
+
+Independently shuffle angular slot IDs with the same seeded RNG:
+
+```text
+azimuth =
+  2π
+  * (radialOffset + (permutedSlot + jitter[-0.5, 0.5]) / count)
+```
+
+Interpolate between adjacent stored sections:
+
+- origin: linear interpolation;
+- radius: linear interpolation;
+- orientation: interpolation starts from section B and slerps toward
+  section A by `alpha`, reversing the usual A→B expectation.
+
+Then compose:
+
+```text
+parent orientation
+  × azimuth around local Y
+  × emergence angle around local X
+```
+
+Do not derive child orientation from a newly constructed tangent frame; that changes the characteristic branch roll and twist.
+
+## 6. Match ring and bark UV construction
+
+Each section emits `radialSegments + 1` vertices by duplicating the first radial vertex at the seam.
+
+Choose one integer circumference wrap count for the entire branch:
+
+```text
+wrapsX = max(1, round(branchStartRadius * barkTextureScaleX))
+u = radialIndex / radialSegments * wrapsX
+v = sectionIndex is even ? 0 : 1
+```
+
+The texture's runtime Y repeat is `1 / barkTextureScaleY`.
+
+This is not a real-distance longitudinal UV. If adapting the visual exactly, retain the alternating ring V pattern. If improving it, record the change as an intentional divergence and re-evaluate bark scale across trunk and twigs.
+
+## 7. Match leaf placement, card geometry, and normals
+
+Leaves are emitted along every final-level branch, not in synthetic clusters at branch tips.
+
+Each leaf is a square card extending from local base `y=0` to tip `y=L`, with width `W`. The double-card mode emits a second card rotated 90° around local Y.
+
+Rounded vertex normal:
+
+```text
+normalize(cardNormal + (vertexPosition - leafOrigin))
+```
+
+Use the same unrotated card normal for both perpendicular cards before adding
+the vertex direction. Preserve that quirk when reproducing the contract. A
+corrected per-card normal is a legitimate extension but changes canopy
+lighting and must be documented.
+
+Use the bundled `ash.png` alpha silhouette. Replacing it with an ellipse or
+analytic lozenge changes crown porosity and edge frequency enough to invalidate
+visual comparison.
+
+## 8. Match material and wind behavior accurately
+
+The complete scene uses:
+
+- textured `MeshPhongMaterial` for bark;
+- double-sided alpha-tested `MeshPhongMaterial` for leaves;
+- Neutral tone mapping with exposure `2`;
+- PCF shadows;
+- fog color `0x94b9f8`, density `0.0015`;
+- a daylight sky gradient and directional sun.
+
+The wind shader deforms leaf vertices only:
+
+```text
+windPhase = simplex3(position / 70)
+wind =
+  0.5 * sin(t * 0.5 + phase)
+  + 0.3 * sin(2t * 0.5 + 1.3phase)
+  + 0.2 * sin(5t * 0.5 + 1.5phase)
+displacement = leafUvY * windStrength * wind
+```
+
+`leafUvY` roots the card base and moves the tip. The demonstrated branch
+geometry is static; do not describe this mechanism as hierarchy-weighted
+trunk/branch wind.
+
+If extending it with branch motion:
+
+1. keep the leaf-root weighting;
+2. add branch-level attributes separately;
+3. deform color and shadow geometry consistently;
+4. label the result as an extension to the contract.
+
+## 9. Match composition before judging the generator
+
+Present the tree in a complete environment:
+
+```text
+startup camera: (100, 20, 0)
+target: (0, 25, 0)
+horizontal camera constraint near the horizon
+foreground tree at origin
+100 background trees using radius = 175 + random * 500 (effective 175–675)
+procedural grass/dirt ground
+5,000 visible grass instances
+flowers and rocks
+blue atmospheric fog
+daylight sky and sun
+```
+
+The exact startup camera clips the leaf bound slightly because its
+upper vertical coverage is approximately `y=82.7` while the leaf maximum is
+approximately `y=83.69`. For a fixed 3:2 evaluation frame, move the camera
+along the same target ray to approximately `x=115`; do not alter the tree to
+solve a framing problem.
+
+A black-background isolated tree is not a valid quality test. It removes
+foliage edge contrast, atmospheric depth, ground contact, and scale cues.
+
+## 10. Required contract diagnostics
+
+Capture:
+
+```text
+final composition
+branch-level colors
+lateral children versus terminal continuations
+child longitudinal slot IDs
+child angular slot IDs
+leaf origins along final branches
+card normals versus rounded normals
+bark UV checker
+wind displacement magnitude
+foreground bounds and camera frustum
+```
+
+Report:
+
+```text
+branch jobs by level
+terminal continuations by level
+lateral children by level
+leaf cards
+vertices and triangles
+seed
+preset name
+intentional divergences from the growth contract
+```
+
+## 11. Numeric contract gate
+
+For the Ash Medium contract, assert:
+
+```text
+branch vertices: 6,639
+branch triangles: 9,120
+leaf vertices: 21,760
+leaf triangles: 10,880
+branch bounds max Y: approximately 80.2981
+leaf bounds max Y: approximately 83.6902
+```
+
+Matching only counts is insufficient; the earlier half-height implementation
+matched all counts while violating runtime section-length behavior.

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

@@ -5,27 +5,35 @@ description: Author procedural real-time VFX for Genex Three.js games. Use for p
 
 # Genex Three.js Procedural VFX
 
-VFX should make player actions legible. Build effects as timed systems with
-budgets, not as one-off bursts.
+Build effects from an event envelope, motion field, geometry representation, and shading response. Avoid independent particle emitters that happen to share a color.
 
-Read [references/vfx-systems.md](references/vfx-systems.md) for event timing,
-particles, trails, pooling, emission, and diagnostics.
+## Effect graph
 
-## Build order
+```text
+ship/event state
+  → effect-specific geometry or instance attributes
+  → flow-facing masks or analytic age
+  → material response
+  → pool/lifetime ownership
+  → HDR and bloom contribution
+```
 
-1. Define the event: cause, start, peak, decay, gameplay meaning, and interrupt
-   behavior.
-2. Split effect layers into core shape, particles, trails, light, distortion,
-   sound hooks, and decal/debris.
-3. Use seeded variation for repeatable runs.
-4. Pool high-count objects and dispose temporary resources.
-5. Keep emission intensities scene-relative.
-6. Expose debug controls for phase, layer toggles, counts, bounds, and overdraw.
+Read [references/vfx-systems.md](references/vfx-systems.md)
+for ship-conforming reentry shells, capsule wakes, dense instanced
+spark/debris pools, HDR hierarchy, and implementation limits.
 
 ## Rules
 
-- Do not let bloom carry the shape of the effect.
-- Keep impact timing aligned to gameplay state.
-- Bound particle counts and lifetimes.
-- Use additive blending deliberately and inspect overdraw.
-- Provide low-quality versions for dense combat or mobile browsers.
+- Every layer must have a role in silhouette, motion, illumination, or residue.
+- Use normalized lifetime curves instead of scattered time constants.
+- Derive secondary motion from the same flow or event direction.
+- Keep bloom as a response to HDR emission, not as the effect's only shape.
+- Pool instances and trails; do not allocate per burst.
+- Expose spawn, simulation, overdraw, and luminance debug views.
+- Include a non-bloom baseline that remains legible.
+
+## Routing boundary
+
+Use `$genex-threejs-temporal-surfaces` only for the screen-space
+frost/touch-history pipeline. Keep ship-space plasma, generated wakes, sparks,
+and pooled debris in this skill.

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

@@ -1,30 +1,218 @@
-# Procedural VFX
+# Layered procedural VFX systems
 
-Use this reference for action effects in Genex games.
+Use this reference for ship-conforming reentry plasma, generated wakes, instanced analytic sparks, dissolving debris, dense-swap pools, and scene-relative HDR contribution.
 
-## Event timeline
+## Contents
 
-- Anticipation: small cue before action when gameplay allows it.
-- Impact: strongest shape and brightness.
-- Decay: particles, trails, smoke, heat, or fragments.
-- Recovery: cleanup and return to readable scene state.
+- Reentry representation
+- Reentry shell shading
+- Wake construction
+- Instanced spark contract
+- Debris dissolve and pool ownership
+- HDR contribution
+- Observed limitations
+- Diagnostics
 
-## Layers
 
-- Shape layer: shockwave, shell, beam, ring, or volume.
-- Particle layer: sparks, embers, fragments, droplets, or dust.
-- Trail layer: motion history or projectile path.
-- Light layer: short-lived local light or emissive material.
-- Surface layer: decal, scorch, foam, or dissolve mask.
+## Reentry representation
 
-## Pooling
+planet-space implementation does not model reentry as one particle emitter. It composes:
 
-- Preallocate repeated particles or meshes.
-- Reuse materials and geometries.
-- Track active counts and peak counts.
-- Avoid per-frame allocation during dense events.
+```text
+ship-shaped front shell
+  + expanding capsule core wake
+  + larger low-opacity haze wake
+  + two asymmetric side shear lobes
+```
+
+The shell is a clone of the actual ship mesh, scaled by `1.005`. This is the
+key silhouette decision: plasma follows authored hull topology instead of a
+generic sphere or cone.
+
+The wake origin is found from sampled ship vertices. For the current local fall
+direction, select the support point with the greatest dot product. Build an
+orthonormal wake frame by projecting local up away from the fall direction,
+falling back to local right when nearly parallel.
+
+```text
+wake forward = normalized fall direction
+wake up = projected local up
+wake right = cross(up, forward)
+wake origin = hull support point along fall direction
+```
+
+## Reentry shell shading
+
+The shell mask uses actual flow-facing geometry:
+
+```text
+facing = saturate(dot(normalWorld, -fallDirectionWorld))
+facing mask = smoothstep(0.18, 0.96, facing)
+```
+
+Two world-space noise bands move along fall direction:
+
+```text
+coarse frequency = 3.6
+fine frequency = 11.2
+coarse/fine mix = 0.62 / 0.38
+fine filament exponent = 3.1
+flow speed basis = time * 5.4 + external flow * 0.08
+```
+
+The shell shader separates:
+
+- core heat from flow-facing area;
+- Fresnel envelope around silhouette;
+- a shock band requiring high facing, rim response, and filaments.
+
+Color hierarchy is explicit:
+
+```text
+hot core: orange -> near white
+ion envelope: magenta -> violet
+outer sheath: violet -> cyan
+shock: white -> blue
+```
+
+The final shell uses additive blending, no depth write, depth test on, double
+sided, and negative polygon offset. Treat the additive multiplier as part of
+the scene’s HDR calibration, not a portable physical unit.
+
+## Wake construction
+
+Each wake is a generated capsule-profile tube. Along normalized length `t`:
+
+```text
+z = -trailLength * t
+radial spread = 1 + t^1.24 * expansion
+axial spread = 1 + 0.1 * t
+profile turbulence = 1 + sin(theta * 3.3 + t * 8.7) * 0.1 * t
+```
+
+Dimensions relative to ship length:
+
+```text
+profile length = 0.74
+profile radius = 0.068
+trail length = 1.55
+
+core: 52 radial x 26 longitudinal, expansion 1.9
+haze: 40 x 20, radius 1.2x, length 1.05x, opacity 0.28
+lobes: 28 x 14, half profile, length 0.88x, opacity 0.34
+```
+
+Wake shading uses elliptical profile distance, a front gate, tail fade,
+coarse/fine longitudinal noise, Fresnel, and separate core/envelope/filament
+colors. The core and haze use different scales and speeds instead of one mesh
+with changed opacity.
+
+## Instanced spark contract
+
+pooled VFX system preallocates a sprite pool of `12000`. Every instance stores:
+
+```text
+startPosition vec3
+startVelocity vec3
+acceleration vec3
+spawnTimeSeconds float
+```
+
+Lifetime is `1.3 s`; velocity decay rate is `16`. Spark size falls linearly to
+zero:
+
+```text
+scale = max((1.3 - age) * 0.4 / 1.3, 0)
+```
+
+The fragment is a circular sprite with radius `0.4`. HDR color interpolates
+from `(1, 0.5, 0) * 80` toward dark red. Spawn adds random X/Z velocity in
+`[-2, 2]`.
+
+The pool is fixed-capacity and material attributes are per instance. No entity
+owns an individual mesh.
+
+## Debris dissolve and pool ownership
+
+Debris spheres use:
+
+```text
+radius = 0.45
+lifetime = random 2 -> 4 seconds
+mass = 0.1
+friction = 0.4
+restitution = 0.8
+gravity scale = 1.2
+```
+
+Per-instance material data:
+
+```text
+isOrange
+removalTimeSeconds
+```
+
+Geometry-space noise creates a spatial dissolve against remaining lifetime.
+The material also adds a Fresnel-shaped color response, a directional fake-AO
+tint, and a low environment term of `0.05`.
+
+When an instance is removed, the render system swaps the last live instance
+into the vacant slot and copies:
+
+- the 4x4 instance matrix;
+- every custom attribute slice;
+- the entity-to-index mapping.
+
+This dense-swap invariant is the reusable pooling mechanism. Updating only
+`mesh.count` without copying custom attributes would attach old effect state to
+the moved instance.
+
+## HDR contribution
+
+The compact signals are intentionally bright before bloom:
+
+```text
+spark core multiplier: 80
+homing projectile multiplier: 30
+laser multiplier: 10
+```
+
+These values are evidence of relative hierarchy inside that scene, not
+universal exposure-independent constants. Preserve the relationship:
+
+```text
+spark flash > projectile > laser > ordinary surface
+```
+
+Validate all three in the raw HDR buffer and with bloom disabled.
+
+## Observed limitations
+
+- Spark position multiplies an already integrated decayed velocity by elapsed
+  time again. This is dimensionally inconsistent but visually deliberate.
+  Preserve it only when that trajectory is explicitly required.
+- Acceleration uses `a * t^2` rather than `0.5 * a * t^2`, also an artistic
+  choice.
+- Spark randomization uses `Math.random`, so captures are not deterministic.
+  Replace it with a seeded generator for regression work.
+- The reentry wake disables depth test. This avoids hull intersections but can
+  draw through unrelated geometry. Validate camera and occluder assumptions.
+- The shell and wakes are analytic procedural meshes, not fluid simulation.
+  Do not describe them as physically simulated plasma.
 
 ## Diagnostics
 
-Expose layer toggles, overdraw view, bounding volumes, active counts, lifetime
-histograms, and final/no-bloom captures.
+Expose:
+
+```text
+fall direction and support point
+shell facing/core/envelope/shock masks
+coarse and fine wake noise
+wake profile distance and tail fade
+raw HDR emission by layer
+bloom contribution by layer
+spark age, velocity, and pool occupancy
+debris remaining time and dissolve threshold
+instance index/entity mapping
+overdraw and depth-test modes
+```

package/templates/skills/genex-threejs-raymarched-space-effects/SKILL.md

@@ -5,26 +5,33 @@ description: Build raymarched space effects for Genex Three.js games. Use for bl
 
 # Genex Three.js Raymarched Space Effects
 
-Use raymarched space effects for strong authored moments. Keep the math bounded,
-diagnosable, and tied to a game purpose.
+Treat these effects as numerical renderers with explicit integration state. The visual character depends on coordinate choice, step policy, and how rays interact with emissive structures.
 
-Read [references/space-effects.md](references/space-effects.md) for curved-ray,
-disk, wormhole, and budget patterns.
+## Workflow
 
-## Build order
+1. Define the effect-space transform and camera ray.
+2. Choose a physical, physically inspired, or purely artistic bending model.
+3. Bound the integration domain.
+4. Track ray position, direction, throughput, and accumulated radiance.
+5. Detect crossings with disks, shells, throats, or event boundaries.
+6. Sample the background only after integration terminates.
+7. Add diagnostics for trajectory, step count, and termination reason.
 
-1. Define the game role: landmark, hazard, portal, sky feature, set piece, or
-   background effect.
-2. Choose ray domain, bounds, step count, and quality tiers.
-3. Implement a no-distortion baseline first.
-4. Add ray steering, density, emission, and environment lookup.
-5. Add compositing with depth and exposure rules.
-6. Expose debug views for steps, ray exit, density, emission, and fallback.
+Read [references/space-effects.md](references/space-effects.md)
+for the RK4 wormhole, artistic curved-ray accretion integrator, disk
+composition, and implementation defects.
 
-## Rules
+## Constraints
 
-- Bound every integration loop.
-- Keep a cheaper fallback for low-end browsers.
-- Avoid unbounded brightness that breaks exposure.
-- Keep controls and collision separate from visual distortion.
-- Validate camera motion and edge cases near the effect.
+- Do not call a UV swirl “gravitational lensing.”
+- Cap iterations and provide early termination.
+- Use continuous crossing tests for thin structures.
+- Keep numerical stability independent from frame rate.
+- Separate the integrator from shading of the accretion disk or wormhole interior.
+- Provide a cheaper approximation for non-hero views.
+
+## Routing boundary
+
+Use `$genex-threejs-procedural-vfx` for ordinary particles, trails, plasma, and event
+effects. This skill is for per-pixel numerical ray integration through curved
+or bounded space-effect domains.