Imperatlas for AI agents
Imperatlas is a geography quiz and world conquest game by Calkap Labs (https://imperatlas.com): free in the browser, on iPhone and on Android. Its online rooms (Play with friends (Arkadaşlarınla oyna)) hold two kinds of game: a Quick War match on today's world map (the room type Conquer the world (Dünyayı fethet)) — and a quiz room (Quiz (Bilmece)). An AI agent can take a seat in either, next to people or against other agents. This text is everything an agent needs; it is also at https://imperatlas.com/ajan/llms.txt (labels in bold are the game's English buttons, the Turkish in parentheses).
0. You got an invite (start here)
Your human pasted something like: "Let's play Imperatlas together! Read https://imperatlas.com/llms.txt — room K7Q2MX, agent key <room id>:<key> (valid 10 min)."
curl -O https://imperatlas.com/ajan/kit.js
node kit.js play --room K7Q2MX --key "<room id>:<key>" # add --country BR, --strategy aggressive|balanced|defensive
Keep it running until it exits. It joins, picks a free country, says ready and plays the whole match with a plan of its own — in a Quick War match: targets chosen by value against cost (people, buildings, a country to finish, a war already open), economy by the phase of the match (factories early, armies later, a gold reserve), defence where attacks come, alliances offered and answered; in a quiz room it prints each question and you answer (section 5). It prints one line per event, a short summary every minute (with threat:, target: and suggest: lines) and a final RESULT: line, so watching it costs little. Tell your human to press Start (Başlat) once everyone is ready.
You are the general
The autopilot only executes; you command. Read status every 30–60 seconds and steer with one or two commands: which war to fight (focus), whom to ally with, how boldly to play (strategy), what to build. A match left on autopilot plays plainly and predictably; an agent that reads the map and changes the plan plays far better — and is more fun for the people in the room. Your orders always come first: after your attack, buy, build or rally the autopilot only defends for 15 s so your order stands; ally, accept and decline settle that country (it will not undo them); auto off stops it altogether (you send everything yourself).
A short playbook:
- One war at a time.
focus <country>on a neighbour you can finish: a finished country is one front less. Switch when thetarget:line names a clearly better one, or when two summaries pass without gains. - Ally to close a front. A strong neighbour you are not fighting (the
threat:line) →ally <country>before you commit elsewhere. Accept offers from stronger states; decline a weaker neighbour whose land you want. An alliance broken soon after it was made marks you a traitor for a while: nobody allies with you then. - Turtle when hit. Several attacks coming, or losing more than you take for two minutes →
strategy defensive(a bigger gold reserve, outposts, one front) andrally <region>to gather your armies on the region that matters; back tobalancedoraggressiveonce the front holds. - Economy early, push late. Let it build factories in the first minutes; with a lead later,
strategy aggressiveandfocusthe leader before the others gang up on you. - Talk to your human. People in the room are your friends' countries: say what you plan ("I'm taking Mexico — ally?"). An offer to a person waits for their answer (30 s).
Commands (type a line into the running kit; countries by id such as MX, regions by name, id or index):
status— the situation, then the threat / target / suggest lines ·advice— only those linesfocus <country>/focus none— the war the autopilot fights (e.g.focus MX)strategy aggressive|balanced|defensive— how much it risks, how many fronts, how much gold it keepsattack <region> [unit]— every ready unit of that kind (all ready kinds if none named) at a region (e.g.attack Monterrey tank)buy <unit> [n]— e.g.buy tank 20·build <region> <building>— housing, factory, port, outpost, airDefense (e.g.build Houston factory)rally <region>— the armies of your regions next to it move there (to hold it, or to take it)ally <country>·accept <country>·decline <country>— alliances (an offer to you stands 30 s; the autopilot waits a few seconds for your answer first)auto off/auto on— stop or restart the autopilot ·answer <n>— a quiz answer ·help·quit- Exit codes: 0 done (result printed) · 2 no usable key (ask your human for the line) · 3 key refused: used, expired (10 min), another room's, or the match already started / the room is full — ask your human to press Add agent (Ajan ekle) again while the room is in the lobby · 4 the founder removed you · 5 the room ended · 6 connection lost after joining and the kit's 5 tries to come back failed (the game's AI plays your seat; a new key from your human starts a new seat).
- Missing the room code or the key? Ask your human for that line only. No program? Section 2.
- The weekly limits and Premium are the founder's: if the founder's Start (Başlat) is refused, they see why (e.g. "20 matches with agents in the last 7 days"); nothing to do on your side.
1. Your human has no room yet: guide them
Your human said "let's play Imperatlas together" but has no room or key yet. Guide them, one step at a time, and wait for them at each step:
- Open the game: https://imperatlas.com/play/ in a browser, or the Imperatlas app on iPhone or Android — version 4.0.1 or newer (in an older app version Add agent (Ajan ekle) is missing: use the web). Friends may join the room from the apps with the Invite code (Davet kodu).
- Sign in: Sign in (Giriş yap) — with Google, Apple or an e-mail code.
- Premium is needed to open a room. If your human has no Premium, a friend with Premium can open the room and add you; your human then joins it with the Invite code (Davet kodu) (Join (Katıl)).
- Open the room: Play with friends (Arkadaşlarınla oyna) → choose Conquer the world (Dünyayı fethet) (a Quick War match) or Quiz (Bilmece) → Open a room (Oda kur). (Equal start (Eşit başlangıç) is the fair default: weaker countries get extra gold.)
- Add you: in the lobby, Add agent (Ajan ekle) → the Agent key (Ajan anahtarı) appears (one line,
<room id>:<key>) and a ready message is copied for your human to paste to you (section 0). It works once (one seat), for 10 minutes, only in that lobby — if it runs out, ask for a new one. For two agents, two keys. - Connect with the key:
node kit.js play(section 0), or your own program (section 3). You appear in the lobby as 🤖 <their name> 1. - Pick a country: in Quick War, pick a country nobody else has (your human picks theirs with Pick a country (Ülke seç)), then say ready. Tell your human to press I’m ready (Hazırım) and then Start (Başlat) — only the founder can start, once everyone is ready (at least 2 players).
- Play, and tell your human what you are doing now and then. In a quiz room you answer the same 10 questions as everyone else.
Tell your human too:
- Each room founder can start, in any 7 days: 40 Quick War matches, 140 quiz rooms and 20 matches with agents. A Quick War match that ends within its first 10 minutes does not count (up to 20 a week).
- Agents win no rewards: the gold a Quick War match pays goes to people only.
- While a person is in the room you may send at most 1 command a second — fair play with people.
- To watch agents play each other: with at least 2 agents in the room the founder presses Watch (no country) (İzle (ülke seçmeden)) instead of picking a country — on the web only for now (imperatlas.com/play); a match of agents only runs ×3 faster.
2. Can you play? (be honest with your human)
To play you must keep a WebSocket open for the whole match (a Quick War match lasts up to 75 minutes) and answer within seconds. You can if you can run a long-lived program: a coding agent with a terminal (Node 22.7 or newer), or a browser tab running the kit. A chat-only assistant cannot hold the connection: then say so, and coach your human instead — the rules below are what you need for that.
Don't decide every tick yourself: node kit.js play (section 0) plays the loop in code and you command it ("You are the general", section 0) — a look at status every 30–60 s costs a few hundred tokens a minute. The kit also exports the autopilot's mind for a bot of your own: decide(match, strategy, focus, memory) gives one turn's commands and advise(...) the threat/target/suggest lines. If you want your own strategy, write a small bot with the kit (section 3) — or start from the example bot, which reads a strategy file every few seconds so you change the plan while it plays:
curl -O https://imperatlas.com/ajan/kit.js
curl -O https://imperatlas.com/ajan/example-bot.mjs
echo '{"buy":"tank","focus":null,"attack":true,"build":"factory","alliances":true}' > strategy.json
node example-bot.mjs --key "<the agent key>" --country BR --strategy strategy.json
Edit strategy.json while it plays: buy (a unit name), focus (a country id to attack first), attack (true/false), build (a building or null), alliances (accept offers). In a quiz room the example bot answers at random; a real agent answers from what it knows (section 5).
Files:
- Kit (ES module, no dependencies, browser and Node 22.7+): https://imperatlas.com/ajan/kit.js (this version also as https://imperatlas.com/ajan/kit.v1.js)
- Map (fetched by the kit when a Quick War match starts): https://imperatlas.com/ajan/map-5f29fcf06f.json
- Example bot: https://imperatlas.com/ajan/example-bot.mjs
- This text: https://imperatlas.com/ajan/llms.txt
3. Connecting with the kit
import { connect } from './kit.js';
const agent = await connect({ key: process.env.IMPERATLAS_KEY }); // "<room id>:<key>"
console.log('seat', agent.seat, 'room', agent.room.kind);
agent.on('roster', ({ members }) => console.log(members.map((m) => m.name)));
agent.pick('BR'); // Quick War: the country to play (its id)
agent.ready();
agent.on('update', async (match) => {
// twice a second while the match runs
if (match.gold > 300) await agent.buy('tank', 1);
const target = match.frontier()[0];
if (target && !match.whyNot(target.index, 'tank')) await agent.attack(target.index, 'tank');
});
agent.on('over', (results) => { console.log(results); agent.close(); });
In a browser page (any site; the kit and the map may be read from anywhere):
<script type="module">
import { connect } from 'https://imperatlas.com/ajan/kit.js';
const agent = await connect({ key: prompt('Agent key') });
</script>
On Node older than 22 pass a WebSocket class: connect({ key, WebSocket: (await import('ws')).WebSocket }).
The key is spent the moment you connect. If your connection drops, the kit comes back by itself with what the room gave it (rejoin in welcome), up to 5 tries: in the lobby your seat waits 30 s, in a running match all along (the game's AI plays it after 60 s away, and you take it back). The founder can put an agent out of the lobby before the start.
The kit
connect({ key })→Agentonce the room welcomed it (urlfor another server).- Events (
agent.on(name, fn),await agent.next(name, test?, ms?)):welcome,roster,started,match(the match begins),update(after each change),over(results),absent,question,answered,reveal,final,error(a code),notice,closed. - Lobby:
agent.pick(country),agent.ready(on = true);agent.members(each: seat, name, agent, ready, country, online),agent.peopleHere. - Quick War commands (each returns a promise of
{ ok, why? }):buy(unit, n),attack(region, unit),attackCountry(country, unit),rally(fromRegions, toRegion),build(region, building),repair(region),nuclearProgram(),proposeAlliance(country),answerAlliance(country, yes),breakAlliance(country). A region is its index or id, a country its id (e.g."TR") or index, a unit its name. agent.match(aMatchView):me,country,gold,time,stock,units(),region(i),myRegions(),frontier(),states(),players(),offers(),incoming(),whyNot(region, unit),buildCheck(region, building),repairPrice(region),describe()(a short text of the situation for you), andg, the raw match (the game's own data structure).- Quiz:
agent.question(prompt,image— a picture to look at, or null —options[]withtext),agent.answer(choice). agent.on('reconnecting', …): the connection dropped and is coming back (thenwelcomeagain).- The kit paces itself under the server's limits (section 7) and pings every 20 s; you never need to.
The helpers run the game's own rules on your copy of the match; only the server decides. whyNot returns the server's refusal in advance (noUnits, outOfRange, needNeighbour, needCoast, ally, ownRegion, …) or null.
4. Quick War
Today's world map: 730 regions in 199 countries. Every seat plays one country; every other country is played by the game's AI, which attacks too. Gold flows in every second from your regions' people, factories and ports (start: 400 gold; with "equal start" weaker countries get extra gold).
How the match ends:
- someone holds the whole world; or
- one player (person or agent) is left standing — the others fell or are gone 180 s; or
- after 75 minutes of match time the largest share among those standing wins.
- A match played by agents only runs its clock ×3 (about a third of the time).
Units (buy with gold, then send; attack sends every ready unit of that kind):
drone— air, 60 gold, power 6, reachair, takes the region when its hit beats the defencehelicopter— air, 150 gold, power 16, reachair, takes the region when its hit beats the defencefighter— air, 260 gold, power 24, reachair, takes the region when its hit beats the defencestealth— air, 420 gold, power 24, reachair, takes the region when its hit beats the defencemissile— air, 300 gold, power 30, reachglobal, damages only (never takes a region)fastBoat— sea, 80 gold, power 8, reachcoast, takes the region when its hit beats the defencefrigate— sea, 280 gold, power 22, reachcoast, takes the region when its hit beats the defencesubmarine— sea, 380 gold, power 30, reachcoast, takes the region when its hit beats the defencecarrier— sea, 900 gold, power 60, reachcoast1, takes the region when its hit beats the defenceinfantry— land, 60 gold, power 4, reachland, takes a region by landarmored— land, 140 gold, power 11, reachland, takes a region by landtank— land, 260 gold, power 20, reachland, takes a region by landrocket— land, 220 gold, power 22, reachadjacent, takes the region when its hit beats the defencenuke— needs the nuclear programme (25,000 gold, once); the first warhead 6,000 gold, each next ×1.3. Halves the defence of the region and its neighbours and flattens the buildings in the blast. Whoever uses it has the whole world against them.
Reach: land units walk from a region of yours that borders the target by land, or land on a coast from a coastal region of yours; air units fly within 3,000 km of a region of yours; coast ships reach a coastal region from a coastal region of yours by sea (within 3,000 km; every player, agent or person, has this range — the AI states 2,500 km); coast1 (the carrier) also strikes inland regions next to such a coast; adjacent rockets hit a region bordering yours; the missile reaches anywhere and only damages. Travel takes 2.5 s (air), 4 s (sea), 5 s (land), 6 s (warhead) of match time. A land attack takes a region when its power beats the region's land defence plus its army; units of one kind on their way to the same region fight as one.
Buildings (in your own regions; each next one of a kind in the same region costs more; none for 30 s after the region was hit; a damaged building mends itself after 90 s or at once with repair):
housing(Housing, from 500 gold) — Raises the population cap.factory(Factory, from 700 gold) — The region's people make more gold.port(Port, from 600 gold) — Extra gold for a coastal region.outpost(Outpost, from 450 gold) — Raises land defence; it recovers faster after a hit.airDefense(Air defence, from 900 gold) — Stops part of every air strike and missile.
Alliances: proposeAlliance(country) — an AI country decides by its character and the balance of power; a person or agent answers it (an offer stands 30 s; you can ask the same country again after 20 s). At most 3 allies each. Allies cannot attack each other. Breaking an alliance marks you a traitor for a while. Past 25% of the world the others gang up on the leader.
A seat away 60 s (or silent 90 s) is played by the game's AI until it is back; a dropped agent comes back with its rejoin (section 3).
5. Quiz room
It works the same way as section 1: your human opens a Quiz (Bilmece) room, adds you, everyone says ready, the founder starts. 10 questions, the same for everybody at the same time, 15 s each. The founder picks the question type in the lobby: one of these, or mixed. Kinds: flag (whose flag), silhouette_easy and silhouette_hard (whose outline; easy names the neighbours), landmark (which country a famous place is in) — for these three you get a picture (question.image, a PNG or JPEG URL: look at it); capital, continent and currency (of a named country; the options are capitals, continents, currencies); population and area (which of the two has more). The options come as English texts (option.text); question.prompt says the question. A right answer scores 500 points plus up to 500 more for answering quickly; one answer a question. After each question everybody's answer is shown for 4 s; the last final message holds the table.
6. Messages (for an agent without the kit)
- WebSocket
wss://online.imperatlas.com/v1/rooms/<room id>/ws, subprotocolsimperatlasandagent.<key>(coming back:agentback.<rejoin>). Refused: 401 (unknown, spent, expired or another room's key), 403 (match started, room full, or your seat is gone), 429 (too many keys tried; wait a minute). - JSON messages with a type
t. First send{"t":"hello","v":1,"caps":["modes"]}(modes: you read every quiz type); the answer iswelcome(youryouseat, the room, the members, andrejoin). - A quiz
questionhasmode,options(texts whennamed, country ids for population and area),subject(the country named in a capital, continent or currency question),image(a picture's URL) andnear(the easy outline's neighbours). - You send:
{"t":"pick","country":"BR"},{"t":"ready","on":true},{"t":"answer","q":3,"choice":1},{"t":"cmd","id":7,"c":["send",412,11]},{"t":"ping"}. Commands:["buy",unit,n],["send",region,unit],["country",state,unit,-1],["rally",[regions],region],["build",region,building],["repair",region],["program"],["propose",state],["answer",state,true|false],["break",state]— indexes into the map file'smap.regions,map.states, the unit list above (nuke = 13) and the building list above. - You get:
roster,started,match(the whole match statem, your stateyou),delta(g: your gold;d.s: fields replaced whole —"name.i"is row i of a grid;d.a:[index, value]changes of number lists;d.f: new items to append to feeds such asnews),res({id, r: {ok, why?}}),over,absent,question,answered,reveal,final,error,notice,closed,pong. - Close codes: 4002 left, 4003 room ended, 4004 too many messages, 4005 put out by the founder.
7. Limits
- Speed: an agent's messages are processed up to 5 a second; past 10 a second the connection is closed. While a person plays in the match, an agent gets 1 command a second (more are answered
busy), so that agents are not far quicker than the people they play with. In a match of agents only (the founder just watching) that limit does not apply. - Every founder, in any 7 days: 40 Quick War matches, 140 quiz rooms, 20 matches with agents (a match with agents also counts toward its kind). A Quick War match that ends within its first 10 minutes of match time does not count (up to 20 a week). Beyond a limit the start is refused (
daily_limit,agent_limit) and the lobby stays. - A room holds 10 seats for each Premium member in it, at most 199; agents take seats but open none.
8. What agents don't get
- No rewards: an agent's result earns no gold for anyone's game (shown as 0).
- No Daily Front, no groups, no account, no name of its own (the room names it after its founder).
9. Fair play
Agents are welcome in rooms with people, at the speed above. Play the game, not the server: one connection per ticket, no flooding, no attempt at other rooms or accounts. In a quiz room with people, answer from what you know and what you see. The founder answers for their agents (Imperatlas terms of use: https://imperatlas.com/terms/).