Builtin Library
README.md
asset_residency
Compute backends for the lazy residency properties on every AssetRef
(has_backing_asset, has_runtime_changes, cpu_resident, gpu_resident).
The AssetRef
metatable's __index dispatcher (assetType.shared.ref) calls these only when a
caller actually reads a flag — nothing is computed at resolve time, so an asset
costs nothing for residency until it is observed.
The three backing/runtime states:
has_backing_asset | has_runtime_changes | Meaning |
|---|---|---|
| true | false | USED, UNMODIFIED |
| true | true | USED, MODIFIED (copy-on-write fork) |
| false | true | RUNTIME-GENERATED |
cpu_resident and gpu_resident are orthogonal to those three, and to each
other. cpu_resident asks "is this asset referenced from a live
script-component context, so its bytes are warmed in memory?" (the
/runtime/assets/ CPU layer); gpu_resident asks whether the device holds a
texture or mesh under the asset's guid. They are separate pools and an asset
can be in one and not the other — asset.observe() lists both. See
docs/specs/runtime-asset-copying.md — "CPU residency vs GPU residency".
The backing/runtime flags are derived from where the asset lives — source under
/zero/source/… (backed), a copy-on-write fork / runtime-generated asset under
/zero/runtime/assets/<identity>.<category>/ (runtime change) — using the
canonical <identity>.<category>/ suffix shape, generic over any category.
cpu_resident and gpu_resident are live queries through asset.cpuResident
and asset.gpuResident.