component

The component namespace: 23 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/add

entity(id).component.add(type: AssetRef | string, data: table?) -> table?

Attach a component, answering its live public proxy — nil when the add was deferred or skipped as a duplicate.

Parameters

• type AssetRef | string
• data table (optional)

Returns table?

entity/proxy/component/addSynced

entity(id).component.addSynced(type: AssetRef | string, data: table?) -> table?

Attach a component and replicate it to every peer.

Parameters

• type AssetRef | string
• data table (optional)

Returns table?

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

entity/proxy/component/clear

entity(id).component.clear() -> ()

Detach every component this entity carries.

Returns ()

entity/proxy/component/create

entity(id).component.create(type: AssetRef | string, data: table?) -> table?

Attach a fresh instance even where one of the type is already present.

Parameters

• type AssetRef | string
• data table (optional)

Returns table?

entity/proxy/component/get

entity(id).component.get(type: AssetRef | string, instanceName: string?) -> table?

This entity's live component proxy of the type, or nil when it carries none.

Parameters

• type AssetRef | string
• instanceName string (optional)

Returns table?

entity/proxy/component/getAll

entity(id).component.getAll(type: (AssetRef | string)?) -> table

Every component on this entity, or every instance of one type.

Parameters

• type (AssetRef | string) (optional)

Returns table

entity/proxy/component/getFromChildren

entity(id).component.getFromChildren(type: AssetRef | string) -> table?

The first descendant's component of the type, or nil when no descendant carries one.

Parameters

• type AssetRef | string

Returns table?

entity/proxy/component/getFromParent

entity(id).component.getFromParent(type: AssetRef | string) -> table?

The nearest ancestor's component of the type, or nil when no ancestor carries one.

Parameters

• type AssetRef | string

Returns table?

entity/proxy/component/has

entity(id).component.has(type: AssetRef | string) -> boolean

Whether this entity carries a component of the type.

Parameters

• type AssetRef | string

Returns boolean

entity/proxy/component/list

entity(id).component.list() -> { string }

The identity string of every component type this entity carries, each of which get takes.

Returns { string }

for _, identity in ipairs(entity(id).component.list()) do
    local component = entity(id).component.get(identity)
    component.enabled = false
end

entity/proxy/component/lock

entity(id).component.lock(names: { string } | string, flags: { [string]: any }?) -> ()

Lock named components on this entity against removal or writes.

Parameters

• names { string } | string
• flags { [string]: any } (optional)

Returns ()

entity/proxy/component/locks

entity(id).component.locks() -> { [string]: any }

The lock state of this entity's components.

Returns { [string]: any }

entity/proxy/component/pending

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

One record per component whose awake() is held back waiting for an asset field to register, naming the component and the fields it waits on; every such component when no type is given.

Parameters

• type (AssetRef | string) (optional)

Returns { { type: string, instance: string?, instanceId: string, fields: { { name: string, spec: string, value: string } } } }

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

entity/proxy/component/remove

entity(id).component.remove(type: AssetRef | string, instanceName: string?) -> ()

Detach a component, by type and optionally by instance name.

Parameters

• type AssetRef | string
• instanceName string (optional)

Returns ()

entity/proxy/component/setEnabled

entity(id).component.setEnabled(type: AssetRef | string, enabled: boolean) -> ()

Enable or disable a component without detaching it.

Parameters

• type AssetRef | string
• enabled boolean

Returns ()

entity/proxy/component/unlock

entity(id).component.unlock(names: ({ string } | string)?, flags: { [string]: any }?) -> ()

Release locks this entity's components hold; every one of them when no name is given.

Parameters

• names ({ string } | string) (optional)
• flags { [string]: any } (optional)

Returns ()