---
url: https://docs.kxtools.xyz/client/acr/recipes.md
---
# Recipes and examples

Patterns for common rotation problems, the mistakes that cause most errors, and two complete builds.

## 16. Recipes {#s16}

Every snippet here passes the ACR's own validator. `C.*` stands for your constants. You can set a handler only once per file, so merge the handler lines from these snippets into one `acr.handlers { ... }`.

### 16.1 Opener that can never get stuck {#s16-1}

```lua
acr.var("opened", false)

acr.group("opener"):when("!opened", "combat_time() < 6000")
    :push(10, skill(C.OPENER_A):range():pre("opened = true;"))
    :push(9, skill(C.OPENER_B):range())

acr.tree("root")
    :push(50, "opener")   -- tried first; if none of its rows can run, the tree moves on
    :push(10, "main")

acr.handlers {
    daemon = "if !in_combat() { opened = false; }",
}
```

### 16.2 One group per weapon set, swap when the set is spent {#s16-2}

```lua
acr.def("on_gs", "on_weapons(GREATSWORD, NONE)")

acr.group("greatsword"):when("on_gs")
    :push(10, skill(C.GS_2):cannot_cancel():range():when("!moving()"))
    :push(9, skill(C.GS_4):range())
    :push(3, swap():when("!ready_bar(GS_2)", "!ready_bar(GS_4)"))
    :push(1, skill { C.GS_AUTO_1, C.GS_AUTO_2, C.GS_AUTO_3 }:range())
```

For kits, shrouds, forges, tomes and attunements, detect the bar by a skill in slots 1-5 that only that bar shows. Don't detect it by the F-key skill that enters or leaves the bar. Give that bar its own group. In conditions, check readiness with the one id your bar uses:

```lua
acr.def("in_kit", "on_bar(GRENADE_1)")
acr.group("grenade_kit"):when("in_kit")
    :push(10, skill(C.GRENADE_2):ground("target"):range())
    :push(2, skill(C.STOW_GRENADE_KIT):when("!ready_bar(GRENADE_2)"))   -- 6110, leaves the kit
acr.group("rifle"):when("on_weapons(RIFLE, NONE)", "!in_kit")
    :push(9, skill(C.GRENADE_KIT):when("ready(GRENADE_2)"))
    :push(1, skill(C.RIFLE_1):range())
```

