---
title: "ecs"
description: "The ecs namespace — the engine's Luau API reference for ecs."
section: "API Reference"
slug: "api-ecs"
canonical: "https://origozero.ai/docs/api-ecs"
updated: "2026-09-05T23:13:46.343511369+00:00"
tags: ["api", "reference"]
---

# ecs

The `ecs` namespace — 40 functions.

## ecs/AudioListener {#ecs-audiolistener}

```lua
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**

- `fields` `any` _(optional)_ — The component's fields

**Returns** `any` — A component value to pass to ecs.insert / ecs.set.

## ecs/AudioSource {#ecs-audiosource}

```lua
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**

- `fields` `any` _(optional)_ — The component's fields

**Returns** `any` — A component value to pass to ecs.insert / ecs.set.

## ecs/Camera {#ecs-camera}

```lua
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**

- `fields` `any` _(optional)_ — The component's fields

**Returns** `any` — A component value to pass to ecs.insert / ecs.set.

## ecs/Collider {#ecs-collider}

```lua
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**

- `fields` `any` _(optional)_ — The component's fields

**Returns** `any` — A component value to pass to ecs.insert / ecs.set.

## ecs/CollisionGroups {#ecs-collisiongroups}

```lua
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**

- `fields` `any` _(optional)_ — The component's fields

**Returns** `any` — A component value to pass to ecs.insert / ecs.set.

## ecs/Light {#ecs-light}

```lua
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**

- `fields` `any` _(optional)_ — The component's fields

**Returns** `any` — A component value to pass to ecs.insert / ecs.set.

## ecs/Material {#ecs-material}

```lua
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**

- `fields` `any` _(optional)_ — The component's fields

**Returns** `any` — A component value to pass to ecs.insert / ecs.set.

## ecs/Mesh {#ecs-mesh}

```lua
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**

- `fields` `any` _(optional)_ — The component's fields

**Returns** `any` — A component value to pass to ecs.insert / ecs.set.

## ecs/MorphWeights {#ecs-morphweights}

```lua
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**

- `fields` `any` _(optional)_ — The component's fields

**Returns** `any` — A component value to pass to ecs.insert / ecs.set.

## ecs/Physics {#ecs-physics}

```lua
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**

- `fields` `any` _(optional)_ — The component's fields

**Returns** `any` — A component value to pass to ecs.insert / ecs.set.

## ecs/PhysicsJoint {#ecs-physicsjoint}

```lua
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**

- `fields` `any` _(optional)_ — The component's fields

**Returns** `any` — A component value to pass to ecs.insert / ecs.set.

## ecs/PlayerOwned {#ecs-playerowned}

```lua
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**

- `fields` `any` _(optional)_ — The component's fields

**Returns** `any` — A component value to pass to ecs.insert / ecs.set.

## ecs/RetargetProfile {#ecs-retargetprofile}

```lua
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**

- `fields` `any` _(optional)_ — The component's fields

**Returns** `any` — A component value to pass to ecs.insert / ecs.set.

## ecs/Skeleton {#ecs-skeleton}

```lua
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**

- `fields` `any` _(optional)_ — The component's fields

**Returns** `any` — A component value to pass to ecs.insert / ecs.set.

## ecs/Sky {#ecs-sky}

```lua
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**

- `fields` `any` _(optional)_ — The component's fields

**Returns** `any` — A component value to pass to ecs.insert / ecs.set.

## ecs/Tessellation {#ecs-tessellation}

```lua
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**

- `fields` `any` _(optional)_ — The component's fields

**Returns** `any` — A component value to pass to ecs.insert / ecs.set.

## ecs/Transform {#ecs-transform}

```lua
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**

- `fields` `any` _(optional)_ — The component's fields

**Returns** `any` — A component value to pass to ecs.insert / ecs.set.

## ecs/TransformConstraints {#ecs-transformconstraints}

```lua
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**

- `fields` `any` _(optional)_ — The component's fields

**Returns** `any` — A component value to pass to ecs.insert / ecs.set.

## ecs/VisibilityRange {#ecs-visibilityrange}

```lua
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**

- `fields` `any` _(optional)_ — The component's fields

**Returns** `any` — A component value to pass to ecs.insert / ecs.set.

## ecs/WheelCollider {#ecs-wheelcollider}

```lua
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**

- `fields` `any` _(optional)_ — The component's fields

**Returns** `any` — A component value to pass to ecs.insert / ecs.set.

## ecs/bind {#ecs-bind}

