entity_reflect

High-level entity introspection and manipulation utilities. Wraps the __reflect FFI global with a cleaner API — no per-script component declaration needed; every method goes through the reflection layer so it works on any entity that carries the relevant component.

Exposed as the Entity global via the --!global Entity directive.

Exports

• Entity.getField(entityId, component, field) -> any / Entity.setField(entityId, component, field, value) -> boolean — generic reflected read/write.
• Entity.getPosition(id) -> Vec3? / Entity.setPosition(id, pos) — Transform.position shortcuts.
• Entity.getRotation(id) -> Quat? — Transform.rotation shortcut.
• Entity.getScale(id) -> Vec3? / Entity.setScale(id, scale) — Transform.scale shortcuts.
• Entity.getName(id) -> string? — Name component read.
• Entity.isVisible(id) -> boolean — Visible component read; missing component is treated as visible.
• Entity.getComponents(id) -> { string }? — list reflected components on this entity.
• Entity.getSchema(componentName) -> { ComponentFieldSchema }? — list field names + types for a component type.
• Entity.snapshot(id) -> any — full { ComponentName = { field = value, ... }, ... } dump.
• Entity.patch(id, component, fields) -> boolean — multi-field update.
• Entity.distance(idA, idB) -> number? — straight-line distance between two entities' Transform.position.
• Entity.allTypes() -> { string } — list every registered reflectable component type.

Types:

• Vec3 = { x: number, y: number, z: number }
• Quat = { x: number, y: number, z: number, w: number }
• ComponentFieldSchema = { name: string, type: string }

Usage

-- `Entity` is a global (--!global Entity); no require needed.

local pos = Entity.getPosition("player")
Entity.setPosition("player", { x = 0, y = 1, z = 0 })

local snap = Entity.snapshot("player")
Entity.patch("player", "Transform", {
    position = { x = 0, y = 1, z = 0 },
    scale    = { x = 1, y = 1, z = 1 },
})

Notes

• Every method goes through the __reflect FFI — nil returns mean the component or field is missing, not that the entity is gone. Use Entity.getComponents(id) to enumerate what's there.
• isVisible treats a missing Visible component as visible (v == nil returns true).
• Entity.distance returns nil when either entity lacks a position; callers should branch on nil before using the result.
• The --!global Entity directive is what makes Entity the global name — the module's local E variable is just an implementation detail.