@genex-ai/cli-demo 0.93.0 → 0.94.0-dev.249

package/templates/skills/genex-threejs-volumetric-clouds/references/volumetric-clouds.md

@@ -1,579 +0,0 @@
-# Weather-shaped cloud volume and reconstruction
-
-Use this reference for planetary or large-world volumetric clouds built from packed weather layers, generated shape and detail fields, bounded integration, temporal reconstruction, and low-cost cloud shadows.
-
-## Contents
-
-1. Four-layer density model
-2. Packed intervals and generated field assets
-3. Weather, shape, turbulence, and detail
-4. Beauty march and lighting
-5. Temporal reconstruction
-6. Shadow system and quality presets
-7. Implementation limits, adaptation, and diagnostics
-
-## 1. Preserve the four-layer vector model
-
-Evaluate four layers in parallel as `vec4` channels. Do not collapse them into
-one scalar weather field before applying per-layer altitude, profile, shape,
-and detail controls.
-
-Default active layers:
-
-| Channel | Altitude | Height | Density | Shape | Detail | Coverage width | Shadow |
-| --- | ---: | ---: | ---: | ---: | ---: | ---: | --- |
-| R low | 750 m | 650 m | 0.2 | 1.0 | 1.0 | 0.6 | yes |
-| G middle | 1000 m | 1200 m | 0.2 | 1.0 | 1.0 | 0.6 | yes |
-| B high | 7500 m | 500 m | 0.003 | 0.4 | 0.0 | 0.5 | no |
-| A spare | disabled | disabled | default | default | default | default | no |
-
-Each layer also owns:
-
-```ts
-type Layer = {
-  weatherChannel: "r" | "g" | "b" | "a"
-  weatherExponent: number
-  shapeAlteringBias: number
-  densityProfile: {
-    exponentialTerm: number
-    exponent: number
-    linearTerm: number
-    constantTerm: number
-  }
-}
-```
-
-Default density profile:
-
-```text
-profile(h) =
-  expTerm * exp(exponent * h)
-  + linearTerm * h
-  + constantTerm
-
-default = 0.75 * h + 0.25
-```
-
-The profile is not a generic bottom/top smoothstep. It is a compact
-artist-authored function that can produce rising, falling, or exponential
-density by layer.
-
-## 2. Understand the packed interval subtlety
-
-The layer system sorts all lower/upper altitude endpoints and merges occupied
-ranges. It then packs up to three intervals where the active-layer balance is
-zero.
-
-Those packed intervals are **empty gaps**, despite names such as
-`minIntervalHeights` and `insideLayerIntervals`.
-
-Beauty and shadow marches use:
-
-```glsl
-if (height is inside any packed gap) {
-  skip density work;
-}
-```
-
-For the default layers, the low and middle ranges merge into one occupied band
-from 750–2200 m, followed by an empty gap before the 7500–8000 m high layer.
-
-If adapting the system:
-
-1. merge occupied layer ranges on CPU;
-2. pack the complementary gaps;
-3. verify the debug view labels them as skipped intervals;
-4. do not accidentally skip the occupied bands.
-
-## 3. Generate field assets once
-
-Render procedural textures into repeatable targets, then sample them during
-the expensive march.
-
-### Local weather RGBA
-
-The procedural weather texture assigns:
-
-```text
-R: low-cloud Worley FBM
-G: middle-cloud Worley FBM
-B: high-cloud anisotropic Perlin
-A: auxiliary Perlin variation
-```
-
-Low and middle fields are intentionally separated:
-
-```text
-middle = smoothstep(1.0, 1.4, WorleyFBM(point + 0.5))
-low = saturate(
-  smoothstep(0.8, 1.4, WorleyFBM(point))
-  - middle
-)
-```
-
-The generation pass later forces alpha to `1`, so the default spare A layer is
-not a second generated weather population. Preserve that behavior when using
-the complete packed-layer contract.
-
-### Base shape volume
-
-The 3D base texture combines Perlin-Worley and Worley FBM:
-
-```text
-perlinWorley =
-  remap(perlin, 0, 1, worleyFBM, 1)
-
-baseShape =
-  remap(perlinWorley, worleyFBM - 1, 1)
-```
-
-The octave weights are dominated by low frequencies:
-
-```text
-0.625, 0.25, 0.125
-```
-
-### Detail volume
-
-The detail volume is Worley-only and builds three progressively finer FBM
-bands from frequencies `2, 4, 8, 16`, again weighted toward low frequencies.
-
-### Turbulence
-
-The 2D turbulence texture stores a normalized curl field derived from three
-offset Perlin channels. It warps shape coordinates; it is not multiplied into
-final density as arbitrary noise.
-
-Generate these textures once or only when their recipes change. A 3D
-render-target path requires one draw per Z layer, so regenerating each frame is
-unacceptable.
-
-## 4. Weather coverage response
-
-For each sample:
-
-```text
-heightFraction =
-  remapClamped(height, layerMin, layerMax)
-```
-
-Round cloud growth toward the upper portion:
-
-```text
-biased = heightFraction ^ shapeAlteringBias
-x = clamp(2 * biased - 1, -1, 1)
-heightScale = 1 - x²
-```
-
-Sample the four selected weather channels, apply each layer’s exponent, then
-modulate by global coverage:
-
-```text
-factor = 1 - coverage * heightScale
-density =
-  remapClamped(
-    mix(localWeather, 1, coverageFilterWidth),
-    factor,
-    factor + coverageFilterWidth
-  )
-```
-
-Global coverage therefore shifts/remaps local weather. It is not a final
-density multiplier.
-
-Debug separately:
-
-```text
-raw local-weather channels
-weather after exponent
-heightScale
-coverage factor
-coverage-remapped density
-```
-
-## 5. Base shape and turbulence
-
-Advect fields through offsets rather than regenerating them:
-
-```text
-localWeatherOffset += localWeatherVelocity * dt
-shapeOffset += shapeVelocity * dt
-detailOffset += detailVelocity * dt
-turbulenceOffset += turbulenceVelocity * dt
-```
-
-The density path adds a radial “evolution” offset related to weather speed,
-then optional turbulence:
-
-```text
-surfaceNormal = normalize(position)
-evolution = -surfaceNormal * length(weatherOffset) * 20000
-
-turbulence =
-  displacement
-  * (curlTexture * 2 - 1)
-  * lowHeightMask
-```
-
-The turbulence mask fades out by roughly the lower 30% of each layer, so it
-distorts bases and growth without scrambling the entire cloud.
-
-Base shape:
-
-```text
-shapePosition =
-  (position + evolution + turbulence)
-  * shapeRepeat
-  + shapeOffset
-
-density =
-  remapClamped(
-    weatherDensity,
-    (1 - shapeNoise) * shapeAmount,
-    1
-  )
-```
-
-Shape amount is per layer. High cirrus uses less base-shape influence.
-
-## 6. Detail changes topology by height
-
-The detail modifier is not uniform erosion.
-
-```text
-top modifier = detail^6
-bottom modifier = 1 - detail
-
-modifier =
-  mix(
-    top modifier,
-    bottom modifier,
-    remapClamped(heightFraction, 0.2, 0.4)
-  )
-```
-
-This makes upper cloud detail fluffy and lower detail whippy/eroded. Then:
-
-```text
-modifier *= shapeDetailAmount
-density =
-  remapClamped(
-    density * 2,
-    modifier * 0.5,
-    1
-  )
-```
-
-Detail is skipped at coarse mip levels using a jittered threshold. Do not spend
-high-frequency texture reads when the sample footprint cannot resolve them.
-
-Finally:
-
-```text
-densityVector =
-  saturate(
-    densityVector
-    * densityScales
-    * profile(heightFraction)
-  )
-
-totalDensity = sum(densityVector)
-layerWeight = densityVector / totalDensity
-scattering = totalDensity * scatteringCoefficient
-extinction =
-  totalDensity * absorptionCoefficient
-  + scattering
-```
-
-Guard zero total density before using layer weights in an independent
-implementation.
-
-## 7. Planetary ray interval
-
-Intersect view rays with concentric spheres at:
-
-```text
-planet radius
-minimum cloud altitude
-maximum cloud altitude
-shadow top altitude
-```
-
-Select near/far based on camera state:
-
-```text
-below clouds
-inside total cloud layer
-above clouds
-ray intersects ground
-```
-
-Then clamp the far distance against opaque scene depth. The beauty march never
-runs beyond the nearest opaque surface.
-
-Return explicit diagnostic flags:
-
-```text
-ground intersection
-scene occlusion
-camera region
-near distance
-far distance
-selected sphere intersections
-```
-
-## 8. Primary march policy
-
-High/default values:
-
-```text
-max iterations: 500
-minimum step: 50 m
-maximum step: 1000 m
-maximum ray distance: 200 km
-perspective step scale: 1.01
-minimum density: 1e-5
-minimum extinction: 1e-5
-minimum transmittance: 1e-2
-```
-
-Initial step size grows with ray entry distance:
-
-```text
-step =
-  minStep
-  + (perspectiveScale - 1) * rayNear
-```
-
-Jitter the first step with spatiotemporal blue noise. Double the jitter
-distance when needed to suppress spatial aliasing.
-
-At each sample:
-
-1. skip packed empty altitude gaps;
-2. sample rough weather;
-3. if all layer densities are below threshold, take a longer mip-aware step;
-4. otherwise sample base shape, optional turbulence, and detail;
-5. if extinction is significant, evaluate lighting and integrate;
-6. terminate at the transmittance threshold.
-
-Long empty-space steps can band near a dense crossing. Treat this as a known
-defect, not a solved feature. A robust adaptation can binary-search the first
-dense crossing.
-
-## 9. Lighting contract
-
-Per occupied sample, evaluate:
-
-```text
-sun irradiance
-sky irradiance
-short optical-depth march toward sun
-Beer shadow-map optical depth beyond that short march
-multi-scattering approximation
-optional ground bounce
-sky gradient contribution
-powder attenuation
-```
-
-The phase function defaults to two Henyey-Greenstein lobes. An optional fitted
-large-particle phase path exists, but it requires adequate multiple scattering
-to remain plausible.
-
-Multi-scattering uses octave accumulation:
-
-```text
-for each octave:
-  contribution +=
-    attenuationA
-    * exp(-opticalDepth * attenuationB)
-    * phase(cosTheta, attenuationC)
-  attenuation *= 0.5
-```
-
-Default high quality uses eight octaves.
-
-Energy-conserving integration:
-
-```text
-stepT = exp(-extinction * stepLength)
-stepScatter =
-  (radiance - radiance * stepT)
-  / max(extinction, epsilon)
-
-accumulatedRadiance += accumulatedT * stepScatter
-accumulatedT *= stepT
-```
-
-Representative depth is a transmittance-weighted sample distance. It is used
-for aerial perspective and temporal velocity, not merely visualized.
-
-## 10. Quarter-resolution temporal upscale
-
-The temporal-upscale path renders the current clouds at one quarter linear
-resolution:
-
-```text
-lowWidth = ceil(fullWidth / 4)
-lowHeight = ceil(fullHeight / 4)
-```
-
-A 4×4 Bayer pattern chooses one current full-resolution pixel per low-resolution
-texel over 16 frames. Projection jitter follows the same offset.
-
-Current targets store:
-
-```text
-RGBA cloud radiance/transmittance
-RGB representative depth + velocity
-optional shadow length
-```
-
-Resolve:
-
-1. use the newly rendered current texel when its Bayer index matches the frame;
-2. otherwise choose the closest-depth sample in a 3×3 neighborhood;
-3. reproject with velocity;
-4. reject history outside the viewport;
-5. variance-clip history against current neighbors;
-6. write the resolved result and swap history buffers.
-
-For full-resolution TAA, blend clipped history toward current with default
-`temporalAlpha = 0.1`.
-
-Reset history on:
-
-```text
-camera cut
-resolution or render-scale change
-weather/shape discontinuity
-layer topology change
-projection mode change
-```
-
-## 11. Cloud shadow representation
-
-The shadow system is not a grayscale beauty march. Each cascade stores:
-
-```text
-R front depth
-G mean extinction
-B maximum accumulated optical depth
-A optical-depth tail estimate after early termination
-```
-
-Beauty lighting reconstructs optical depth beyond a local short sun march from
-this compact representation.
-
-Shadow marching uses structured volume sampling:
-
-1. choose one of three icosahedral structure normals from ray direction and
-   jitter;
-2. intersect regularly spaced planes perpendicular to that normal;
-3. march samples on those planes.
-
-This intentionally trades some spatial aliasing for strong temporal stability,
-which matters for low-resolution cascaded shadow maps.
-
-Default shadow budget:
-
-```text
-3 cascades
-512 × 512 maps
-50 iterations
-100–1000 m step size
-minimum transmittance 1e-4
-```
-
-Low tier:
-
-```text
-2 cascades
-256 × 256 maps
-25 iterations
-minimum transmittance 1e-2
-```
-
-## 12. Quality tiers must remove expensive mechanisms intentionally
-
-The low tier disables:
-
-```text
-light shafts
-shape detail
-turbulence
-ground bounce
-accurate sun/sky lookup
-```
-
-It keeps:
-
-```text
-weather-shaped density
-base 3D shape
-one short sun march
-temporal reconstruction
-cloud shadows at reduced quality
-```
-
-This is a legitimate fallback because silhouette, weather control, and
-directional self-shadowing survive.
-
-## 13. Required diagnostics
-
-Expose:
-
-```text
-weather RGBA
-per-layer height fractions
-packed empty intervals
-coverage-remapped density
-base shape
-detail modifier
-turbulence displacement
-final per-layer density vector
-total scattering/extinction
-ray near/far and scene clamp
-primary/shape/detail sample counts
-sun optical depth
-Beer shadow-map channels
-transmittance
-representative depth
-velocity
-history UV
-variance bounds
-history rejection
-shadow cascade index
-shadow structured-sampling planes
-```
-
-## 14. Failure diagnosis
-
-```text
-clouds disappear between low and high layers:
-  occupied ranges were mistaken for packed empty gaps
-
-all cloud types share one silhouette:
-  layer vectors were summed before profile/shape controls
-
-porous smoke:
-  detail was added uniformly instead of height-dependent remapping
-
-boiling motion:
-  field offsets use unrelated directions/speeds or textures regenerate
-
-bright flat interior:
-  short sun optical depth or shadow map is missing
-
-dark featureless cloud:
-  multi-scattering, sky light, or powder balance is absent
-
-edge trails:
-  representative depth/velocity is wrong or history lacks variance clipping
-
-flickering cloud shadows:
-  beauty jitter was reused instead of temporally stable structured sampling
-
-cost scales with view distance:
-  shell interval, scene depth clamp, or empty-gap skipping is broken
-```

