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 2 hours ago by josue valencia
diagrams, repo

[phosit]

4 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.)

4 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"}

 

4 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 recently been 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.

[Emacz]

Ive been using AI to help improve Petra.  I have an "expert" version that comes with Classical Warfare AEA.  But I'm you could easily just download the AI files. ALthough it does specifically work with some of our overall changes.  It can randomly roll 4 strategies, p1 rush, p2 military tech push, p3 max pop max techs and I forget the 4th one  It beats very hard 95% of the time (and only has a 20% gather resource bonus instead of the 56% that VH has)  but I'm still trying to get it to be more efficient.  A lot of times it will basically break very hard by 10 min, but then it takes another 10-15m to actually finish the gam 

[josue valencia]

Thanks @phosit, this is exactly the feedback I wanted.

PRs. Fair. Those were low-priority fixes I made while setting up my local environment on macOS (not easy) and to test the AI-assisted workflow I'm using now. I'll reopen the ones that still make sense (#8976 fixes the still-open #8975; #8977 I owe you the commit split) and answer the pending reviews. No hard feelings.

Quote

"Every code should be possible to understand."

I agree, and I'd put the line here: the model never writes behaviour. Every stratagem, every question and every fallback rule is plain JS/Python you can read. The model only picks between options we wrote, and the rule arm (a hand-written distance rule) exists precisely so the model can be swapped out and compared. - i am building it now with laya, but it should allow easily swap to use other like Jev - At the end of the day the model will pick up which "function" in the system to use.  

Two tasks in one system. Partly a misunderstanding on my side of the post: hero "playbooks" are strategy (Fabius = delay, Leonidas = hold the pass), not unit micro, and the actual fight stays Petra's. But you're right that "hold / strike / fall back" every few seconds sits between strategy and tactics. I'll keep the questions at the strategic level (which stratagem, where, when to commit) and leave "when to end an attack" to Petra's existing attack-plan logic unless the data says otherwise.

Starting strategies. Looked at startingStrategy.js (configFirstBase): flags from land/food/wood plus the personality axis, chosen once, no civ or enemy input. That's a natural home for the civ-doctrine part (a named opening per civ instead of threshold flags), and a smaller, more upstreamable change than what I described. I'll start there for the early game.

State as language. I won't feed raw commands. The state is a short readable summary ("enemy army of ~30 units, 80 m from the pass, moving toward our tower; our 25 units garrisoned"), which is what these classifiers are trained on. I measured Laya locally today: ~40 ms per question on a laptop CPU after a one-time 55 s load. I'll publish the exact input format with the dataset.

Host-only model. You mean #8786, I think. That one moves all of Petra to the host and clients stop simulating it, so a modified AI would be undetectable; I understand why it stalled. This proposal is narrower: Petra keeps running on every client (so the OOS hash still covers it) and only the hint is a host command, the same class as any command a human host sends. The residual risk is a host sending sabotaging hints to an AI slot, which is a "bad ally" problem, not a desync one. It's not doable as a pure mod, agreed: the server must accept that one command type for AI slots. That's a small engine change, and single-player needs none of it.

please take a look at, Script and the Output. Reproducible in 5 min: pip install laya, run this script;

And yes, using a model to find where Petra is weak is a good use too; the labeled game states from this work could feed that.

To be clear about the goal. Performance (Petra's or AI lag in general) is not what I'm trying to improve. The goal is a smarter Petra: strategies that fit the civilization and the hero it's playing, the way those armies actually fought. Whether that needs a model at all is an open question. Right now this is a prototype, there's plenty of room for improvement, and I'm fully open to dropping the model if a deterministic, hand-written way gets the same result. 
 

Edited 19 minutes ago by josue valencia

[josue valencia]

thanks, @Emacz
 

That's great to hear, and close to what phosit suggested above: named openings instead of Petra's threshold flags. I had a look at your repo (Emacz2/classical-warefare-aea); the expertDecision/ stage machine and build-order planner are very much the "hands" side done well. A few questions:

1. The AI looks tied to Classical Warfare units (Athenian Marine etc.). Is there a version that runs on vanilla, or an older build with the 4 random strategies? I'd like to use it as a second, stronger baseline in my headless harness (fixed seeds, Petra vs Petra). - will be funny, to have different AI battling each other 
2. "Breaks Very Hard by 10 min, then 15 more to finish": the finishing problem (when to commit and end the game) is one of the questions I want to measure. Any intuition what it's missing there?

Happy to compare notes; your work is a good deterministic baseline against which anything model-driven has to prove itself.

Where I think we differ, and why I'm not just doing the same: your expert AI makes Petra stronger, with a well-tuned build order and a stage machine, and it works. What I'm after is variety: a Petra that plays differently as Sparta under Leonidas than as Carthage under Hannibal, that holds a pass on one map and builds a trade network on another, and that reacts to what the opponent is doing. Strength is a side effect there, not the goal; the "expert" doctrine could well be one of the openings a civ picks. So the two are complementary: your work is the hands, mine tries to be the head.

[Emacz]

4 minutes ago, josue valencia said:

thanks, @Emacz
 

That's great to hear, and close to what phosit suggested above: named openings instead of Petra's threshold flags. I had a look at your repo (Emacz2/classical-warefare-aea); the expertDecision/ stage machine and build-order planner are very much the "hands" side done well. A few questions:

1. The AI looks tied to Classical Warfare units (Athenian Marine etc.). Is there a version that runs on vanilla, or an older build with the 4 random strategies? I'd like to use it as a second, stronger baseline in my headless harness (fixed seeds, Petra vs Petra). - will be funny, to have different AI battling each other 
2. "Breaks Very Hard by 10 min, then 15 more to finish": the finishing problem (when to commit and end the game) is one of the questions I want to measure. Any intuition what it's missing there?

Happy to compare notes; your work is a good deterministic baseline against which anything model-driven has to prove itself.

Where I think we differ, and why I'm not just doing the same: your expert AI makes Petra stronger, with a well-tuned build order and a stage machine, and it works. What I'm after is variety: a Petra that plays differently as Sparta under Leonidas than as Carthage under Hannibal, that holds a pass on one map and builds a trade network on another, and that reacts to what the opponent is doing. Strength is a side effect there, not the goal; the "expert" doctrine could well be one of the openings a civ picks. So the two are complementary: your work is the hands, mine tries to be the head.

Appreciate you response @josue valencia.
Juist so we are clear, I know very little about what I'm doing, AI is doing most of it for me I basically send replays/interesting log and send to chatGPT and then tell it what i see think should be improved and it writes the changes.
Yes the AI is tied to Classical Warfare, so you would have to download the AI only and probably recode some of it.
However, I think we are trying to be similar in ways that you might not be aware of.  In general we changed CWA so that the Civs were a little more different and represented their heroes/styles better.  For example greek hoplites are a little stronger than most spearman and the first melee attack tech is aviabile in p1 for greek city states.  So in the p1 rush for Greeks the AI is supposed to try and get that attack to give it an advantage.  There are still llots of little things that need cleaning up.  ANd I continue to work on it daily.  Would be great to bounce ideas off someone else, but yes I realize it is mainly tied into the changes we made to CWA and some, if not a lot of people may not want that.  Although some of those changes will probably be coming to newer versions of the base game, like "charge" type behavior and other things I think.