Asset loading, cache and metadata (asset.* kits) #

How the files of a game reach the player: loaded in the order the game needs them, kept between two visits, and described by their passport. Readable offline: gripforge docs asset-preload, or the MCP tool gripforge_docs (topic asset-preload).

The map #

All three require only game.engine and are services (role service). asset.preload reads asset.cache before downloading and writes to it afterwards. The loading view is another module: the title screen of ui.menu, ui.endscreen between two levels, the bar of hud.action (loadingBar: true), or the page.

Turn it on #

gripforge_gamekit_install   { project_id: "gkp_…", id: "asset.preload" }
gripforge_gamekit_install   { project_id: "gkp_…", id: "asset.cache" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "asset.preload", config: { "aheadScenes": 2, "concurrency": 4 } }

Only the keys that differ from the defaults need to be written. The full reference of a kit is gripforge kit api <id>.

asset.preload #

The plan #

Every file goes in one phase:

Inside a phase, higher priority first, then the order of the game. One download per file: every caller gets the same promise while it downloads, then the same bytes (the page, the web player, several kits, several labels of one glTF). A file with a SHA-256 is read from asset.cache first, checked (size, SHA-256, then the host's format check) and kept for the next visit. A request jumps the queue.

Settings and defaults #

The game shapes the plan with documents of the collection asset_preload (moddable, so a mod does the same):

{ "id": "boss_early", "asset": "boss", "phase": "first", "priority": 10 }
{ "id": "intro_movie", "asset": "assets/intro.webm", "remove": true }
{ "id": "extra_music", "path": "assets/music/night.ogg", "sha256": "…", "bytes": 4200000, "phase": "next", "scene": "night" }

State, events, service #

Variables: asset.preload.phase (idle, first, background, next, done), asset.preload.progress (0 to 1), asset.preload.first_ready, asset.preload.source (cache, network, mixed). Events: asset.preload.planned, .phase, .progress (phase, ratio, first_ratio, downloaded_bytes, total_bytes, verified, count, from_cache, from_network, source), .loaded, .failed, .done, .ahead, .started, .complete, .released. Service: plan(), progress(), request(path, priority?), prioritize(path, priority, phase?), prefetch(scene), cancel(path?), ledger().

Hook asset.preload.plan { id, path, phase, priority, scene, bytes }: phase and priority can change; cancelled, the file leaves the plan and is loaded only when asked. A mod may override enabled, defaultPhase, nextScenes, aheadScenes, concurrency, memoryMB, rules and add documents to asset_preload.

asset.cache #

The store is IndexedDB in a page, else Cache Storage with a service worker scoped to the game, else the HTTP cache through the servers' headers, else memory or nothing. The key is the path and the SHA-256 (assets/scene.glb@<sha>): a new version has another key, so it is downloaded and the old entry of the path is removed. A file without a checksum is never kept. A browser that refuses storage gives mode: off and the game plays, each file still downloaded once.

Service: stats() (mode, entries, bytes, quota, hits, misses, writes, evicted), entries(), invalidate(path), clear(), write, read. Variables asset.cache.mode, asset.cache.bytes, asset.cache.entries. Hooks asset.cache.store { path, sha, bytes } (cancel: not kept) and asset.cache.evict. A mod may override enabled, quotaMB, fallbacks, eviction, minBytes. The servers answer Cache-Control: immutable for a name that carries its version, and an ETag (the SHA-256) otherwise.

asset.meta #

Every asset carries a mesh passport (lib_….gfmesh.json, next to the file in the library): real size, orientation, skeleton, colliders, clips, and one section per game kit (kits.<section>, owned by the kit that reads it; the first is lod for render.lod: triangles, radius, levels, category, impostor, ratios, screenSizes, shadow levels). The measured values are auto, the user's corrections are manual and always win; the game receives the resolved passport.

Passports are documents of the project collection asset_passports, one per bound slot, filled from the library when the web bundle or an engine delivery is built:

{ "id": "tree", "item": "lib_…", "kind": "prop", "name": "Old oak",
  "passport": { "etalon": { "height": 7.4 }, "kits": { "lod": { "category": "vegetation", "triangles": 18200, "radius": 4.1 } } } }

The kit has no config. Service: of(ref) (the resolved passport or null), section(ref, name), info(ref), has(ref), ids(), register(id, passport, info), bind(entity, id), reload(); ref is an entity id, a slot id or a library id. Event asset.meta.changed { id }. A kit that reads it must work without it: an asset without a passport answers null.

const lod = services.get('asset.meta')?.section(entityId, 'lod'); // null: use your own defaults

Nothing is moddable: a passport is the measured truth of an asset, so a mod that adds or patches an asset_passports document is refused (collection_not_moddable). A mod changes what the game does with an asset, not what the asset is.

Engines #

When it does not do what you expect #