@genex-ai/cli-demo 0.6.1 → 0.7.0

package/templates/skills/genex-threejs-procedural-animation/references/procedural-motion.md

@@ -1,33 +1,362 @@
-# Procedural Motion
+# Procedural motion and docking systems
 
-Use this reference for authored real-time motion in Genex games.
+Use this reference for phase-based launch, staging, docking, spring, rotating-frame, detachment, and debris motion with explicit coordinate frames and terminal states.
 
-## Analytic timelines
+## Contents
 
-- Normalize timeline progress to `t` in `[0, 1]`.
-- Apply named easing functions per phase.
-- Derive all animated properties from the same normalized phase when they must
-  stay synchronized.
-- Record phase names in debug output so screenshots can be interpreted.
+- State contract
+- Piecewise launch kinematics
+- Planet-relative gravity turn
+- Camera-independent shake and roll
+- Stage detachment
+- Spin-docking timeline
+- Docking-frame decomposition
+- Spring convergence and terminal lock
+- Peeling and released debris
+- planet-space implementation response and orientation patterns
+- Failure modes and diagnostics
 
-## Springs
 
-- Use springs for pursuit, vehicle lag, recoil, camera follow, or UI-like
-  physical response.
-- Keep spring constants in named parameters.
-- Clamp extreme `deltaTime` after tab resumes.
-- Snap to target when distance and velocity fall below a threshold.
+## State contract
 
-## Rotating frames
+Use explicit persistent state:
 
-- For docking, orbit, or planet-relative scenes, define the moving frame first.
-- Convert local target axes to world axes each frame.
-- Slerp orientation toward the target quaternion.
-- Avoid mixing Euler interpolation with quaternion alignment.
+```ts
+type ProceduralAnimationState = {
+  elapsedSeconds: number
+  phase: string
+  position: THREE.Vector3
+  velocity: THREE.Vector3
+  baseQuaternion: THREE.Quaternion
+  spinAngle: number
+  angularVelocity: THREE.Vector3
+  eventFlags: Record<string, boolean>
+}
+```
 
-## Debris and secondary motion
+Keep scratch vectors/quaternions outside the state. Reset all persistent values
+when restarting the sequence.
 
