# Mechanica Animation System

Milestone 4 introduces a standard animation layer for all procedural and asset-backed machines. The core contract is `MachineAnimationModule` in `src/animations/types.ts`; each machine exports metadata, cycle steps, lifecycle hooks, and a single `update(context)` function that manipulates named part `Object3D` instances.

## Core Player

`MachineAnimationPlayer` supports:

- Play, pause, resume, restart, and stop
- RPM control with per-machine min/default/max bounds
- Time-scale control from `0.1x` to `3x`
- Looping or one-shot playback
- Step-through mode using machine-defined cycle steps
- RAF or GSAP ticker clock drivers
- Reduced-motion handling:
  - `pause-autoplay` prevents automatic playback when the user prefers reduced motion
  - `slow` caps continuous playback speed
  - `allow` leaves playback unchanged for explicit simulation use cases
- Per-machine lifecycle hooks: setup, update, seek, teardown, play, pause, resume, restart, loop, and step

The player never hardcodes machine behavior. It only maintains time, phase, RPM, highlighted parts, and part lookup.

## React Hook

`useMachineAnimation` wraps the player for React/R3F scenes. It accepts a stable part registry map and returns:

- `player`
- reactive `snapshot`
- `controls`
- `prefersReducedMotion`

A scene component should register parts by ID, pass the map to the hook, and bind UI controls to `controls`.

## Guided Tours

`src/animations/guidedTour.ts` defines `GuidedTour` and `GuidedTourStep`. Steps can:

- Highlight one or more parts
- Seek to a normalized animation time
- Override RPM or time scale
- Play or pause the animation
- Request camera poses for the viewer shell
- Emit captions and engineering callouts

`useGuidedTour` provides start, pause, resume, stop, next, previous, and go-to controls. It avoids auto-advancing when reduced motion is enabled.

## Procedural Demo Definitions

The first batch of procedural machine demos lives in `src/modules/machines/procedural`:

1. Four Stroke Petrol Engine
2. Planetary Gearbox
3. Differential Gear
4. Centrifugal Pump

Each definition includes:

- Machine catalogue metadata
- Difficulty, category, tags, and sort fields
- Engineering facts
- Per-part descriptions/specs/materials
- Camera presets
- Standard animation module
- Guided tour choreography
- React component that builds geometry procedurally with Three.js primitives

The remaining Milestone 4 demo machines will be added to the same registry without changing the player API.

## Adding a Machine

1. Create a file in `src/modules/machines/procedural/<machine>.tsx`.
2. Define a `parts` array with stable part IDs.
3. Build a React component that wraps every interactive assembly in `<Part id="...">`.
4. Export a `MachineAnimationModule` whose `update(context)` reads parts with `context.part(id)`.
5. Export a `ProceduralMachineDefinition` with learning content, camera presets, animation, and tour.
6. Add the definition to `src/modules/machines/procedural/index.ts`.

Use stable, semantic part IDs. URLs, opacity controls, visibility controls, guided tours, and selection panels all depend on those IDs staying consistent.