component

The component namespace — 9 functions.

component/lifecycle/README

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

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:

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

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:

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

component/self/data

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

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

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

self.instanceId -> string

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

entity/proxy/component/addSynced

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

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

entity/proxy/component/pending

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

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