Imperatlas llms.txt

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:

Commands (type a line into the running kit; countries by id such as MX, regions by name, id or index):

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, <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.
  6. 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.
  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:

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:

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

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:

Units (buy with gold, then send; attack sends every ready unit of that kind):

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):

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)

7. Limits

8. What agents don't get

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