Finding Objects

Choose a lookup

Find Actors

proj.find() finds Actors. It does not find Cells.

const door = proj.find("Door")
if door != nil {
    door.visible = false
}

It searches the project hierarchy and its descendants. No match returns nil. Multiple matches produce a warning and return the first match. Use proj.find.all() when names may be shared.

const enemies = proj.find.all("Enemy")
for enemy in enemies {
    debug.log(enemy.id)
}

A folder narrows the search: proj.Dungeon.find("Door") searches that folder and its descendants.

Find Cells

Global find() can find named Cells, including authored Cells. It also searches Actors and live Entities. Its result is always a basket, so check it before indexing.

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

Use a distinct Cell name when other object types may share it. No matches returns an empty basket. Global find() remains available as a compatibility lookup; proj.find() is not a replacement for Cell lookup. If you know a Cell's ID, use cell.get(id). If you need a whole Cell class, use getAllCellsOfClass("Block").

Find live Entities

get_entity("Goblin") finds a live Entity by name. entity.get(id) uses its runtime ID. An Actor ID and an Entity ID are different. Check for nil before using a lookup result. If the object may have been destroyed later, check is_valid() too.

Find Player Modules

player.find("Inventory") searches Modules attached to the Player. It does not search World Cells or arbitrary Actors. Use player.find.all() for all matching Modules. See Actors and Modules for script paths and attachment.

Find UI controls

ui.find("health_text") uses the control's script key, not its display name. No match returns nil. ui.get("health_text") reports an error instead. Use ui.find("hud", "health_text") to supply a document key. It must match the document loaded for Play.

Reference

See project lookups, global find, Cell lookup, and UI lookup.