-- Generate seeded velocity, angular velocity, lifetime, and drag.
-- Use object pools for many particles or fragments.
-- Remove or recycle expired fragments deterministically.
-- Keep collision or damage state separate from decorative debris.
+## Piecewise launch kinematics
+
+cinematic implementation’s launch sequence uses:
+
+```text
+ignition hold = 1.2 s
+ascent = 24 s
+slow phase = 5 s
+acceleration phase = 11 s
+deceleration phase = 8 s
+slow distance fraction = 0.00035
+coast linear = 1.2 s
+terminal deceleration = 4 s
+```
+
+`computeAscentKinematics()` solves a normalized distance curve whose position
+and speed remain continuous across all three ascent phases.
+
+For slow phase:
+
+```text
+speed = slowDistance / slowDuration
+distance = speed * t
+```
+
+Solve acceleration so total normalized distance reaches one after the
+acceleration and deceleration phases:
+
+```text
+remaining = 1 - slowDistance
+accel =
+  (
+    remaining
+    - slowSpeed * (accelDuration + 0.5 * decelDuration)
+  )
+  /
+  (
+    0.5 * accelDuration * (accelDuration + decelDuration)
+  )
+
+peakSpeed = slowSpeed + accel * accelDuration
+decel = peakSpeed / decelDuration
+```
+
+Then integrate each phase analytically. Do not approximate this authored
+timeline by repeatedly lerping position toward an endpoint.
+
+## Planet-relative gravity turn
+
+The launch maps normalized distance to:
+
+```text
+altitude = ascentProgress * targetOrbitAltitude + coastDistance * coastRate
+
+groundArcDistance =
+  ascentProgress^1.22 * maxGroundArcDistance * turnBlend
+  + coastDistance * groundTrackRate
+
+arcAngle = groundArcDistance / planetRadius
+```
+
+Motion constants:
+
+```text
+target altitude = 420 km in scene scale
+max ground arc = 2200 km
+max crossrange = 26 km
+```
+
+Construct:
+
+```text
+radial = normalize(0, cos(arcAngle), -sin(arcAngle))
+tangent = normalize(0, -sin(arcAngle), -cos(arcAngle))
+position = planetCenter + radial * (planetRadius + altitude)
+position.x += crossrange
+```
+
+Orientation:
+
+```text
+flightDirection = normalize(lerp(radial, tangent, gravityTurn * 0.9))
+base = quaternionFromUnitVectors(rocketLocalUp, flightDirection)
+roll = quaternionAround(flightDirection, rollAmount)
+orientation = base * roll
+```
+
+This separates trajectory direction from authored roll/vibration.
+
+## Camera-independent shake and roll
+
+Rocket roll:
+
+```text
+shake envelope = 1 - smoothstep(0.05, 0.9, ascentProgress)
+vibration =
+  (
+    sin(time * 52)
+    + sin(time * 31 + 0.7)
+  )
+  * 0.0024
+  * envelope
+
+roll =
+  sin(time * 2.5) * 0.008 * envelope
+  + vibration
+```
+
+The camera has a separate early launch shake envelope and offset. Keep object
+vibration and camera shake separate so either can be disabled for diagnostics.
+
+## Stage detachment
+
+Before reparenting stage one:
+
+```text
+capture world position
+capture world quaternion
+capture world scale
+remove from rocket
+add to scene
+restore captured world transform
+```
+
+The detached stage immediately receives readable separation:
+
+```text
+along offset = -3.4 m
+side offset = 4.2 m
+earthward offset = 1.2 m
+
+along speed = -5.2 m/s
+side speed = 5.8 m/s
+earthward speed = 4.2 m/s
+```
+
+It then integrates separate along, side, and earthward scalar velocities. A
+short kick phase blends into growing lag accelerations.
+
+For the first `2 s`, orientation slerps from the captured quaternion to a
+random `10–30°` tilt. Afterward, it integrates a bounded spin rate
+`0.06–0.15 rad/s`.
+
+The side direction is chosen relative to the camera so separation reads in the
+shot. That is a presentation-aware choice, not a physical rule.
+
+## Spin-docking timeline
+
+Docking phases:
+
+```text
+Endurance spin = 3.15 rad/s
+Ranger spin-up = 6.5 s
+approach starts = 4.0 s
+approach duration = 14.5 s
+dock settle = 3.0 s
+post-dock spin-down = 3.0 s
+dock axial clearance = 4.1
+dock radial offset = 0.35
+```
+
+Every phase uses a named `smoothstepRange(start, end, time)`. The sequence does
+not hide all timing in one normalized zero-to-one value.
+
+Endurance:
+
+```text
+currentSpinRate = lerp(3.15, 0, spinDownT)
+spinAngle += currentSpinRate * dt
+orientation = baseOrientation * rotation(localForward, spinAngle)
+```
+
+The docking frame is recomputed from the newly rotated Endurance every frame.
+
+## Docking-frame decomposition
+
+At approach start:
+
+```text
+offset = rangerPosition - dockPort
+parallel = dot(offset, dockAxis)
+radialVector = offset - dockAxis * parallel
+radialDistance = length(radialVector)
+radialDirection = normalize(radialVector)
+```
+
+Target during approach:
+
+```text
+parallelApproach =
+  lerp(startParallel, dockClearance, approachT)
+
+parallel =
+  lerp(parallelApproach, dockClearance, dockT)
+
+radialApproach =
+  lerp(startRadial, dockRadialOffset, approachT)
+
+radial =
+  lerp(radialApproach, 0, dockT)
+radial = lerp(radial, 0, spinDownT)
+
+target =
+  dockPort
+  + dockAxis * parallel
+  + radialDirection * radial
+```
+
+This preserves a readable approach corridor while progressively removing
+lateral error.
+
+## Spring convergence and terminal lock
+
+Ranger position follows target through a vector spring:
+
+```text
+acceleration =
+  (target - current) * stiffness
+  - velocity * damping
+
+velocity += acceleration * dt
+current += velocity * dt
+```
+
+Stiffness increases from `5.0` to `9.8`; damping from `4.6` to `7.4` as docking
+settles.
+
+Orientation aligns local up to negative docking axis, then applies spin around
+the docking axis:
+
+```text
+alignment = quaternionFromUnitVectors(localUp, -dockAxis)
+spin = quaternionAround(dockAxis, rangerSpinAngle)
+orientation = spin * alignment
+```
+
+Near completed docking, position receives a final `lerp` toward target. After
+spin-down reaches `0.995`, copy target exactly and zero velocity. A spring alone
+can retain imperceptible but destabilizing residual motion.
+
+## Peeling and released debris
+
+Endurance debris has two states.
+
+Attached peel:
+
+```text
+peelT = smoothstep(peelStart, detachTime, sequenceTime)
+peelDistance = maxDistance * peelT^2
+position = shipTransform(localAnchor + outward * peelDistance)
+orientation = shipOrientation * localBase * peelTwist
+```
+
+At release, velocity inherits rotating-frame tangential velocity:
+
+```text
+angularVelocityOfShip =
+  dockAxis * currentSpinRate
+
+tangentialVelocity =
+  cross(angularVelocityOfShip, worldOffsetFromShip)
+
+velocity =
+  tangentialVelocity
+  + outward * outwardSpeed
+  + axis * axialSpeed
+```
+
+Released debris then integrates linear velocity and quaternion rotation from
+its angular-velocity vector. Speed is capped at `95`.
+
+This rotating-frame inheritance is the defining mechanism. Random outward
+velocity alone would not match the spinning hull.
+
+## planet-space implementation response and orientation patterns
+
+planet-space implementation uses frame-rate-independent exponential response:
+
+```text
+alpha = 1 - exp(-lambda * dt)
+value = lerp(value, target, alpha)
+```
+
+It uses this for camera blends, side-camera forward, effect intensities, color
+response, and control state.
+
+Ship orientation control separates desired forward/up from angular physics.
+Quaternion targets are converted to angular error; damping acts on angular
+velocity. This keeps user control and rigid-body response distinct.
+
+For bounded camera lag, planet-space implementation uses a second-order spring with critical-like
+damping ratios rather than exponential interpolation. Choose exponential
+response for perceptual parameter smoothing and a spring when velocity/inertia
+is part of the motion.
+
+## Failure modes and diagnostics
+
+Observed boundaries:
+
+- cinematic implementation detachment randomness uses `Math.random`; seed it for replay and
+  regression.
+- Semi-implicit springs need a clamped `dt`, especially after tab suspension.
+- The launch path is authored for one planet scale and shot duration.
+- Camera-relative separation is intentionally cinematic rather than physical.
+- Repeated quaternion multiplication should normalize periodically.
+- Timeline phase constants are coupled; changing one duration requires
+  recomputing later event boundaries.
+
+Expose:
+
+```text
+sequence time and current phase
+analytic position/speed curve
+radial, tangent, and flight-direction vectors
+base orientation, roll, and final orientation
+stage world transform before/after reparent
+detached scalar offsets/velocities
+dock port, axis, parallel error, and radial error
+spring target, velocity, stiffness, and damping
+spin rates and accumulated angles
+debris inherited tangential/outward/axial velocity
+terminal lock state
+```

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

