Apex is a skirmish AI for Beyond All Reason (BAR), the RTS on the Recoil engine. It started as a fork of BARb, the AI that ships with the game, and has since replaced most of how BARb decides what to build and when. This repo is its source, its test harness and its notes.
You need BAR, started at least once so it has downloaded its engine. These steps are for Windows;
on Linux, download Apex-AI-<version>-LINUX.tar.gz instead and run
tar xzf Apex-AI-<version>-LINUX.tar.gz && bash install.sh (the Linux build is new and lightly tested).
- Open the latest release and download the
file named
Apex-AI-<version>-INSTALL.zip(a few MB). Not "Source code (zip)" or "(tar.gz)": GitHub adds those to every release, they are this whole repository, very large, and have no installer. - Close BAR.
- Right-click the zip, Extract All, and double-click
Install.batin the extracted folder. It finds your BAR install, copies the AI into the engine folder, and turns off the lobby's "Simple AI list", which would otherwise hide it. - Start BAR. In a skirmish or a hosted lobby, Add AI and pick Apex with its version.
Only the player hosting the game needs it installed. Everyone else just joins.
Some things to know:
- Engine version. Each zip is built for one BAR engine, named in the zip and on the release
page (for example
recoil_2026.07.04). On a different engine the AI fails to load without a useful error. The installer warns you if yours does not match. - BAR updates. An engine update wipes the AI folder. Run
Install.batagain, or get the release built for the new engine. - Keep one version installed. A hosted lobby does not send which version you picked, so the
engine loads the highest Apex version installed. Delete old ones from
<BAR install>\data\engine\<engine>\AI\Skirmish\Apex\. - Manual install.
INSTALL.txtin the zip has the steps if the installer cannot find BAR. - Uninstall. Delete the
Apexfolder above.
Each Apex bot in a lobby has its own options. The defaults are the AI's strongest play and what gets tested.
| Option | What it does |
|---|---|
| Personalities | Off (default): the standard AI. On: each game the team secretly picks a style (balanced, artillery, snipers and stealth, air, T3, nukes or rush) and leans its building toward it, switching style if it keeps trading badly; each bot also gets its own random tastes. More varied games, measured somewhat weaker. Set it the same on every bot of a team. |
| Economy player | 0 (default) is off. Above 0 makes this bot its team's economy player: economy first, army and defence held back until its economy is halfway to its goal, then brought in. 1 is a full economy phase, 0.5 half as long. An enemy army near its base brings army and defence back while it stays. Suits a bot at the back of a team. Not measured. |
| Advanced | Map-wide vision (a cheat), keeping out of allied bases (leave on), and units this bot never builds. |
Most RTS AIs are a build order plus a pile of rules: "after 4 extractors build a factory", "keep 6 defenders at home", "go T2 at 20 metal income". Apex has none of those on purpose. Every decision answers one question: what is the fastest path to the state we are trying to reach? The AI names a target (this much army, or that much army with a fusion reactor behind it) and takes the move that gets there soonest.
So order, counts and limits come out of the arithmetic. They are never typed in. When a hand-written threshold, cap or build order turns up in this code, it is treated as a bug: it means the pricing behind it is wrong somewhere, and the fix belongs there.
When a constructor is free, it holds an election. About twenty proposers each put forward their best job: an extractor, a solar, a converter, a nano turret, a defence, a reclaim run, an extractor upgrade. Each job is priced as gain over cost, and cost includes metal, build time, the walk to the site and the chance of dying on the way. The constructor takes the best one.
A judgement never forbids an option outright. If a tower is badly placed it gets a bad price, but it can still win when nothing better exists, so the AI can still try it and learn from it. Only true impossibilities (the ground is taken, the unit cannot reach) rule an option out.
The core tenet comes from the player who directs this AI: always be making economy. Metal spots are few and fixed, so economy also means energy, generators and converters (about 60 energy buys one metal). Some hands are always on economy, and army and defence are held at their share of the economy we have built.
Two nets sit on top of the market. A policy network reads about 70 facts about the game (incomes, army sizes on both sides, threats, what is standing) plus each option's own numbers, and scales that option's value up or down. Small heads each set one number a hand-written rule would otherwise set, such as how hard to expand, how many constructors to make, or how strong an escort should be. With every output at zero the nets leave the prices alone, and the hand-written prices and rules play on their own.
Training is being rebuilt. The nets in current releases came from a search over many games, and measurement showed it could not tell a good net from a lucky one. Learning from whether the game was won fails for a similar reason: one builder's choice is drowned out by everything else the team does. Two things replace it. The prices are being made sound, each one checked against what actually happened to each building: did it survive, how long it really took to build, what it produced. And the net now learns from its own choices. In training games every output is pushed a little off what the net would play, and each push is credited with how our position (economy, army, trades) moved in the next two minutes. Credit tied to the decision itself, such as whether an extractor got built or its constructor died, comes next.
Every training game draws its setup at random (map, team sizes, factions, resource bonus, length) so the net cannot learn one map's game. Training never uses games against people, and lobby games never explore. A new net ships only if it beats the current one over 24 or more games.
docs/doctrine.md is one experienced BAR player's account of how the AI should
play: what to do, what never to do, and facts of the game. It is the spec. Code that breaks a line
under Never is a bug. A Do line is a default the nets may overrule where games show it
loses.
The order of goals in that file is worth knowing. Fun to play against comes first: surprise, challenge, and interaction all game. A huge economy followed by one overwhelming army is called out as the boring arc. After fun come beating BARb in more than 80% of even games (a goal it has not reached yet), ending games when they can be ended, and making them worth watching: bombing raids, nuke salvos, long-range plasma.
- It only uses what a player could see. Hidden enemy units are not read; the "see the whole map" cheat is an explicit lobby option, off by default.
- It runs entirely on the host. Nothing is added to the game's synced code, so it works in normal multiplayer lobbies with no mod.
- Apex players on one team share a team board. They co-build one experimental gantry, share extractor upgrades, and give advanced constructors to allies who have none; with Personalities on they also play one shared style. This team play is experimental and not measured.
Changes are tested in headless AI-vs-AI games, mostly against stock BARb, and judged on what the
games show rather than on whether the new code ran. Each release tag
records what it measured, including the changes that made it worse (docs/versions.md).
You need Windows 10 or 11, BAR, git and Python 3.13 (the tools use the standard library only). Docker Desktop is needed only to rebuild the C++ part.
git clone https://github.com/apexearth/bar-ai
cd bar-ai
python tools/bar_env.py # prints the BAR install and engine it found
python tools/deploy_ai.py deploy Unstable --repo-dll
python tools/deploy_ai.py statustools/bar_env.py finds BAR on its own. If your install is somewhere unusual, set BAR_ROOT,
BAR_DATA or BAR_ENGINE. --repo-dll ships the DLL checked into the repo instead of one you
built; it can lag behind cpp/, and if the AI's script then fails to compile, build the DLL
(below). After deploying, the lobby lists Apex Unstable. Uninstall any release while you test
it, or a hosted game will load the release instead.
The harness plays AI-vs-AI games with no window, much faster than real time, and writes each one
to matches/ or tournaments/.
python tools/sync_game.py # build the harness's copy of the game from your lobby's version
python tools/deploy_ai.py gadgets # install the autoquit and result gadgets into it
python tools/run_match.py --a Apex:Unstable:standard --b BARb:stable:hard \
--map "Comet Catcher" --minutes 30 --seed 1 --speed 20
python tools/run_tournament.py --a Apex:Unstable:standard --b BARb:stable:hard \
--maps "Comet Catcher,Supreme Isthmus" --games 10 --speed 20
python tools/run_tournament.py --report
python tools/review.py <run> # judge a run: did it compile, run, and what happened
python tools/story.py <match> # why a game was won or lost
python tools/dashboard.py # a local web UI for runs, launching, deploying and tunablesAlways pass --speed. An uncapped headless game runs so fast that commanders stall, and the
results stop meaning anything. Each engine uses 5 to 6 GB of memory, so count before launching
several. docs/working.md has every command and the rules for testing a
change.
The AI has three layers. You edit them under ai/Unstable/, and deploy_ai.py deploy copies them
into BAR.
| Layer | Where | Build | What it decides |
|---|---|---|---|
| JSON config | ai/Unstable/game-side/config/ |
none | unit roles, threat, retreat thresholds |
| AngelScript | ai/Unstable/game-side/script/ |
none | everything built and produced, army use, the commander, air, nukes, the nets |
| C++ | cpp/ |
Docker | squad movement and fights, threat maps, placement, the script bindings |
Most work happens in AngelScript, and the builder election lives in
script/standard/manager/brain/market/. Every default the AI plays with is one line in
script/standard/tunables.as, and docs/tunables.md says why each is what it
is. python tools/check.py runs the static checks, including the one that fails any spending
outside the market.
The C++ builds in Docker against the Recoil engine source: python tools/bootstrap_sources.py engine, then python tools/build_dll.py --deploy. See "Building the DLL" in
docs/working.md. Releases are built by
.github/workflows/release.yml from the pins in
.github/release.env.
ai/Unstable/ the AI, source of truth; ai/v*/ are frozen releases
cpp/ the C++ source of the DLL (a fork of CircuitAI)
game-patches/ changes to shared BAR files, and the dev gadgets the harness uses
tools/ deploy, the headless harness, analysis, the dashboard
docs/ the documents below
reference/ stock BARb, for diffing (read-only)
matches/ tournaments/ runtime/ vendor/ game output and upstream clones (gitignored)
docs/doctrine.md |
how the AI should play: goals, Do, Never |
docs/how-it-works.md |
how each part decides, from the current code |
docs/army.md |
the army layer and how army changes are tested |
docs/working.md |
commands, testing, building, releasing |
docs/traps.md |
silent failure modes, each with its check |
docs/tunables.md |
why each default is what it is |
docs/versions.md |
one line per release |
ISSUES.md is what is wrong now, TODO.md holds plays not yet built, and USER-FEEDBACK.md the
owner's open requests.
Most of the code here is written with Claude Code, directed and
play-tested by the owner. CLAUDE.md is its index to the repo. If you send a change upstream to
BAR or CircuitAI, their AI_POLICY.md asks you to disclose AI-assisted code and to have a human
verify it.
Apex is built on CircuitAI by rlcevg (its barbarian
branch is BARb), Beyond All Reason and
the Recoil engine. The BAR Discord is where
their developers are.