@genex-ai/cli-demo 0.6.1 → 0.6.2

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

@@ -1,30 +1,579 @@
-# Volumetric Clouds
+# Weather-shaped cloud volume and reconstruction
 
-Use this reference for cloud rendering in Genex games.
+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.
 
-## Density model
+## Contents
 
-- Weather map controls coverage, cloud type, and density scale.
-- Height profile controls base, body, and top falloff.
-- Detail erosion breaks up silhouettes.
-- Wind moves the sample domain consistently over time.
+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
 
-## Raymarching
+## 1. Preserve the four-layer vector model
 
-- Intersect the camera ray with a bounded cloud volume.
-- Use coarse steps before expensive lighting.
-- Early-exit when transmittance is low.
-- Keep step count and resolution adjustable.
+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.
 
-## Lighting
+Default active layers:
 
-- Use sun direction from the scene.
-- Add forward-scattering emphasis for bright cloud edges.
-- Approximate self-shadow with short secondary samples or cached maps.
-- Keep cloud shadows optional and low-frequency.
+| 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 |
 
-## Temporal behavior
+Each layer also owns:
 
-- Reprojection can reduce cost but must expose history diagnostics.
-- Validate camera cuts, fast turns, and pause/resume behavior.
-- Provide a single-frame mode for debugging.
+```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

@@ -5,26 +5,41 @@ description: Build analytic water surfaces for Genex Three.js games. Use for riv
 
 # Genex Three.js Water Optics
 
-Use analytic water when the game needs readable local water with clear
-interaction, refraction, and shading without a full ocean simulation.
+Treat water as geometry motion, surface orientation, and a participating optical layer. A blue transparent material is not a water system.
 
-Read [references/water-optics.md](references/water-optics.md) for wave,
-normal, refraction, and fallback patterns.
+For large stochastic seas driven by directional spectra and GPU FFTs, use
+`$genex-threejs-spectral-ocean` instead.
 
-## Build order
+## Analytic surface build order
 
-1. Define water role: pool, river, lake, shoreline, hazard, boundary, or
-   traversal affordance.
-2. Build shared wave displacement and normals from named wave bands.
-3. Add Fresnel reflection, absorption, depth color, and controlled refraction.
-4. Derive crest foam and shoreline foam from wave height, slope, or masks.
-5. Add interaction ripples only after the base water reads.
-6. Expose debug views for displacement, normals, depth, refraction, and foam.
+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.
 
-## Rules
+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.
 
-- Use the same wave state for geometry, normals, and foam.
-- Keep refraction optional; provide a readable fallback.
-- Avoid screen-space refraction artifacts at silhouettes and edges.
-- Bound normal intensity so water does not shimmer in motion.
-- Keep gameplay collision and visual displacement expectations aligned.
+## 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. This skill owns
+authored analytic waves, bounded heightfield simulation, ray-traced
+pool-volume optics, and bounded-water optics.