# Asset metadata (asset.meta)

## What it is for

Every asset of the game can say what it really is: its mesh passport holds the real size, the orientation, the skeleton, the colliders and the clips, plus sections that game kits own (for example `lod`, read by the level-of-detail kit: mesh levels, texture sizes, cull distance, impostor, far shadows, category). `asset.meta` hands these passports to the other kits at run time as plain data. It is optional for every kit: without it, or for an asset without a passport, kits use their own defaults. It is one of three kits that work together: see the [asset loading guide](guide:asset-preload).

## Turn it on

```text
gripforge_gamekit_install { project_id: "gkp_…", id: "asset.meta" }
```

It has no setting; install it and the other kits that want passports read them. The passports of the bound assets travel with the game, in the project data collection `asset_passports`; a game can add or correct documents.

## First example

<!-- test: kits/game_engine/host/tests/asset_meta.rs::a_passport_is_found_by_key_by_entity_slot_and_by_library_id -->
A passport is found by its key, by the model slot of an entity (then without its variant), or by Library id. A passport registered at run time is merged over the shipped one, its kit sections one level deeper.

```text
data asset_passports = [ { "id": "hero", "item": "lib_1", "passport": { "rig": "humanoid", "kits": { "lod": { "cull": 120 } } } },
                         { "id": "hero:red", "passport": { "rig": "red" } } ]
of(<entity with model { slot: "hero", variant: "red" }>)  -> { "rig": "red" }
of(<entity with model { slot: "hero", variant: "blue" }>) -> { "rig": "humanoid" }
info("lib_1").id -> "hero"            section("hero", "lod") -> { "cull": 120 }       of("nope") -> null
register("hero", { "rig": "custom", "kits": { "lod": { "far": true } } })
of("hero") -> { "rig": "custom", "kits": { "lod": { "cull": 120, "far": true } } }
```

## Settings and defaults

The kit has no setting and nothing to configure: the passports are the measured truth of the assets (written by the bundle and the engine deliveries), so a mod cannot rewrite them. A mod changes what the game does with an asset, not what the asset is.

A passport is free-form plain data in metres with +Y up, shaped like `{ etalon, orientation, rig, colliders, anim, kits: { lod: { … } } }`; a document of the collection is `{ id, item, kind, name, passport }` where `id` is the slot (or `slot:variant`, or a Library id).

## Services

- `of(ref)`: the resolved passport, or null; `ref` is an entity id, a slot id or a Library id.
- `section(ref, name)`: one kit section of the passport, for example `section("hero", "lod")`.
- `info(ref)`: the document around the passport (`id`, `item` the Library id, `kind`, `name`); `has(ref)` tells whether there is one; `ids()` lists the keys.
- `register(id, passport, info)`: adds or merges a passport at run time (a kit may register what it measured); `bind(entity, id)` ties an entity to a passport; `reload()` reads the collection again.

## Events

- `asset.meta.changed` (payload `{ id }`): a passport was registered or removed at run time, or an entity was bound to an asset; `id` is the key, or the entity.

## When it does not do what you expect

- `of(ref)` answers null: there is no passport for that key, slot or Library id; kits then use their own defaults, so add a document to `asset_passports` or `register` one.

## Limits

- It decides nothing about the game: it only hands data to the kits that ask, and it has no hook.
- Web, native, Godot, Unity and Unreal serve the same passports with the same model; engine entities are matched through their `model` component.

## Versions

1.1.0 (2026-10-10): attached to `game.engine` as a service, no behaviour change; 1.0.0 (2026-10-02): first release. Requires `game.engine`.