@genex-ai/cli-demo 0.6.0 → 0.6.2

package/templates/skills/genex-threejs-camera-direction/references/camera-rigs.md

@@ -1,38 +1,370 @@
-# Camera Rigs
+# Camera rig and cinematic systems
 
-Use these patterns when a Genex scene needs authored camera behavior.
+Use this reference for scale-aware chase, side, orbit, authored-shot, pointer-look, floating-origin, projection, and lifecycle camera systems.
 
-## Chase camera
+## Contents
 
-- Base the offset on the controlled object's bounding sphere.
-- Track a target point slightly ahead of the object, not only its origin.
-- Smooth position with an exponential factor based on `deltaTime`.
-- Smooth orientation separately so fast direction changes do not roll the view.
-- Clamp pitch and distance so the player cannot bury the camera in geometry.
+- Camera contract
+- planet-space implementation ship-scaled chase mount
+- planet-space implementation thrust-lag spring
+- planet-space implementation side and orbit camera
+- Explicit camera handoffs
+- cinematic implementation shot ownership
+- Pointer-look and movement constraints
+- Floating origin and background handling
+- Projection and lifecycle ownership
+- Failure modes and diagnostics
 
-## Orbit camera
 
-- Store yaw, pitch, and distance as explicit state.
-- Clamp pitch before deriving the spherical offset.
-- Recompute the target from the game object each frame.
-- Disable or reduce damping during scripted handoffs.
+## Camera contract
 
-## Side or authored shot
+Record before implementation:
 
-- Define shot anchors in scene space or subject-relative space.
-- Keep screen occupancy stable across subject scale changes.
-- Blend only one transition source at a time.
-- Expose a debug view showing target point, camera point, and frustum.
+```ts
+type CameraDirectionContract = {
+  subject: THREE.Object3D
+  subjectScale: number
+  projection: { fov: number; near: number; far: number }
+  positionMode: "authored" | "mount" | "body-relative" | "floating-origin"
+  upMode: "world" | "subject" | "dominant-body"
+  inputMode: "locked" | "pointer-look" | "orbit-offset"
+  handoffOwner: string
+  spatialConstraints: string[]
+}
+```
 
-## Pointer look
+Do not combine modes until each can produce a valid position and quaternion
+independently.
 
-- On lock acquisition, derive yaw and pitch from the current camera quaternion.
-- Apply pointer deltas to yaw/pitch state, then rebuild the quaternion.
-- Release cleanly on escape, tab changes, and scene disposal.
+## planet-space implementation ship-scaled chase mount
 
-## Large worlds
+`CameraRigSystem` derives the chase mount from ship length:
 
