# Asset search

## Getting the library

```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, download nothing
./apps/arcade/download_assets.sh --transcode            # ogg -> wav, needs ffmpeg
```

Gitignored, pinned (starter kits to exact GitHub commits, the rest to content-hashed kenney.nl URLs), every file sha256-verified. Sequential with a delay by design.

Mirrors — `resources/MIRROR.toml` carries URL, sha256, size and model count per pack:

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

A mirror serves `<base>/<slug>.zip` and is **never trusted more than upstream**: the sha256 is verified identically whichever host served the bytes.

## How search works

Query by **description**, never filename. The agent gets `find_model` plus a one-paragraph summary — never the catalogue, which at 5000 entries would not fit a prompt (and the summary stays ~480 characters however large the library grows).

Three findability layers: per-pack theme curation (~55 rows, giving every model a setting), filename token parsing (free — Kenney's names are systematic), and a query-time synonym table (~240 rows) applied across the whole catalogue. Item-level curation is spent only on the few hundred most-requested things.

Query-side stemming means an inflected request still reaches a base-form alias ("smashing" → the `smash` alias). On a score tie, the kind the query implies wins: an unqualified noun like "spaceship" is an object request, while "metal clang" or "win music" wants something audible.

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

## Writing queries

Describe the **thing**, with the attributes that matter:

- Good: `yellow pickup truck`, `medieval wooden door`, `pine tree`, `rusty barrel`
- Poor: `vehicle-truck-yellow.glb` (filename), `something cool for the level` (no referent), `player` (a role, not an object)

Narrow with `Filters` and `AssetKind` when the kind is ambiguous. Use `CATEGORIES` to browse what exists before assuming a gap.

## Ids

`kenney/racing/vehicle-truck-yellow` — `pack / kit / model`. Stable across re-downloads, which is the property that makes it safe for generated game code to write them into source.

Resolve ids once at load, then assert:

```rust
assert!(renderer.model_is_loaded(id), "missing {id}");
```

Without this, a typo'd id silently renders a primitive and looks like a style choice.

## Kits

`KitInfo` describes a set of models designed together — consistent scale, palette and grid. **Build a scene from one kit**, or the mismatch in scale and style reads immediately as assembled-from-parts. `kit_from_index` and `level_placements` in `makepad-game-script::compose` place kit tiles (`PlacedTile`).

## Casts

`find_cast` / `CastInfo`. A cast shares one skeleton, so any clip plays on any member.

| 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 |

KayKit: five adventurers (Knight, Barbarian, Mage, Rogue, Rogue_Hooded) and four skeletons (Warrior, Mage, Rogue, Minion) on one 41-joint rig; adventurers ship 76 clips, skeletons those plus 19 undead extras.

Pick members from **one** cast per scene; use **different** members so a crowd is not clones. Recasting a part is then a one-line change.

## Audio

`AUDIO_CATEGORIES` and the same index. Kenney audio ships `.ogg` only; `makepad-game-audio` decodes Vorbis and WAV to `Pcm`. See `makepad-audio-generator`.

## Degradation

With no assets, the game runs on primitives and asset-dependent tests skip with a hint. Good for CI, dangerous for reporting — always check whether tests skipped before calling them passed.

## Credits

All CC0; attribution is not required by the licence. Credit anyway. `resources/CREDITS.toml` is machine-readable 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) — the rigs and animation sets are the expensive part, and they were given away.