@genex-ai/cli-demo 0.6.1 → 0.7.0

package/templates/skills/genex-threejs-camera-direction/SKILL.md

@@ -5,32 +5,44 @@ description: Design advanced Three.js camera systems for Genex browser games. Us
 
 # Genex Three.js Camera Direction
 
-Treat the camera as part of the game design, not a passive viewport. It must
-explain scale, support the player verb, and survive mode changes.
-
-Read [references/camera-rigs.md](references/camera-rigs.md) for concrete rig
-patterns, handoff rules, and browser checks.
+Treat the camera as an authored visual system, not a passive viewport. Compose
+the subject, establish scale, choose a stable up frame, and make every mode
+handoff explicit.
 
 ## Build order
 
-1. Define subject size, play distance, screen occupancy, lens, near/far planes,
-   input mode, and up-axis convention.
-2. Choose semantic camera frames: player body, vehicle, track, planet normal,
-   arena center, or authored shot marker.
-3. Compute target position and orientation separately, then compose the final
-   camera transform once.
-4. Add orbit, chase, side, or pointer-look constraints around the chosen frame.
-5. Use frame-rate-independent smoothing for follow motion; avoid stacked
-   smoothing during explicit transitions.
-6. Snapshot and restore projection, controls, and ownership when scenes mount or
-   dispose.
-
-## Rules
-
-- Derive distances from subject bounds; do not hard-code one offset for every
-  game object.
-- Use `lerp` for positions and `slerp` for orientations.
-- Re-sync yaw and pitch from the active camera when pointer lock is acquired.
-- Update projection matrices after FOV, near, far, or aspect changes.
-- Keep infinite backgrounds camera-relative in large worlds.
-- Validate resize, pointer-lock recovery, mode transitions, and collision edges.
+1. Define the design frame: subject size, screen occupancy, lens, near/far,
+   motion, and horizon/up convention.
+2. Build camera targets in semantic frames: ship, body surface, docking axis,
+   or scene-authored shot.
+3. Derive position and orientation independently, then combine them once.
+4. Add input orbit/look only inside declared yaw/pitch and spatial constraints.
+5. Add frame-rate-independent follow or a bounded spring where the reference
+   uses inertia.
+6. Snapshot and restore camera projection/state when a scene owns it.
+7. Test mode transitions, cuts, pointer-lock reacquisition, resize, and large
+   coordinates.
+
+Read [references/camera-rigs.md](references/camera-rigs.md)
+for exact chase/side/orbit rigs, projection values, transition
+rules, floating-origin shot, pointer controls, and implementation limits.
+
+## Non-negotiable rules
+
+- Use subject dimensions to derive offsets; do not tune one fixed distance for
+  differently scaled assets.
+- For planetary motion, derive up from the dominant body rather than global Y.
+- Interpolate position with `lerp` and orientation with `slerp`.
+- During an explicit handoff, use one interpolation stage. Do not stack a
+  transition blend and a second follow smoother over the same interval.
+- Re-sync yaw/pitch from the camera when pointer lock is acquired.
+- Update the projection matrix whenever FOV, near, far, or aspect changes.
+- Keep stars or infinite backgrounds camera-relative when large translation
+  would create false parallax or precision loss.
+- Restore camera and input ownership on scene disposal.
+
+## Routing boundary
+
+Use `$genex-threejs-procedural-animation` for object motion timelines, springs,
+docking, staging, and debris. This skill owns how the scene is viewed and how
+camera modes hand off.

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.