# Animation Validation Matrix

This milestone now includes a deterministic animation engine and eight procedural machine rigs with standard lifecycle hooks, reduced-motion handling, guided tours, per-part metadata, and mechanically believable looped motion.

## Runtime coverage

| Requirement | Delivered implementation |
| --- | --- |
| Standard module interface | `MachineAnimationModule` in `src/animations/types.ts` defines `initialize`, `update`, `dispose`, `onPlay`, `onPause`, `onResume`, `onRestart`, `onStep`, `onBeforeTick`, and `onAfterTick`. |
| Core player controls | `MachineAnimationPlayer` supports play, pause, resume, restart, stop, seek, cycle seek, RPM, time scale, loop, reverse direction, and step-through mode. |
| GSAP / RAF timing | GSAP ticker drives the clock; frame deltas are clamped for tab-resume stability. Camera tour transitions use GSAP tweens. |
| Reduced motion | The player detects and accepts reduced-motion state through `useMachineAnimation`; modules select `slow`, `pause`, `static-snapshot`, or `continue`. Guided tours suppress camera animation duration when reduced motion is active. |
| Guided tours | `GuidedTourPlayer` sequences captions, camera requests, part highlights, phase windows, and RPM suggestions. |
| Part interactions | Procedural parts register Three.js objects, expose hover/click selection, opacity, visibility, wireframe, explosion offsets, and labels. |
| Shareable state | `ProceduralDemoExperience` writes machine, RPM, and exploded-view parameters to the URL and includes a copy-link button. |

## Machine motion checks

| Machine | Key animation checks |
| --- | --- |
| Four Stroke Petrol Engine | Two crank revolutions per cycle; camshaft half speed; intake valve opens during intake; exhaust valve opens during exhaust; spark pulse near top dead centre; crank-slider geometry drives piston/rod. |
| Planetary Gearbox | Fixed ring, sun input, carrier output; carrier ratio is `sun/(sun+ring)`; planets orbit with the carrier and counter-spin against the sun. |
| Differential Gear | Ring/pinion input drives the carrier; side gears match speed while straight; spider gears spin and axle speeds diverge during cornering window. |
| Centrifugal Pump | Impeller rotates at shaft speed; inlet and outlet flow pulses follow blade phase; pressure indicator scales with RPM; cavitation bubbles appear at high RPM. |
| Geneva Drive | One driver revolution advances one slot; dwell holds output between engagement windows; drive pin position follows the rotating driver. |
| Ball Bearing | Inner race rotates; cage moves at fractional speed; balls orbit and spin; load-zone balls subtly scale to show contact stress. |
| Disc Brake Caliper | Hydraulic pressure window extends piston and pads; rotor slows visually during clamp; heat band opacity tracks braking work. |
| Wankel Rotary Engine | Rotor center orbits on eccentric; rotor angle is one-third shaft speed; apex seals follow rotor tips; intake, exhaust, and combustion pulses phase around the housing. |

## Build hygiene notes

The implementation uses only declared dependencies: React, Three.js, React Three Fiber, Drei, GSAP, and Framer Motion. No generated lockfile is included; maintainers should run `npm install` once to resolve the dependency graph and generate a local lockfile.