@fourjs/motion

Motion system — time, the fixed-step loop, kinematics, and controllers. Part of fourJS.

Implements §9–§13, §38–§39, and the §111 advanced-motion tier (§99, Parts II & VI) of docs/SPECIFICATION.md; shipped across Phases 1, 2, and 8. All times are seconds.

What's here

• Time (§9) — TimeState / Clock (the same type; §9's public name is Clock, PH-22l) / createTimeState / copyTimeState distinguishing real, render, simulation, scaled, and unscaled time.
• Scheduler (§10) — the fixed-delta accumulator (Scheduler, DEFAULT_FIXED_DELTA_TIME, DEFAULT_MAXIMUM_SUB_STEPS, dropped-time surfacing, interpolationAlpha).
• System registry (§39) — SystemRegistry, SimulationSystem, and the PRIORITY_* step-order constants; nothing edits the scheduler directly.
• Integrators (§38) — explicitEuler, semiImplicitEuler, rk2, rk4, velocityVerlet (INTEGRATORS).
• Kinematics — MotionComponent / MotionSystem (velocity/acceleration) and KinematicController / KinematicSystem (per-channel move/rotate/path-follow commands under §42 transform authority).
• Trajectories (§13) — linear, parabolic, ballistic, circular, elliptical, cubic Bézier, Catmull-Rom, damped spring, and parametric.
• Controllers and steering (§111) — PIDController (conditional-integration anti-windup), SpringDamper (exact ZOH matrix-exponential step, unconditionally stable), the Reynolds steering set (seek, flee, pursue, evade, arrive, wander, wanderSpherical) plus flocking (separation, cohesion, alignment) via SteeringAgent.
• Camera rigs (§44) — OrbitRig, FollowRig (follow target and spring arm), CameraShake (interpolated value-noise, trauma/impulse), LookAtConstraint + ConstraintSystem at §39 step 7 under §42's "constraint" authority; CharacterController / FirstPersonLook under "kinematic".
• Prediction and IK — predictLinear / predictBallistic, intercept solving, analytic two-bone IK (solveTwoBoneIK; positions, not joint angles), and iterative solveCCD / solveFABRIK (per-joint hinge/ball limits, caller-owned chain, tolerance / maxIterations contract).

Staged / not yet implemented

• Fly (two lines of application code over the shipped orbit/dolly surface), stereo/XR.
• Path-planning adapters (RFC) and robotic joint-command mapping (the PID → joint-motor cascade is demonstrated in tests instead). SpatialHash ships for radius neighbour queries (WP-8.2). Camera shake, spherical wander, and CCD/FABRIK shipped.

Unit tests are colocated in tests/ per §92.

Workspace name @fourjs/motion; publishes as @danielsimonjr/fourjs-motion.