ecs
The ecs namespace — 40 functions.
ecs/AudioListener
ecs.AudioListener(fields?) -> value
Typed constructor for the AudioListener component — ecs.AudioListener{...} builds a value the ecs verbs apply. Call ecs.AudioListener:schema() for its fields.
Parameters
fieldsany(optional) — The component's fields
Returns any — A component value to pass to ecs.insert / ecs.set.
ecs/AudioSource
ecs.AudioSource(fields?) -> value
Typed constructor for the AudioSource component — ecs.AudioSource{...} builds a value the ecs verbs apply. Call ecs.AudioSource:schema() for its fields.
Parameters
fieldsany(optional) — The component's fields
Returns any — A component value to pass to ecs.insert / ecs.set.
ecs/Camera
ecs.Camera(fields?) -> value
Typed constructor for the Camera component — ecs.Camera{...} builds a value the ecs verbs apply. Call ecs.Camera:schema() for its fields.
Parameters
fieldsany(optional) — The component's fields
Returns any — A component value to pass to ecs.insert / ecs.set.
ecs/Collider
ecs.Collider(fields?) -> value
Typed constructor for the Collider component — ecs.Collider{...} builds a value the ecs verbs apply. Call ecs.Collider:schema() for its fields.
Parameters
fieldsany(optional) — The component's fields
Returns any — A component value to pass to ecs.insert / ecs.set.
ecs/CollisionGroups
ecs.CollisionGroups(fields?) -> value
Typed constructor for the CollisionGroups component — ecs.CollisionGroups{...} builds a value the ecs verbs apply. Call ecs.CollisionGroups:schema() for its fields.
Parameters
fieldsany(optional) — The component's fields
Returns any — A component value to pass to ecs.insert / ecs.set.
ecs/Light
ecs.Light(fields?) -> value
Typed constructor for the Light component — ecs.Light{...} builds a value the ecs verbs apply. Call ecs.Light:schema() for its fields.
Parameters
fieldsany(optional) — The component's fields
Returns any — A component value to pass to ecs.insert / ecs.set.
ecs/Material
ecs.Material(fields?) -> value
Typed constructor for the Material component — ecs.Material{...} builds a value the ecs verbs apply. Call ecs.Material:schema() for its fields.
Parameters
fieldsany(optional) — The component's fields
Returns any — A component value to pass to ecs.insert / ecs.set.
ecs/Mesh
ecs.Mesh(fields?) -> value
Typed constructor for the Mesh component — ecs.Mesh{...} builds a value the ecs verbs apply. Call ecs.Mesh:schema() for its fields.
Parameters
fieldsany(optional) — The component's fields
Returns any — A component value to pass to ecs.insert / ecs.set.
ecs/MorphWeights
ecs.MorphWeights(fields?) -> value
Typed constructor for the MorphWeights component — ecs.MorphWeights{...} builds a value the ecs verbs apply. Call ecs.MorphWeights:schema() for its fields.
Parameters
fieldsany(optional) — The component's fields
Returns any — A component value to pass to ecs.insert / ecs.set.
ecs/Physics
ecs.Physics(fields?) -> value
Typed constructor for the Physics component — ecs.Physics{...} builds a value the ecs verbs apply. Call ecs.Physics:schema() for its fields.
Parameters
fieldsany(optional) — The component's fields
Returns any — A component value to pass to ecs.insert / ecs.set.
ecs/PhysicsJoint
ecs.PhysicsJoint(fields?) -> value
Typed constructor for the PhysicsJoint component — ecs.PhysicsJoint{...} builds a value the ecs verbs apply. Call ecs.PhysicsJoint:schema() for its fields.
Parameters
fieldsany(optional) — The component's fields
Returns any — A component value to pass to ecs.insert / ecs.set.
ecs/PlayerOwned
ecs.PlayerOwned(fields?) -> value
Typed constructor for the PlayerOwned component — ecs.PlayerOwned{...} builds a value the ecs verbs apply. Call ecs.PlayerOwned:schema() for its fields.
Parameters
fieldsany(optional) — The component's fields
Returns any — A component value to pass to ecs.insert / ecs.set.
ecs/RetargetProfile
ecs.RetargetProfile(fields?) -> value
Typed constructor for the RetargetProfile component — ecs.RetargetProfile{...} builds a value the ecs verbs apply. Call ecs.RetargetProfile:schema() for its fields.
Parameters
fieldsany(optional) — The component's fields
Returns any — A component value to pass to ecs.insert / ecs.set.
ecs/Skeleton
ecs.Skeleton(fields?) -> value
Typed constructor for the Skeleton component — ecs.Skeleton{...} builds a value the ecs verbs apply. Call ecs.Skeleton:schema() for its fields.
Parameters
fieldsany(optional) — The component's fields
Returns any — A component value to pass to ecs.insert / ecs.set.
ecs/Sky
ecs.Sky(fields?) -> value
Typed constructor for the Sky component — ecs.Sky{...} builds a value the ecs verbs apply. Call ecs.Sky:schema() for its fields.
Parameters
fieldsany(optional) — The component's fields
Returns any — A component value to pass to ecs.insert / ecs.set.
ecs/Tessellation
ecs.Tessellation(fields?) -> value
Typed constructor for the Tessellation component — ecs.Tessellation{...} builds a value the ecs verbs apply. Call ecs.Tessellation:schema() for its fields.
Parameters
fieldsany(optional) — The component's fields
Returns any — A component value to pass to ecs.insert / ecs.set.
ecs/Transform
ecs.Transform(fields?) -> value
Typed constructor for the Transform component — ecs.Transform{...} builds a value the ecs verbs apply. Call ecs.Transform:schema() for its fields.
Parameters
fieldsany(optional) — The component's fields
Returns any — A component value to pass to ecs.insert / ecs.set.
ecs/TransformConstraints
ecs.TransformConstraints(fields?) -> value
Typed constructor for the TransformConstraints component — ecs.TransformConstraints{...} builds a value the ecs verbs apply. Call ecs.TransformConstraints:schema() for its fields.
Parameters
fieldsany(optional) — The component's fields
Returns any — A component value to pass to ecs.insert / ecs.set.
ecs/VisibilityRange
ecs.VisibilityRange(fields?) -> value
Typed constructor for the VisibilityRange component — ecs.VisibilityRange{...} builds a value the ecs verbs apply. Call ecs.VisibilityRange:schema() for its fields.
Parameters
fieldsany(optional) — The component's fields
Returns any — A component value to pass to ecs.insert / ecs.set.
ecs/WheelCollider
ecs.WheelCollider(fields?) -> value
Typed constructor for the WheelCollider component — ecs.WheelCollider{...} builds a value the ecs verbs apply. Call ecs.WheelCollider:schema() for its fields.
Parameters
fieldsany(optional) — The component's fields
Returns any — A component value to pass to ecs.insert / ecs.set.
ecs/bind
ecs.bind(id, component, field, mode?) -> handle?
A retained accessor for a single component field. The typed front door is ecs.get; component is the Rust component name.
Parameters
idstring | entityRef— The entity id or proxycomponentstring— The Rust component namefieldstring— The Rust field namemodestring(optional) — The access mode
Returns any — The field handle or nil.
ecs/bindEntities
ecs.bindEntities(ids) -> handle
Bind a batch of entity ids for retained access.
Parameters
ids{ string }— The entity ids to bind
Returns any — A batch handle.
ecs/blobs/clear
ecs.blobs.clear(handle)
Release a staged blob by its handle.
Parameters
handlestring— A handle returned by ecs.blobs.set
ecs/blobs/get
ecs.blobs.get(handle) -> string?
Read back the bytes for a blob handle.
Parameters
handlestring— A handle returned by ecs.blobs.set
Returns string — The staged bytes or nil.
ecs/blobs/set
ecs.blobs.set(bytes) -> string
Stage a file's bytes and return a handle to pass through a component field.
Parameters
bytesstring— The raw bytes to stage
Returns string — The blob handle.
ecs/components
ecs.components(id) -> { string }?
The public component names present on an entity or nil.
Parameters
idstring | entityRef— The entity id or proxy
Returns { string } — Public component names or nil.
ecs/describe
ecs.describe(which?) -> table
The runtime component catalog — every component with its fields. Pass a name or descriptor for a single component's schema.
Parameters
whichany(optional) — A component name or descriptor — omit for the full catalog
Returns table — One schema or an array of every component's schema.
ecs/entities
ecs.entities() -> { table }
The whole scene as records, for a caller that reads all of it — serialisation, an inspector listing, a scene diff. It materialises fresh Luau tables on each call, so it costs the size of the scene (~4ms at 471 entities, ~109ms at 2471) whatever the caller was after. To find the entities carrying a component, ecs.queryIds reads an index and costs the number of matches.
Returns { any } — Every entity as a record with id, name and components.
ecs/get
ecs.get(id, descriptor) -> handle?
Get a typed handle to a component on an entity or nil when the component is absent. Indexing the handle reads the field live and assigning to it writes the component — h.intensity = 77 and h:set("intensity", 77) are one operation, so the read after either answers what the component holds. A field that cannot hold the value it is given keeps what it had and the write warns, naming the component, the field under the name you wrote it as, and the value refused.
Parameters
idstring | entityRef— The entity id or proxydescriptorany— A component type such as ecs.Transform
Returns any — The component handle or nil.
ecs/has
ecs.has(id, descriptor) -> boolean
Whether an entity has the given component type.
Parameters
idstring | entityRef— The entity id or proxydescriptorany— A component type such as ecs.Transform
Returns boolean — True when the component is present.
ecs/insert
ecs.insert(id, value) -> Promise
Asynchronously upsert a component value onto an entity — await the returned promise for same-tick visibility.
Parameters
idstring | entityRef— The entity id or proxyvalueany— A typed component value such as ecs.Mesh{...}
Returns any — Resolves once the component is applied.
ecs/insertMany
ecs.insertMany(ids, value) -> number
Insert one component value into many entities in a single FFI crossing.
Parameters
ids{ string | entityRef }— The target entitiesvalueany— A typed component value such as ecs.Mesh{...}
Returns number — The count applied this tick.
ecs/insertSync
ecs.insertSync(id, value)
Upsert a component value onto an entity so it is visible this tick. Raises on failure.
Parameters
idstring | entityRef— The entity id or proxyvalueany— A typed component value such as ecs.Mesh{...}
ecs/len
ecs.len(id, descriptor, field) -> number?
How many elements a collection-valued field holds, counted off the field so none of them are built. Reading the field to measure it converts every element — on a 50-bone Skeleton that is ~1ms against one crossing here — so ask this whenever the question is how many, or whether any.
Parameters
idstring | entityRef— The entity id or proxydescriptorany— A component type such as ecs.Transformfieldstring— The field holding the collection
Returns number — The element count, or nil when the component is absent or the field is not a collection.
ecs/query
ecs.query(...) -> { entityRef }
Like ecs.queryIds but returns entity proxies instead of id strings.
Parameters
...any— One or more component terms — an ecs.descriptor or a script component name
Returns { any } — The matching entity proxies.
ecs/queryIds
ecs.queryIds(...) -> { string }
The entity ids holding every one of the given component types. A term is an ecs.
Parameters
...any— One or more component terms — an ecs.descriptor or a script component name
Returns { string } — The matching entity ids.
ecs/remove
ecs.remove(id, descriptor)
Remove a component type from an entity.
Parameters
idstring | entityRef— The entity id or proxydescriptorany— A component type such as ecs.Transform
ecs/set
ecs.set(id, value) -> (boolean, { string }?)
Patch the fields of a component already present on an entity. Raises when absent — use ecs.insert to create it. A field that cannot hold the value it is given keeps what it had while the rest of the write lands: the call warns naming the component, the field and the value, and names that field in its second return.
Parameters
idstring | entityRef— The entity id or proxyvalueany— A typed component value carrying the fields to patch
Returns (boolean, { string }?) — True and nil when every field landed; false and the public names of the fields that kept the value they had.
ecs/snapshot
ecs.snapshot(id) -> table?
Every native component on an entity as a nested table keyed by public component name or nil.
Parameters
idstring | entityRef— The entity id or proxy
Returns table — Component data keyed by public name or nil.
ecs/types
ecs.types() -> { string }
The public component names available as ecs.
Returns { string } — Sorted public component names.