Assets
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 |
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.
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; onlycooked/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_unloadfrees 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.