---
url: https://docs.kxtools.xyz/client/acr/api.md
---
# Lua API

Every `acr.*` function and node method, and the expression language your conditions are written in. The functions you can call inside a condition are on [Builtins](/client/acr/builtins).

## 6. `acr.build { ... }` {#s6}

Who the rotation is for. Every field is optional except `id` and `name`. An unknown field is an error.

| Field | Value |
| --- | --- |
| `id` | unique snake_case id; use it as the file name too (`<id>.lua`) |
| `name` | display name |
| `origin` | `"user"` for your own builds (the others are `"current"`, `"historical"` and `"kx"`) |
| `profession` | `acr.GUARDIAN`, `acr.WARRIOR`, `acr.ENGINEER`, `acr.RANGER`, `acr.THIEF`, `acr.ELEMENTALIST`, `acr.MESMER`, `acr.NECROMANCER`, `acr.REVENANT` |
| `elite` | elite specialization id ([section 21](/client/acr/reference#s21)). The build only runs while your character has that elite. Leave it out for a build any specialization can use. |
| `specs` | the 3 specialization ids |
| `traits` | the 9 trait ids, three per specialization |
| `skills` | heal, three utilities, elite (skill ids; `0` leaves a slot empty) |
| `legends` | Revenant: the two legend ids, for example `{ 46409, 28494 }` |
| `special` | weapon skills for slots 6 and up |
| `weapons` | weapon sets: `{ { acr.GREATSWORD }, { acr.AXE, acr.AXE } }`, one-handed main + off-hand or one two-hander per set |
| `links` | `{ build = url, benchmark = url, chat = "[&...]" }` |
| `source` | free data about where the build comes from |

KX uses `profession`, `elite`, `specs`, `traits` and `weapons` to pick the best build for a character automatically and to notice "Wrong weapons". Fill them in.

## 7. Constants and names {#s7}

### `local C = acr.const { NAME = value, ... }`

Names you can use in Lua (`C.GS_2`) and inside expressions (`"cd_bar(GS_2) > 3000"`). Values:

* a number, integer or float: a skill id, buff id, distance, duration or any threshold you want to name (`ENTER_AT = 80`);
* a boolean;
* `acr.buff "Might"`: a named buff group ([section 23](/client/acr/reference#s23));
* `acr.agent "Matthias Gabrel"`: an NPC by name ([section 23](/client/acr/reference#s23));
* `acr.fx "effect name"`: a ground effect by its hashed name (advanced).

You can call `acr.const` more than once. You can define a name only once. `acr.const` returns the table, so `local C = acr.const {...}` works.

## 8. Toggles (switches on the Skills page) {#s8}

### `acr.toggle(key, label, { skill =, icon =, tip =, default =, section = })`

Adds a switch on the Skills page and returns `key`.

* `default`: `true` when left out. An **integer** default makes a number field instead of a checkbox (useful for thresholds).
* `skill`: the skill whose icon is shown. `tip`: hover text.
* `icon`: a game picture for a switch that is not about one single skill. Only `icon = "weapon_swap"` (the weapon swap button) exists so far. Any other name is an error. Give every weapon swap switch this icon. A switch that gates only `swap()` nodes (through `:enabled(key)`) shows this icon on its own, so builds without the `icon` field still get the icon.
* `section`: a header the switch is listed under, for example `section = "CC"`. Declare switches of one section together. The page keeps the declaration order.
* In expressions a toggle reads as its value: `"!my_build_use_rush"`, `"hp() * 100.0 < my_build_heal_below"`.
* A row can depend on a toggle directly with `:enabled("key")`.

## 9. Variables, timers, stopwatches and tasks {#s9}

| Lua | Meaning |
| --- | --- |
| `acr.var(name, init)` | A variable. Its type follows `init`: `true`/`false`, an integer, or a float such as `0.0`. Change it in statements: `"opened = true;"`. |
| `acr.timer(name, delay_ms, { started = true })` | A timer that finishes `delay_ms` after it starts. |
| `acr.stopwatch(name)` | Counts up from when it is started. |
| `acr.task(name, delay_ms)` | "At most once per delay": `task_run(name)` is true and restarts the task when the delay has passed. |

Start, read and stop them with the builtins in "Timers, stopwatches and tasks" ([section 22](/client/acr/builtins)): `t_start`, `t_force`, `t_reset`, `t_started`, `t_finished`, `t_elapsed`, `t_remaining`, `sw_elapsed`, `task_ready`, `task_run`. `t_start`, `t_force`, `t_reset` and `t_started` work on stopwatches too.

Statements run in handlers (usually `daemon`) and in a row's `:pre(...)`, which runs just before that row's action.

## 10. Defs (named expressions) {#s10}

### `acr.def("name(a, b)", "expression")`

A named snippet. KX pastes it in wherever you use the name (like a macro). The body counts as one value, as if it were in parentheses, so `!name(...)` and `x && name` work as expected. A def without parameters is used without parentheses.

```lua
acr.def("on_gs", "on_weapons(GREATSWORD, NONE)")
acr.def("full_adrenaline", "has_res(ADRENALINE) && res(ADRENALINE) >= res_max(ADRENALINE)")
acr.def("both_spent(a, b)", "!ready_bar(a) && !ready_bar(b)")
```

## 11. Nodes (one thing the rotation can do) {#s11}

A node (row) starts with a kind, then chains options.

| Kind | Meaning |
| --- | --- |
| `skill(C.ID)` | cast a skill |
| `skill { C.A, C.B }` | one row per id, same priority, in this order (variants of one slot, auto-attack chains) |
| `swap()` | swap weapon sets (leave a kit with its stow skill instead, [recipe 16.2](/client/acr/recipes#s16-2)) |
| `kennel(cmd, C.ID)` | pet or mech command: `cmd` is `"skill1"`, `"skill2"`, `"skill3"`, `"attack"` or `"return"`; the id names the skill it casts. Mechanist: `skill1`/`skill2`/`skill3` = mech F1/F2/F3. Ranger: `skill1` = the pet's F2 skill. `kennel("return")` needs no id. |
| `acr.cancel(C.ID, "stow")`, `acr.cancel(C.ID, "cancel")` | stow a bundle, or cancel a channel |
| `acr.evade { mode =, dir =, endurance = }` | dodge. `mode = "special"` (recommended, used by every built-in): dodge the way your dodge key does, so specialization dodges (Daredevil, Mirage, Vindicator) work. `mode = "direction"` with `dir` 0-7: back, back-left, back-right, forward, forward-left, forward-right, left, right. `mode = "mouse"`: toward the cursor. `endurance`: the least endurance needed. |
| `acr.node()` | no kind yet: a template whose uses set the skill |

### Conditions

* `:when(expr, ...)`: every expression must be true. Repeat it to add more.
* `:when_any(expr, ...)`: at least one must be true.
* A row passes when all its `when` expressions hold and either it has no `when_any` or one of them holds. So use both for "all of these, and at least one of those".

### Options

| Option | Meaning |
| --- | --- |
| `:enabled(toggle_key)` | only while that toggle is on |
| `:range()` / `:range(n)` | the target is within the skill's range (or `n`), measured to the target's edge (its hit radius is added, as the game does). If the game data has no range for the skill, `:range()` checks nothing, so give a number. `:range("d0")` / `:range("d1")` use the skill's own distance values (rare). |
| `:radius()` / `:radius(n)` | the skill's area reaches the target. A skill with no area checks nothing, so pair it with `:range()`. On a ground skill it also lets the aim use the circle's size ([16.12](/client/acr/recipes#s16-12)). |
| `:min_range(n)` | the target is at least `n` away (to its edge) |
| `:facing()` / `:facing(radians)` | the target is in front of you (default about 78° either side, or your angle). It only checks. It does not turn you ([16.11](/client/acr/recipes#s16-11)) |
| `:cone(angle, length)`, `:dash(width, length)` | shape checks for cones and dashes |
| `:target("default")`, `:target("target")` | cast at the default target, or at the selected target |
| `:ground(mode)` | where a ground-targeted skill lands: `"target"` (on the target), `"center"` (the target's centre), `"self"` (at your feet), `"minimize"` (the near edge of the target's hitbox, or your feet when that already reaches it) / `"maximize"` (the farthest point in range through the target), `"mouse"` (the cursor), `"boon"` / `"heal"` (where it reaches the most allies). Default: at the target, or at full range toward it while the circle still reaches its hitbox. Add `:range():radius()` ([16.12](/client/acr/recipes#s16-12)). |
| `:target_with(expr)` | choose the target per cast with an int expression (`TARGET_*`, `GROUND_*` constants) |
| `:insta()` / `:insta(false)` | fire alongside the chosen row instead of competing. Skills the game marks instant already do. `:insta(false)` makes such a skill wait its turn |
| `:on_bar(false)`, `:ready(false)`, `:casting(false)`, `:queue(false)` | turn off a default check |
| `:will_cancel()` | this skill would cancel the current cast, so it waits for that cast to end (it is sent to start as the cast ends). `:will_cancel()` does not hold instants and swaps. Gate those with `!busy()`. |
| `:cannot_cancel()` | once it starts, nothing may cancel it (channels such as Hundred Blades) |
| `:queue_after()` | queue it behind the current cast |
| `:post_face()` | face the target after casting (put `executor_daemon();` in `daemon` when you use it) |
| `:cast_time(ms)`, `:hits(n)`, `:custom_trigger(n)`, `:last_trigger_idx(n)`, `:last_trigger_type(n)` | when a cast counts as finished, for skills whose game data doesn't say (rarely needed) |
| `:override_by("all")`, `:override_by { C.A, C.B }` | which skills may interrupt this one (any, or only those) |
| `:actual_skill(C.ID)` | the skill id the game reports while this one runs |
| `:pre("statements;")` | statements to run just before the action |
| `:label(text)` | a name for the row, shown in KX's views |
| `:skill(C.ID)` | change the skill (on a clone) |

## 12. Templates {#s12}

A template is a row you use more than once. Push it as it is, or clone it and change the clone.

```lua
local grenade_kit = acr.template("grenade_kit", skill(C.GRENADE_KIT):when("!ready_bar(PISTOL_3)"))
group:push(8, grenade_kit)                                   -- as it is
group:push(8, grenade_kit:clone():skill(C.GRENADE_KIT_ALT))  -- a variant
group:push(7, grenade_kit:clone():when("target_hp() < 0.5")) -- adds a condition
```

* A template is fixed once registered. Changing it is an error ("clone() it before changing it").
* `clone()` makes a variant that inherits everything. Options you set on the clone replace the template's options. The clone's `when` / `when_any` add to the template's.
* `group:push(p, "template_name")` also works.

## 13. Groups and trees {#s13}

### `acr.group(name)`

A priority list. `:when(...)` / `:when_any(...)` gate the whole group. `:push(priority, node)` adds a row. Higher numbers win. On a tie, the later push wins. Instant rows that pass also fire.

### `acr.tree(name)`

A list of groups and trees: `:push(priority, "group or tree name")` (or the group object itself). `:when(...)` / `:when_any(...)` gate a tree the same way they gate a group. A tree runs its best child **that can run now**: a child counts only when its `when` holds and one of its rows can run. So a group whose skills are all recharging never blocks a lower one. That is what makes a rotation dynamic.

Groups and trees are names in expressions too: `run(root)`, `can_run(cc)`.

Required: a group or tree named **`root`** (the default `rotation` runs it). Optional, by name: **`cc`** (break-bar phase), **`idle`** (out of combat).

## 14. Handlers {#s14}

### `acr.handlers { ... }`

Code the engine runs each tick. A handler takes statements (`"run(root); run(instants);"`) or, if it is marked bool or agent, an expression. All handlers are optional. An unknown handler is an error.

| Handler | When | Default |
| --- | --- | --- |
| `daemon` | every tick, first | nothing |
| `idle` | out of combat | `run(idle);` when a group or tree `idle` exists |
| `rotation` | an enemy is selected | `run(root);` |
| `ccAvailable` | bool: is a break-bar phase worth running? | `can_run(cc)` |
| `cc` | the target's break bar is up, `ccAvailable` holds and the player's CC switch is on; runs **instead of** `rotation` | `run(cc);` |
| `targetInvuln` | bool: treat the target as invulnerable (adds to KX's own list) | `false` |
| `handleInvuln` | while the target is invulnerable | nothing |
| `noTarget` | in combat with nothing selected | nothing |
| `revivable` | agent: an ally to revive, or -1 | `-1` |
| `revive` | revive that ally | nothing |
| `onWeapons` | bool: are we on this build's weapons? While true, KX turns on the game's fast ground targeting option and, unless the player switched Auto-attack off, the game's auto-attack (they stay on). It never stops the rotation. | the current set is one of `weapons` |

Without a `cc` group, the rotation simply keeps running during break bars. Because `cc` runs *instead of* the rotation, make `cc` a tree that falls back to `root` ([recipe 16.6](/client/acr/recipes#s16-6)).

## 15. The expression language {#s15}

Conditions (`:when`, `:when_any`), handler code, `:pre` and `acr.def` bodies are written in this language, as Lua strings.

* **Types:** `bool`, `int` (64-bit), `float` (32-bit). An int mixed with a float becomes a float. Literals: `true`, `false`, `12`, `0.5`.
* **Operators**, loosest first: `?:`, `||`, `&&`, `==` `!=`, `<` `<=` `>` `>=`, `+` `-`, `*` `/` `%`, unary `!` `-`. `&&`, `||` and `?:` short-circuit. Integer `/` and `%` truncate, and dividing by zero gives 0.
* **Casts and helpers:** `u32(x)`, `i32(x)`, `u64(x)`, `i64(x)`, `float(x)`, `min(a, b)`, `max(a, b)`.
* **Match:** `match(x, {1 | 2: a, 3: b}, fallback)` compares an int with constant keys.
* **Statements** (handlers, `:pre`): `name = expr;`, `if c { ... } else if c { ... } else { ... }`, calls such as `t_start(my_timer);`. `{ s1; s2; value }` runs the statements, then returns the value.
* **Aggregates** over a collection, with `e` bound to each element: `any_of(c, e => test)`, `all_of`, `count_of`, `sum_of(c, e => value)`, `min_of(c, e => value, fallback)`, `max_of`.
* **Collections:** `players` (every player in view, you included), `allies` (friendly players and you), `party`, `subgroup` (your squad subgroup), `npcs` (every non-player character in view), `effects` (ground effects in view). Read their elements with the `a_*` / `e_*` builtins.
* **Names you can use:** your `acr.const` names, toggles, variables, defs, groups, trees, timers, the constants in [section 21](/client/acr/reference#s21) (weapons, resources, attitudes, targets) and the builtins below.
* **Missing values** read as 0, false, or -1 where noted (for example `cd_bar` of a skill not on the bar).
* No comments inside expression strings. Put comments in the Lua around them.
