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.

Turn it on #

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.

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.