Strategos: a strategy layer for Petra, driven by a small open-source model that runs locally (proposal + fork to test)

[josue valencia]

Hi all,

I'm Josue (josue on Gitea), a fairly new contributor. I want to share a project I'm about to start, get your feedback before I write code, and later hand you a fork to test and pick apart.

The itch

Petra is a solid executor. It gathers, builds, places, trains and fights well. But it plays the same linear game on every map, against every opponent: gather, age up, train, attack the nearest Civic Center, repeat. It doesn't use terrain, it doesn't read you, and difficulty is mostly a handicap (gather rate ×0.42 on Sandbox up to ×1.56 on Very Hard, plus some caps).

Meanwhile the game ships 51 historical heroes across 15 civilizations: Hannibal, Alexander, Vercingetorix, Leonidas, Fabius Cunctator, Viriathus, Themistocles... and the AI never fights like any of them. Petra's Leonidas doesn't hold a pass. Petra's Fabius doesn't delay. Nobody builds Alesia.

The idea

https://gitea.wildfiregames.com/josue/0ad/src/branch/strategos/mvp1/docs/strategos

Split the bot into hands and head.

• Hands stay Petra: economy, building placement, gathering, queues, trade and garrison mechanics, the actual battle.
• The head is new: a small strategy layer that picks a stratagem: wall the choke by the river and wait; build a trade network; garrison the towers along the enemy's approach; strike their army while it's strung out in a pass; fall back.

A stratagem enters Petra through one door (Headquarters), which hands it to the manager that already knows how to execute it. The ambush and the Persian trade network go through the same channel.

Who picks the stratagem? We write the doctrine, a model judges.

• Civ doctrine: read from the civ bonuses that already exist as data. Romans fortify, Carthage goes to the sea and to elephants, Persians trade, Spartans hold ground.
• Hero archetypes: 5–6 playbooks mapped to the heroes: siege builder, ambusher, hammer and anvil, hold the pass, delayer, naval raider.
• Stages triggered by the game, not the clock: early game follows the civ doctrine; mid game picks a hero and runs their playbook (hero dies → next hero); when heroes run out the AI goes defensive: commerce and fortification.
• Opponent model: is the other player rushing, booming or turtling? Where is their army heading? Are they weak at sea? This is what changes every game, and it's what Petra has never had.

The model doesn't invent strategy. It answers typed questions ("hold, strike or fall back?", "rush, boom or turtle?") with probabilities. That's a classification job, which is why a small model can do it.

Free and open, by design