-- Use a floating origin or camera-relative background for scenes with very large
-  coordinates.
-- Keep stars, sky domes, and infinite grids from translating in ways that imply
-  false parallax.
+```text
+height = shipLength * 0.5
+back = shipLength * 1.3
+mount position = (0, height, -back)
+
+look target:
+  up = shipLength * 0.0001
+  forward = shipLength * 0.35
+```
+
+It constructs a basis:
+
+```text
+forward = normalize(target - mount)
+right = normalize(cross(worldUp, forward))
+up = normalize(cross(forward, right))
+quaternion = quaternion(makeBasis(right, up, forward))
+quaternion *= rotation(worldUp, π)
+```
+
+The final `π` correction is model-convention specific. Verify the camera’s
+local forward convention before retaining it.
+
+The mount is parented to `ShipRoot`, so its world position/quaternion follows
+the ship without recomputing the authored chase pose.
+
+## planet-space implementation thrust-lag spring
+
+planet-space implementation adds camera distance behind the ship only while manual thrust is
+active. Throttle and boost own separate scalar spring states:
+
+```text
+throttle max = 3.8
+boost max = 5.8
+combined max = 8.2
+
+drive acceleration:
+  throttle 12
+  boost 22.8
+
+held stiffness:
+  throttle 6
+  boost 7.5
+
+return stiffness = 34
+held damping ratio = 1.04
+return damping ratio = 1.30
+```
+
+Per component:
+
+```text
+damping = 2 * dampingRatio * sqrt(stiffness)
+acceleration =
+  activeDrive
+  - stiffness * distance
+  - damping * velocity
+
+velocity += acceleration * dt
+distance += velocity * dt
+distance = clamp(distance, 0, maxDistance)
+```
+
+If clamping blocks velocity in the same direction, zero it. Apply total lag
+along negative ship forward after reading the chase mount’s world pose.
+
+This gives acceleration weight without adding camera rotation lag.
+
+## planet-space implementation side and orbit camera
+
+Scale-aware offsets after the ship model loads:
+
+```text
+side = (
+  shipLength * 3.2,
+  shipLength * 1.0,
+  -shipLength * 1.35
+)
+
+orbit = (
+  shipLength * 4.85,
+  shipLength * 1.35,
+  -shipLength * 2.15
+)
+```
+
+The camera uses the dominant-body radial vector as up:
+
+```text
+bodyUp = normalize(shipPosition - bodyPosition)
+```
+
+For orbit lock, forward comes from relative velocity; otherwise it comes from
+ship orientation. Project forward onto the body tangent plane:
+
+```text
+tangent = forward - bodyUp * dot(forward, bodyUp)
+```
+
+Frame-rate-independent smoothing:
+
+```text
+side forward response = 1 - exp(-6.5 * dt)
+offset response = 1 - exp(-3.6 * dt)
+mode blend lambda = 3.2
+```
+
+Rebuild an orthonormal frame:
+
+```text
+right = normalize(cross(bodyUp, tangent))
+tangent = normalize(cross(right, bodyUp))
+offset =
+  right * offset.x
+  + bodyUp * offset.y
+  + tangent * offset.z
+```
+
+Yaw rotates the offset around `bodyUp`. Pitch rotates around
+`cross(bodyUp, offset)`. Pointer input scales:
+
+```text
+yaw -= mouseDeltaX * 0.0022
+pitch -= mouseDeltaY * 0.0018
+```
+
+Pitch bounds vary by flight mode. The implementation also enforces camera height above
+the ship:
+
+```text
+landed minimum = shipLength * 0.42
+other side-camera minimum = shipLength * 0.20
+```
+
+If tangent becomes nearly parallel to up (`abs(dot) > 0.985`), rebuild it from
+`cross(bodyUp, worldUp)` and then X as a final fallback.
+
+Look target:
+
+```text
+target = bodyUp * shipLength * 0.12
+quaternion = lookAt(cameraPosition, target, bodyUp)
+```
+
+This camera is positioned in ship-root-local coordinates. Preserve that
+coordinate ownership when adapting the rig.
+
+## Explicit camera handoffs
+
+planet-space implementation captures position and quaternion at transition start. Launch handoff
+begins at progress `0.68`; orbit-exit duration varies from `1.1` to `2.6`
+seconds based on the current side-camera blend.
+
+Ease:
+
+```text
+eased = 1 - (1 - t)^1.8
+position = lerp(startPosition, chasePosition, eased)
+orientation = slerp(startQuaternion, chaseQuaternion, eased)
+```
+
+Critical transition invariant:
+
+```text
+explicit transition active
+  -> write camera directly from one lerp/slerp
+  -> return from camera update
+```
+
+Do not apply the normal follow smoother after this interpolation. Stacked
+smoothing causes a mid-transition half-halt.
+
+Outside explicit transitions, the final chase/side pose is followed with:
+
+```text
+lambda 9.5 while side blend is active/transitioning
+lambda 18 when pure chase
+```
+
+At effectively zero blend, copy the chase pose exactly to prevent a permanent
+subpixel tail.
+
+## cinematic implementation shot ownership
+
+Each cinematic implementation scene owns its shot and projection values, for example:
+
+```text
+Saturn approach:
+  FOV 40
+  near 12
+  far 360000
+
+spin docking:
+  FOV 46
+  near 35
+  far 90000
+```
+
+Scenes save prior FOV/near/far, update the projection, and restore all three on
+dispose.
+
+The spin-docking shot uses authored world anchors:
+
+```text
+camera position = (6878.606, 4914.173, 6141.678)
+look target = (6301.714, 4779.175, 5336.091)
+```
+
+Ships are then staged in the camera frame:
+
+```text
+forward = normalize(lookTarget - cameraPosition)
+right = normalize(cross(forward, worldUp))
+up = normalize(cross(right, forward))
+
+staging center = cameraPosition + forward * 340
+```
+
+Subject offsets are expressed in this shot basis. This is more robust than
+tuning independent world coordinates after the camera is framed.
+
+The launch shot instead hard-anchors to a rocket-relative orbit target every
+frame. It intentionally avoids follow lag against a rapidly accelerating
+subject.
+
+## Pointer-look and movement constraints
+
+`PointerLookControls` uses Euler order `YXZ`, clamps pitch to
+`±(π/2 - 0.01)`, and re-syncs yaw/pitch from the current camera quaternion
+whenever pointer lock is acquired.
+
+Movement:
+
+```text
+forward = camera world direction
+right = normalize(cross(forward, worldUp))
+distance = movementSpeed * dt
+```
+
+Default speed is `9`, sensitivity `0.0023`.
+
+Keys are cleared on:
+
+- pointer-lock exit;
+- window blur;
+- any update while unlocked.
+
+Scene-specific constraints then run after controls:
+
+- NASA room clamps X/Y/Z with floor, ceiling, and wall clearance.
+- Mann’s Planet clamps camera Y above sampled terrain plus `0.2`.
+- cinematic scenes block movement keys while retaining their authored camera.
+
+Input control and spatial constraint are separate layers.
+
+## Floating origin and background handling
+
+The Saturn scene first computes a virtual camera pose, stores its orientation
+basis, then:
+
+```text
+camera position = origin
+Saturn group position = -virtualCameraPosition
+atmosphere center uniform = Saturn group position
+stars position = camera position
+```
+
+The ship flyby is animated in the stored camera basis. This preserves the
+authored composition while avoiding enormous camera coordinates.
+
+Stars are tethered to the camera in multiple scenes to remove deep-space
+parallax and prevent them from crossing the far envelope.
+
+## Projection and lifecycle ownership
+
+planet-space implementation’s global camera uses:
+
+```text
+FOV 38
+near 0.2
+far 3.0e7
+```
+
+It prewarms pipelines by temporarily aiming at representative bodies, then
+restores both position and quaternion in `finally`.
+
+cinematic implementation’s scene manager:
+
+```text
+dispose active scene
+clear scene-root children
+create next scene
+await init
+```
+
+Every scene that changes projection or background restores it on disposal.
+This ownership prevents one shot’s lens from leaking into another.
+
+## Failure modes and diagnostics
+
+Observed boundaries:
+
+- planet-space implementation’s scalar spring is semi-implicit Euler; clamp `dt` during long frame
+  stalls.
+- The chase mount’s final 180-degree correction depends on model conventions.
+- Side-camera local/world ownership is easy to break when adapting the ship
+  hierarchy.
+- Authored cinematic world coordinates are scene-specific; preserve the
+  camera-frame staging method, not literal positions.
+- Hard camera anchoring is correct for launch composition but unsuitable when
+  inertial camera feel is the goal.
+- Global-Y pointer movement is not valid for walking on a spherical planet.
+
+Expose:
+
+```text
+camera mode and owner
+design-frame guides and subject screen bounds
+camera local basis
+body-up/tangent/right vectors
+chase mount and thrust-lag distance/velocity
+side/orbit target pose and blend
+handoff start, target, t, and easing
+FOV/near/far and depth precision
+constraint contacts
+floating-origin offset
+camera-relative background state
+```

