Skip to content

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) and reports what happened (section 19).

20.1 Set up once (player) ​

  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 ​

PathWhat it is
%APPDATA%\KX Client\acr\<id>.luaThe installed build. KX loads it again within about a second of a change.
%APPDATA%\KX Client\acr\logs\<YYYYMMDD-HHMMSS>-<id>\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\acrEvery 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 <id>.lua.tmp next to the installed file, then rename it over <id>.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). 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:

FileContent
completion.jsonWritten 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.jsonrotation: the id of the build that ran. Also profession, specs, traits, weapons, and attributes (critChance, critDamage, boonDuration, conditionDuration).
config.jsontoggles: every switch of the build with its value in this fight. settings: the ACR's own switches.
frames.delta.jsonlThe fight itself, one line per game frame.
the other filesNot 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:

PatchMeaning
nullunchanged
[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.

FieldMeaning
tgame clock in milliseconds
mapmap id; 1154 is the Special Forces Training Area
agentsevery character and object near you, one object each (below)
damagethe 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).
skillsyour skill bar: rows that start [skill id, slot, on bar, ready, ground-targeted, recharge left ms, full recharge ms, ...]
setthe 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.togglesthe build's switches as they are in this frame
Field of an agentMeaning
idagent id, the same for the whole recording
localtrue for your own character
ownerthe id of the agent that owns it (pets, minions, the mech), 0 for none
contentthe kind of NPC. The training golems are 16199, 19645 and 19676, one per hitbox size.
health[now, max, barrier], or null
buffsrows [buff id, stacks, milliseconds left, yours]
orderthe 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 ​

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:

BytesMeaning
0always 13: a build template
1the profession number (section 21)
2, 4, 6the three specialization ids
3, 5, 7the 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 three ids>. The specialization with elite: true there is the elite one.
8 to 27ten 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/<Name>?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. The first recording then shows what is really on the bar (20.2).

The benchmark log is the https://dps.report/... link on the page. https://dps.report/getJson?permalink=<that link> returns it as JSON. The site answers with an error at times: ask again later. Use these fields:

FieldMeaning
players[0].dpsTargets[0][0].dpsthe benchmark DPS
phases[0].endthe 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].rotationevery 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[].rotationthe same for pets, minions and the mech
skillMap["s<id>"].namethe name of a skill id. The names of conditions and other effects are in buffMap["b<id>"].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].buffUptimesrows {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, 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) ​

  1. Check that you can do it. You need to write %APPDATA%\KX Client\acr\<id>.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): 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. 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). Ask the player to pick the build once (20.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 and 22. 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 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, 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 ​

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(<the block>) 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 asks for averages.

20.6 Prompt for the agent ​

Copy this into the agent together with this file. The build link is the only thing to fill in.

text
BUILD LINK: <paste the build link here>

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.