The target model is Laya (convaiinnovations/laya on Hugging Face): Apache 2.0, 421M parameters, a classifier that answers typed questions and runs on a CPU (the model card says roughly 200–450 ms per question on CPU; I haven't measured it yet).

• Optional download (~650 MB). Without it you get plain Petra; nothing changes.
• No account, no API key, no network, no cost.
• Multiplayer-safe: only the host runs the model, and its decisions go out as ordinary network commands. Clients don't need the model, lockstep holds, replays replay. This also sidesteps floating-point differences between platforms. One engine change is needed for it: today the server drops commands sent on behalf of another player unless cheats are on (NetServer.cpp), so the host must be allowed to send this one command type for AI-controlled slots. Single-player is unaffected.
• Mod first: a strategos mod that overlays only the Petra files it touches. Default Petra stays untouched.

An honest note on prototyping: to learn quickly which questions matter, the very first prototype uses a hosted typed-question API (TypeSafe's Jev), called from an external Python script through the existing RL interface. That is developer scaffolding only. It will never ship and players will never need it. Both models take the same question format, so swapping to the local model doesn't change the questions.

Performance: what it costs

Lag is already the most common complaint, and AI plus pathfinding are big parts of it. Today every AI runs on the simulation thread, on every client, every turn. So this has to be designed not to make it worse:

• The in-engine part is tiny. Petra reads at most one hint per played turn and hands it to a manager it already runs. I'll measure Petra's turn time (the existing PetraBot bot (player N) profiler section) with and without the mod, and publish the numbers. The target is ≤5% overhead.
• The model never runs on the simulation thread. At 200–450 ms per question on a CPU, running it inline would freeze the host, and in lockstep that means everyone. So questions are asked every few seconds (not every turn), inference runs on a worker thread, and the answer comes back as a command a few turns later. The engine already has a TODO for exactly this pattern (async AI tasks that return after a fixed number of turns, in CCmpAIManager.cpp), and it lines up with the ongoing threading work (#5874). If that helper gets built, Petra's own heavy analysis could use it too.
• Only the host pays. Clients run nothing extra. The host pays CPU on a spare core, plus the model's memory (roughly 0.5–1.7 GB depending on quantization; I'll measure and publish it).
• It won't fix lag. I'm not promising a speedup. At best, stratagems replace some of Petra's per-turn strategic scans with a cached decision; that's a side effect, not the goal.

How it relates to existing plans

From the Gameplay Feature Status and Game Performance wiki pages:

• Advanced AI is listed as "partially complete" (#973, #3003). The terrain and threat reading here (choke points, the enemy's approach) overlaps #3003 ("Petra should be aware of dangerous areas"). Anything reusable goes upstream on its own.
• The naval raider archetype depends on #3002 (Petra using ships for warfare), so it comes later.
• Directional attack bonuses (flanking) aren't implemented, so "hammer and anvil" can only win through positioning and surrounding, not a flank bonus. I'll keep the playbooks honest about what the game actually rewards.
• "Ambush" here is AI behavior (hold a choke, strike at the right moment). It's unrelated to the concealment mechanic in #3177.
• Narrative and strategic campaigns were cut from Part 1. A historically flavored opponent in skirmish is a cheap way to get some of that feeling back.

How I'll prove it (before anyone gets excited)

MVP of the MVP: one map with clear choke points, one stratagem (ambush at the pass), one question (hold, strike or fall back). Three arms on the same seeds:

1. vanilla Petra
2. ambush + a dumb distance rule ("strike when their army is within N metres")
3. ambush + the model

Arm 2 vs 1 measures the stratagem; arm 3 vs 2 measures the model. Before any game, the model has to beat the rule on 50–100 hand-labeled game states. If it can't, I'll post that result here too.

Roadmap

• Phase 0: headless Petra vs Petra harness through the RL interface; determinism checked through replays.
• Phase 1: the hint channel (a new strategos-hint command → Headquarters dispatch). JS only, no engine changes.
• Phase 2: choke points extracted from the passability grid.
• Phase 3: the ambush stratagem in Petra.
• Phases 4–5: rule arm, labeled dataset, model arm; results posted here.
• After that: the local model on the host, outside the simulation (optional ONNX Runtime dependency, off by default), the small network change above, then more stratagems, civ doctrines, hero playbooks, the opponent model.

What I'll share, and what I'm asking

I'll share:

• Everything in my fork, https://gitea.wildfiregames.com/josue/0ad (branch strategos/mvp1): code, match results, replays and the labeled dataset, for anyone to test, reproduce or tear apart.
• Fixes, as normal PRs, for the RL-interface bugs I run into along the way. #7854 and #7628 look like the first ones I'll hit.

I'm asking for feedback from:

• Petra maintainers: is a single "stratagem hint" entry point in Headquarters acceptable, or would you prefer a different hook?
• Engine folks: what do you think of an optional ONNX Runtime dependency behind a build flag, off by default?
• Players and history nerds: which hero should fight how? Which maps have good passes?
• Everyone: is this a direction the project would consider upstream one day, or should it live as a mod? Either is fine with me.

Disclosure: I drafted this post with help from an AI assistant (Claude). The plan and the decisions are mine, and any code will go through the normal review process.

Edited 1 hour ago by josue valencia
diagrams, repo

[phosit]

3 hours ago, josue valencia said:

I'm Josue (josue on Gitea), a fairly new contributor.

Hi, i closed your PRs as you didn't reply for some months. Feel free to reopen them.

Nice that you work on this. I also had plans to use AI to improve the Petra. (Not to integrate it but to use it to see where Petra is bad at.)

3 hours ago, josue valencia said:

Engine folks: what do you think of an optional ONNX Runtime dependency behind a build flag, off by default?
Everyone: is this a direction the project would consider upstream one day, or should it live as a mod? Either is fine with me.

Integrating it that much goes (for me) against the free software philosophy. Every code should be possible to understand.

You want the AI to choose a strategy. But you also want the AI to say when to end an attack (fall back) and how a hero should fight. Thous seem pretty different tasks. I think it's bad to solve both with the same system.

Currently there are starting-strategies witch are chosen from. It would be good when you take a look there. Maybe you can extend that.

The model you choose takes language as "state". Yes it can be json formated and yes it's multilingual but i'm not sure it understands something like 

{"type":"repair","entities":[177],"target":4030,"autocontinue":true,"queued":false,"pushFront":false,"formation":"special/formations/null"}

 

3 hours ago, josue valencia said:

only the host runs the model, and its decisions go out as ordinary network commands. Clients don't need the model

Why? There has been recently a PR wanting to do a similar thing for Petra. As i remember it the conclusion was to not continue the plan for now.
I don't think that it is possible to do it in a mod.