Skip to content
AEOWUN
Docs Menu

Actor handles

Look up Actor calls and properties. Here actor stands for a handle found with proj.find().

actor.id

Read the authored Actor ID.

Arguments

No call arguments. Read this property.

Returns

number. Read-only.

Works with

actor handles.

Missing values and errors

Assigning to this property is not supported. Removed objects and unsupported handle kinds cannot supply this property.

const actor = proj.find("Guard")
if actor != nil {
    debug.log(actor.id)
}

actor.actor_id

Read the authored Actor ID.

Arguments

No call arguments. Read this property.

Returns

number. Read-only.

Works with

actor handles.

Missing values and errors

Assigning to this property is not supported. Removed objects and unsupported handle kinds cannot supply this property.

const actor = proj.find("Guard")
if actor != nil {
    debug.log(actor.actor_id)
}

actor.is_actor

Check the authored Actor kind.

Arguments

No call arguments. Read this property.

Returns

bool. Read-only.

Works with

actor handles.

Missing values and errors

Assigning to this property is not supported. Removed objects and unsupported handle kinds cannot supply this property.

const actor = proj.find("Guard")
if actor != nil {
    debug.log(actor.is_actor)
}

actor.name

Read the Actor name.

Arguments

No call arguments. Read this property.

Returns

string. Read-only.

Works with

actor handles.

Missing values and errors

Assigning to this property is not supported. Removed objects and unsupported handle kinds cannot supply this property.

const actor = proj.find("Guard")
if actor != nil {
    debug.log(actor.name)
}

actor.position

Read or change the Actor position.

Arguments

No call arguments. Assign [x, y, z] numbers to change it.

Returns

[x, y, z] numbers. Readable and writable.

Works with

actor handles.

Missing values and errors

Removed objects and unsupported handle kinds cannot supply this property.

const actor = proj.find("Guard")
if actor != nil {
    debug.log(actor.position)
}

actor.rotation

Read or change Actor rotation.

Arguments

No call arguments. Assign [x, y, z] numbers to change it.

Returns

[x, y, z] numbers. Readable and writable.

Works with

actor handles.

Missing values and errors

Removed objects and unsupported handle kinds cannot supply this property.

const actor = proj.find("Guard")
if actor != nil {
    debug.log(actor.rotation)
}

actor.scale

Read or change Actor scale.

Arguments

No call arguments. Assign [x, y, z] numbers to change it.

Returns

[x, y, z] numbers. Readable and writable.

Works with

actor handles.

Missing values and errors

Removed objects and unsupported handle kinds cannot supply this property.

const actor = proj.find("Guard")
if actor != nil {
    debug.log(actor.scale)
}

actor.visible

Show or hide the Actor.

Arguments

No call arguments. Assign bool to change it.

Returns

bool. Readable and writable.

Works with

actor handles.

Missing values and errors

Removed objects and unsupported handle kinds cannot supply this property.

const actor = proj.find("Guard")
if actor != nil {
    debug.log(actor.visible)
}

actor.enabled

Enable or disable the Actor.

Arguments

No call arguments. Assign bool to change it.

Returns

bool. Readable and writable.

Works with

actor handles.

Missing values and errors

Removed objects and unsupported handle kinds cannot supply this property.

const actor = proj.find("Guard")
if actor != nil {
    debug.log(actor.enabled)
}

actor.package

Read the Actor package name.

Arguments

No call arguments. Read this property.

Returns

string. Read-only.

Works with

actor handles.

Missing values and errors

Assigning to this property is not supported. Removed objects and unsupported handle kinds cannot supply this property.

const actor = proj.find("Guard")
if actor != nil {
    debug.log(actor.package)
}

actor.attributes

Read the Actor attributes.

Arguments

No call arguments. Read this property.

Returns

map. Read-only.

Works with

actor handles.

Missing values and errors

Assigning to this property is not supported. Removed objects and unsupported handle kinds cannot supply this property.

const actor = proj.find("Guard")
if actor != nil {
    debug.log(actor.attributes)
}

actor.facing

Read the Actor facing direction.

Arguments