Inside an Engineer kit, `on_weapons` is false for every set, so the kit group must not depend on `on_weapons`. Treat shrouds, forges, tomes and attunements the same way: detect them with `on_bar(...)` only, and add `!in_shroud`-style conditions to the weapon groups so a weapon group never fires on the wrong bar. Enter a kit, shroud or forge by casting its skill id. Leave it with its own stow or exit skill, which is on the bar while you are in it (Stow Grenade Kit 6110, Exit Reaper's Shroud, Deactivate Photon Forge, ...). Don't use `swap()` to leave a kit. Revenant legend swaps are the legend stance skills. Gate them with `stance_ready()` / `stance_cd()`.

### 16.3 Instants that weave into casts {#s16-3}

```lua
acr.group("instants")
    :push(10, skill(C.SIGNET):insta():when("target_hp() > 0.1"))

acr.handlers {
    rotation = "run(root); run(instants);",
}
```

### 16.4 Buffs, resources, charges, execute range {#s16-4}

```lua
:push(15, skill(C.BOON_SKILL):when_any("buff_time(MIGHT) < 2000", "need_buff(QUICKNESS, 600.0)"))
:push(14, skill(C.EXECUTE):range():when("target_hp() < 0.5"))
:push(12, skill(C.CHARGE_SKILL):range():when("ammo_bar(CHARGE_SKILL) >= 2 || target_buff_stacks(VULNERABILITY) < 10"))
:push(11, skill(C.COSTLY):range():when("has_res(INITIATIVE) && res(INITIATIVE) >= 4.0"))
```

### 16.5 "At most once every 10 seconds" {#s16-5}

```lua
acr.task("big_hit_gate", 10000)
-- in a group:
:push(20, skill(C.BIG_HIT):range():when("task_ready(big_hit_gate)"):pre("task_run(big_hit_gate);"))
```

### 16.6 Break bars without losing the rotation {#s16-6}

```lua
acr.group("cc_skills")
    :push(10, skill(C.HARD_CC):range())
    :push(9, skill(C.SOFT_CC):enabled("my_build_soft_cc"):range())

acr.tree("cc")             -- runs instead of the rotation while a break bar is up
    :push(20, "cc_skills") -- CC first...
    :push(10, "root")      -- ...then the normal rotation keeps going
```

To use a skill only on break bars inside the normal rotation instead: `:when("target_breakable()")`.

### 16.7 Area skills only on packs {#s16-7}

```lua
acr.def("pack(n)", "count_of(npcs, e => a_alive(e) && a_attitude(e) == HOSTILE && a_dist2(e) < 600.0) >= n")
:push(13, skill(C.AOE_SKILL):enabled("my_build_aoe"):radius():when("pack(3)"))
```

### 16.8 Ground skills, pets, dodges {#s16-8}

```lua
:push(11, skill(C.GROUND_SKILL):ground("target"):range():radius())   -- hitbox-edge aiming: 16.12
:push(10, kennel("skill1", C.PET_SKILL):range())
:push(9, acr.evade { mode = "special", endurance = 50 }:when("endurance() >= 100"))
```

### 16.9 Timers and stopwatches {#s16-9}

```lua
acr.timer("burst_window", 6000)
acr.stopwatch("since_swap")
:push(3, swap():when("!t_started(since_swap) || sw_elapsed(since_swap) > 5000"):pre("t_force(since_swap); t_start(burst_window);"))
acr.handlers { daemon = "if !in_combat() { t_reset(burst_window); }" }
```

### 16.10 Out of combat and no target {#s16-10}

```lua
acr.group("idle")
    :push(10, swap():when("on_axes"))    -- start fights on the first set

acr.handlers {
    noTarget = "run_untargeted(instants);",
    targetInvuln = "target_is(BOSS) && target_buff_named(PROTECTION)",
}
```

### 16.11 Facing the target {#s16-11}

Skills that hit in front of you miss when the target is behind you. Three tools:

```lua
-- 1. Cast only while the target is in front (about 78° either side; :facing(0.5) sets your own angle in radians).
:push(12, skill(C.HEADBUTT):range():facing())

-- 2. Turn to the target just before casting.
:push(11, skill(C.MANTIS_STING):range():pre("face_target()"))

-- 3. Turn back to the target once the cast ends (skills that leave you facing elsewhere).
:push(10, skill(C.HARB_SHROUD_2):facing():range():post_face())
acr.handlers { daemon = "executor_daemon();" }   -- required for :post_face()
```

* `face_target()` is a statement: it turns you toward the target. Use it in `:pre(...)` or a handler. It is rate-limited, but it turns even when you already face the target.
* `facing_target(angle)` is the condition form: `:when("facing_target(1.0)")`.
* `:facing()` only checks; it never turns you. Add `:pre("face_target()")` when the rotation should turn instead of waiting.
* Without `executor_daemon();` in `daemon`, `:post_face()` does nothing. If `daemon` has other statements, add it to them: `daemon = "executor_daemon(); if !in_combat() { IN_OPENER = true; }"`.

### 16.12 Ground skills at the edge of the hitbox {#s16-12}

A ground skill hits when its circle touches the target's hitbox, not only on the target's centre. Big targets (bosses, golems) have big hitboxes, so KX aims at the hitbox edge. This lets you cast from further away and keeps you from walking in. This example is Jump Shot from Power Mechanist, a leap kept to melee range:

```lua
acr.def("mech_in_melee", "target_in_range2(240.0 + target_radius())")   -- within 240 of the hitbox edge
:push(9, skill(C.JUMP_SHOT):ground("minimize"):range():radius():when("mech_in_melee"))
```

* **No `:ground`, or `:ground("target")`:** when the target's centre is in range, the circle lands on it. When the centre is not in range, but the circle can still reach the hitbox, KX casts the skill at full range toward the target. Then the edge of the circle overlaps the hitbox. When the target is further away, the row does not cast.
* **`:ground("minimize")`:** the circle goes on the near edge of the hitbox, the side facing you. When a circle at your feet already touches the hitbox, KX casts the skill at your feet. Use it for most damage fields, wells and leaps.
* **`:ground("maximize")`:** the farthest point in range on the line through the target, for skills that should land past it.
* KX counts 80% of the skill's radius as the reach of the circle. This margin makes sure the circle still touches a target that moves a little. "Can still reach" means within range + 80% of the radius + the hitbox radius.
* **Always write `:range():radius()` on these rows.** The aim uses the skill's circle only when the row has `:radius()` (the size from the game data) or `:radius(n)` (your own, when the data has none). Without `:radius()`, KX treats the circle as a point: `"minimize"` lands right on the hitbox edge and the skill reaches only range + hitbox.
* `target_radius()` is the target's hitbox radius in game units. `target_in_range2(n)` measures to the target's centre, so add `target_radius()` to measure to its edge.

## 17. Common mistakes and the errors they give {#s17}

| You wrote | The ACR says | Fix |
| --- | --- | --- |
| `"ready(GS_4) and target_hp() < 0.5"` | `unexpected text (... at "and target_hp() < 0.5")` | `&&` for and; [section 15](/client/acr/api#s15) lists or and not |
| `"cd(C.GS_2) ~= 0"` | `unexpected character (... at ".GS_2) ~= 0")` | bare names and `!=` inside strings: `"cd(GS_2) != 0"` |
| `"redy(GS_2)"` | `unknown function 'redy' (did you mean 'ready'?...)` | spelling |
| `"target_hp() < 50%"` | `expected a value` | fractions: `target_hp() < 0.5` |
| `"hp"` | `unknown name 'hp' (hp is a builtin: call it as hp()...)` | `hp()` |
| `:enabled("use_rsh")` | `names no toggle use_rsh (did you mean 'use_rush'?...)` | the exact toggle key |
| `acr.build { profesion = ... }` | `acr.build: unknown field 'profesion' (did you mean profession?)` | spelling |
| a template changed after `acr.template` | `template '...' is fixed: clone() it before changing it` | `t:clone():when(...)` |

Errors look like `my_build.lua:21: groups.root.nodes[0].and[0]: unknown function ...`: the line, then where in the build (group `root`, row 0, its first `when`).

**Mistakes the validator can't catch** (the file loads, but the rotation misbehaves):

* A wrong or guessed skill id: that row never casts.
* Only the first id of an auto-attack chain: the rotation stalls after one hit.
* `cd_bar(X) < 500` for a skill that is not on the bar: true (it reads -1). `cd(X) == 0` for an unknown skill: true. Pair them with `on_bar(X)` / `ready_bar(X)`.
* A higher-priority row that is always allowed (no conditions, no recharge) starves everything below it.
* `cc` as a plain group of CC skills: during break bars your damage rotation stops (use [recipe 16.6](/client/acr/recipes#s16-6)).
* Kit, shroud or forge skills without their own group or `on_bar` gate: the rotation doesn't know which bar it is on.
* Leaving an Engineer kit with `swap()`, or gating the kit group on `on_weapons(...)`: the rotation stays stuck in the kit. Use the kit's stow skill and `on_bar(...)` ([recipe 16.2](/client/acr/recipes#s16-2)).
* Detecting a forge or shroud by its F-key enter/exit skill (`on_bar(DEACTIVATE_FORGE)`): it can be true outside the forge or shroud, and then it blocks every weapon skill. Use a skill in slots 1-5 of that bar.
* `ready(A) || ready(A_ALT)` with a variant id you never cast: it can stay true, so the rotation keeps entering a kit or mode with nothing to use. Check the id your bar uses.
* Gating costed skills on `ready()` only: the game refuses the cast while you lack the resource.

## 18. Complete examples {#s18}

### 18.1 Small: Power Berserker, greatsword + axe/axe {#s18-1}

```lua
local skill, swap = acr.skill, acr.swap

acr.build {
    id = "my_power_berserker",
    name = "My Power Berserker",
    origin = "user",
    profession = acr.WARRIOR,
    elite = 18,
    weapons = { { acr.GREATSWORD }, { acr.AXE, acr.AXE } },
}

local C = acr.const {
    GS_AUTO_1 = 14356,
    GS_AUTO_2 = 14373,
    GS_AUTO_3 = 14374,
    GS_2 = 14554,
    GS_4 = 14510,
    GS_5 = 14446,
    AXE_AUTO_1 = 14369,
    AXE_AUTO_2 = 14370,
    AXE_AUTO_3 = 14371,
    AXE_2 = 14421,
    AXE_4 = 14418,
}

acr.toggle("use_rush", "Rush", { skill = C.GS_5, tip = "Use Rush to close distance." })

acr.group("greatsword"):when("on_weapons(GREATSWORD, NONE)")
    :push(10, skill(C.GS_2):cannot_cancel():range():when("!moving()"))
    :push(9, skill(C.GS_4):range())
    :push(8, skill(C.GS_5):enabled("use_rush"):range():min_range(360))
    :push(2, swap():when("!ready(GS_2)", "!ready(GS_4)"))
    :push(1, skill { C.GS_AUTO_1, C.GS_AUTO_2, C.GS_AUTO_3 }:range())

acr.group("axes"):when("on_weapons(AXE, AXE)")
    :push(10, skill(C.AXE_2):range())
    :push(9, skill(C.AXE_4):range())
    :push(2, swap():when("!ready(AXE_2)", "!ready(AXE_4)"))
    :push(1, skill { C.AXE_AUTO_1, C.AXE_AUTO_2, C.AXE_AUTO_3 }:range())

acr.tree("root")
    :push(1, "greatsword")
    :push(1, "axes")
```

Each tick, `root` runs the group whose weapon set you hold, and that group casts its best ready skill. Hundred Blades won't start while you move. The rotation uses Rush only on targets at least 360 away, and only while its toggle is on. Each set swaps once both of its main skills are recharging.

### 18.2 Full: Power Berserker with Berserk, bursts, heal, utilities and break bars {#s18-2}

```lua
-- My Power Berserker: greatsword + axe/axe. Full example for the KX ACR Lua API.
local skill, swap = acr.skill, acr.swap

acr.build {
    id = "my_power_berserker_full",
    name = "My Power Berserker (full example)",
    origin = "user",
    profession = acr.WARRIOR,
    elite = 18,
    specs = { 4, 51, 18 },
    traits = { 1444, 1449, 1437, 1413, 1489, 1369, 2049, 2011, 1928 },
    skills = { 30189, 14410, 14404, 30258, 30343 },
    weapons = { { acr.GREATSWORD }, { acr.AXE, acr.AXE } },
}

local C = acr.const {
    -- Greatsword
    GS_AUTO_1 = 14356,       -- Greatsword Swing
    GS_AUTO_2 = 14373,       -- Greatsword Slice
    GS_AUTO_3 = 14374,       -- Brutal Strike
    GS_2 = 14554,            -- Hundred Blades
    GS_4 = 14510,            -- Bladetrail
    GS_5 = 14446,            -- Rush
    ARC_DIVIDER = 29852,     -- greatsword burst while Berserk
    -- Axe / axe
    AXE_AUTO_1 = 14369,      -- Chop
    AXE_AUTO_2 = 14370,      -- Double Chop
    AXE_AUTO_3 = 14371,      -- Triple Chop
    AXE_2 = 14421,           -- Cyclone Axe
    AXE_4 = 14418,           -- Dual Strike
    AXE_5 = 14399,           -- Whirling Axe
    DECAPITATE = 30851,      -- axe burst while Berserk
    -- Heal, utilities, elite, profession
    BLOOD_RECKONING = 30189, -- heal
    OUTRAGE = 30258,         -- utility, breaks stun
    HEADBUTT = 30343,        -- elite Head Butt (stuns you too)
    BERSERK_F2 = 30435,      -- enters Berserk
    -- Break-bar skills
    WILD_BLOW = 29941,
    KICK = 14502,
    -- Buffs by name (names with ids in the names table work on every client)
    BERSERK = acr.buff "Berserk",
    STUN = acr.buff "Stun",
}

acr.toggle("my_zerk_rush", "Rush", { skill = C.GS_5, tip = "Use Rush to close distance." })
acr.toggle("my_zerk_heal_below", "Heal below health %", { skill = C.BLOOD_RECKONING, tip = "Cast the heal below this health percent.", default = 50 })
acr.toggle("my_zerk_wild_blow", "Wild Blow", { skill = C.WILD_BLOW, tip = "Use Wild Blow on break bars.", section = "CC" })
acr.toggle("my_zerk_kick", "Kick", { skill = C.KICK, tip = "Use Kick on break bars.", section = "CC" })

acr.def("full_adrenaline", "has_res(ADRENALINE) && res(ADRENALINE) >= res_max(ADRENALINE)")
acr.def("berserk", "buff_named(BERSERK)")
acr.def("stunned", "buff_named(STUN)")
acr.def("on_gs", "on_weapons(GREATSWORD, NONE)")
acr.def("on_axes", "on_weapons(AXE, AXE)")

local gs_autos = acr.template("gs_autos", skill { C.GS_AUTO_1, C.GS_AUTO_2, C.GS_AUTO_3 }:range())
local axe_autos = acr.template("axe_autos", skill { C.AXE_AUTO_1, C.AXE_AUTO_2, C.AXE_AUTO_3 }:range())
local headbutt = acr.template("headbutt", skill(C.HEADBUTT):facing():range())

acr.group("survive")
    :push(10, skill(C.BLOOD_RECKONING):when("hp() * 100.0 < my_zerk_heal_below"))

acr.group("utility")
    :push(10, skill(C.OUTRAGE):when("stunned", "used_within(HEADBUTT, 3000)"))
    :push(9, skill(C.BERSERK_F2):when("!berserk", "full_adrenaline", "!stunned"))
    :push(8, headbutt:clone():when("berserk", "ready(OUTRAGE)"))

acr.group("greatsword"):when("on_gs")
    :push(10, skill(C.ARC_DIVIDER):range():when("full_adrenaline"))
    :push(9, skill(C.GS_2):cannot_cancel():range():when("!moving()"))
    :push(8, skill(C.GS_4):range())
    :push(3, swap():when("!ready_bar(GS_2)", "!ready_bar(GS_4)"))
    :push(2, skill(C.GS_5):enabled("my_zerk_rush"):range():min_range(360))
    :push(1, gs_autos)

acr.group("axes"):when("on_axes")
    :push(10, skill(C.DECAPITATE):range():when("full_adrenaline"))
    :push(9, skill(C.AXE_2):range())
    :push(8, skill(C.AXE_4):range())
    :push(7, skill(C.AXE_5):cannot_cancel():range())
    :push(3, swap():when("!ready_bar(AXE_2)", "!ready_bar(AXE_4)"))
    :push(1, axe_autos)

acr.tree("root")
    :push(30, "survive")
    :push(20, "utility")
    :push(10, "greatsword")
    :push(10, "axes")

acr.group("cc_skills")
    :push(10, headbutt)
    :push(9, skill(C.WILD_BLOW):enabled("my_zerk_wild_blow"):range())
    :push(8, skill(C.KICK):enabled("my_zerk_kick"):will_cancel():range())

acr.tree("cc")
    :push(20, "cc_skills")
    :push(10, "root")

acr.group("idle")
    :push(10, swap():when("on_axes"))
```

What it does: `root` tries `survive` (heal below the Skills-page threshold), then `utility`, then the group of the weapon set you hold. The rotation enters Berserk at full adrenaline. While you are in Berserk, the rotation casts Head Butt if Outrage is ready. Outrage breaks the stun that Head Butt puts on you. In Berserk the weapon bursts (Arc Divider, Decapitate) fire at full adrenaline. While a break bar is up, `cc` tries the CC rows first, then falls back to the normal rotation. Wild Blow and Kick fire only when they are on your bar. The rotation skips a row whose skill isn't on your bar. Out of combat, the rotation swaps back to the greatsword.
