Appearance
22. Builtins (every function you can call in a condition)
The ones you will use most:
| Need | Use |
|---|---|
| Is a skill on my bar / ready? | on_bar(X), ready_bar(X) (ready(X) also counts skills not on the bar) |
| Recharge left | cd_bar(X) (ms; -1 when not on the bar, so cd_bar(X) < 500 is true then), cd(X) (0 when ready or unknown) |
| Charges | ammo_bar(X), ammo_cd_bar(X) |
| Which weapon set | on_weapons(GREATSWORD, NONE), on_weapons(AXE, AXE), swap_ready() |
| My resources | res(ADRENALINE), res_max(ADRENALINE), has_res(INITIATIVE), endurance() |
| My health / target health | hp(), target_hp() (fractions 0.0-1.0) |
| Buffs on me / the target | buff(ID), buff_stacks(ID), buff_time(ID), target_buff(ID), target_buff_stacks(ID), buff_named(acr.buff) |
| What I am casting | busy(), cur_skill(), current(X), cast_pct(), cast_remaining(), final_effect_fired(), last_skill() |
| Recently used | used_within(X, ms), time_since(X), recently_used(X, ms) |
| Fight state | in_combat(), combat_time(), moving(), target_breakable(), has_target() |
| Range | target_in_range2(units), target_in_skill_range(X), skill_range(X) |
| Allies | need_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
| Builtin | Returns | Meaning |
|---|---|---|
e_hash(e: effect) | int | The effect's hashed name (compare with an acr.fx constant). |
e_on_target(e: effect, radius: units, height: units, target_height: units) | bool | The 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) | float | The effect's x position in game units. |
e_y(e: effect) | float | The effect's y position in game units. |
e_z(e: effect) | float | The effect's z position in game units. |
Elements (agents in a collection, target(), pet())
| Builtin | Returns | Meaning |
|---|---|---|
a_alive(e: element) | bool | The element is alive. |
a_attitude(e: element) | int | The element's attitude: FRIENDLY, HOSTILE, NEUTRAL or UNATTACKABLE. |
a_buff(e: element, id: buff) | bool | The element has the buff. |
a_buff_named(e: element, name: acr.buff) | bool | The element carries a buff of that named group. |
a_buff_named_stacks(e: element, name: acr.buff) | int | Stacks of a named buff group on the element, added up over every application. |
a_buff_stacks(e: element, id: buff) | int | Stacks of the buff on the element, added up over every application. |
a_buff_time(e: element, id: buff) | int | Ms left on the buff on the element. |
a_conditions(e: element) | bool | The element has a damaging or control condition (the list under target_conditions). |
a_dist2(e: element) | float | Distance from the local character to the element in game units (2D). |
a_dist3(e: element) | float | Distance from the local character to the element in game units (3D). |
a_downed(e: element) | bool | The element is downed. |
a_has_health(e: element) | bool | The element has health (characters and gadgets). |
a_health_max(e: element) | float | The 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) | float | The element's health as a fraction 0.0 to 1.0. |
a_id(e: element) | int | The element's agent id (0 when none). |
a_is(e: element, name: acr.agent) | bool | The element is that named agent. |
a_is_ccd(e: element) | bool | The element is a character that is knocked down, floating, stunned, launched or knocked back. |
a_local(e: element) | bool | The element is the local character. |
a_mine(e: element) | bool | The element belongs to the local character (a pet, minion or clone). |
a_missing(e: element) | float | The element's missing health in health points. |
a_radius(e: element) | float | The element's hitbox radius in game units. |
a_x(e: element) | float | The element's x position in game units. |
a_y(e: element) | float | The element's y position in game units. |
a_z(e: element) | float | The element's z position in game units. |
Group helpers
| Builtin | Returns | Meaning |
|---|---|---|
downed_ally(range: units, missing: health) | int | The 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) | bool | The selected character has any of up to four named buff groups; pass -1 for unused slots. |
need_buff(id: buff, range: units) | bool | A 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) | bool | A group member within range has less than ms left on the buff. |
need_buff_stacks(id: buff, stacks: int, range: units) | bool | A group member within range has fewer than stacks of the buff (added up over every application). |
need_cleanse(range: units) | bool | Another friendly player within range has a damaging or control condition. |
need_heal(below: fraction, range: units) | bool | A friendly player (you included) within range is at or below below health (0.0 to 1.0). |
Groups, trees and executors
| Builtin | Returns | Meaning |
|---|---|---|
can_run(unit: group or tree) | bool | Some node of the group or tree could run now (instants included). |
can_run_normal(unit: group or tree) | bool | A non-instant node of the group or tree could run now. |
executor_daemon() | statement | Statement: 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) | statement | Statement: run a group or tree with the handler's target; it casts the best node that passes. |
run_untargeted(unit: group or tree) | statement | Statement: run with no target. |
Pet and mech
| Builtin | Returns | Meaning |
|---|---|---|
kennel_cd(skill: skill id) | int | The active pet's recharge of that skill in ms; -1 when the pet does not have it. |
kennel_in_range(range: units) | bool | The pet (or mech) is within range game units of the selected target (3D). |
kennel_on_bar(skill: skill id) | bool | The active pet has that skill. |
kennel_ready(skill: skill id) | bool | The active pet has the skill and it is ready. |
kennel_swap() | statement | Statement: swap pets, only while a pet is out. |
kennel_swap_ready() | bool | A pet is out and the pet swap is off recharge. |
pet() | int | The active pet (or mech) as an element handle; -1 with none out. |
Resources
| Builtin | Returns | Meaning |
|---|---|---|
energy() | float | The 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() | float | The maximum of energy(). |
enough_energy(skill: skill id) | bool | The profession's first resource (see energy()) is at least the skill's life_force_cost. |
has_res(kind: resource) | bool | The character has that resource. |
life_force_cost(skill: skill id) | float | The skill's life-force (or first-resource) cost; 0 when none. |
res(kind: resource) | float | A resource's current value: ADRENALINE, INITIATIVE, LIFE_FORCE, REVENANT_ENERGY, CLONES, ... (constants below). 0 when the character has none. |
res_max(kind: resource) | float | The resource's maximum. |
reset_count(skill: skill id) | statement | Statement: reset the skill's cast counter to 0. |
skill_cost(skill: skill id) | int | The skill's resource cost (initiative, energy...) as an integer; 0 when it has none. |
Skills
| Builtin | Returns | Meaning |
|---|---|---|
ammo(skill: skill id) | int | Charges available (0 for an unknown skill). |
ammo_bar(skill: skill id) | int | Charges available for a skill on the bar; 0 when it is not on the bar. |
ammo_cd(skill: skill id) | int | Ms until the next charge comes back (0 when full or unknown). |
ammo_cd_bar(skill: skill id) | int | Ms until the next charge, for a skill on the bar; -1 when it is not on the bar. |
available(skill: skill id) | bool | ready(skill) and the selected target within the skill's range + 0.8 x its radius + the target's radius. |
available_bar(skill: skill id) | bool | ready_bar(skill) and the selected target within range, as available. |
cd(skill: skill id) | int | Recharge left in ms (0 when ready or unknown). |
cd_adj(skill: skill id) | int | Recharge left in ms, as the game shows it with alacrity applied. |
cd_bar(skill: skill id) | int | Recharge 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) | int | Recharge 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) | int | How many times the skill has been cast since its counter was last reset. |
current(skill: skill id) | bool | The local character's current skill order is this skill (it is being cast). |
on_bar(skill: skill id) | bool | The skill is on the current skill bar. |
queued(skill: skill id) | bool | The skill is in the engine's cast queue. |
ready(skill: skill id) | bool | The 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) | bool | Like 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) | bool | The skill went on recharge within the last ms: its full recharge minus ms is below the recharge left. |
skill_radius(skill: skill id) | float | The skill's area radius in game units (0 when it has none or is unknown). |
skill_range(skill: skill id) | float | The skill's range in game units (0 when unknown). |
slot_skill(slot: int) | int | The 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) | int | Ms since the skill was last cast (very large when never). |
used_within(skill: skill id, ms: int) | bool | The skill was cast within the last ms milliseconds. A skill never cast reads as long ago. |
Target
| Builtin | Returns | Meaning |
|---|---|---|
get_target() | int | The agent the engine would pick as target right now, as an element handle; -1 when none. |
has_target() | bool | An agent is selected. |
largos_cc_phase() | bool | Encounter: the selected Largos twin has barrier (its break-bar phase). |
matthias_stacks() | int | Encounter: Blood Shield stacks on Matthias (0 elsewhere). |
sabir_cc_phase() | bool | Encounter: Cardinal Sabir has barrier (his break-bar phase). |
target() | int | The handler's target as an element handle; -1 when none. |
target_barrier() | float | The selected target's barrier in health points. |
target_breakable() | bool | The selected target has a break bar that can be broken now. |
target_buff(id: buff) | bool | The selected character has the buff. |
target_buff_mine(id: buff) | bool | The selected character has a stack of the buff that you applied. |
target_buff_named(name: acr.buff) | bool | The selected character has a buff of that named group. |
target_buff_named_stacks(name: acr.buff) | int | Stacks of a named buff group on the selected character, added up over every application (0 when none). |
target_buff_named_time(name: acr.buff) | int | Ms left on a named buff group on the selected character (0 when none). |
target_buff_stacks(id: buff) | int | Stacks of the buff on the selected character, added up over every application. |
target_buff_time(id: buff) | int | Ms left on the buff on the selected character. |
target_conditions() | bool | The 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() | float | The selected target's health as a fraction 0.0 to 1.0 (0 when none). |
target_in_combat() | bool | The selected character is in combat. |
target_in_range2(range: units) | bool | The selected target's centre is within range game units (2D). |
target_in_range3(range: units) | bool | The selected target's centre is within range game units (3D). |
target_in_range_skill(skill: skill id) | bool | The selected target is within the skill's range + the target's radius (2D). |
target_in_skill_range(skill: skill id) | bool | The selected target is within the skill's range + 0.8 x its radius + the target's radius (2D). |
target_is(name: acr.agent) | bool | The selected character is that named agent. |
target_is_ccd() | bool | The selected character is knocked down, floating, stunned, launched or knocked back. |
target_is_player() | bool | The selected character is a player. |
target_radius() | float | The selected target's hitbox radius in game units. |
The current cast
| Builtin | Returns | Meaning |
|---|---|---|
busy() | bool | A cast is in progress and below 100%. |
cast_max() | int | Full cast time of the current cast in ms (0 when not casting). |
cast_pct() | float | How 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() | int | Ms left in the current cast (0 when not casting). |
cast_skill(skill: skill id) | statement | Statement: cast the skill by id with no target, if it is on the bar. |
cast_time() | int | Ms the current cast has run (0 when not casting). |
cur_skill() | int | The skill id being cast right now, as the engine's tracker sees it; -1 when not casting. |
hits() | int | Hits counted so far on the current cast. |
last_skill() | int | The skill id of the last finished cast; -1 before the first. |
order_id() | int | The 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
| Builtin | Returns | Meaning |
|---|---|---|
sw_elapsed(t: stopwatch) | int | Ms since the stopwatch started; 0 when not started. |
t_elapsed(t: timer) | int | Ms since the timer started, at most its delay; 0 when not started. |
t_finished(t: timer) | bool | The timer's delay has passed since it started. |
t_force(t: timer) | statement | Statement: restart the timer from now. |
t_remaining(t: timer) | int | Ms until the timer finishes; 0 when finished. |
t_reset(t: timer) | statement | Statement: stop the timer. |
t_start(t: timer) | statement | Statement: start the timer if it is not running. |
t_started(t: timer) | bool | The timer is running or has finished. |
task_ready(t: task) | bool | The task is not running or its delay has passed (does not restart it). |
task_run(t: task) | bool | True 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
| Builtin | Returns | Meaning |
|---|---|---|
equip_legends(a: skill, b: skill) | statement | Statement (Revenant): equip legend a in the active slot and b in the other one. |
on_current_weapons(main: weapon, offhand: weapon) | bool | Like on_weapons, for the set the game reports right now (ignores a swap just sent). |
on_weapons(main: weapon, offhand: weapon) | bool | The 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() | bool | A weapon swap has been sent and the game has not shown it yet. |
stance_cd() | int | Revenant: legend swap recharge left in ms (0 on other professions). |
stance_id() | int | Revenant: the active legend's id (0 on other professions). |
stance_ready() | bool | Revenant: legend swap is off recharge. False on other professions. |
swap_cd() | int | Weapon swap recharge left in ms. |
swap_now() | statement | Statement: swap weapons now. |
swap_ready() | bool | Weapon swap is off recharge. |
You and the world
| Builtin | Returns | Meaning |
|---|---|---|
alive() | bool | The local character is alive (not downed or dead). |
barrier() | float | The local character's barrier in health points. |
combat_time() | int | Ms since the local character entered combat; 0 out of combat. Useful for timed openers. |
downed() | bool | The local character is downed. |
endurance() | int | The local character's endurance, 0 to 100 (a dodge costs 50). |
evading() | bool | The local character is dodging or evading. |
face_target() | statement | Statement: turn to face the handler's target (rate-limited). |
facing_target(angle: radians) | bool | The selected target is within angle radians of where the local character faces (2D). |
final_effect_fired() | bool | The 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() | float | The local character's health in health points. |
health_max() | float | The local character's maximum health in health points. |
hp() | float | The local character's health as a fraction, 0.0 to 1.0 (hp() < 0.5 is below half). |
in_combat() | bool | The local character is in combat. |
in_cylinder(bx: float, by: float, bz: float, r: float, height: float, px: float, py: float, pz: float) | bool | The 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() | bool | The local player is in a party. |
in_squad() | bool | The local player is in a squad. |
is_ccd() | bool | The local character is knocked down, floating, stunned, launched or knocked back. |
map_id() | int | The current map id. |
melee_only(enabled: bool, range: units) | bool | True when enabled is false. Otherwise the selected target is within its own radius + range game units (3D). |
moving() | bool | The local character is moving (a movement direction is held). |
not_moving(enabled: bool) | bool | True when enabled is false. Otherwise true once the character has stood still (no movement, no evade) for a short settle time. |
now() | int | The game clock in ms. |
ping() | int | Network latency in ms. |
profession() | int | The local character's profession id (see acr.GUARDIAN ... in the Lua API). |
revive_agent(e: element) | statement | Statement: 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() | int | The local character's elite specialization id (0 for core). |
special_evading() | bool | The 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() | bool | The local character is underwater. |
Your buffs
| Builtin | Returns | Meaning |
|---|---|---|
buff(id: buff) | bool | The local character has the buff (a buff id, or a name from acr.buff). |
buff_mine(id: buff) | bool | The local character has a stack of the buff that it applied itself. |
buff_named(name: acr.buff) | bool | The local character has a buff of that named group. |
buff_named_stacks(name: acr.buff) | int | Stacks of a named buff group on the local character, added up over every application. |
buff_named_time(name: acr.buff) | int | Ms left on a named buff group on the local character. |
buff_stacks(id: buff) | int | Stacks of the buff on the local character, added up over every application (0 when none). |
buff_time(id: buff) | int | Ms left on the buff on the local character (0 when none). |