Skip to content

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.

6. acr.build { ... } ​

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

FieldValue
idunique snake_case id; use it as the file name too (<id>.lua)
namedisplay name
origin"user" for your own builds (the others are "current", "historical" and "kx")
professionacr.GUARDIAN, acr.WARRIOR, acr.ENGINEER, acr.RANGER, acr.THIEF, acr.ELEMENTALIST, acr.MESMER, acr.NECROMANCER, acr.REVENANT
eliteelite specialization id (section 21). The build only runs while your character has that elite. Leave it out for a build any specialization can use.
specsthe 3 specialization ids
traitsthe 9 trait ids, three per specialization
skillsheal, three utilities, elite (skill ids; 0 leaves a slot empty)
legendsRevenant: the two legend ids, for example { 46409, 28494 }
specialweapon skills for slots 6 and up
weaponsweapon sets: { { acr.GREATSWORD }, { acr.AXE, acr.AXE } }, one-handed main + off-hand or one two-hander per set
links{ build = url, benchmark = url, chat = "[&...]" }
sourcefree 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 ​

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);
  • acr.agent "Matthias Gabrel": an NPC by name (section 23);
  • 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) ​

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 ​

LuaMeaning
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): 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) ​

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) ​

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

KindMeaning
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)
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 ​

OptionMeaning
: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).
: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)
: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).
: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 ​

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 ​

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 ​

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.

HandlerWhenDefault
daemonevery tick, firstnothing
idleout of combatrun(idle); when a group or tree idle exists
rotationan enemy is selectedrun(root);
ccAvailablebool: is a break-bar phase worth running?can_run(cc)
ccthe target's break bar is up, ccAvailable holds and the player's CC switch is on; runs instead of rotationrun(cc);
targetInvulnbool: treat the target as invulnerable (adds to KX's own list)false
handleInvulnwhile the target is invulnerablenothing
noTargetin combat with nothing selectednothing
revivableagent: an ally to revive, or -1-1
reviverevive that allynothing
onWeaponsbool: 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).

15. The expression language ​

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 (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.