Skip to content

22. Builtins (every function you can call in a condition) ​

The ones you will use most:

NeedUse
Is a skill on my bar / ready?on_bar(X), ready_bar(X) (ready(X) also counts skills not on the bar)
Recharge leftcd_bar(X) (ms; -1 when not on the bar, so cd_bar(X) < 500 is true then), cd(X) (0 when ready or unknown)
Chargesammo_bar(X), ammo_cd_bar(X)
Which weapon seton_weapons(GREATSWORD, NONE), on_weapons(AXE, AXE), swap_ready()
My resourcesres(ADRENALINE), res_max(ADRENALINE), has_res(INITIATIVE), endurance()
My health / target healthhp(), target_hp() (fractions 0.0-1.0)
Buffs on me / the targetbuff(ID), buff_stacks(ID), buff_time(ID), target_buff(ID), target_buff_stacks(ID), buff_named(acr.buff)
What I am castingbusy(), cur_skill(), current(X), cast_pct(), cast_remaining(), final_effect_fired(), last_skill()
Recently usedused_within(X, ms), time_since(X), recently_used(X, ms)
Fight statein_combat(), combat_time(), moving(), target_breakable(), has_target()
Rangetarget_in_range2(units), target_in_skill_range(X), skill_range(X)
Alliesneed_buff(ID, range), need_heal(fraction, range), need_cleanse(range), downed_ally(range, missing)

All builtins ​

Skill arguments take a skill id or an acr.const name for one; buff arguments take a buff id or an acr.buff name. A statement builtin does something. Use it in handlers and :pre, not in conditions.

Effects ​

BuiltinReturnsMeaning
e_hash(e: effect)intThe effect's hashed name (compare with an acr.fx constant).
e_on_target(e: effect, radius: units, height: units, target_height: units)boolThe effect, as an upright cylinder of that radius and height, overlaps the selected target's cylinder (its radius, target_height tall).
e_x(e: effect)floatThe effect's x position in game units.
e_y(e: effect)floatThe effect's y position in game units.
e_z(e: effect)floatThe effect's z position in game units.

Elements (agents in a collection, target(), pet()) ​

BuiltinReturnsMeaning
a_alive(e: element)boolThe element is alive.
a_attitude(e: element)intThe element's attitude: FRIENDLY, HOSTILE, NEUTRAL or UNATTACKABLE.
a_buff(e: element, id: buff)boolThe element has the buff.
a_buff_named(e: element, name: acr.buff)boolThe element carries a buff of that named group.
a_buff_named_stacks(e: element, name: acr.buff)intStacks of a named buff group on the element, added up over every application.
a_buff_stacks(e: element, id: buff)intStacks of the buff on the element, added up over every application.
a_buff_time(e: element, id: buff)intMs left on the buff on the element.
a_conditions(e: element)boolThe element has a damaging or control condition (the list under target_conditions).
a_dist2(e: element)floatDistance from the local character to the element in game units (2D).
a_dist3(e: element)floatDistance from the local character to the element in game units (3D).
a_downed(e: element)boolThe element is downed.
a_has_health(e: element)boolThe element has health (characters and gadgets).
a_health_max(e: element)floatThe element's maximum health in health points; 0 when it has no health. Use it with a_missing(e) to get the missing fraction without rounding through a_hp(e).
a_hp(e: element)floatThe element's health as a fraction 0.0 to 1.0.
a_id(e: element)intThe element's agent id (0 when none).
a_is(e: element, name: acr.agent)boolThe element is that named agent.
a_is_ccd(e: element)boolThe element is a character that is knocked down, floating, stunned, launched or knocked back.
a_local(e: element)boolThe element is the local character.
a_mine(e: element)boolThe element belongs to the local character (a pet, minion or clone).
a_missing(e: element)floatThe element's missing health in health points.
a_radius(e: element)floatThe element's hitbox radius in game units.
a_x(e: element)floatThe element's x position in game units.
a_y(e: element)floatThe element's y position in game units.
a_z(e: element)floatThe element's z position in game units.

Group helpers ​