```lua
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**

- `id` `string | entityRef` — The entity id or proxy
- `component` `string` — The Rust component name
- `field` `string` — The Rust field name
- `mode` `string` _(optional)_ — The access mode

**Returns** `any` — The field handle or nil.

## ecs/bindEntities {#ecs-bindentities}

```lua
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}

```lua
ecs.blobs.clear(handle)
```

Release a staged blob by its handle.

**Parameters**

- `handle` `string` — A handle returned by ecs.blobs.set

## ecs/blobs/get {#ecs-blobs-get}

```lua
ecs.blobs.get(handle) -> string?
```

Read back the bytes for a blob handle.

**Parameters**

- `handle` `string` — A handle returned by ecs.blobs.set

**Returns** `string` — The staged bytes or nil.

## ecs/blobs/set {#ecs-blobs-set}

```lua
ecs.blobs.set(bytes) -> string
```

Stage a file's bytes and return a handle to pass through a component field.

**Parameters**

- `bytes` `string` — The raw bytes to stage

**Returns** `string` — The blob handle.

## ecs/components {#ecs-components}

```lua
ecs.components(id) -> { string }?
```

The public component names present on an entity or nil.

**Parameters**

- `id` `string | entityRef` — The entity id or proxy

**Returns** `{ string }` — Public component names or nil.

## ecs/describe {#ecs-describe}

```lua
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**

- `which` `any` _(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}

```lua
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}

```lua
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**

- `id` `string | entityRef` — The entity id or proxy
- `descriptor` `any` — A component type such as ecs.Transform

**Returns** `any` — The component handle or nil.

## ecs/has {#ecs-has}

```lua
ecs.has(id, descriptor) -> boolean
```

Whether an entity has the given component type.

**Parameters**

- `id` `string | entityRef` — The entity id or proxy
- `descriptor` `any` — A component type such as ecs.Transform

**Returns** `boolean` — True when the component is present.

## ecs/insert {#ecs-insert}

```lua
ecs.insert(id, value) -> Promise
```

Asynchronously upsert a component value onto an entity — await the returned promise for same-tick visibility.

**Parameters**

- `id` `string | entityRef` — The entity id or proxy
- `value` `any` — A typed component value such as ecs.Mesh{...}

**Returns** `any` — Resolves once the component is applied.

## ecs/insertMany {#ecs-insertmany}

```lua
ecs.insertMany(ids, value) -> number
```

Insert one component value into many entities in a single FFI crossing.

**Parameters**

- `ids` `{ string | entityRef }` — The target entities
- `value` `any` — A typed component value such as ecs.Mesh{...}

**Returns** `number` — The count applied this tick.

## ecs/insertSync {#ecs-insertsync}

```lua
ecs.insertSync(id, value)
```

Upsert a component value onto an entity so it is visible this tick. Raises on failure.

**Parameters**

- `id` `string | entityRef` — The entity id or proxy
- `value` `any` — A typed component value such as ecs.Mesh{...}

## ecs/len {#ecs-len}

```lua
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**

- `id` `string | entityRef` — The entity id or proxy
- `descriptor` `any` — A component type such as ecs.Transform
- `field` `string` — 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}

```lua
ecs.query(...) -> { entityRef }
```

Like ecs.queryIds but returns entity proxies instead of id strings.

**Parameters**

- `...` `any` — One or more component terms — an ecs.<Name> descriptor or a script component name

**Returns** `{ any }` — The matching entity proxies.

## ecs/queryIds {#ecs-queryids}

```lua
ecs.queryIds(...) -> { string }
```

The entity ids holding every one of the given component types. A term is an ecs.<Name> descriptor (ecs.Camera) or the name of a script component ("PlayerSpawn"); the two mix in one call. Index-backed, so the cost is the number of matches rather than the size of the scene.

**Parameters**

- `...` `any` — One or more component terms — an ecs.<Name> descriptor or a script component name

**Returns** `{ string }` — The matching entity ids.

## ecs/remove {#ecs-remove}

```lua
ecs.remove(id, descriptor)
```

Remove a component type from an entity.

**Parameters**

- `id` `string | entityRef` — The entity id or proxy
- `descriptor` `any` — A component type such as ecs.Transform

## ecs/set {#ecs-set}

```lua
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**

- `id` `string | entityRef` — The entity id or proxy
- `value` `any` — 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}

```lua
ecs.snapshot(id) -> table?
```

Every native component on an entity as a nested table keyed by public component name or nil.

**Parameters**

- `id` `string | entityRef` — The entity id or proxy

**Returns** `table` — Component data keyed by public name or nil.

## ecs/types {#ecs-types}

```lua
ecs.types() -> { string }
```

The public component names available as ecs.<Name>.

**Returns** `{ string }` — Sorted public component names.