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

# component

The `component` namespace — 9 functions.

## component/lifecycle/README {#component-lifecycle-readme}

```lua
Component lifecycle hooks
```

Functions you can define in a component script. All are optional.

| Hook | When | Use |
|------|------|-----|
| awake() | Once, when added | Init state, set up bridges |
| start() | Once, after all awake | Cross-component setup |
| update(dt) | Every frame | Movement, logic, animation |
| fixedUpdate(dt) | Physics rate | Force application |
| onPropertyChanged(key, val, old) | Public prop written externally | React to config changes |
| onEnable() / onDisable() | Toggled | Pause/resume |
| onDestroy() | Removed | Cleanup |
| onError(error) | Error occurs | Error indicators, recovery |

## component/public/README {#component-public-readme}

```lua
public — Component public properties
```

Declared with `declare {}` at the top of a component script. Public properties are visible to other scripts and the editor. Changes trigger onPropertyChanged().

Example:
```lua
declare {
speed = 5.0,
label = "Hello",
visible = true,
}

function update(dt)
-- public.speed is readable/writable from outside
local p = self.entity.position
self.entity.position = { p.x, p.y + public.speed * dt, p.z }
end
```

Read from outside: entity(id).component.get("MyComp").speed
Write from outside: entity(id).component.get("MyComp").speed = 10

## component/self/README {#component-self-readme}

```lua
self — Component instance context
```

Available inside any component script. Provides access to the entity, instance ID, and init data.

Fields:
- self.entity — entity proxy (same as entity(self.entityId)). Access position, rotation, scale, components.
- self.entityId — string ID of the entity this component is attached to
- self.instanceId — unique string ID for this component instance
- self.data — the initial data table passed to entity.component.add()
- self.errors() — get error list for this component instance

Example:
```lua
function update(dt)
local p = self.entity.position
self.entity.position = { p.x, p.y + dt, p.z }
end
```

## component/self/data {#component-self-data}

```lua
self.data -> table | nil
```

The initial data table passed as the second argument to entity.component.add(type, data). Available in awake() and all lifecycle hooks.

## component/self/entity {#component-self-entity}

```lua
self.entity -> EntityProxy
```

Entity proxy for the entity this component is on. Shorthand for entity(self.entityId). Use it to read/write position, rotation, scale, and manage other components.

Properties (read components, assign vectors):
- self.entity.position.x/.y/.z (read) ; self.entity.position = { x, y, z } (write) ; self.entity.position.x = n (one axis)
- self.entity.rotation.x/.y/.z/.w or .eulerAngles (read) ; self.entity.rotation = { qx,qy,qz,qw } or .eulerAngles = { pitch,yaw,roll } (write) ; .rotation.rotateAxisAngle(ax,ay,az,radians)
- self.entity.localScale.x/.y/.z (read) ; self.entity.localScale = { x, y, z } (write)
- self.entity.component.add(type, data?) / .remove(type) / .has(type) / .get(type) / .getAll()
- self.entity.name() -> string
- self.entity.id() -> string
- self.entity.setParent(parentId) / .unparent()

## component/self/entityId {#component-self-entityid}

```lua
self.entityId -> string
```

The entity ID string for the entity this component is attached to. Use with entity() to get a proxy, or pass to API functions that take an entity ID.

## component/self/instanceId {#component-self-instanceid}

```lua
self.instanceId -> string
```

Unique identifier for this specific component instance. Useful for generating unique screen names, mesh IDs, etc.

## entity/proxy/component/addSynced {#entity-proxy-component-addsynced}

```lua
entity(id).component.addSynced(type, data?) -> table | nil
```

Add a component that replicates to all peers. Same as add() — including returning the new component's live public proxy — but forces sync registration even without a sync {} block.

**Parameters**

- `type` `AssetRef` — Component identity
- `data` `table` _(optional)_ — Initial property values for the component

**Returns** `table | nil` — The new component's live public proxy; nil when deferred or skipped

```lua
local health = entity(id).component.addSynced('Health', { hp = 100 })
```

## entity/proxy/component/pending {#entity-proxy-component-pending}

```lua
entity(id).component.pending(type?) -> { {type: string, instance: string?, instanceId: string, fields: { {name: string, spec: string, value: string} }} }
```

The components on this entity whose awake() is held back waiting for an asset field to register, and for each one the field, its declared spec, and the identity string that did not resolve. A component in this list is attached and idle: it renders nothing and its methods return nothing until the asset arrives. Empty when every component on the entity has run. Ask here when a component appears to have done nothing — the answer separates an asset still arriving from an identity that names no asset.

**Parameters**

- `type` `AssetRef` _(optional)_ — Component identity to narrow the answer to

**Returns** `table` — Array of { type, instance?, instanceId, fields } records; empty when nothing is waiting

```lua
local waiting = entity(id).component.pending('Terrain')
if #waiting > 0 then print(waiting[1].fields[1].name, waiting[1].fields[1].value) end
```