package/templates/skills/genex-threejs-exposure-color-grading/SKILL.md

@@ -5,26 +5,35 @@ description: Build exposure and color grading for Genex Three.js games. Use for
 
 # Genex Three.js Exposure And Color Grading
 
-Exposure and grading are final image controls. Use them to preserve readability
-across gameplay, not to fix broken lighting.
+Treat exposure, tone mapping, grading, and output conversion as distinct stages. Tune them from measured HDR signal, not by stacking compensating color operations.
 
-Read [references/exposure-grading.md](references/exposure-grading.md) for
-metering, tone mapping, LUTs, and validation.
+## Order
 
-## Build order
+```text
+HDR scene
+  → luminance meter
+  → adapted exposure
+  → tone map
+  → creative grade / 3D LUT
+  → final output conversion
+```
 
-1. Confirm render color space, tone-mapping owner, and output transform.
-2. Define target luminance range and adaptation speed.
-3. Meter luminance from an intentionally downsampled or sampled source.
-4. Apply exposure before tone mapping.
-5. Apply grading after tone mapping if using a display-style LUT.
-6. Expose debug views for luminance, exposure, tone map, LUT, and final output.
+Read [references/exposure-grading.md](references/exposure-grading.md)
+for the exact 64x36 meter, encoded readback, adaptation constants, 32-cube LUT,
+and signal-ownership ambiguities.
 