BuiltinReturnsMeaning
downed_ally(range: units, missing: health)intThe first downed player within range who misses at least missing health, as an element handle; -1 when none.
need_boon_strip(a: acr.buff, b: acr.buff, c: acr.buff, d: acr.buff)boolThe selected character has any of up to four named buff groups; pass -1 for unused slots.
need_buff(id: buff, range: units)boolA group member within range lacks the buff. The group is your party, else your squad subgroup, else friendly players.
need_buff_duration(id: buff, ms: int, range: units)boolA group member within range has less than ms left on the buff.
need_buff_stacks(id: buff, stacks: int, range: units)boolA group member within range has fewer than stacks of the buff (added up over every application).
need_cleanse(range: units)boolAnother friendly player within range has a damaging or control condition.
need_heal(below: fraction, range: units)boolA friendly player (you included) within range is at or below below health (0.0 to 1.0).

Groups, trees and executors ​

BuiltinReturnsMeaning
can_run(unit: group or tree)boolSome node of the group or tree could run now (instants included).
can_run_normal(unit: group or tree)boolA non-instant node of the group or tree could run now.
executor_daemon()statementStatement: run the post-cast facing step of the KX executor (put it in daemon for rotations that use :post_face()).
run(unit: group or tree)statementStatement: run a group or tree with the handler's target; it casts the best node that passes.
run_untargeted(unit: group or tree)statementStatement: run with no target.

Pet and mech ​

BuiltinReturnsMeaning
kennel_cd(skill: skill id)intThe active pet's recharge of that skill in ms; -1 when the pet does not have it.
kennel_in_range(range: units)boolThe pet (or mech) is within range game units of the selected target (3D).
kennel_on_bar(skill: skill id)boolThe active pet has that skill.
kennel_ready(skill: skill id)boolThe active pet has the skill and it is ready.
kennel_swap()statementStatement: swap pets, only while a pet is out.
kennel_swap_ready()boolA pet is out and the pet swap is off recharge.
pet()intThe active pet (or mech) as an element handle; -1 with none out.

Resources ​

BuiltinReturnsMeaning
energy()floatThe profession's first resource, in this order: tome pages, astral force, revenant energy, heat, adrenaline, life force, catalyst energy, clones, shadow force. 0 when none.
energy_max()floatThe maximum of energy().
enough_energy(skill: skill id)boolThe profession's first resource (see energy()) is at least the skill's life_force_cost.
has_res(kind: resource)boolThe character has that resource.
life_force_cost(skill: skill id)floatThe skill's life-force (or first-resource) cost; 0 when none.
res(kind: resource)floatA resource's current value: ADRENALINE, INITIATIVE, LIFE_FORCE, REVENANT_ENERGY, CLONES, ... (constants below). 0 when the character has none.
res_max(kind: resource)floatThe resource's maximum.
reset_count(skill: skill id)statementStatement: reset the skill's cast counter to 0.
skill_cost(skill: skill id)intThe skill's resource cost (initiative, energy...) as an integer; 0 when it has none.

Skills ​

BuiltinReturnsMeaning
ammo(skill: skill id)intCharges available (0 for an unknown skill).
ammo_bar(skill: skill id)intCharges available for a skill on the bar; 0 when it is not on the bar.
ammo_cd(skill: skill id)intMs until the next charge comes back (0 when full or unknown).
ammo_cd_bar(skill: skill id)intMs until the next charge, for a skill on the bar; -1 when it is not on the bar.
available(skill: skill id)boolready(skill) and the selected target within the skill's range + 0.8 x its radius + the target's radius.
available_bar(skill: skill id)boolready_bar(skill) and the selected target within range, as available.
cd(skill: skill id)intRecharge left in ms (0 when ready or unknown).
cd_adj(skill: skill id)intRecharge left in ms, as the game shows it with alacrity applied.
cd_bar(skill: skill id)intRecharge left in ms for a skill on the bar; -1 when it is not on the bar, so cd_bar(x) < 500 is also true then.
cd_cta(skill: skill id)intRecharge left in ms minus the time left in the current cast, never below 0: the recharge that will remain once the cast in progress ends.
count(skill: skill id)intHow many times the skill has been cast since its counter was last reset.
current(skill: skill id)boolThe local character's current skill order is this skill (it is being cast).
on_bar(skill: skill id)boolThe skill is on the current skill bar.
queued(skill: skill id)boolThe skill is in the engine's cast queue.
ready(skill: skill id)boolThe skill is off recharge, with a charge left for charge skills. Any skill the player has, on the bar or not. False for a skill KX has never seen.
ready_bar(skill: skill id)boolLike ready, for a skill on the current skill bar only; false when it is not on the bar.
recently_used(skill: skill id, ms: int)boolThe skill went on recharge within the last ms: its full recharge minus ms is below the recharge left.
skill_radius(skill: skill id)floatThe skill's area radius in game units (0 when it has none or is unknown).
skill_range(skill: skill id)floatThe skill's range in game units (0 when unknown).
slot_skill(slot: int)intThe skill in a bar slot: 0 heal, 1-3 utilities, 4 elite, 5-9 weapon skills 1-5, 10 and up profession skills. -1 when the slot is empty.
time_since(skill: skill id)intMs since the skill was last cast (very large when never).
used_within(skill: skill id, ms: int)boolThe skill was cast within the last ms milliseconds. A skill never cast reads as long ago.

