Characters

Agent

A handle to one character, gadget, attack target or ground item.

An Agent holds only an agent id and looks the agent up again on every call, so it's always safe to keep one between ticks. Once the agent is gone, agent:valid() is false and its other methods return nil.

Methods that don't apply to an agent's kind return nil: agent:health() on a ground item, or agent:skills() on a gadget. Two handles to the same agent are ==, and tostring(agent) is Agent(id, kind, name).

local target = agents.selected()
if target and target:is_character() then
    local hp = target:health()
    print(target:name(), hp.current .. "/" .. hp.max, target:has_buff("Stability"))
end

Identity

These work even after the agent is gone.

agent:id()integer

The agent id.

agent:kind()string

"character", "gadget", "attack_target" or "ground_item".

agent:valid()boolean

Whether the agent is still there.

agent:is_character()boolean

Whether it's a character.

agent:is_gadget()boolean

Whether it's a gadget.

agent:is_attack_target()boolean

Whether it's an attack target.

agent:is_ground_item()boolean

Whether it's a ground item.

Every kind of agent

agent:name()string?

The agent's name. Attack targets have none.

agent:position()Vec3

Where the agent is.

agent:rotation()Vec3

Which way it faces.

agent:movement()Vec3

How it's moving.

agent:speed()number

Its movement speed.

agent:height()number

Its height.

agent:collision_radius()number

The radius it takes up.

agent:agent_type()integer

One of the agents.TYPE_* constants.

agent:sub_type()integer

One of the agents.SUBTYPE_* constants.

agent:is_player()boolean

Whether it's a player's character.

agent:is_monster()boolean

Whether it's a character that isn't a player.

agent:is_local_player()boolean

Whether it's your character.

agent:distance(pos)number

The distance to a position (or to another agent).

agent:distance2d(pos)number

The distance on the ground, ignoring height.

agent:in_range(pos, range)boolean

Whether it's closer than range to a position.

agent:in_range2d(pos, range)boolean

The same, ignoring height.

agent:local_distance()number?

The distance to your character.

agent:local_distance2d()number?

The distance to your character, ignoring height.

Actions

Your character does these to the agent.

agent:interact()

Interacts with it: talks to an NPC, gathers a node, uses an object.

agent:revive()

Revives it.

agent:finish()

Finishes it (stomps a downed enemy).

agent:select()

Targets it.

agent:pickup()

Picks it up, if it's a ground item.

Characters and gadgets

agent:health()table?

{current, max, barrier, percent}.

agent:break_bar()table?

{state, current}: state is one of agents.BREAK_BAR_*, current how much is left.

agent:buffs()Buff[]?

Its boons, conditions and effects. See Buff.

agent:buff(id_or_name)Buff?

One buff, by buff id or by name.

agent:has_buff(id_or_name)boolean

Whether it has a buff.

agent:attitude()integer?

One of the agents.ATTITUDE_* constants.

agent:flags()integer?

The game's raw flags for the agent.

agent:owner()Agent?

Who it belongs to: the player for a pet, minion or clone.

agent:owner_agent_id()integer?

Its owner's agent id.

agent:selectable()boolean?

Whether it can be targeted.

Characters

agent:is_alive()boolean

Whether it's alive.

agent:is_downed()boolean

Downed.

agent:is_dead()boolean

Dead.

agent:dead_flags()integer

One of the agents.DEAD_STATE_* constants.

agent:in_combat()boolean

In combat.

agent:aggroed()boolean

Has aggro on someone.

agent:is_talking()boolean

In a conversation.

agent:is_clone()boolean

A mesmer clone.

agent:is_moving()boolean

Moving.

agent:is_gliding()boolean

Gliding.

agent:glider_is_accelerating()boolean

Gliding faster.

agent:glider_is_decelerating()boolean

Gliding slower.

agent:glider_endurance()number

The glider's endurance.

agent:vertical_movement_dir()number

Going up or down while swimming or flying.

agent:swimming_flags()integer

Raw swimming state.

agent:visible_position()Vec3

Where the character is drawn, which can lag behind position().

agent:team_id()integer

Its team, in PvP and WvW.

agent:monster_id()integer

The kind of monster (the same for every one of its kind).

agent:player_idx()integer

The player's index in the game's player list.

agent:player_name()string?

The player's character name.

agent:uuid()string?

The player's uuid, as 32 hex digits.

agent:profession()integer?

The profession id; see professions.

agent:endurance()table?

{current, max}: the dodge bar.

agent:core_stats()table?

{race, gender, profession, stats, scaled_stats}, where both stat tables are Stats.

agent:specs()Spec[]?

A player's three selected specializations, with their traits. See Spec.

agent:profession_energy()table?

Profession mechanics, each {current, max} or nil: warrior_adrenaline, thief_initiative, necromancer_life_force, holosmith_heat, druid_astral_force, firebrand_pages, mesmer_clones, deadeye_malice, specter_shadow_force, scourge_shades, catalyst_energy, evoker_skill_charge, evoker_empowered_skill_charge, galeshot_arrows, bladesworn_flow, conduit_affinity, and revenant as {energy, stance_id, stance_swap_cooldown, stance_swap_ready}.