# Machine Registry Format

The machine registry is the domain spine of Mechanica. It lets the app add, browse, route, render, animate, and teach mechanical systems without hardcoding machine-specific logic in pages or viewer panels.

## Files

```text
src/modules/machines/schema.ts
src/modules/machines/registry.ts
src/modules/machines/selectors.ts
```

## Registry entry

Each machine is a `MachineRegistryEntry` with:

- Stable `id`
- URL-safe `slug`
- Human `title`
- Category and difficulty
- Complexity score
- Release date for catalogue sorting
- Search tags
- Summary and long description
- Thumbnail gradient metadata
- Model source descriptor
- Engineering facts
- Part metadata
- Animation profile metadata
- Viewer defaults
- Guided-tour steps
- Related machine IDs

## Why data-driven?

A viewer panel should not contain logic like:

```ts
if (machine.id === 'four-stroke-petrol-engine') {
  showValves();
}
```

Instead, the panel receives `machine.parts`, `machine.facts`, `machine.tour`, and `machine.animation`. Machine-specific behavior is isolated to model assets and animation modules keyed by the registry ID.

## Current Phase 1 coverage

The scaffold includes all 28 required Phase 1 machines:

1. Four Stroke Petrol Engine
2. Two Stroke Engine
3. Diesel Engine
4. V8 Engine
5. Wankel Rotary Engine
6. Steam Engine
7. Jet Engine (Turbojet)
8. Turbofan Engine
9. Planetary Gearbox
10. Differential Gear
11. Manual Gearbox (5-speed)
12. CVT
13. Worm Gear Drive
14. Bevel Gear Set
15. Centrifugal Pump
16. Gear Pump
17. Piston Pump
18. Hydraulic Cylinder
19. Scotch Yoke
20. Geneva Drive
21. Cam and Follower
22. Rack and Pinion
23. Slider Crank
24. Toggle Clamp
25. Ball Bearing
26. Roller Bearing
27. Disc Brake Caliper
28. Turbocharger

## Adding a new machine

1. Add a new entry in `registry.ts`.
2. Use a stable `id`; never rename it after links or favourites exist.
3. Use a URL-safe `slug`.
4. Assign a category from `MACHINE_CATEGORIES`.
5. Add meaningful tags for catalogue search.
6. Add part IDs that match GLB object metadata or animation module expectations.
7. Add engineering facts and guided-tour copy.
8. Add valid `relatedIds`.
9. If using GLB, set `model.kind = 'gltf'` and provide `assetPath`.
10. Create an animation module matching `MachineAnimationModule` when real kinematics are implemented.

## Model source strategy

The schema supports:

```ts
{ kind: 'procedural', archetype: 'inline-engine', units: 'meters' }
```

and:

```ts
{
  kind: 'gltf',
  assetPath: '/models/engines/four-stroke.glb',
  draco: true,
  ktx2: true,
  units: 'meters'
}
```

The current milestone uses procedural entries so every viewer route is functional without missing asset requests.

## Part metadata contract

Part IDs must be:

- Unique within a machine.
- Stable over time.
- Lowercase kebab-case.
- Shared by registry, GLB `userData.partId`, animation modules, visibility controls, opacity controls, URL state, guided-tour highlights, and detail drawer.

## Validation to add in a later milestone

A repository script should validate:

- Unique IDs and slugs.
- Valid related IDs.
- Valid tour part IDs.
- Valid animation step normalized times.
- GLB asset existence.
- No orphaned animation module.
- No duplicate part IDs per machine.