package/templates/skills/genex-threejs-water-optics/SKILL.md

@@ -1,57 +0,0 @@
----
-name: genex-threejs-water-optics
-description: Build analytic water surfaces for Genex Three.js games. Use for rivers, pools, lakes, shoreline water, bounded heightfield pool simulation, object-driven ripples, differential-area caustics, ray-traced pool volume optics, shared wave displacement, normals, Fresnel, refraction, absorption, crest foam, underwater color, and cheaper water than a full spectral ocean.
----
-
-# Genex Three.js Water Optics
-
-Treat water as geometry motion, surface orientation, and a participating optical layer. A blue transparent material is not a water system.
-
-For large stochastic seas driven by directional spectra and GPU FFTs, use
-`$genex-threejs-spectral-ocean` instead.
-
-## Analytic surface build order
-
-1. Define wave bands and evaluate displacement.
-2. Derive the normal analytically from the same waves.
-3. Choose displaced geometry or explicitly normal-only water.
-4. Establish scene-color ownership for heuristic refraction.
-5. Declare whether absorption uses true depth or a fallback path-length estimate.
-6. Blend analytic reflection/refraction through side-aware Fresnel.
-7. Derive foam and glints from the shared wave response.
-8. Filter unresolved normal bands from derivatives.
-
-Read [references/water-optics.md](references/water-optics.md)
-for the exact five-wave displaced ocean, six-band normal-only water, optical
-hierarchy, and the limits that distinguish both from the spectral-ocean skill.
-
-## Bounded pool volumes
-
-A bounded pool couples a small RGBA heightfield simulation (height and velocity,
-with local drop injection and moving-object displacement) with the optical
-layer: normals derive from the simulated heights and feed differential-area
-caustics on the pool floor, and the water volume is shaded by ray-tracing
-against the pool bounds. Keep the simulation, the normal derivation, and the
-caustics reading the same field — a caustic pattern detached from the simulated
-surface is a failure condition below.
-
-## Failure conditions
-
-- normal texture motion does not agree with displaced crests;
-- heuristic refraction can sample foreground objects but the limitation is undisclosed;
-- fallback path length is presented as reconstructed scene thickness;
-- bounded pool caustics are a decorative projection detached from simulated
-  height normals;
-- micro-waves alias into sparkling noise;
-- foam is a scrolling texture unrelated to the shared crest metric;
-- Fresnel is replaced by constant opacity;
-- reflection, refraction, and transparency are all added without energy control.
-
-## Routing boundary
-
-Use `$genex-threejs-spectral-ocean` for stochastic directional spectra, FFT
-cascades, Jacobian breaking, and persistent ocean foam. Use
-`$genex-threejs-precipitation-surfaces` for rain-driven puddle wetness, ripple
-masks, and weather-coupled splashes on ground surfaces. This skill owns
-authored analytic waves, bounded heightfield simulation, ray-traced
-pool-volume optics, and bounded-water optics.