asset Module

Public Luau surface over the __asset Internal FFI namespace — asset resolver, ref envelope builder, sidecar metadata.

Purpose

Wrap the raw __asset.* FFI namespace in a typed Luau table that gets auto-injected as _G.asset via the prelude. Three families:

• Lookup — resolve, ref, typeRef, inspect, source, identity, guid, meta, deps. Every op accepts any name an asset has (handle, guid, identity, path, bare name) and returns the requested view.
• Discovery — categories, list, containing.
• Generic .metadata sidecar — metadata, set_metadata, field-level get_field / set_field / remove_field / has_field, tag helpers (tags, has_tag, add_tag, remove_tag), and validate.

The previously-FFI bundle.* namespace was dissolved into the bundle assetType (see src/lua/lib/assetTypes/bundle.assetType/); that's not exposed here. The prelude mints bundle separately as a thin Luau table grafted from bundle_update.

Usage

-- Lookup
local cam = asset.resolve("@builtin::components.Camera")
local ref = asset.ref("animations.idle", "animation")
print(asset.identity(cam), asset.guid(cam), asset.source(cam))

-- Discovery
for _, c in ipairs(asset.categories()) do print(c) end
for _, sceneRef in ipairs(asset.list("scene")) do print(sceneRef.identity) end
local s = asset.containing("/zero/source/scenes/main.scene/scene.json")

-- Metadata sidecar (agent-editable)
asset.set_field(ref, "category", "movement")
asset.add_tag(ref, "looping")
print(asset.has_tag(ref, "looping"))

-- Structural validation
local v = asset.validate(cam)
for _, p in ipairs(v.problems) do print(p.severity, p.message) end

Exports

• Lookup: resolve, ref, typeRef, inspect, source, identity, guid, meta, deps.
• Discovery: categories, list, containing.
• .metadata sidecar: metadata, set_metadata, get_field, set_field, remove_field, has_field, tags, has_tag, add_tag, remove_tag, list_fields, list_field_values.
• Validation: validate.