Global functions

debug.log(...)

Print values to Output.

Arguments

Any values, in the order you want to print them.

Returns

nil.

Works with

Values from your script.

Missing values and errors

No lookup is performed. Printing a handle does not check whether its object still exists.

debug.log("Score:", 25)

find(name)

Find named Cells, Actors, and live Entities.

Arguments

name: string. Matches object identity names.

Returns

A basket of handles. No match returns an empty basket.

Works with

Active World Cells, authored Actors, and runtime Entities.

Missing values and errors

Names can be shared. A result may contain different handle kinds. Check the basket before indexing. If an Actor matches, its backing Entity is not returned again. Wrong argument counts or types report an error.

Also available as: find() — legacy.

This compatibility lookup still finds Cells. proj.find() only finds Actors. It is not a replacement for Cell lookup.

const matches = find("DoorCell")
if basket.len(matches) > 0 {
    matches[0].visible = false
}

get_entity(name)

Find a live Entity by name.

Arguments

name: string naming a runtime Entity.

Returns

An Entity handle, or nil if none matches.

Works with

Live Entities.

Missing values and errors

Does not search authored Cells. Runtime names can be shared; use an ID when you need a specific Entity. Wrong argument counts or types report an error.

const enemy = get_entity("Goblin")
if enemy != nil {
    debug.log(enemy.health)
}

getAllCellsOfClass(class_name)

Find active Cells of a class.

Arguments

class_name: string, such as "Block" or "Light".

Returns

A basket of Cell handles. No matches returns an empty basket.

Works with

Active and effective World Cells.

Missing values and errors

Does not search Actor packages. Wrong argument counts or types report an error.

const blocks = getAllCellsOfClass("Block")
debug.log(basket.len(blocks))

get_light(x, y, z)

Find a Light at World coordinates.

Arguments

Three numbers: x, y, and z.

Returns

A Light handle, or nil.

Works with

Light Cells.

Missing values and errors

No Light at those coordinates returns nil. Wrong argument counts or types report an error.

const lamp = get_light(0, 2, 0)
if lamp != nil {
    lamp.enabled = true
}

spawn(name, position [, package])

Create a live Entity at a position.

Arguments

name: string. position: [x, y, z] numbers. Optional package: Character package name.

Returns

The new Entity handle.

Works with

Runtime Entities and Character packages.

Missing values and errors

Without a package, the default Character package is used. Invalid positions and unavailable packages report an error.

const enemy = spawn("Goblin", [10, 1, 5])
debug.log(enemy.id)

wait(seconds)

Pause this script, then continue.

Arguments

seconds: finite positive number of seconds.

Returns

Execution resumes after the pause; no useful return value.

Works with

Top-level scripts, functions, events, and Modules.

Missing values and errors

Zero, negative, or non-finite durations report an error. Disabling the script cancels the paused work.

Waiting in Actor Modules [BETA]

Actor-attached Modules resume with their Actor parent intact.

debug.log("Starting")
wait(1.0)
debug.log("One second later")

time.delta

Read the current frame duration.

Arguments

No arguments. Read this property.

Returns

A number of seconds.

Works with

The current script host frame.

Missing values and errors

This is a frame duration, not elapsed game time.

debug.log("Frame seconds:", time.delta)

attach(child, child_point, parent, parent_point)

Attach an object to a named rig point.

Arguments

child and parent: Actor or Entity handles. Point names: strings naming rig attachment points.

Returns

true on success.

Works with

Actors and Entities with suitable Character packages and attachment points.

Missing values and errors

Invalid handles, missing points, unsupported kinds, and attachment cycles report an error. Attached objects follow the parent; ordinary movement and physics are suspended.

const sword = proj.find("Sword")
const hero = proj.find("Hero")
if sword != nil && hero != nil {
    attach(sword, "Grip", hero, "RightHand")
}

detach(child)

Remove an attachment and restore normal movement.

Arguments

child: Actor or Entity handle.

Returns

true if removed; false if not attached.

Works with

Attached Actors and Entities.

Missing values and errors

Invalid handles or unsupported object kinds report an error.

const sword = proj.find("Sword")
if sword != nil {
    debug.log(detach(sword))
}