--- url: https://docs.kxtools.xyz/intro.md --- # Overview Guides and API references for KX Tools products. ## Products * **[KX Client](/client/):** includes ACR, automatic combat rotations you can write yourself in Lua. * **KX Trainer Pro** and **KX Void:** docs coming later. ## Using these docs with AI We write everything here for both people and AI to read. * **One file per guide.** Each guide has a single Markdown file to attach to ChatGPT, Claude or Gemini, for example the [ACR guide](/client/acr/kx-acr-lua-api.md){target="\_blank" download}. * **One line for coding agents.** Claude Code, Codex, Gemini CLI or Cursor can set themselves up from a setup file, for example [agent.md](/client/acr/agent.md){target="\_blank"} for ACR. * **Every page as Markdown.** Add `.md` to any page URL, for example [/client/acr/api.md](/client/acr/api.md){target="\_blank"}. * **[llms.txt](/llms.txt){target="\_blank"}** and **[llms-full.txt](/llms-full.txt){target="\_blank"}** list or contain the whole site, following [llmstxt.org](https://llmstxt.org/). --- --- url: https://docs.kxtools.xyz/client.md --- # KX Client Docs for KX Client. * **[ACR: Lua API](/client/acr/):** write your own automatic combat rotations in Lua, by hand or with an AI. --- --- url: https://docs.kxtools.xyz/client/acr.md --- # ACR: Lua API **ACR (automatic combat rotation)** is the part of KX Client that plays your build's rotation for you. KX ships built-in builds, and you can write your own. A build is **one Lua file** that describes the skills, their priority and the conditions for each skill. The engine checks that description many times a second and casts the best skill that is ready. * **No scripts, no timelines.** Each row of the rotation has its own live conditions, so a missed skill never blocks the rest. * **Hot reload.** Save the file and KX loads it within about a second. * **AI-friendly.** This guide is written so ChatGPT, Claude, Gemini or a coding agent can write the build for you. ## Quick start ### With a coding agent Claude Code, Codex, Gemini CLI, Cursor and similar agents can do every step below by themselves. If they can, they also [test and tune the build](/client/acr/self-improving) fight after fight. Paste this one line: ```text Read https://docs.kxtools.xyz/client/acr/agent.md and follow it. Build: ``` ### With a chat AI {#download-for-your-ai} 1. **Get the guide.** Download **[kx-acr-lua-api.md](/client/acr/kx-acr-lua-api.md){target="\_blank" download}**, the whole ACR guide as one file, written for your AI to read. 2. **Collect your build.** A build link, or the skill ids of your bar ([where to find them](/client/acr/basics#s3)). Never let the AI guess an id: a wrong one fails silently. 3. **Ask your AI.** Attach the file and paste the [prompt template](/client/acr/ai#s19) with your build filled in. The AI answers with one complete Lua file. 4. **Load it in game.** ACR window → **Editor** → **Paste**, then save it under the build's id. Or save it as `.lua` in `%APPDATA%\KX Client\acr\`. No restart needed ([details](/client/acr/basics#s4)). 5. **Test and fix.** Check **Builds**: a build with errors never runs. Copy the error lines back to your AI word for word. Then turn the ACR on and attack a training golem. If it plays wrong, tell the AI what you saw. ## About this guide Written for KX players who want to make their own ACR (automatic combat rotation), and for the AI helping them. Matches KX ACR as of 2026-11-11. **Players: give [this whole guide as one file](#download-for-your-ai) to your AI** (ChatGPT, Claude, Gemini, ...), say which build you want, and paste the skill ids or a build link. [Section 19](/client/acr/ai#s19) has a ready-made prompt. Then load the AI's file in game as [section 4](/client/acr/basics#s4) shows. The file is long. If your AI reads files in parts, tell it to read the whole file. The reference tables and the full function list are at the end. **An AI that works on your PC by itself** (Claude Code, Codex, Gemini CLI, Cursor and similar) can also test and improve the build by itself, fight after fight. [Section 20](/client/acr/self-improving) has the setup, the rules and the prompt for that. > If English is not your language: give the whole file to your AI, then describe the build you want in your own language. Use numeric ids for skills and effects. The ids are the same on the Chinese and global servers. ## Pages * **[Basics](/client/acr/basics):** how an ACR runs, ids, loading and testing, a file top to bottom. * **[Lua API](/client/acr/api):** every `acr.*` function, node options and the expression language. * **[Builtins](/client/acr/builtins):** every function you can call in a condition. * **[Reference](/client/acr/reference):** professions, specs, weapons, resources, buff and agent names. * **[Recipes and examples](/client/acr/recipes):** common patterns, common mistakes, complete builds. * **[Working with AI](/client/acr/ai):** the AI's rules and the prompt template. * **[Self-improving ACRs](/client/acr/self-improving):** an agent that tunes the build by itself. --- --- url: https://docs.kxtools.xyz/client/acr/basics.md --- # Basics How an ACR runs, where skill and buff ids come from, how to load and test a build, and what a build file looks like. ## 2. How an ACR runs {#s2} * An ACR is **one Lua file**. It runs **once**, when the ACR loads, and describes the rotation: the build, its skills, the priority order and the conditions for each skill. The engine compiles that description and evaluates it every tick, without calling Lua again. So loops and helper functions in Lua are fine: they only run at load. * **Every tick** (many times a second) the engine: 1. runs the `daemon` handler; 2. does nothing more while you are mounted, gliding, downed or defeated, while the ACR is off, or while you cast something yourself (it resumes on its own); 3. runs `idle` when you are out of combat; 4. if an enemy is selected (hostile or neutral, alive), it runs `cc` when the enemy's break bar is up, your build has CC to use (`ccAvailable`) and the player's CC switch is on. Else, if the target is invulnerable, it runs `handleInvuln` (KX knows the common invulnerability effects, and you can add your own with `targetInvuln`). Otherwise it runs `rotation`. This step also runs out of combat. That is how selecting an enemy with the ACR on starts the fight; 5. runs `noTarget` when you are in combat with nothing selected. * `rotation` runs `run(root);` unless you change it. **`run(x)` casts the best row of a group or tree:** of all rows whose checks pass right now, the one with the **highest priority number**. When rows have equal priority, the row pushed **later** wins. * Each row checks by default that its skill is **on your bar**, **ready** (off recharge, with a charge left), **not already being cast** and **not already queued**. Then come the options you add (range, facing, ...) and your conditions. * **Instants:** a row marked `:insta()`, or a skill the game marks instant, fires *alongside* the chosen row instead of competing with it. `:insta(false)` makes it wait its turn. * The engine sends the next skill near the end of the current cast, on the game clock. You can add a random human-like delay in Settings. * **Player settings outside your file:** game modes (PvE and training area on, PvP and WvW off by default), the CC switch, auto-revive, the auto-attack switch, auto-heal below a health fraction, the reaction delay and hotkeys are all in the ACR window's Settings. Your file doesn't need to handle them. Add a heal row only if the build wants something smarter than the player's auto-heal. ## 3. Getting skill, trait and buff ids {#s3} KX uses the game's own numeric ids. They are the same on the global and the Chinese client, and the same as the official API. **In game (most reliable):** ACR window → **Editor** → **Add skill**, or any skill or effect picker. Search by name, and hover a result to see its id. Skills on your current bar are listed first, so you get exactly the version your bar shows. **Official GW2 API** (for an AI with web access, or a browser): * `https://api.guildwars2.com/v2/professions/Warrior` lists the profession's weapons with their skills. For example, `weapons.Greatsword.skills` gives `id` and `slot` (such as `Weapon_1`). It also lists the heal, utility and elite skills (`skills`) and the profession's specializations. Replace `Warrior` with the profession name. * `https://api.guildwars2.com/v2/skills?ids=14554,14510` gives names and details. `next_chain` is the next step of an auto-attack chain and `flip_skill` is what a skill turns into after use. * `https://api.guildwars2.com/v2/specializations/18` gives a specialization (elite ids are in [section 21](/client/acr/reference#s21)) with its trait ids. `https://api.guildwars2.com/v2/traits?ids=...` gives trait names. **Buff ids:** common boons and conditions are in [section 23](/client/acr/reference#s23). For any other effect, use the in-game effect picker (hover for the id). **Watch out:** * Several ids often share one name, such as a PvP copy, an underwater copy, a trait variant, or each adrenaline level of a warrior burst. Use the one the in-game picker shows for your bar, or list several in one row. * Kits, shrouds, forges, tomes, attunements, transforms and Berserk-style modes **replace** bar skills with other ids. Each of those skills needs its own id. The profession endpoint's weapon lists don't include them. Enter the kit or mode in game and open the picker (that bar is listed first), or search `/v2/skills` by name. ## 4. Loading and testing your ACR in game {#s4} **Option A: paste** 1. Copy the whole Lua file. 2. Open the ACR window (KX bar) → **Editor** → **Paste**, then switch to **Code** if it doesn't open there. 3. The line above the code says **Valid**, or shows the first error with its line number. 4. Type a **Saved file name** (use the build's `id`), then click the disk icon. The build reloads right away. **Option B: file** * Save the file as `.lua` in `%APPDATA%\KX Client\acr\` (the folder button in the Editor opens it). **No reload or restart needed.** The ACR checks that folder about once a second while the KX menu is open or the ACR is on. It finds new, changed and deleted `.lua` files by itself. Saving from the Editor reloads right away. If the changed build is the one running, the ACR switches to the new version immediately, and its state (opener, timers) starts over. **Then:** 1. **Builds** lists your build marked "yours". If it has problems it is marked "has errors", and each error is shown with its line number. Copy those lines back to your AI word for word. **A build with errors never runs.** Until you fix it, the ACR quietly uses the best other build for your character (possibly a built-in), or none. So if a change seems to do nothing, check Builds first. 2. Pick your build (or let KX pick the best match for your profession, specializations and traits). 3. Turn the ACR on (button, status widget or hotkey), select a training golem (Special Forces Training Area) and attack. The **Rotation** page says in one line what the ACR is doing and why, for example "No target" or "Wrong weapons". 4. The switches you declared with `acr.toggle` are on the **Skills** page. **Good to know** * A file whose `id` matches a built-in build replaces that built-in for you. Use your own id to keep both. * Keep the AI's file as your master copy, and edit it in **Code** or in the file. If you change the build in the visual editor and save there, KX writes the build as plain Lua again and drops your comments and Lua helper functions. * To see how KX writes a profession's mechanics, open a built-in on **Builds** with its copy button and switch to **Code**. The builds KX wrote itself (`origin = "kx"` at the top of their Code) are the cleanest examples. * If the ACR does something wrong, **Recorder** → **Record now** saves the fight. Send the newest folder from **Open recordings** with your report. ## 5. A file, top to bottom {#s5} ```lua local skill, swap, kennel = acr.skill, acr.swap, acr.kennel acr.build { ... } -- who the rotation is for local C = acr.const { ... } -- skill ids and other names acr.toggle(...) -- switches on the Skills page acr.var(...) -- state kept between ticks (optional) acr.def(...) -- named expression snippets local t = acr.template(...) -- reusable rows acr.group(...):push(...) -- priority lists acr.tree(...):push(...) -- lists of groups and trees acr.handlers { ... } -- what runs each tick (optional; defaults cover most builds) ``` **The Lua sandbox:** the Lua base library, `string`, `table`, `math`, `utf8` and `acr` are available. Files, the operating system, `require`, `load`, `loadfile`, `dofile`, `print` and `collectgarbage` are not. A script may use 64 MB and 50 million Lua instructions. A rotation needs only a tiny fraction of that. Errors name the file and line. **Style:** 4 spaces. Order: build, constants, toggles, variables, defs, templates, groups, trees, handlers. Lua code uses `C.NAME`; expressions use bare `NAME`. A short header comment (build, source, date) is welcome. --- --- 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 (`.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. --- --- url: https://docs.kxtools.xyz/client/acr/builtins.md --- # 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). | --- --- url: https://docs.kxtools.xyz/client/acr/reference.md --- # Reference Professions, specializations, weapons, resources and attitudes, then common buff ids and named buff and agent groups. ## 21. Reference tables {#s21} ### Professions (Lua: `acr.NAME`; inside expressions compare `profession()` with the number) | Guardian | Warrior | Engineer | Ranger | Thief | Elementalist | Mesmer | Necromancer | Revenant | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | ### Elite specialization ids (`spec()` returns one, 0 for core) | Profession | Elite specializations | | --- | --- | | Guardian | Dragonhunter 27, Firebrand 62, Willbender 65, Luminary 81 | | Warrior | Berserker 18, Spellbreaker 61, Bladesworn 68, Paragon 74 | | Engineer | Scrapper 43, Holosmith 57, Mechanist 70, Amalgam 75 | | Ranger | Druid 5, Soulbeast 55, Untamed 72, Galeshot 78 | | Thief | Daredevil 7, Deadeye 58, Specter 71, Antiquary 77 | | Elementalist | Tempest 48, Weaver 56, Catalyst 67, Evoker 80 | | Mesmer | Chronomancer 40, Mirage 59, Virtuoso 66, Troubadour 73 | | Necromancer | Reaper 34, Scourge 60, Harbinger 64, Ritualist 76 | | Revenant | Herald 52, Renegade 63, Vindicator 69, Conduit 79 | Core specialization and trait ids: `https://api.guildwars2.com/v2/professions/` (`specializations`), then `https://api.guildwars2.com/v2/specializations/` (`major_traits`, `minor_traits`). ### Weapons (Lua: `acr.NAME`; in expressions: bare `NAME`) | Name | Value | Name | Value | Name | Value | | --- | --- | --- | --- | --- | --- | | `SWORD` | 0 | `MACE` | 7 | `TORCH` | 14 | | `HAMMER` | 1 | `PISTOL` | 8 | `WARHORN` | 15 | | `LONGBOW` | 2 | `POLEARM` | 9 | `SHIELD` | 16 | | `SHORTBOW` | 3 | `RIFLE` | 10 | `SMALL_BUNDLE` | 17 | | `AXE` | 4 | `SCEPTER` | 11 | `LARGE_BUNDLE` | 18 | | `DAGGER` | 5 | `STAFF` | 12 | `SPEAR` | 19 | | `GREATSWORD` | 6 | `FOCUS` | 13 | `HARPOON_GUN` | 20 | | `NONE` (no off-hand, in expressions) | -1 | `TRIDENT` | 21 | `TOY` | 22 | ### Resources (`res(...)`, `res_max(...)`, `has_res(...)`; in each resource's own units) | Name | Name | Name | | --- | --- | --- | | `FIREBRAND_PAGES` | `ADRENALINE` | `CLONES` | | `ASTRAL_FORCE` | `LIFE_FORCE` | `INITIATIVE` | | `GALESHOT_ARROWS` | `SHADES` | `MALICE` | | `REVENANT_ENERGY` | `CATALYST_ENERGY` | `SHADOW_FORCE` | | `HOLOSMITH_HEAT` | `EVOKER_CHARGE` | | Every resource is in the game's own units, not a percentage. Some maximums change with traits. Compare against `res_max(...)` unless you know the scale: "life force above 25%" is `res(LIFE_FORCE) > 0.25 * res_max(LIFE_FORCE)`. ### Attitudes and targets * `a_attitude(e)`: `FRIENDLY` 0, `HOSTILE` 1, `NEUTRAL` 2, `UNATTACKABLE` 3. * `:target_with(...)`: `TARGET_DEFAULT` 0, `TARGET_AGENT` 1, `GROUND_TARGET` 2, `GROUND_CENTER` 3, `GROUND_SELF` 4, `GROUND_MINIMIZE` 5, `GROUND_MAXIMIZE` 6, `GROUND_MOUSE` 7, `GROUND_BOON` 8, `GROUND_HEAL` 9. ## 23. Buff and agent names {#s23} ### Common boon and condition ids Use these ids directly (`acr.const { MIGHT = 740 }`, then `buff(MIGHT)`). Ids work on every game client and in every language. | Boon | Id | Condition | Id | | --- | --- | --- | --- | | Protection | 717 | Blinded | 720 | | Regeneration | 718 | Crippled | 721 | | Swiftness | 719 | Chilled | 722 | | Fury | 725 | Poisoned | 723 | | Vigor | 726 | Immobilized | 727 | | Might | 740 | Bleeding | 736 | | Aegis | 743 | Burning | 737 | | Resolution | 873 | Vulnerability | 738 | | Stability | 1122 | Weakness | 742 | | Quickness | 1187 | Fear | 791 | | Superspeed | 5974 | Confusion | 861 | | Resistance | 26980 | Stun | 872 | | Alacrity | 30328 | Torment | 19426 | | Stealth | 13017 | Slow | 26766 | | Revealed | 890 | Taunt | 27705 | ### `acr.buff "Name"`: named buff groups A name stands for every id listed with it, so `buff_named(acr.buff "Berserk")` catches every version of Berserk. **Only use names from this table:** they carry their ids, so they work on every client. KX also knows some encounter effects by name only. Those names match only on an English game client. | Name | Ids | | --- | --- | | Aetherized Shielding | 21585 | | Alacrity | 30328 | | Berserk | 1941, 1942, 29502, 30185, 30435, 55862, 61643, 61821, 73517 | | Bleeding | 559, 736 | | Blinded | 720, 15334 | | Burning | 737, 40549 | | Chilled | 722, 53550 | | Confusion | 861 | | Crystalline Shield | 55558 | | Determined | 762, 788, 31450, 40546, 41495, 60880 | | Fear | 791, 4800, 6991, 10660, 12740, 15333, 15529, 24593, 31691, 44360, 49328 | | Fury | 725, 16535, 77172 | | Invulnerability | 757, 801, 24435, 56227 | | Might | 740, 16536, 76834 | | Overload | 1489, 16921, 17841 | | Parry | 3596, 14441, 14442, 46443 | | Peak Performance | 46853 | | Protection | 717, 3573, 12742, 34672, 34674, 42717, 55117, 76980 | | Protector's Defense | 35486 | | Quickness | 1187 | | Renewed Focus | 9154, 9255, 68666 | | Resolution | 873, 24529, 75755 | | Slick Skin | 26578 | | Slow | 26766 | | Stun | 872, 27012, 44852, 67893, 71734, 72528, 72860 | | Taunt | 2807, 3483, 7356, 12068, 27399, 27705, 33212, 41471, 49748, 61631 | | Time Anchored | 30136 | | Torment | 19419, 19426, 20197, 21632 | | Vulnerability | 738 | | Weakness | 742, 36815 | ### `acr.agent "Name"`: NPCs by name KX matches these by the NPC's English name. Known names: Captain Ashym, Cardinal Sabir, Clashing Champions, Conjured Amalgamate, Construct Core, Eastgate of Tarir, Ender's Echo, Ensolyss, Ensolyss of the Endless Torment, Exalted Explosive, Exquisite Conjunction, Fortified Wall, Hand of Erosion, Hand of Eruption, Icy Patch, Illusionary Swordsman, Illusionary Warden, Kenut, MAMA, Matthias Gabrel, Maw of Nourys, Modniir Ulgoth, Multiform Ambulatory Mobile Artillery, Nikare, Northgate of Tarir, Octovine \[East], Octovine \[North], Octovine \[South], Octovine \[West], Pylon, Pylon of Resilience, Pylon of Valor, Pylon of Vigilance, Reinforced Wall, Seeker, Solar Bloom, Soul Feast, Southgate of Tarir, Spirit of Anguish, Spirit of Preservation, Spirit of Wanderlust, Tower Lord, Triggerblossom, Wall, Westgate of Tarir. Use them with `target_is(NAME)` and `a_is(e, NAME)`. For common raid phases there are ready-made builtins: `matthias_stacks()`, `largos_cc_phase()` and `sabir_cc_phase()`. --- --- 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. --- --- url: https://docs.kxtools.xyz/client/acr/ai.md --- # Working with AI The rules your AI follows and the prompt to give it. For an agent that tests the build by itself, see [Self-improving ACRs](/client/acr/self-improving). ## 1. For the AI: rules {#s1} Follow these every time you write or change a KX ACR. 1. **Output one complete Lua file** that follows this document. When you change a file, send the whole file again, not a diff. 2. **Use only what this document lists.** Every `acr.*` function and node method is in [sections 6-14](/client/acr/api#s6). Every function you may call inside a condition is in [section 22](/client/acr/builtins). Never invent one. If you can't express something, say so plainly. Don't fake it. 3. **Never guess a skill, trait, buff or specialization id.** Use ids the player gave you, or ids you looked up from the sources in [section 3](/client/acr/basics#s3). Put every id in `acr.const` under a readable NAME and write the skill name in a comment. If an id is missing, ask for it, or list it under "ids to check" at the end of your answer. A wrong id fails silently: that row simply never casts. 4. **Write a dynamic priority rotation, never a script.** Each row has its own live conditions (ready, recharge, charges, resources, buffs, weapon set, target). A skill that was missed or is unavailable must never block the rest. Don't use step counters that only advance after a particular cast, and don't use fixed timelines. An opener may be a short group of guarded rows, but every row in it must be skippable, and the main rotation must always run once in combat ([recipe 16.1](/client/acr/recipes#s16-1)). 5. **Conditions are strings in the KX expression language, not Lua.** Use `&&`, `||`, `!`, `==` and `!=` (never `and`, `or`, `not` or `~=`). Inside a condition, write constants bare (`ready(GS_2)`). In Lua code, write them as `C.GS_2`. 6. **Units:** time in milliseconds, distance in game units (a range-1200 skill reaches 1200). Health from `hp()` and `target_hp()` is a fraction from 0.0 to 1.0, so "below 50%" is `target_hp() < 0.5`. 7. **Auto-attack chains:** list every step in one row, `skill { C.AUTO_1, C.AUTO_2, C.AUTO_3 }`. With only the first id, the row stops matching after one hit. 8. **Skills with several ids:** many skills have more than one id (PvE/PvP versions, trait variants, kit or attunement versions). When you are not sure which one the bar shows, list them all in the row itself, `skill { C.A, C.B }`. Only the one actually on the bar casts. **In conditions** (`ready`, `cd`, `on_bar`, ...), use only the one id the bar shows. A variant you never cast can read as ready forever, so `ready(A) || ready(A_ALT)` may never turn false. 9. **Range and facing:** give damage skills `:range()`, and add `:facing()` for skills that hit in front ([16.11](/client/acr/recipes#s16-11)). Ground-targeted skills land on the target by default. `:ground(...)` changes that. `:ground("minimize"):range():radius()` aims at the near edge of the target's hitbox ([16.12](/client/acr/recipes#s16-12)). 10. **Know which bar you are on.** Gate each weapon set's group with `on_weapons(MAIN, OFFHAND)`. Kits, shrouds, forges, tomes and attunements replace the bar. Inside an Engineer kit, `on_weapons` is false for every set. Inside the other replacement bars, you can't rely on `on_weapons` either. Give each of those bars its own group gated with `on_bar()`, for example its auto-attack, and add `!in_kit` / `!in_shroud`-style conditions to the weapon groups ([recipe 16.2](/client/acr/recipes#s16-2)). Don't detect a bar by the F-key skill that enters or leaves it (Engage/Deactivate Photon Forge, Exit Shroud): use a skill 1-5 of the bar. Leave a kit with its stow skill, never with `swap()`. 11. **Costed skills:** in game, `ready()` checks recharge and charges only. Gate initiative, adrenaline or energy costs yourself, for example `res(INITIATIVE) >= 5`. 12. **Ids and keys:** the build `id` is unique snake_case and `origin = "user"`. Begin toggle keys with the build id so they never clash. Don't reuse a built-in build's id unless the player wants to replace that built-in. 13. **Don't write** `library = ...`, `run_legacy(...)`, `can_run_legacy(...)`, `legacy_*` or `acr.visual { ... }`. Some built-in builds the player may show you contain them. They exist only so builds imported from older formats keep working; new builds don't use them. 14. **Answer in the player's language.** Lua and expressions stay as written here. 15. **Switches and break bars:** give every skill except the auto attack a toggle, on by default. When a toggle is off, make every condition that waits for that skill treat the skill as used, so nothing else stalls. Put every CC skill of the build (stuns, dazes, knockbacks, launches, pulls, fears, taunts, moa) in the break-bar phase ([recipe 16.6](/client/acr/recipes#s16-6)). Give each CC skill a single toggle with `section = "CC"`. All rows of that skill use this one toggle, in the break-bar phase and in the rotation. A CC skill the player switched off must never cast. 16. After the file, explain in a few short lines what the rotation does each tick: which groups exist, what wins and when it swaps. Then list the toggles and the ids to check. 17. **If you can run programs and read and write files on the player's PC,** you can test and improve the build yourself. [Section 20](/client/acr/self-improving) says how. If you cannot, never claim that you tested anything. ## 19. Prompt template {#s19} Copy this into your AI together with this file: ```text Write a KX ACR for Guild Wars 2 in Lua, following the attached "KX ACR: Lua API" exactly. Build: Profession and elite specialization: Weapons: set 1 <...>, set 2 <...> Heal, utilities, elite: How to play it: Skill ids: Switches I want on the Skills page: Rules: dynamic priority rotation (no step-by-step script), never guess ids, one complete .lua file. After it, explain the priorities in a few lines and list any ids I should check. ``` When the ACR shows errors: ```text KX says: Fix the file and give me the whole file again. ``` When it loads but plays wrong, describe what you saw: "it never uses X", "it swaps too early", "it stands still after one auto attack". An AI that works on your PC by itself uses the prompt in [section 20.6](/client/acr/self-improving#s20-6) instead. ## Using a coding agent An agent that can run programs on your PC (Claude Code, Codex, Gemini CLI, Cursor and similar) needs only one line. It downloads this guide by itself. If it can, it also [tests and tunes the build](/client/acr/self-improving): ```text Read https://docs.kxtools.xyz/client/acr/agent.md and follow it. Build: ``` --- --- url: https://docs.kxtools.xyz/client/acr/self-improving.md --- # 20. Self-improving ACRs: an AI that tunes the build by itself KX can fight the training golem again and again, write every fight to disk, and reload a build file the moment it changes. So an AI **agent** can do the whole job alone, if it can run programs and read and write files on the player's PC (Claude Code, Codex, Gemini CLI, Cursor and similar). The agent writes the build, reads how the fight went, changes one thing, and repeats until the build plays like its benchmark. A chat AI with no access to the PC cannot run this loop. A chat AI says so, and works the manual way: the player loads the file ([section 4](/client/acr/basics#s4)) and reports what happened ([section 19](/client/acr/ai#s19)). ## 20.1 Set up once (player) {#s20-1} 1. **Start the game with `-acr`.** In the KX launcher, type `-acr` into the account's **Arguments** field (or into **Global arguments** on the launcher's Settings page) and start the game from the launcher. The game ignores the word. KX reads it and shows the **Automatic golem loop** switch. Without `-acr` the switch is hidden and the loop never runs. WeGame accounts take no arguments, so they cannot use the loop. 2. **Go to the Special Forces Training Area** on the character the build is for, set up exactly as the build page says: gear, runes, sigils, relic, traits, skills, weapons. 3. **Utility window → Automation → Training area:** turn on **Setup boons**. Also turn on **Setup golem**, with **Apply hitbox** or **Apply health** on, set to the golem the benchmark used. The golem only spawns with one of the two on. Utility gets your boons, puts the conditions on the golem and spawns the golem. The loop needs Utility for these steps. 4. Optional: **Inventory window → Buffs:** pick your food and utility. The loop then waits for both before every fight. 5. **ACR window → Rotation:** turn on **ACR** and **Automatic golem loop**. The ACR's Settings must allow the training area. This is the default. The loop stays on between sessions and starts by itself in the training area. 6. **Once the agent has installed its first version, pick it:** ACR window → **Builds**, the row marked "yours". KX then always uses that build for the profession, for as long as its id stays the same. The shirt button on the row also equips the build's specializations, traits and skills. Each round, the loop waits for combat to end, has Utility spawn a fresh golem, and waits 5 seconds. Then it resets your cooldowns with Mushroom King's Blessing and waits until every skill is ready. Then it starts a recording, runs the build's `idle` handler, presses auto-attack once and lets the ACR fight until the golem dies. The line under the switch says what the loop is doing or waiting for. The loop moves your character by itself, so don't touch the keyboard and mouse while the loop runs. If a "Stopped: ..." line does not clear by itself, switch the loop off and on. Without `-acr` an agent can still work from recordings: turn on **Record every fight** on the Recorder page and fight the golem by hand. Everything below stays the same, but somebody has to start each fight. ## 20.2 The files {#s20-2} | Path | What it is | | --- | --- | | `%APPDATA%\KX Client\acr\.lua` | The installed build. KX loads it again within about a second of a change. | | `%APPDATA%\KX Client\acr\logs\-\` | One recording per fight. The time is the PC's local time when the recording started. The loop records every fight by itself. | | A work folder of your own, **outside** `KX Client\acr` | Every version, the best version so far, the results, your notes and the state to resume from. | * **KX watches every `.lua` and `.json` file directly inside `KX Client\acr`.** When one is added, changed or deleted, it loads all builds again and the running build starts over (opener, timers, variables). Keep exactly one file of yours there. Never put backups, notes or results in that folder. * **KX notices a change by two things:** how many `.lua` and `.json` files that folder holds, and the newest "modified" time among them. So when you put a file in place, set its modified time to now. KX can miss a restored old version that keeps its old date. * **Replace the file in one step.** Write the new version as `.lua.tmp` next to the installed file, then rename it over `.lua`. KX ignores `.tmp` files, so KX never sees a half-written build. If the rename fails because the file is in use, try again a moment later. * **A build with errors never runs.** KX quietly uses another build ([section 4](/client/acr/basics#s4)). Only the game shows the error text, on the **Builds** page. * Recordings are deleted after 7 days by default, and each fight takes tens of megabytes. Save the numbers you need in your work folder. Do not delete recordings yourself: the player does that on the Recorder page. A recording folder holds: | File | Content | | --- | --- | | `completion.json` | Written last, when the recording is finished. While it is missing, the fight is still running. A good recording has `recordingComplete` `true` and `droppedFrames` `0`. | | `recording.json` | `rotation`: the id of the build that ran. Also `profession`, `specs`, `traits`, `weapons`, and `attributes` (`critChance`, `critDamage`, `boonDuration`, `conditionDuration`). | | `config.json` | `toggles`: every switch of the build with its value in this fight. `settings`: the ACR's own switches. | | `frames.delta.jsonl` | The fight itself, one line per game frame. | | the other files | Not needed. | **`frames.delta.jsonl`:** the first line is the header `{"format":"kx-acr-delta","version":2}`. Every later line is `[n, patch]`: the frame number, counting from 1, and what changed since the frame before. A patch is one of: | Patch | Meaning | | --- | --- | | `null` | unchanged | | `[0, value]` | this value replaces the old one (frame 1 is always this) | | `[1, {key: patch, ...}, [removed keys]]` | an object: these keys changed, those keys are gone | | `[2, {"index": patch, ...}]` | an array of the same length: these elements changed | **A decoded frame.** Rely only on the fields listed here. The other fields change between KX versions. | Field | Meaning | | --- | --- | | `t` | game clock in milliseconds | | `map` | map id; 1154 is the Special Forces Training Area | | `agents` | every character and object near you, one object each (below) | | `damage` | the hits that arrived in this frame: `[source agent id, target agent id, skill id, amount]`. A hit for 0 has no amount, and a fifth value may follow. Condition damage is listed under the condition's id ([section 23](/client/acr/reference#s23)). | | `skills` | your skill bar: rows that start `[skill id, slot, on bar, ready, ground-targeted, recharge left ms, full recharge ms, ...]` | | `set` | the game's number for the weapon set in hand. It changes when you swap weapons or enter a kit. Compare it, don't interpret it. | | `runtime.toggles` | the build's switches as they are in this frame | | Field of an agent | Meaning | | --- | --- | | `id` | agent id, the same for the whole recording | | `local` | `true` for your own character | | `owner` | the id of the agent that owns it (pets, minions, the mech), 0 for none | | `content` | the kind of NPC. The training golems are 16199, 19645 and 19676, one per hitbox size. | | `health` | `[now, max, barrier]`, or `null` | | `buffs` | rows `[buff id, stacks, milliseconds left, yours]` | | `order` | the skill the character is using now: `[action id, skill id, target agent id]`, or `null` | **A complete reader** (Python, standard library only; write the same thing in another language if you prefer). We checked it against real fights. ```python import json, sys from pathlib import Path GOLEMS = {16199, 19645, 19676} # the training golems, one per hitbox size def apply(prev, patch): if patch is None: return prev # unchanged kind = patch[0] if kind == 0: return patch[1] # replaced by this value out = prev.copy() if kind == 1: # object: [1, {key: patch}, [removed keys]] for key in patch[2]: del out[key] for key, change in patch[1].items(): out[key] = apply(prev.get(key), change) elif kind == 2: # array of the same length: [2, {"index": patch}] for index, change in patch[1].items(): out[int(index)] = apply(prev[int(index)], change) else: raise ValueError("unknown patch kind") return out def frames(folder): with open(Path(folder) / "frames.delta.jsonl", "rb") as f: assert json.loads(next(f))["format"] == "kx-acr-delta" state = None for line in f: state = apply(state, json.loads(line)[1]) yield state # read only: the next frame shares its unchanged parts def summarize(folder): folder = Path(folder) if not (folder / "completion.json").is_file(): return {"finished": False} # still being written done = json.loads((folder / "completion.json").read_text()) build = json.loads((folder / "recording.json").read_text())["rotation"] golem = first = end = start = final = t = None before, owned, casts, damage, lost, last = {}, set(), [], {}, [], None for f in frames(folder): t, agents = f["t"], f["agents"] me = next((a for a in agents if a.get("local")), None) if me is None: continue owned.update(a["id"] for a in agents if a.get("owner") == me["id"]) mine = [d for d in f.get("damage") or [] # your hits and your pets' that did damage if (d[0] == me["id"] or d[0] in owned) and len(d) > 3 and d[3] > 0] if golem is None: hit = next((d for d in mine if d[1] in before), None) if hit: golem, first, start, final = hit[1], t, before[hit[1]], before[hit[1]][0] else: before = {a["id"]: a["health"] for a in agents if a.get("content") in GOLEMS and a.get("health")} order = me.get("order") cast = (order[0], order[1]) if order and order[1] else None if cast and cast != last and not (casts and casts[-1][1] == cast[1] and t - casts[-1][0] < 400): casts.append((t, cast[1])) last = cast if golem is None: continue for d in mine: if d[1] == golem: row = damage.setdefault(d[2], [0, 0]) row[0] += d[3]; row[1] += 1 g = next((a for a in agents if a["id"] == golem), None) if g is None: # a dead golem leaves the list if final <= 0.05 * start[1]: final, end = 0, t break # gone with more health left: despawned, not a kill if g.get("health"): final = g["health"][0] while t - first >= 1000 * len(lost): lost.append(round(start[0] - final)) if first is None or (end or t) == first: return {"finished": True, "build": build, "fight": False} seconds = ((end or t) - first) / 1000 dps, health_dps = sum(row[0] for row in damage.values()) / seconds, (start[0] - final) / seconds return { "finished": True, "build": build, "fight": True, "killed": end is not None, "seconds": round(seconds, 1), "dps": round(dps), # your hits and your pets', from the game's combat data "health_dps": round(health_dps), # the golem's health lost per second, from every source "clean": bool(end is not None and start[0] >= 0.99 * start[1] and abs(health_dps - dps) <= 0.03 * health_dps and done.get("recordingComplete") and not done.get("droppedFrames")), "casts": [(round((at - first) / 1000, 2), skill) for at, skill in casts if first - 6000 <= at <= (end or t)], "damage_by_skill": dict(sorted(damage.items(), key=lambda row: -row[1][0])), # skill id: [damage, hits] "health_lost_by_second": lost, # entry n: the golem's health lost n seconds after the first hit } if __name__ == "__main__": print(json.dumps(summarize(sys.argv[1]))) ``` What the reader tells you about a fight: * **`finished`** is false while `completion.json` is missing: the fight is still being recorded. * **The fight** runs from your first damaging hit on the golem to the golem's death. A dead golem leaves `agents`. Its health rarely reads 0 before that. A golem that leaves with more than 5% of its health was despawned, not killed. * **`dps`** is your damage (and your pets') per second. **`health_dps`** is the golem's health lost per second. The golem also loses a little health to the console's conditions, so `health_dps` is slightly higher (under 1% in our fights). Compare `dps` with the benchmark's number, which also counts only the player's own damage. `health_dps` is the cross-check. `damage_by_skill` gives the damage and the number of hits of each skill, and `health_lost_by_second` shows how the fight went second by second. * **`clean`** is true when the golem started with 99% of its health or more, died, the two numbers agree within 3% and the recording is complete. Count only clean fights. A bigger difference between the two numbers means something else hit the golem or hits are missing. Some recordings hold no fight or only part of one (`fight` or `killed` false): skip those. * **`casts`** is the time in seconds and the skill id of each cast, from 6 seconds before the first hit. The game sometimes shows one cast twice a moment apart, so the reader merges repeats of one skill within 0.4 s. An instant skill used during another cast may not show: look for its hits, its buff, or its recharge in `skills`. * **The `skills` rows whose third value (`on bar`) is true are the ids really on your bar in that frame,** for the weapon set or kit you hold then. Use them to check every skill id in your file. ## 20.3 From the build link to the facts {#s20-3} The first version needs two things from the build page: the **build template chat code** and the **benchmark log**. Snow Crows build pages carry both. On another site, look for the same two things. If the page lacks one, ask the player for it. The chat code is what "copy template" on the game's Build tab gives. Fetch the page as HTML. Some sites refuse a request that has no browser-like `User-Agent` header. **The chat code** looks like `[&DQ...=]`. Decode the text between `[&` and `]` as base64: | Bytes | Meaning | | --- | --- | | 0 | always 13: a build template | | 1 | the profession number ([section 21](/client/acr/reference#s21)) | | 2, 4, 6 | the three specialization ids | | 3, 5, 7 | the trait picks of each specialization, 2 bits per tier, lowest bits first: 0 none, 1 top, 2 middle, 3 bottom. The trait id is `major_traits[tier * 3 + pick - 1]` (tier 0 to 2) from `https://api.guildwars2.com/v2/specializations?ids=`. The specialization with `elite: true` there is the elite one. | | 8 to 27 | ten 2-byte numbers, low byte first. Numbers 1, 3, 5, 7 and 9 are the land heal, utility 1, 2, 3 and elite as palette ids. The others are their underwater twins. `https://api.guildwars2.com/v2/professions/?v=latest` has `skills_by_palette`, a list of `[palette id, skill id]` pairs. | That gives `profession`, `elite`, `specs`, `traits` and `skills` for `acr.build`, in the game's own slot order. Weapon skill ids come from [section 3](/client/acr/basics#s3). The first recording then shows what is really on the bar ([20.2](/client/acr/self-improving#s20-2)). **The benchmark log** is the `https://dps.report/...` link on the page. `https://dps.report/getJson?permalink=` returns it as JSON. The site answers with an error at times: ask again later. Use these fields: | Field | Meaning | | --- | --- | | `players[0].dpsTargets[0][0].dps` | the benchmark DPS | | `phases[0].end` | the length of the fight in ms | | `targets[0]` | the golem: `id` is the same number as `content` in a recording, and `totalHealth` is its health. Tell the player to set up this golem. | | `players[0].rotation` | every cast, one entry per skill: `{id, skills: [{castTime, ...}]}`. `castTime` is in ms from the start of the log, and negative for a cast before the first hit. Id -2 is a weapon swap. The log also shows id -2 when you enter or leave a kit. The log lists procs of sigils and traits as casts too. | | `players[0].minions[].rotation` | the same for pets, minions and the mech | | `skillMap["s"].name` | the name of a skill id. The names of conditions and other effects are in `buffMap["b"].name` instead. | | `players[0].targetDamageDist[0][0]` | damage per skill on the golem: `id`, `totalDamage`, `connectedHits` | | `players[0].targetDamage1S[0][0]` | the damage done to the golem after each second | | `players[0].buffUptimes` | rows `{id, buffData[0].uptime}`: boon uptime in percent, average stacks for Might | Study the log before you write a line of Lua: * Write down the opener (the first 6 to 10 seconds, with the casts before the first hit). Also write down how often each skill is cast against its recharge (on recharge, or held for something), what is cast when two things are ready at once, and when the weapon swaps and kit visits happen. * Turn that into priorities and conditions, never into a script ([section 1](/client/acr/ai#s1), rule 4). * A cast lasts from its start to the start of the next cast. Do not use the log's `duration` field: it ends before the next skill can start. * Quirks of the log: a pet or mech command also shows as a player cast at the same time, some skills are listed twice, and damage from a cast before the log starts has no cast. Compare like with like once you have fights: * Your `casts` against `rotation`: the casts per skill, and the order in the opener. * Your `damage_by_skill` against `targetDamageDist`: damage per hit, yours divided by the benchmark's. Near 1.00 (0.97 and up in our fights) means gear, food and boons match. Around 0.85 means one of them is wrong, and no Lua change will fix that. * Your `health_lost_by_second` against `targetDamage1S`: where the fight falls behind. Behind at 20 seconds is an opener problem. ## 20.4 The loop (rules for the agent) {#s20-4} 1. **Check that you can do it.** You need to write `%APPDATA%\KX Client\acr\.lua`, read `logs\`, run a script, and see new training-area recordings appear (new recordings show that the golem loop is running). If you lack one of these, name it and stop. Never pretend to have run a fight. A fight on the 4 million health golem takes about 100 seconds at 40,000 DPS, and longer with less. If nothing new appears for 10 minutes, ask the player to read the line under the Automatic golem loop switch. 2. **Get the facts from the build link** ([20.3](/client/acr/self-improving#s20-3)): the build (specializations, traits, skills, weapons, gear), the rotation guidance and the matching benchmark log with its DPS. Write the first version by [sections 1 to 19](/client/acr/ai#s1). Give it a new id of your own, keep that id permanently, and use one file name. Start the file with a comment that holds the version number and what changed. An id you could not confirm does not stop the loop: note it, tell the player in your next update, and check it against the bar in the first recording ([20.2](/client/acr/self-improving#s20-2)). Ask the player to pick the build once ([20.1](/client/acr/self-improving#s20-1), step 6). 3. **Take a baseline.** Install the file and score the next clean fights. Before you blame the Lua for a DPS gap, check the setup in the recording: * `rotation` is your id. * `specs`, `traits` and `weapons` match the build. * Every switch in `config.json` is as you meant it. * Your boons are up in the frames (Might at 25 stacks, Fury, Quickness, Alacrity). * The golem carries its conditions (Vulnerability at 25). * `attributes` fit the build's gear. The player must fix wrong gear, traits, food or golem settings: tell the player. 4. **One change per version.** Find the biggest problem the recording shows: a skill that sits ready and unused, a skill cast less often than in the benchmark, a gap with nothing cast, a weapon set held too long, a buff or resource that runs out or overflows. Check it against the facts in 20.5 first. Change that one thing. Save the result as the next version in your work folder. Check the whole file before you install it: the Lua syntax with any Lua parser the PC has, and every name inside a condition string against [sections 7 to 10](/client/acr/api#s7) and [22](/client/acr/builtins). KX's own check runs only in the game. 5. **Install only between fights.** Prepare the next version while a fight runs. The gap opens when the newest recording folder gets its `completion.json`, which is right after the golem dies. The gap closes when a newer folder appears. In our runs it lasted 10 to 19 seconds. Your own turns are too slow for that, so let a small script of yours do it: it waits for that `completion.json`, checks that no newer folder exists, renames the prepared file into place and writes down the time. Never install during a fight: the build starts over in the middle, and that fight is worth nothing. 6. **Make sure the fight ran your version.** A fight counts for a version only when the time in its recording folder's name (the PC's local time) is at least 5 seconds after that version went in, its `rotation` is your id, and `clean` is true. A fight that started earlier counts for no version: wait for the next one. If `rotation` names another build, the player has not picked your build yet, or your file has an error. If your file has an error, put the last good version back in the next gap, then find the mistake with [section 17](/client/acr/recipes#s17) or ask the player for the lines on the Builds page. 7. **Decide on averages.** Fights differ by a few percent with no change at all. Score at least 3 clean fights per version and compare the means. Keep a change that is clearly better, and take back one that is clearly worse. When you cannot tell, run more fights and alternate the two versions fight by fight (A, B, A, B): two blocks of fights one after the other drift apart on their own. A change worth less than 1% cannot be proven by DPS in a handful of fights. Check in the recording that the thing you changed really happened (the cast moved, the missing hit is back) and keep the change based on that proof. Never report the best fight as the result. 8. **Write it down, then go on.** After every decision, save in your work folder: the installed version, the best version with its mean and fight count, what you tried with its result, and the ideas you still want to test. Then continue with the next idea without asking. Keep each update to the player short: the change, the result, kept or taken back, the next test. A later session picks up from the saved state. 9. **Stop** when the player says so, when a blocker needs the player (name it), or when the build is steady near its benchmark and you have no justified, testable idea left. Leave the best checked version installed, and finish with a short report: the mean DPS and the number of fights behind it, the percent of the benchmark, the switches the build has, the ids still unconfirmed, and what golem fights could not prove. Limits: * Golem DPS on one standing target proves the damage rotation, nothing else. It does not prove break bars, movement, boons given to allies or any encounter mechanic. Keep the build's role (damage, boon, support), its weapon set, and the toggle and CC rules of [section 1](/client/acr/ai#s1), even where a shortcut would gain golem DPS. * Read only the files named here. Never touch the game, other KX files or other people's builds, and never invent a function, an id, a recording field or a result. ## 20.5 Facts that decide the last few percent {#s20-5} We measured each of these on real fights while we tuned KX's own builds. Check them before you change a rotation. Reading the game right: * **A skill that is still casting shows recharge 0** until a moment after the cast. Test "this skill was used" as `current(X) || cd_bar(X) > 0`, never as `cd_bar(X) > 0` alone. * **`cd_bar(X)` is the number on the bar.** It ignores alacrity and moves in steps. `cd_adj(X)` is real time. Compare a recharge with `swap_cd()` or any other real time through `cd_adj`. * **`time_since(X)` counts from the last frame X was the running cast.** It stays near 0 while X casts. It never counts an instant skill with no charges. To remember a moment, set an `acr.var` in the `daemon` handler. * **A block or channel counts as a running cast for its whole length.** Its follow-up skill is on the bar at once, but as a normal row it waits for the block to end. Make that row `:insta()` with `current()` as its condition. What cuts or delays a cast: * **A ground-targeted skill sent during another cast ends that cast** if it arrives before the cast releases. A normal skill waits its turn instead. The skill that was cut deals no damage. When the skill before a ground skill loses hits, put `:last_trigger_type(0)` on the skill before the ground skill. * **Do not delay a ground skill with `final_effect_fired()`.** It then loses its turn to auto-attacks. * **A queued normal skill always waits for the whole cast before it.** Sending it later saves nothing. Only a weapon swap ends a cast early. * **A refunded skill is back on the bar in the frame the refunding skill ends.** A filler cast in between delays it, so do not cast fillers right after a refund. * **Use a refund skill right after the skill it refunds,** not shortly before that skill comes back by itself. * **A stay on one weapon set lasts one swap recharge.** Wait for skill X before you swap only when `cd_adj(X) <= swap_cd()`. * **Utilities cast on a finished weapon set just before the swap only delay the swap.** The golem and the loop: * **The training golem's break bar cannot be broken.** CC rows never change golem numbers and cannot be tested there. * **A long-lasting ground field cast as the golem dies is still there when the next golem spawns.** It keeps you in combat and spoils the next fight. Give such skills a `target_hp()` condition so the ACR does not cast them on a golem that is about to die. * **Fights of one unchanged version differed by 500 to 1,200 DPS in our runs,** with the same rotation every time. That is why rule 7 of [20.4](/client/acr/self-improving#s20-4) asks for averages. ## 20.6 Prompt for the agent {#s20-6} Copy this into the agent together with this file. The build link is the only thing to fill in. ```text BUILD LINK: Act as an autonomous KX ACR author and tuner. Read the attached "KX ACR: Lua API" completely, and follow its section 20 exactly. The build link is my only input: get the build, the rotation guidance and the matching benchmark from it yourself. Use only the API the guide documents. No library field, run_legacy, can_run_legacy, legacy_* calls or acr.visual blocks. Follow the guide's rules for dynamic priority rotations, skill ids, toggles and CC. Keep the weapon set and the role (damage, boon or support) the build page advertises. With your own tools on this PC, run this loop yourself: 1. Check the setup and take one clean baseline fight. Check gear, consumables, boons, golem settings and which build really ran before you blame the Lua for a DPS gap. 2. Find the biggest problem the recording shows and make ONE change for it. 3. Check the complete Lua, then install it only in a gap between fights that you have verified. KX reloads the file by itself: no game restart. 4. Read the next complete, clean fight, make sure it ran your version, and judge the damage and the casts. Keep what is clearly better, take back what is clearly worse, and repeat fights when you cannot tell. 5. Write down the result, pick the next idea and go on without asking me to say "continue". The game runs with -acr. Check that the Automatic golem loop is really running: new training-area recordings must keep appearing. Keep ONE build id and ONE file in %APPDATA%\KX Client\acr\. Keep every version, the best version, the results, the open ideas and the state to resume from in a work folder outside that folder. Prepare changes during a fight and never install during one. Aim for steady results near the matching benchmark with the role and mechanics intact. Compare complete fights of the same setup and report averages, never one lucky fight. Never invent API calls, ids, recording fields, access or results. Golem DPS on one target does not prove encounter mechanics. Go on until I stop you, until something needs me, or until the build is steady and you have no justified, testable improvement left. Keep the best checked version installed and resume from your saved state in a later session. Keep your updates short: the change, the result, kept or taken back, the next test. This needs real file and tool access on this PC and fight recordings you can read. If you lack one of them, tell me exactly which, and do not pretend to run the loop. Start now. ```