Target ​

BuiltinReturnsMeaning
get_target()intThe agent the engine would pick as target right now, as an element handle; -1 when none.
has_target()boolAn agent is selected.
largos_cc_phase()boolEncounter: the selected Largos twin has barrier (its break-bar phase).
matthias_stacks()intEncounter: Blood Shield stacks on Matthias (0 elsewhere).
sabir_cc_phase()boolEncounter: Cardinal Sabir has barrier (his break-bar phase).
target()intThe handler's target as an element handle; -1 when none.
target_barrier()floatThe selected target's barrier in health points.
target_breakable()boolThe selected target has a break bar that can be broken now.
target_buff(id: buff)boolThe selected character has the buff.
target_buff_mine(id: buff)boolThe selected character has a stack of the buff that you applied.
target_buff_named(name: acr.buff)boolThe selected character has a buff of that named group.
target_buff_named_stacks(name: acr.buff)intStacks of a named buff group on the selected character, added up over every application (0 when none).
target_buff_named_time(name: acr.buff)intMs left on a named buff group on the selected character (0 when none).
target_buff_stacks(id: buff)intStacks of the buff on the selected character, added up over every application.
target_buff_time(id: buff)intMs left on the buff on the selected character.
target_conditions()boolThe selected target has a damaging or control condition (bleeding, blind, burning, chill, confusion, cripple, fear, immobile, poison, slow, taunt, torment, vulnerability, weakness, daze, stun).
target_hp()floatThe selected target's health as a fraction 0.0 to 1.0 (0 when none).
target_in_combat()boolThe selected character is in combat.
target_in_range2(range: units)boolThe selected target's centre is within range game units (2D).
target_in_range3(range: units)boolThe selected target's centre is within range game units (3D).
target_in_range_skill(skill: skill id)boolThe selected target is within the skill's range + the target's radius (2D).
target_in_skill_range(skill: skill id)boolThe selected target is within the skill's range + 0.8 x its radius + the target's radius (2D).
target_is(name: acr.agent)boolThe selected character is that named agent.
target_is_ccd()boolThe selected character is knocked down, floating, stunned, launched or knocked back.
target_is_player()boolThe selected character is a player.
target_radius()floatThe selected target's hitbox radius in game units.

The current cast ​

BuiltinReturnsMeaning
busy()boolA cast is in progress and below 100%.
cast_max()intFull cast time of the current cast in ms (0 when not casting).
cast_pct()floatHow far the current cast is, 0.0 to 1.0 of its full cast time (1.0 for a skill with no cast time; 0.0 when not casting).
cast_remaining()intMs left in the current cast (0 when not casting).
cast_skill(skill: skill id)statementStatement: cast the skill by id with no target, if it is on the bar.
cast_time()intMs the current cast has run (0 when not casting).
cur_skill()intThe skill id being cast right now, as the engine's tracker sees it; -1 when not casting.
hits()intHits counted so far on the current cast.
last_skill()intThe skill id of the last finished cast; -1 before the first.
order_id()intThe local character's current skill order id; -1 with no order. A new order of the same skill gets a new id.

Timers, stopwatches and tasks ​

