---
title: "Entity"
description: "The Entity namespace — the engine's Luau API reference for Entity."
section: "API Reference"
slug: "api-entity-2"
canonical: "https://origozero.ai/docs/api-entity-2"
updated: "2026-08-29T15:58:05.935446933+00:00"
tags: ["api", "reference"]
---

# Entity

The `Entity` namespace — 15 functions.

## globals/Entity/allTypes {#globals-entity-alltypes}

```lua
Entity.allTypes() -> { string }
```

List all registered reflectable component types in this engine instance.

**Returns** `{ string }` — Array of component name strings.

```lua
local types = Entity.allTypes()
```

## globals/Entity/distance {#globals-entity-distance}

```lua
Entity.distance(entityIdA: string, entityIdB: string) -> number?
```

Compute the straight-line distance between two entities' `Transform.position` fields.

**Parameters**

- `entityIdA` `string` — First entity id.
- `entityIdB` `string` — Second entity id.

**Returns** `number?` — The distance, or `nil` when either entity is missing a position.

```lua
local d = Entity.distance("player", "enemy")
```

## globals/Entity/getComponents {#globals-entity-getcomponents}

```lua
Entity.getComponents(entityId: string) -> { string }?
```

List all reflected component types on an entity.

**Parameters**

- `entityId` `string` — The entity id.

**Returns** `{ string }?` — Array of component name strings, or `nil` when the entity has no reflected components.

```lua
local comps = Entity.getComponents("player")
```

## globals/Entity/getField {#globals-entity-getfield}

```lua
Entity.getField(entityId: string, component: string, field: string) -> any
```

Get a specific component field value. An engine-struct component
reads through reflection; a component declared in Luau reads through its
component ref, so one call serves both.

**Parameters**

- `entityId` `string` — The entity id.
- `component` `string` — The component name (e.g. `"Transform"`, `"Model"`).
- `field` `string` — The field name (e.g. `"position"`, `"tintBlend"`).

**Returns** `any` — The field value, or `nil` when the entity/component/field is missing. A component name this engine does not declare raises.

```lua
local pos = Entity.getField("player", "Transform", "position")
```

## globals/Entity/getName {#globals-entity-getname}

```lua
Entity.getName(entityId: string) -> string?
```

Get the name of an entity from its `Name` component.

**Parameters**

- `entityId` `string` — The entity id.

**Returns** `string?` — The name string, or `nil` when the entity has no `Name` component.

```lua
local name = Entity.getName("player")
```

## globals/Entity/getPosition {#globals-entity-getposition}

```lua
Entity.getPosition(entityId: string) -> Vec3?
```

Get the position of an entity — shortcut for `getField(id, "Transform", "position")`.

**Parameters**

- `entityId` `string` — The entity id.

**Returns** `Vec3?` — The position `{ x, y, z }`, or `nil` when the entity has no Transform.

```lua
local pos = Entity.getPosition("player")
```

## globals/Entity/getRotation {#globals-entity-getrotation}

```lua
Entity.getRotation(entityId: string) -> Quat?
```

Get the rotation of an entity — shortcut for `getField(id, "Transform", "rotation")`.

**Parameters**

- `entityId` `string` — The entity id.

**Returns** `Quat?` — The rotation quaternion `{ x, y, z, w }`, or `nil` when the entity has no Transform.

```lua
local rot = Entity.getRotation("player")
```

## globals/Entity/getScale {#globals-entity-getscale}

```lua
Entity.getScale(entityId: string) -> Vec3?
```

Get the scale of an entity — shortcut for `getField(id, "Transform", "scale")`.

**Parameters**

- `entityId` `string` — The entity id.

**Returns** `Vec3?` — The scale `{ x, y, z }`, or `nil` when the entity has no Transform.

```lua
local scale = Entity.getScale("player")
```

## globals/Entity/getSchema {#globals-entity-getschema}

```lua
Entity.getSchema(componentName: string) -> { ComponentFieldSchema }?
```

Get the full schema of a component type — field names + types.

**Parameters**

- `componentName` `string` — The component name.

**Returns** `{ ComponentFieldSchema }?` — Array of `{ name, type }` schema entries, or `nil` when the component is not registered.

```lua
local schema = Entity.getSchema("Transform")
```

## globals/Entity/isVisible {#globals-entity-isvisible}

```lua
Entity.isVisible(entityId: string) -> boolean
```

Check if an entity is visible — reads the `Visible` component. Missing component is treated as visible.

**Parameters**

- `entityId` `string` — The entity id.

**Returns** `boolean` — `true` when visible (or no `Visible` component is present), `false` when explicitly hidden.

```lua
local visible = Entity.isVisible("player")
```

## globals/Entity/patch {#globals-entity-patch}

```lua
Entity.patch(entityId: string, component: string, fields: { [string]: any }) -> boolean
```

Patch multiple fields on a single component at once. Serves an
engine-struct component and a component declared in Luau alike.

**Parameters**

- `entityId` `string` — The entity id.
- `component` `string` — The component name.
- `fields` `{ [string]: any }` — `{ fieldName = value, ... }` map of fields to write.

**Returns** `boolean` — `true` when every named field was written. A component name this engine does not declare raises.

```lua
Entity.patch("player", "Transform", { position = pos, scale = scl })
```

## globals/Entity/setField {#globals-entity-setfield}

```lua
Entity.setField(entityId: string, component: string, field: string, value: any?) -> boolean
```

Set a specific component field value. An engine-struct component
writes through reflection; a component declared in Luau writes through its
component ref, so one call serves both.

**Parameters**

- `entityId` `string` — The entity id.
- `component` `string` — The component name.
- `field` `string` — The field name.
- `value` `any` _(optional)_ — The new value.

**Returns** `boolean` — `true` when the write succeeded, `false` otherwise. A component name this engine does not declare raises.

```lua
Entity.setField("player", "Transform", "position", { x = 0, y = 1, z = 0 })
```

## globals/Entity/setPosition {#globals-entity-setposition}

```lua
Entity.setPosition(entityId: string, pos: Vec3)
```

Set the position of an entity — shortcut for `setField(id, "Transform", "position", pos)`.

**Parameters**

- `entityId` `string` — The entity id.
- `pos` `Vec3` — The new position `{ x, y, z }`.

```lua
Entity.setPosition("player", { x = 0, y = 1, z = 0 })
```

## globals/Entity/setScale {#globals-entity-setscale}

```lua
Entity.setScale(entityId: string, scale: Vec3)
```

Set the scale of an entity — shortcut for `setField(id, "Transform", "scale", scale)`.

**Parameters**

- `entityId` `string` — The entity id.
- `scale` `Vec3` — The new scale `{ x, y, z }`.

```lua
Entity.setScale("player", { x = 1, y = 1, z = 1 })
```

## globals/Entity/snapshot {#globals-entity-snapshot}

```lua
Entity.snapshot(entityId: string) -> any
```

Snapshot all reflected components on an entity into a `{ ComponentName = { field = value, ... }, ... }` map.

**Parameters**

- `entityId` `string` — The entity id.

**Returns** `any` — The snapshot table, or `nil` when the entity does not exist.

```lua
local snap = Entity.snapshot("player")
```