Characters

agents

Finding characters, gadgets, attack targets and ground items.

Everything in the world you can target or interact with is an agent: characters (players, monsters, NPCs, pets), gadgets (nodes, doors, waypoints, objects), attack targets (the hittable parts of some gadgets) and ground items. The agents module finds them and returns Agent handles.

local me = agents.local_player()
if me then
    for _, foe in ipairs(agents.monsters()) do
        if foe:is_alive() and foe:attitude() == agents.ATTITUDE_HOSTILE
            and foe:local_distance() < 900 then
            print(foe:name(), foe:health().percent)
        end
    end
end

Lookups return nil when nothing matches, and lists are empty while there's no map (on the loading screen or at character select).

Lookups

agents.local_player()Agent?
Your character.
agents.get(agent_id)Agent?
Any agent by agent id, whatever kind it is.
agents.character(agent_id)Agent?
A character by agent id.
agents.gadget(agent_id)Agent?
A gadget by agent id.
agents.attack_target(agent_id)Agent?
An attack target by agent id.
agents.ground_item(agent_id)Agent?
A ground item by agent id.
agents.local_player_info()table?
{name, uuid} of the player you're logged in as.

Players

agents.players()Agent[]
Every player character nearby, you included.
agents.player_by_agent_id(agent_id)Agent?
A player by agent id.
agents.player_by_name(name)Agent?
A player by character name.
agents.player_by_uuid(uuid)Agent?
A player by their uuid (32 hex digits, dashes allowed).

Monsters

Monsters are every character that isn't a player: enemies, NPCs, pets, minions, clones. Their id (agent:monster_id()) is the kind of monster, the same for every one of its kind.

agents.monsters()Agent[]
Every monster nearby.
agents.monster_by_agent_id(agent_id)Agent?
A monster by agent id.
agents.monster_by_id(id)Agent?
The first monster of a kind, by monster id.
agents.monsters_by_id(id)Agent[]
Every monster of a kind.
agents.monster_by_name(name)Agent?
The first monster with this name.
agents.monsters_by_name(name)Agent[]
Every monster with this name.

Gadgets, attack targets and ground items

agents.gadgets()Agent[]
Every gadget nearby.
agents.gadget_by_name(name)Agent?
The first gadget with this name.
agents.gadgets_by_name(name)Agent[]
Every gadget with this name.
agents.attack_targets()Agent[]
Every attack target nearby.
agents.ground_items()Agent[]
Every item lying on the ground nearby.
agents.ground_item_by_id(item_id)Agent?
The first ground item of an item id.
agents.ground_items_by_id(item_id)Agent[]
Every ground item of an item id.
agents.ground_item_by_name(name)Agent?
The first ground item with this name.
agents.ground_items_by_name(name)Agent[]
Every ground item with this name.

Selection

agents.selected()Agent?
Your current target.
agents.selected_id()integer?
Your current target's agent id.
agents.select(agent)
Targets an agent (an Agent or an agent id).
agents.deselect()
Clears your target.
agents.draw_agent_status()boolean
Whether the target's status (health bar and name above it) is drawn.
agents.set_draw_agent_status(on)
Shows or hides the target's status.

Constants

Attitudes, for agent:attitude()
ATTITUDE_FRIENDLYATTITUDE_HOSTILEATTITUDE_NEUTRALATTITUDE_UNATTACKABLE
Dead states, for agent:dead_flags()
DEAD_STATE_ALIVEDEAD_STATE_DOWNEDDEAD_STATE_DEAD
Break bar states, for agent:break_bar().state
BREAK_BAR_AVAILABLEBREAK_BAR_BROKENBREAK_BAR_UNAVAILABLE
Agent types, for agent:agent_type()
TYPE_CHARACTERTYPE_COMBATANTTYPE_GADGETTYPE_GADGET_ATTACK_TARGETTYPE_GROUND_ITEM
Gadget sub-types, for agent:sub_type()
SUBTYPE_NONESUBTYPE_DESTRUCTABLESUBTYPE_POINTSUBTYPE_CRAFTSUBTYPE_DOORSUBTYPE_DOORWAYSUBTYPE_INTERACTSUBTYPE_PLAYER_SPECIFICSUBTYPE_ATK_TARGETSUBTYPE_MAP_PORTALSUBTYPE_WAYPOINTSUBTYPE_RESOURCE_NODESUBTYPE_PROPSUBTYPE_PLAYER_CREATEDSUBTYPE_VISTASUBTYPE_BUILD_SITE
PreviousFiles