-## Rules
+## Failure conditions
 
-- Use one tone-mapping owner.
-- Keep adaptation asymmetric if bright-to-dark and dark-to-bright need different
-  response.
-- Avoid grading that hides gameplay colors or UI states.
-- Validate bright, dark, indoor, outdoor, and VFX-heavy moments.
-- Document known artistic compromises.
+- tone mapping occurs in both materials and post;
+- exposure is used to repair physically inconsistent light ratios;
+- meter weighting and scene framing are not inspected;
+- adaptation speed is the same toward light and dark;
+- LUT input/output spaces are undocumented;
+- sRGB encoding happens twice;
+- a display-domain LUT is moved before tone mapping without being rebuilt.
+
+## Routing boundary
+
+Use `$genex-threejs-bloom` for HDR glow contribution and
+`$genex-threejs-image-pipeline` when this color path must share ownership with AO,
+atmosphere, or effect-local render targets.

package/templates/skills/genex-threejs-exposure-color-grading/references/exposure-grading.md

@@ -1,30 +1,205 @@
-# Exposure And Color Grading
+# Scene-referred exposure and color pipeline
 
-Use this reference for final image response.
+Use this reference for a measured HDR-to-display path with encoded luminance readback, asymmetric adaptation, one tone-map owner, and a generated display-domain 3D LUT.
 
-## Metering
+## Contents
 
-- Downsample luminance or sample a stable set of pixels.
-- Use log-average luminance for robust exposure.
-- Ignore or reduce weighting for UI and transient VFX when they should not drive
-  exposure.
-- Clamp exposure range.
+- Exact pipeline order
+- Luminance meter
+- Exposure target and adaptation
+- 3D LUT construction
+- LUT placement
+- Tone mapping ownership
+- Observed limitations
+- Diagnostics
 
-## Adaptation
 
-- Use different speeds for brightening and darkening when useful.
-- Smooth by `deltaTime`.
-- Reset or seed exposure intentionally on scene transitions.
+## Exact pipeline order
 
-## Tone mapping
+The pipeline computes:
 
-- Choose one tone mapping stage.
-- Place bloom before tone mapping.
-- Place display grading after tone mapping unless the project has a specific
-  scene-referred grading path.
+```text
+HDR scene after AO/atmosphere
+  -> bloom added in HDR
+  -> multiply by adapted exposure
+  -> renderOutput using renderer tone mapping
+  -> saturate to LUT domain
+  -> sample 3D LUT
+  -> blend LUT intensity
+  -> optional FXAA
+```
 
-## Grading
+`RenderPipeline.outputColorTransform` is disabled and one output node owns the
+final conversion. Renderer tone-mapping mode and renderer exposure are still
+configuration inputs to `renderOutput`.
 
