handle

Lazy handle over a present component, returned by ecs.get(id, ecs.<Name>). It retains a bind accessor per field (resolved once, reused, revalidated) and closes over the component's compiled conversion plan, so reads and writes stay live without re-crossing into the native substrate.

Reads

Index the handle by the public (mapped) field name you construct with — h.castsShadows, h.tint — or by the underlying rust field name — h["casts_shadows"], h["tint_r"]. Public names win when both resolve. A vec3 field recomposes into { x, y, z } (also mirrored to [1], [2], [3]). Reads are live, never stale.

Writes

Assign to the same names you read: h.castsShadows = false, h.tint = { 1, 0, 0 }. The assignment writes the component's row, so the read after it answers what the component holds. handle:set(key, value) is the same write in method form.

The component's row is the handle's only store — a name the component does not have raises, and a value the field will not take leaves the field as it was and warns, naming the component, the field under the name you wrote it as, and the value refused.

Methods

• handle:set(key, value) -> handle — write a field by public or rust name; resolves and coerces handle-typed fields, and expands a vec3 into its three scalars. Returns the handle.
• handle:read() -> table — batch-read every rust field in one pass (point-in-time copy keyed by rust field name).
• handle:release(): destroy the retained bind accessors now. A handle nothing reaches gives them back on its own once the collector frees it.

A behavior-bearing component (e.g. Physics) also attaches its per-entity imperative methods directly on the handle, each bound to this entity's id.

Usage

local body = ecs.get(id, ecs.Mesh)
local visible = body.visible
body.castsShadows = false
body:set("tint", { 1, 0, 0 })