BuiltinReturnsMeaning
sw_elapsed(t: stopwatch)intMs since the stopwatch started; 0 when not started.
t_elapsed(t: timer)intMs since the timer started, at most its delay; 0 when not started.
t_finished(t: timer)boolThe timer's delay has passed since it started.
t_force(t: timer)statementStatement: restart the timer from now.
t_remaining(t: timer)intMs until the timer finishes; 0 when finished.
t_reset(t: timer)statementStatement: stop the timer.
t_start(t: timer)statementStatement: start the timer if it is not running.
t_started(t: timer)boolThe timer is running or has finished.
task_ready(t: task)boolThe task is not running or its delay has passed (does not restart it).
task_run(t: task)boolTrue when the task is not running or its delay has passed, and then it restarts the task. False while the task is still running. Use it to do something at most once per delay.

Weapons and legends ​

BuiltinReturnsMeaning
equip_legends(a: skill, b: skill)statementStatement (Revenant): equip legend a in the active slot and b in the other one.
on_current_weapons(main: weapon, offhand: weapon)boolLike on_weapons, for the set the game reports right now (ignores a swap just sent).
on_weapons(main: weapon, offhand: weapon)boolThe weapon set the rotation is on (including a swap just sent) is main + offhand. Use NONE as offhand for a two-handed weapon, for example on_weapons(GREATSWORD, NONE).
pending_swap()boolA weapon swap has been sent and the game has not shown it yet.
stance_cd()intRevenant: legend swap recharge left in ms (0 on other professions).
stance_id()intRevenant: the active legend's id (0 on other professions).
stance_ready()boolRevenant: legend swap is off recharge. False on other professions.
swap_cd()intWeapon swap recharge left in ms.
swap_now()statementStatement: swap weapons now.
swap_ready()boolWeapon swap is off recharge.

You and the world ​

BuiltinReturnsMeaning
alive()boolThe local character is alive (not downed or dead).
barrier()floatThe local character's barrier in health points.
combat_time()intMs since the local character entered combat; 0 out of combat. Useful for timed openers.
downed()boolThe local character is downed.
endurance()intThe local character's endurance, 0 to 100 (a dodge costs 50).
evading()boolThe local character is dodging or evading.
face_target()statementStatement: turn to face the handler's target (rate-limited).
facing_target(angle: radians)boolThe selected target is within angle radians of where the local character faces (2D).
final_effect_fired()boolThe skill you are casting has fired its last effect, so what remains of the cast is only the end of the animation. False when the game does not say.
health()floatThe local character's health in health points.
health_max()floatThe local character's maximum health in health points.
hp()floatThe local character's health as a fraction, 0.0 to 1.0 (hp() < 0.5 is below half).
in_combat()boolThe local character is in combat.
in_cylinder(bx: float, by: float, bz: float, r: float, height: float, px: float, py: float, pz: float)boolThe point (px, py, pz) is inside the upright cylinder with its bottom centre at (bx, by, bz): z within [bz, bz + height], then 2D distance <= r. Game units.
in_party()boolThe local player is in a party.
in_squad()boolThe local player is in a squad.
is_ccd()boolThe local character is knocked down, floating, stunned, launched or knocked back.
map_id()intThe current map id.
melee_only(enabled: bool, range: units)boolTrue when enabled is false. Otherwise the selected target is within its own radius + range game units (3D).
moving()boolThe local character is moving (a movement direction is held).
not_moving(enabled: bool)boolTrue when enabled is false. Otherwise true once the character has stood still (no movement, no evade) for a short settle time.
now()intThe game clock in ms.
ping()intNetwork latency in ms.
profession()intThe local character's profession id (see acr.GUARDIAN ... in the Lua API).
revive_agent(e: element)statementStatement: revive that ally. If your own jump, dodge or walk ended your revive of an ally, it skips that ally until the ally gets up, is defeated or leaves revive range.
spec()intThe local character's elite specialization id (0 for core).
special_evading()boolThe special-action dodge (for example the Vindicator's) is active. KX does not capture it in game yet, so it is always false there.
swimming()boolThe local character is underwater.

Your buffs ​

BuiltinReturnsMeaning
buff(id: buff)boolThe local character has the buff (a buff id, or a name from acr.buff).
buff_mine(id: buff)boolThe local character has a stack of the buff that it applied itself.
buff_named(name: acr.buff)boolThe local character has a buff of that named group.
buff_named_stacks(name: acr.buff)intStacks of a named buff group on the local character, added up over every application.
buff_named_time(name: acr.buff)intMs left on a named buff group on the local character.
buff_stacks(id: buff)intStacks of the buff on the local character, added up over every application (0 when none).
buff_time(id: buff)intMs left on the buff on the local character (0 when none).