---
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 `<id>.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.
