# Asset library

This repo replaces the Three.js pack's paid generation APIs with a vendored, verifiable CC0 library plus procedural generation. No API key is required for anything here.

## Fetching

Binaries are **not** in git.

```bash
./apps/arcade/download_assets.sh                      # core, ~1900 models, ~75 MB
./apps/arcade/download_assets.sh --packs=all          # 4669 models / 47 packs, ~185 MB
./apps/arcade/download_assets.sh --packs=nature-kit,car-kit
./apps/arcade/download_assets.sh --list               # inspect only
./apps/arcade/download_assets.sh --transcode          # ogg -> wav, needs ffmpeg
```

Everything is gitignored, pinned (starter kits to exact GitHub commits, the rest to content-hashed kenney.nl URLs) and sha256-verified. A moved or tampered upstream fails loudly. Downloads are sequential with a delay — that is someone else's bandwidth, do not parallelise it.

Mirrors: `resources/MIRROR.toml` lists every pack with canonical URL, sha256, size and model count.

```bash
ARCADE_ASSET_MIRROR=https://your.host/assets ./apps/arcade/download_assets.sh
```

The sha256 is verified identically whichever host served the bytes. **A mirror is never trusted more than upstream; the hash is the authority.**

## Searching

Query by *description*, never filename, through `makepad-game-assets`. The agent gets a `find_model` tool and a one-paragraph summary — it never receives the catalogue, and that summary stays ~480 characters however large the library grows.

Ids look like `kenney/racing/vehicle-truck-yellow` and are **stable across re-downloads**, because generated game code writes them.

Findability is three layers: per-pack theme curation (~55 rows), filename token parsing, and a query-time synonym table (~240 rows). Query-side stemming means "smashing" reaches the `smash` alias. On ties, the kind the query implies wins — "spaceship" is an object request, "metal clang" or "win music" wants something audible.

At the full 4,999-entry catalogue: index build ~120 ms, a search ~0.2 ms, ~2.1 MB heap (release).

Useful types: `AssetIndex`, `AssetEntry`, `AssetKind`, `Source`, `Filters`, `Hit`, `KitInfo`, `CastInfo`, `CATEGORIES`, `AUDIO_CATEGORIES`, and `Palette` / `Spread` / `VarietyParams` for colour variety.

## Rigged characters

`find_cast` lists animated casts. A cast is a set of characters sharing one skeleton, so any state works on any member and a part can be recast without touching animation code.

| rig | members | clips | notable states |
| --- | --- | --- | --- |
| 41 joints (KayKit) | 9 | 76–95 | block, dodge, hurt, dance, sleep, carry |
| 7 joints (Kenney mini) | 22 | 25–32 | walk, run, jump, attack, sit, wave |
| 6 joints (Kenney platformer) | 5 | 25 | walk, run, jump, attack |

Two rules: **pick members from ONE cast per scene**, and **use different members so a crowd is not clones** — the same rule that applies to props.

## Audio

Every Kenney audio pack ships `.ogg` only. `makepad-game-audio` includes a Vorbis decoder (`vorbis/`, `ogg.rs`) plus `wav.rs`, so sounds are decodable to `Pcm` via `decode(bytes)`. If you hit an undecodable file, `--transcode` converts to WAV where ffmpeg exists. See `makepad-audio-generator`.

## Procedural fallback

When nothing in the library fits, generate it. `makepad-game-gen` covers terrain, meshes, trees (`tree`, `lsystem`), splines, scatter, interiors, kits, level generation, implicit surfaces, and textures (`texgen`) — all from a seeded `rng`, so output is byte-identical across devices and replicates as `(preset, seed, position)` rather than vertex data.

Prefer procedural for: terrain, roads, foliage fields, building interiors, tiling textures, level layout.
Prefer library for: hero props, vehicles, characters, anything whose silhouette must read as a specific recognisable object.

## Degradation

With no assets downloaded the demo runs on primitive shapes and asset-dependent tests skip with a hint. This is good for CI and dangerous for you: **a wrong model id degrades to a primitive rather than erroring.** Assert `renderer.model_is_loaded(id)` in any test whose claim depends on real geometry.

## Credits

All CC0; attribution is not required by the licence. Credit anyway — machine-readable attribution is in `resources/CREDITS.toml` so a published `makepad-game-pkg` package carries credit with it. Kenney (47 model packs, five starter kits, seven sound packs) and KayKit / Kay Lousberg (nine rigged characters on one 41-joint skeleton).