-- Keep gameplay-critical colors distinguishable.
-- Provide a neutral grade toggle.
-- Validate captures on multiple scene lighting states.
+## Luminance meter
+
+The implementation renders a `64 x 36` meter target using unsigned bytes. It encodes
+unbounded luminance:
+
+```text
+encoded = luminance / (luminance + 1)
+decoded = encoded / max(0.0001, 1 - encoded)
+```
+
+Readback occurs asynchronously every `12` frames by default. While one readback
+is pending, another is not started.
+
+CPU reduction uses weighted log average:
+
+```text
+weight = 1.0 when luminance > 0.002
+weight = 0.15 otherwise
+
+average =
+  exp(sum(log(max(luminance, 0.0001)) * weight) / sum(weight))
+```
+
+This suppresses black-pixel dominance without requiring a histogram.
+
+## Exposure target and adaptation
+
+Defaults:
+
+```text
+minimum exposure = 0.45
+maximum exposure = 1.85
+middle gray = 0.18
+compensation = 0 EV
+speed up = 3.2
+speed down = 1.1
+```
+
+Target:
+
+```text
+target =
+  clamp(
+    middleGray / averageLuminance
+    * 2^exposureCompensation,
+    minExposure,
+    maxExposure
+  )
+```
+
+Frame-rate-independent adaptation:
+
+```text
+speed = target > current ? speedUp : speedDown
+amount = 1 - exp(-max(deltaSeconds, 0) * speed)
+current += (target - current) * amount
+```
+
+When disabled, current and target reset to `1`.
+
+## 3D LUT construction
+
+Build a `32^3` RGBA `Data3DTexture` with linear filtering, clamp wrapping, no
+mipmaps, and unsigned-byte storage.
+
+Each preset recipe owns:
+
+```text
+contrast
+saturation
+vibrance
+black/white point
+per-channel gamma
+shadow/midtone/highlight tint
+strength for each tonal range
+```
+
+Recipe order:
+
+```text
+normalize black/white range
+S-curve blend, fixed amount 0.44
+contrast around 0.5
+shadow tint
+midtone tint
+highlight tint
+per-channel gamma
+saturation
+vibrance
+small highlight glow bias
+clamp to [0, 1]
+```
+
+Tonal weights are calculated from pre-grade luminance:
+
+```text
+shadow = 1 - smoothstep(0.12, 0.54, luma)
+highlight = smoothstep(0.48, 0.92, luma)
+midtone = max(0, 1 - abs(luma - 0.5) * 2)
+```
+
+## LUT placement
+
+The LUT samples tone-mapped display-linear RGB after saturation:
+
+```text
+uv = saturate(displayColor.rgb) * ((32 - 1) / 32) + 0.5 / 32
+graded = texture3D(lut, uv)
+final = mix(displayColor, graded, lutIntensity)
+```
+
+This means the included recipes are authored for a bounded post-tone-map
+domain. Do not move them before tone mapping without rebuilding the recipes and
+documenting a scene-linear or log domain.
+
+## Tone mapping ownership
+
+Available renderer modes include:
+
+```text
+None, Linear, Reinhard, Cineon, ACES, AgX, Neutral
+```
+
+Color defaults:
+
+```text
+tone mapping = ACES
+renderer exposure = 0.72
+LUT = Real Daylight
+LUT intensity = 1
+```
+
+The feature factory initially disables LUT intensity and eye adaptation until
+enabled through settings. Distinguish configuration defaults from active
+feature state.
+
+## Observed limitations
+
+- The meter has no center weighting, percentile clipping, sky mask, or UI mask.
+- Unsigned-byte encoding loses precision near extreme luminance.
+- Readback cadence is frame-count based, so wall-clock cadence changes with
+  frame rate.
+- A failed readback resets target exposure to `1`, which can cause a visible
+  adaptation shift.
+- LUT generation clamps every entry to `[0,1]`; it is display-domain grading,
+  not HDR scene-referred grading.
+- The pipeline exposes both renderer `toneMappingExposure` and a separate
+  adapted exposure multiplier. Their combined ownership must be documented to
+  avoid accidental double exposure.
+- FXAA is applied after grading, but dithering/gamut compression are absent.
+
+## Diagnostics
+
+Expose:
+
+```text
+meter source
+encoded meter target
+decoded luminance
+weight mask
+measured average
+target/current exposure over time
+readback pending and cadence
+HDR before exposure
+tone-mapped before LUT
+neutral versus selected LUT
+per-recipe tonal weights
+clipped/out-of-domain mask
+final with one exposure stage disabled at a time
+```