No call arguments. Read this property.

Returns

[x, z] numbers. Read-only.

Works with

actor handles.

Missing values and errors

Assigning to this property is not supported. Removed objects and unsupported handle kinds cannot supply this property.

const actor = proj.find("Guard")
if actor != nil {
    debug.log(actor.facing)
}

actor.is_valid()

Check whether the object still exists.

Arguments

No arguments.

Returns

bool. False if removed.

Works with

Actor handles.

Missing values and errors

A removed object returns false. Wrong argument counts or types report an error.

const object = proj.find("Guard")
if object != nil {
    debug.log(object.is_valid())
}

actor.name()

Read the object name.

Arguments

No arguments.

Returns

string.

Works with

Actor handles.

Missing values and errors

Use a valid handle. Wrong argument counts or types report an error.

const object = proj.find("Guard")
if object != nil {
    debug.log(object.name())
}

actor.set_position(x, y, z)

Set the object position.

Arguments

Three numbers: x, y, z.

Returns

nil.

Works with

Actor handles.

Missing values and errors

Use a valid handle. Wrong argument counts or types report an error.

const object = proj.find("Guard")
if object != nil {
    object.set_position(0, 2, 0)
}

actor.translate(x, y, z)

Move the object by an offset.

Arguments

Three numbers: x, y, z.

Returns

nil.

Works with

Actor handles.

Missing values and errors

Use a valid handle. Wrong argument counts or types report an error.

const object = proj.find("Guard")
if object != nil {
    object.translate(1, 0, 0)
}

actor.destroy()

Destroy the live object.

Arguments

No arguments.

Returns

true.

Works with

Actor handles.

Missing values and errors

Use a valid handle. Wrong argument counts or types report an error.

const object = proj.find("Guard")
if object != nil {
    object.destroy()
}

actor.set_horizontal_velocity(vx, vz)

Set horizontal movement speed.

Arguments

Two numbers: x and z velocity.

Returns

nil.

Works with

Actor handles with the required runtime movement support.

Missing values and errors

Use a valid handle. Wrong argument counts or types report an error.

const actor = proj.find("Guard")
if actor != nil {
    actor.set_horizontal_velocity(2, 0)
}

actor.set_facing_direction(dx, dz)

Set the direction the Character faces.

Arguments

Two numbers: x and z direction.

Returns

nil.

Works with

Actor handles with the required runtime movement support.

Missing values and errors

Use a valid handle. Wrong argument counts or types report an error.

const actor = proj.find("Guard")
if actor != nil {
    actor.set_facing_direction(1, 0)
}

actor.select_animation(name)

Choose a Character animation.

Arguments

Animation name string.

Returns

nil.

Works with

Actor handles with the required runtime movement support.

Missing values and errors

Use a valid handle. Wrong argument counts or types report an error.

const actor = proj.find("Guard")
if actor != nil {
    actor.select_animation("Walk")
}

actor.is_grounded()

Check whether the Character is on the ground.

Arguments

No arguments.

Returns

bool.

Works with

Actor handles with the required runtime movement support.

Missing values and errors

Use a valid handle. Wrong argument counts or types report an error.

const actor = proj.find("Guard")
if actor != nil {
    actor.is_grounded()
}

actor.apply_vertical_impulse(impulse)

Apply upward or downward movement.

Arguments

One number: vertical impulse.

Returns

nil.

Works with

Actor handles with the required runtime movement support.

Missing values and errors

Use a valid handle. Wrong argument counts or types report an error.

const actor = proj.find("Guard")
if actor != nil {
    actor.apply_vertical_impulse(5)
}

actor.navigate_to(position [, speed [, stop_distance]])

Ask the engine to move an Actor along a route.

Arguments

position: [x, y, z]. Speed defaults to 4.0; stop distance defaults to 0.1.

Returns

true when a route starts. false if it cannot start.

Works with

Movable Actors with runtime navigation support.

Missing values and errors

No path emits navigation_failed(actor, reason). Invalid targets, speed, or stop distance report an error. Completion emits navigation_finished(actor).

