handles

Loads the native components a saved record lists. A record (a scene entity, a bundle entity_template entry) states its native components beside its script components as ecs = { { type = "<public name>", data = <row> } }: type is the name the component answers to under ecs, and data is the row ecs.snapshot answers for it. Every field that holds a GPU handle is written as the guid of the ASSET the handle came from, because the guid outlives the session and the handle does not.

Loading resolves each of those guids to the handle the component holds (ref:handle(), the call a Model makes, which puts the asset on the GPU) and inserts one value into every entity that states the same entry.

Exports

• M.handleFields(typeName) -> { { rust, category } }? - the fields of a native component that hold a GPU handle, each with the asset category its guid names (mesh, material or texture). nil for a name ecs does not hold.
• M.value(entry, site?) -> value - the component value one { type, data } entry states, ready for ecs.insert. A guid that names no asset of the field's category raises, naming the component and field. site is the path or identity of the asset the entry was read from: a site inside a carried mount reads each guid within that mount's closure (asset.tryResolve(guid, category, site)).
• M.insertAll(specs, site?) -> failures - inserts { id, type, data } specs, one ecs.insertMany per distinct (type, data), reading every guid at site the way M.value does. Answers one { type, ids, message } per entry that did not land.

Usage

local handles = require("modules.api.engine.ecs.handles")
local failed = handles.insertAll({
    { id = a, type = "Mesh", data = { mesh = meshGuid } },
    { id = b, type = "Mesh", data = { mesh = meshGuid } },
    { id = a, type = "Material", data = { id = materialGuid } },
})
for _, failure in ipairs(failed) do
    log.error(failure.type .. ": " .. failure.message)
end

The scene loader and bundle:instantiate call insertAll after a record's script components are added.