# Asset Pipeline and Loading System

Mechanica is designed for GLB/GLTF mechanical assemblies with compressed geometry and textures. This milestone ships procedural model previews so routes and interactions work before production assets are available.

## Asset directory convention

Public runtime assets should be served from:

```text
public/assets/
├── models/
│   ├── engines/
│   ├── gearboxes-drives/
│   ├── pumps-fluid/
│   ├── mechanisms/
│   └── structural-other/
├── textures/
├── environments/
└── thumbnails/
```

Source authoring files such as Blender, CAD exports, and high-resolution textures should not be served directly by Vite. Keep them in an external asset repository or a non-public source folder if introduced later.

## Preferred model format

- Runtime format: `.glb`
- Units: meters
- Origin: logical machine center
- Axis convention: Y up
- Materials: PBR metallic/roughness
- Part metadata: Object3D `userData.partId`
- Compression: Draco for geometry where beneficial
- Texture compression: KTX2/Basis for production textures

## Registry integration

Each machine registry entry contains a model source:

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

The current entries use:

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

This avoids broken network requests while the viewer foundation is built.

## GLB preparation checklist

1. Clean mesh topology and remove hidden authoring geometry.
2. Name major nodes consistently.
3. Add `userData.partId` for selectable parts.
4. Apply transforms.
5. Ensure meter scale.
6. Limit material count.
7. Bake high-frequency detail to normal maps when appropriate.
8. Export GLB.
9. Run `gltf-transform` optimization.
10. Validate in an external GLTF viewer.
11. Add registry `assetPath`.
12. Add thumbnail/poster once generated.

## Loading system plan

The future `GltfMachineModel` adapter should:

- Use Drei `useGLTF` for route-level lazy loading.
- Configure Draco decoder path once decoder assets are hosted.
- Configure KTX2 transcoder once compressed textures exist.
- Show a layout-stable progress overlay.
- Fail gracefully to procedural preview if the asset fails.
- Preload a machine when the user hovers/focuses its catalogue card.
- Cache model data across route transitions.

## Asset size targets

| Asset type | Target |
| --- | ---: |
| Core GLB geometry per machine | 1-8 MB compressed |
| Large advanced engines | 8-18 MB compressed |
| Thumbnail | < 120 KB |
| Environment map | < 1 MB compressed |
| Texture set per machine | < 4 MB compressed |

## Material conventions

Use clear material names:

- `metal_brushed_dark`
- `metal_cast_aluminum`
- `rubber_belt`
- `glass_cutaway`
- `fluid_blue`
- `combustion_warm`
- `section_cap_orange`

Avoid duplicating identical material definitions across parts.

## Future automation

Add scripts later for:

- Registry validation.
- GLB existence checks.
- GLB transform optimization.
- Thumbnail generation.
- Draco/KTX2 compression.
- Bundle asset budget reports.