const guard = proj.find("Guard")
if guard != nil {
    debug.log(guard.navigate_to([12, 0, 8], 3.5, 0.25))
}

actor.cancel_navigation()

Cancel the current navigation request.

Arguments

No arguments.

Returns

Whether an active request was cancelled.

Works with

Actor handles.

Missing values and errors

Use a valid handle. Wrong argument counts or types report an error.

const guard = proj.find("Guard")
if guard != nil {
    debug.log(guard.cancel_navigation())
}

actor.is_navigating()

Check whether the Actor has an active route.

Arguments

No arguments.

Returns

bool.

Works with

Actor handles.

Missing values and errors

Use a valid handle. Wrong argument counts or types report an error.

const guard = proj.find("Guard")
if guard != nil {
    debug.log(guard.is_navigating())
}

tags.find(tag) [BETA]

Find Actors with a tag.

Arguments

One string tag of 1–64 characters, with no leading or trailing spaces or controls.

Returns

Basket of Actor handles.

Works with

Authored and runtime Actors.

Missing values and errors

Invalid tag names report errors.

const doors = tags.find("Door")
debug.log(doors)

tags.has(actor, tag) [BETA]

Check an Actor tag.

Arguments

A live Actor handle and a valid tag string.

Returns

Boolean result.

Works with

Actor handles.

Missing values and errors

Missing Actor handles, wrong types or invalid tags report errors.

const door = proj.find("Door")
if door != nil {
    debug.log(tags.has(door, "Door"))
}

tags.add(actor, tag) [BETA]

Add an Actor tag.

Arguments

A live Actor handle and a valid tag string.

Returns

Boolean result.

Works with

Actor handles.

Missing values and errors

Missing Actor handles, wrong types or invalid tags report errors.

const door = proj.find("Door")
if door != nil {
    debug.log(tags.add(door, "Door"))
}

tags.remove(actor, tag) [BETA]

Remove an Actor tag.

Arguments

A live Actor handle and a valid tag string.

Returns

Boolean result.

Works with

Actor handles.

Missing values and errors

Missing Actor handles, wrong types or invalid tags report errors.

const door = proj.find("Door")
if door != nil {
    debug.log(tags.remove(door, "Door"))
}

tags.get(tag) [BETA]

Find all supported tagged Actor and Cell handles.

Arguments

One tag string.

Returns

Basket of handles; empty if none match.

Works with

Tagged Actors and Cells in the active world.

Missing values and errors

Different handle kinds may be returned; check before calling type-specific methods.

tags.find() searches Actors. tags.get() includes supported Cells.

const matches = tags.get("interactable")

actor.can_collide [BETA]

Read or set Actor collision.

Arguments

Boolean.

Returns

Current property value.

Works with

Live compatible handle.

Missing values and errors

Invalid handles and values are rejected.

actor.can_collide = true

actor.find_path(target) [BETA]

Find a route for an Actor backed by a Character.

Arguments

Three-number target [x, y, z].

Returns

Basket of waypoints or nil if unreachable.

Works with

Only Actors with a live Character runtime.

Missing values and errors

An ordinary Actor without a Character reports an error.

const waypoints = npc.find_path([10, 0, 10])

actor.damage(amount) [BETA]

Request gameplay damage for an Actor.

Arguments

Finite nonnegative damage number.

Returns

true when queued.

Works with

Actors with a game-defined damage handler.

Missing values and errors

Queues a damage event; Worldkiln does not own built-in HP or automatic death.

npc.damage(1)

actor.get_attachments() [BETA]

Find the current Actor attachment Cells.

Arguments

No arguments.

Returns

Basket of Cell/Light handles.

Works with

Authored and supported runtime spatial attachments.

Missing values and errors

Invalid Actor or arguments report an error.

const attached = hero.get_attachments()

actor.find_attachment_by_name(name) [BETA]

Find a named Actor attachment Cell.

Arguments

String attachment name.

Returns

Cell/Light handle or nil if not found.

Works with

Authored and supported runtime spatial attachments.

Missing values and errors

A name that does not match returns nil.

const torch = hero.find_attachment_by_name("Torch")