@@ -5,26 +5,45 @@ description: Create procedural architecture for Genex Three.js games. Use for bu
 
 # Genex Three.js Procedural Architecture
 
-Architecture should communicate function, scale, traversal, and affordance. Use
-grammars that emit semantic parts rather than arbitrary boxes.
+Separate design planning from mesh emission. A building generator should produce an inspectable plan before it produces triangles.
 
-Read [references/architecture-systems.md](references/architecture-systems.md)
-for massing, facade rules, module compilation, and gameplay checks.
+## Required architecture
 
-## Build order
+```text
+settings
+  → mass grammar
+  → exposed-surface graph
+  → façade/roof placements
+  → module registry
+  → material-slot mesh writer
+  → geometries
+```
 
-1. Define gameplay role: backdrop, obstacle, climbable surface, interior shell,
-   landmark, cover, or arena boundary.
-2. Build massing volumes and exposed edges.
-3. Apply facade grammar by face orientation, floor band, corner, and entrance.
-4. Emit material slots and collision proxies separately from decorative meshes.
-5. Add detail only where camera distance supports it.
-6. Expose debug views for modules, floors, entrances, collision, and LOD.
+Read [references/architecture-systems.md](references/architecture-systems.md) before implementing the generator.
 
 ## Rules
 
-- Keep doors, ledges, stairs, and openings aligned with player scale.
-- Use repeated modules deliberately; break repetition with semantic variation.
-- Do not spend triangle budget on invisible internal faces.
-- Keep material slots stable so generated variants can share assets.
-- Validate collision and navigation against the visual promise.
+- Massing, façade rhythm, and detail modules are separate layers.
+- Resolve exposed edges before façade placement. Do not decorate hidden internal faces.
+- Modules own semantic anchors and construction depth, not global building coordinates.
+- Compile by material slot to reduce draw calls without destroying material separation.
+- Preserve real dimensions for floor height, bay width, trim projection, and texture density.
+- Randomness may select among valid designs; it must not repair invalid geometry.
+- Provide topology, placement, material-slot, and UV-density debug modes.
+
+## Acceptance
+
+The generated building must survive:
+
+- silhouette-only view;
+- flat untextured material;
+- grazing light;
+- close inspection of corners and roof transitions;
+- seed variation without broken bays, overlapping ownership, or floating ornament;
+- triangle and module-count reporting.
+
+## Routing boundary
+
+Use `$genex-threejs-procedural-geometry` for a reusable profile, sweep, ring, or mesh
+writer without a building grammar. This skill owns massing, façade semantics,
+architectural modules, and building-plan compilation.