# Assets

> Drop source files in assets/, the build cooks them, and the game loads them asynchronously by path.

Your source files (models, textures, sounds, fonts, your own data) go in `assets/`. The build *cooks* them into `cooked/`: the format each platform's GPU and audio want, compressed, ready to load in one read. The game only ever loads cooked files, and `assets/` isn't shipped.

| Kind | Source formats |
|---|---|
| Models and animations | `.glb`, `.gltf`, `.fbx`, `.vrm` |
| Images | `.png`, `.jpg`, `.webp`, `.hdr` (environments) |
| Audio | `.wav`, `.flac`, `.mp3` |
| Video | `.mp4` |
| Everything else | `.hzt`: materials, scenes, your own [data files](https://kaigen3d.com/docs/data) |

Cooking is incremental: only what changed is recooked. A model brings its materials and textures with it.

## Loading

Every load is asynchronous. `asset_load` returns a handle right away, and the asset is ready some frames later.

Loading a model and putting it in the world:

```
HzHandleT(ModelBlobAsset) tree =
    asset_load(ModelBlobAsset, assets, .path = "my_game/tree.glb");

// once asset_is_ready(assets, tree)
ecs_renderer_spawn(world, renderer, &(EcsRendererSpawnDesc){
    .model_asset = blob_asset_ref_from_handle(ModelBlobAsset, tree),
    .transform = {{2, 0, 5}, quat_identity(), V3_ONE}, // position, rotation, scale
    .casts_shadow = true,
});
```

Most of the time you don't load models from code at all: you place them in a scene with the editor, and the scene loads what it needs.

If you need to know exactly when something finished, `asset_load_cb` calls you back on the main lane when it's ready.

## Worth knowing

- Paths are relative to `assets/` and always the *source* name (`my_game/tree.glb`), on every platform.
- Never read files from `assets/` yourself. It isn't on the phone or the web page; only `cooked/` is.
- In debug builds, loading an asset whose source is newer than its cooked file stops with "run hz/hzbuild cook".
- Loads are reference counted. `asset_unload` frees an asset when the last user lets go.
- Big worlds can spread loading over frames with a budget (`asset_system_set_budget`) and priorities.

The API is in `hz/src/engine/assets/assets.h`.
