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)
}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 = trueactor.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")