Game Objects API

Query and interact with game objects (scenery, doors, objects).

Functions

find_first

game_objects:find_first(filters: table?) -> GameObject?

Find first game object matching filters.

Parameters:

Parameter	Type	Required	Description
filters	table	No	Filter options

Returns:

• GameObject? - First matching object

Filters:

Filter	Type	Description
name	string	Exact name match
name_contains	string	Name contains text
name_matches_regex	string	Name matches regex
name_any	table	Match if name equals any in array of strings
name_contains_any	table	Match if name contains any substring in array
id	number	Exact ID match
ids	table	Array of IDs
obj_type	string	Object type (Interactive, Boundary, Floor, Wall)
within_distance_of_local	number	Distance from player
within_distance_of	table	Distance from coordinates
at	table	Exact tile location {x, y, z} or [x, y, z]
at_any	table	Array of tiles to check {{x, y, z}, ...}
actions_contains	string	Has an action containing this text (case-insensitive)
actions_equals	string	Has an action exactly matching this text (case-insensitive)

Example:

local door = game_objects:find_first({name = "Door"})
local tree = game_objects:find_first({name_contains = "Tree"})

-- Find objects with specific action
local choppable_tree = game_objects:find_first({
    name_contains = "Tree",
    actions_contains = "Chop"
})

-- Find exact action match
local openable_door = game_objects:find_first({
    name = "Door",
    actions_equals = "Open"
})

-- Find object at specific tile
local booth = game_objects:find_first({
    name = "Bank booth",
    at = {3200, 3210, 0}  -- or at = {x = 3200, y = 3210, floor = 0}
})

-- Find object at any of several tiles
local booth_any = game_objects:find_first({
    name = "Bank booth",
    at_any = {
        {3092, 3490, 0},
        {3092, 3489, 0}
    }
})

-- Find objects with any of multiple names
local obj = game_objects:find_first({
    name_any = {"Door", "Gate", "Ladder"}
})

-- Find objects containing any substring
local resource = game_objects:find_first({
    name_contains_any = {"tree", "rock", "ore"}
})

---

find_all

game_objects:find_all(filters: table?) -> table

Find all game objects matching filters.

Parameters:

Parameter	Type	Required	Description
filters	table	No	Filter options

Returns:

• table - Array of GameObject objects

---

find_nearest

game_objects:find_nearest(filters: table?) -> GameObject?

Find nearest game object matching filters.

Parameters:

Parameter	Type	Required	Description
filters	table	No	Filter options

Returns:

• GameObject? - Nearest matching object

---

Common Patterns

Door Interaction

local function interact_with_door()
    local door = game_objects:find_nearest({name = "Door"})
    
    if door then
        logger:info("Interacting with door")
        door:smart_interact({action = "Open"})
        return true
    end
    
    return false
end

---

Resource Gathering

local function find_resource(resource_name)
    local resource = game_objects:find_nearest({name = resource_name})
    
    if resource then
        logger:info("Found " .. resource:name())
        return resource:smart_interact({action = "Mine"})
    end
    
    return false
end

---

Related APIs

• NPCs API - NPC interaction
• Ground Items API - Ground item interaction