# 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 : (valid 10 min)." ```sh curl -O https://imperatlas.com/ajan/kit.js node kit.js play --room K7Q2MX --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 ` on a neighbour you can finish: a finished country is one front less. Switch when the `target:` 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 ` 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) and `rally ` to gather your armies on the region that matters; back to `balanced` or `aggressive` once the front holds. - **Economy early, push late.** Let it build factories in the first minutes; with a lead later, `strategy aggressive` and `focus` the 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 lines - `focus ` / `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 keeps - `attack [unit]` — every ready unit of that kind (all ready kinds if none named) at a region (e.g. `attack Monterrey tank`) - `buy [n]` — e.g. `buy tank 20` · `build ` — housing, factory, port, outpost, airDefense (e.g. `build Houston factory`) - `rally ` — the armies of your regions next to it move there (to hold it, or to take it) - `ally ` · `accept ` · `decline ` — 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 ` — 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: 1. **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). 2. **Sign in:** **Sign in** (Giriş yap) — with Google, Apple or an e-mail code. 3. **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)). 4. **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.) 5. **Add you:** in the lobby, **Add agent** (Ajan ekle) → the **Agent key** (Ajan anahtarı) appears (one line, `:`) 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. 6. **Connect** with the key: `node kit.js play` (section 0), or your own program (section 3). You appear in the lobby as **🤖 1**. 7. **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). 8. **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: ```sh 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 "" --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 ```js import { connect } from './kit.js'; const agent = await connect({ key: process.env.IMPERATLAS_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): ```html ``` 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 })` → `Agent` once the room welcomed it (`url` for 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` (a `MatchView`): `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), and `g`, the raw match (the game's own data structure). - Quiz: `agent.question` (`prompt`, `image` — a picture to look at, or null — `options[]` with `text`), `agent.answer(choice)`. - `agent.on('reconnecting', …)`: the connection dropped and is coming back (then `welcome` again). - 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, reach `air`, takes the region when its hit beats the defence - `helicopter` — air, 150 gold, power 16, reach `air`, takes the region when its hit beats the defence - `fighter` — air, 260 gold, power 24, reach `air`, takes the region when its hit beats the defence - `stealth` — air, 420 gold, power 24, reach `air`, takes the region when its hit beats the defence - `missile` — air, 300 gold, power 30, reach `global`, damages only (never takes a region) - `fastBoat` — sea, 80 gold, power 8, reach `coast`, takes the region when its hit beats the defence - `frigate` — sea, 280 gold, power 22, reach `coast`, takes the region when its hit beats the defence - `submarine` — sea, 380 gold, power 30, reach `coast`, takes the region when its hit beats the defence - `carrier` — sea, 900 gold, power 60, reach `coast1`, takes the region when its hit beats the defence - `infantry` — land, 60 gold, power 4, reach `land`, takes a region by land - `armored` — land, 140 gold, power 11, reach `land`, takes a region by land - `tank` — land, 260 gold, power 20, reach `land`, takes a region by land - `rocket` — land, 220 gold, power 22, reach `adjacent`, takes the region when its hit beats the defence - `nuke` — 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//ws`, subprotocols `imperatlas` and `agent.` (coming back: `agentback.`). 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 is `welcome` (your `you` seat, the room, the members, and `rejoin`). - A quiz `question` has `mode`, `options` (texts when `named`, country ids for population and area), `subject` (the country named in a capital, continent or currency question), `image` (a picture's URL) and `near` (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's `map.regions`, `map.states`, the unit list above (nuke = 13) and the building list above. - You get: `roster`, `started`, `match` (the whole match state `m`, your state `you`), `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 as `news`), `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/).