toHandle(ref: ?) → void

Bridge a resource to its live GPU HANDLE for the ecs layer. An AssetRef materialises its GPU resource via `:handle()` (the Disk→CPU→GPU upload — a mesh uploads its geometry, a material uploads the material and its textures) and the handle is returned; a value that already is a handle is returned as-is. The component owns this asset→GPU step and hands the ecs layer a resident handle.

materialHandle(ref: ?) → void

Resolve the material AssetRef to a live GPU handle, robust to a stale guid. A material is registry-keyed by its identity; deleting and recreating one mints a fresh guid and orphans the old, so a saved-scene ref that still carries the old guid resolves to nothing and the mesh renders the white fallback. When the ref's guid is no longer a live material, resolve through the stable identity — which tracks the current material — so the mesh binds the material the author named. The guid stays the preferred lookup; the identity is consulted only when the guid has gone dead.

meshFields( ) → void

Collect the public fields into the ecs.Mesh constructor's input shape. The constructor maps these to MeshInstance's rust fields (tint expands to the per-channel scalars, camelCase -> snake_case for the rest). `mesh` is bridged to its GPU handle (toHandle) so the ecs layer receives a resident GPU resource — the ecs layer just reads the handle's guid.

applyOutline( ) → void

Drive the canonical outline (a jump-flood silhouette rim) from the outline fields. `outlineIntensity` scales the rim's pixel thickness; 0 clears it. The fields and the `setOutline`/`clearOutline` methods share this one path, so authoring the outline as component data renders identically to calling the method.

renderBroken(reason: string) → void

applyMesh( ) → void

Apply `public.model` to the entity's MeshInstance. Absent model → remove the component; present → insert (async; the renderable appears once the mesh load resolves). insert is an upsert, so re-applying re-syncs every renderer-facing field at once.

applyMaterial( ) → void

Apply the entity's rendered material to its MaterialRef: the session material when one is active, else the authored `material`. The renderer pairs MaterialRef with the MeshInstance on the same entity automatically.

awake( ) → void

onPropertyChanged(key: ?, value: ?, _oldValue: ?) → void

onEnable( ) → void

onDisable( ) → void

onError(error: ?) → void

onAssetReload(field: ?) → void

The mesh or material this model draws with was edited in place — same ref, new content. Baked lighting reads a surface's albedo and emissive out of its material and its shape out of its mesh, so tell the bake: nothing about this entity changed, but the light it bounces did.

onDestroy( ) → void

setTint(color: table, blend: number?) → void

Set the mesh tint colour and blend amount. are 0-1.

model:setTint({1, 0, 0})

model:setTint({r = 1, g = 0, b = 0}, 0.5)

clearTint( ) → void

Reset the tint so the mesh renders with its original material colour.

model:clearTint()

setOutline(color: table, intensity: number?) → void

Set the outline colour and intensity for this mesh. values are 0-1.

model:setOutline({0, 1, 0})

model:setOutline({r = 1, g = 1, b = 0}, 0.8)

clearOutline( ) → void

Remove the outline from this mesh.

model:clearOutline()

sessionSchema( ) → any

The session copy's vocabulary — the properties its record carries and the texture slots it binds — in the shape `MaterialSchema.route` reads, held by the renderer module per record and answered as a table lookup. A write resolves its key here and asks the renderer nothing: what the renderer holds for the material is a different document, and reading it is a cost no write pays. nil when the record carries neither, which writes every key as the caller spelled it: the permissive stance the authored path takes when a shader's schema can't be resolved.

routeSessionWrite(schema: any?, name: string, value: any) → void

Where a written key lands on the session copy — the surface its shader declares the name under, and the name it declares. With no vocabulary reported the key is taken as the caller spelled it.

setMaterialProperty(property: string, value: any) → void

Set a property on this Model's material. With a session material active (see `applySessionMaterial`), the write lands on this entity's session copy alone; otherwise it changes the shared material at runtime, which every entity sharing it takes since material properties are registry-wide. Either way the change reaches the GPU and not the material's `mat.yaml` — call `material:saveDefinition()` to write the current values into the asset. The key resolves against the material's declared vocabulary on both targets, so the same name reaches the same uniform.

model:setMaterialProperty("baseColor", {1, 0, 0, 1})

model:setMaterialProperty("roughness", 0.5)

setMaterialProperties(props: { [string]: any }) → number

Set many properties on this Model's material in one call, the plural of `setMaterialProperty` and with the same target: this entity's session copy when one is active, else the authored material every entity sharing it takes. Each key resolves against the material's declared vocabulary the way the singular resolves it; a property the material's shader does not expose is skipped, so one patch table serves models on different shaders.

model:setMaterialProperties({ roughness = 0.2, metallic = 0.9 })

getMaterialProperty(property: string) →

Read a property from this Model's material — the session material when one is active, else the authored material.

local color = model:getMaterialProperty("baseColor")

getMaterialPropertyNames( ) →

List all property names available on this Model's material — the session material when one is active, else the authored material.

for _, name in ipairs(model:getMaterialPropertyNames()) do print(name) end

resolveMobility( ) → string

Resolve this entity's effective mobility: `"static"` (stands still — receives lightmaps, occludes baked light) or `"movable"` (moves — samples probe volumes for indirect light). An explicit `mobility` field value wins; `"auto"` derives it from the entity AND everything carrying it: anything that animates, simulates, or is driven (a non-static `Physics` body, a `SkinnedModel`, a `ClipPlayer`, a `Mover`/`FreeMover` — on this entity or any ancestor — or a non-world runtime participation) is movable, everything else is static.

if model:resolveMobility() == "static" then Lightmap.bake(id) end

applySessionMaterial(handle: any) → void

Show a session-created runtime material on this Model in place of its authored material. The authored `material` field is never touched — persisted state always carries the authored ref, so nothing broken can be saved. The handle is kept in the session store under `renderer.material.sessionKeyFor(entityId)`, so awake re-adopts it across VM reloads; on a fresh boot (runtime materials gone) the Model renders its authored material again automatically. Called with no handle, it copies this Model's current material into a fresh session material keyed to this entity, so later `setMaterialProperty` edits land on the copy instead of the shared authored material. A copy per entity is what a DIFFERENT LOOK per entity costs — its own pipeline binding and its own row in the material table. When entities want the same look and differ only in a VALUE, `renderer.instanceData.set` writes one of the four `vec4` lanes every drawn object already carries, which the shader reads as `input.shader_data[lane]`, and one material serves them all. and `renderer.material.animatedTexture` return it. Its `guid` field is the material's registry key, which is what `renderer.material.setProperty` / `describe` / `destroy` take; this call takes the handle itself. Omit to copy this Model's current material into a new session material.

model:applySessionMaterial(handle)

model:applySessionMaterial()  -- copy the current material for per-entity edits

restoreSessionMaterial( ) → boolean

End the session-material swap: the Model renders its authored material again.

model:restoreSessionMaterial()