A tiny real-time strategy game that runs in your terminal. Pure ASCII, no save games, no dependencies — you run it, pick Play, and you are up against the computer with a square-wave march looping in the background and a bank of one-shot effects over the top of it: steel when your soldiers connect, a fanfare out of the barracks door, masonry when something comes down.
git clone https://github.com/gogl92/AoE-CLI
cd AoE-CLI
./play.pyThere is nothing to install — but if you would rather have it on your PATH,
pip install . gives you an aoe-cli command that does the same thing.
Python 3.8+ and a terminal at least 40x10 — the map is much bigger than
any terminal and the view scrolls, so a bigger window just shows more of it,
and you can resize mid-match. No dependencies at all: the graphics are
curses from the standard library and the music is synthesised at runtime
into a WAV.
Team identity is letter case: your stuff is lowercase, the computer's is
UPPERCASE. Colour is layered on top of that — sage grass, forest green
trees, deep blue water, cyan for you and red for the computer, using the
terminal's 256-colour palette where there is one — but the game is entirely
playable without it (--no-color, or NO_COLOR=1).
There is a second drawing set if you want one. --theme medieval, the
Theme row in Options, or t mid-match swaps the letters for chess pieces
and the terrain for symbols: your king ♔ in a light keep against the
computer's ♚ in a double-walled one, pawns for villagers, knights for
archers, ♣ woods and ≈ water.
⋅♣⋅⋅⋅│ ♔ │♙✿✿⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅♣⋈≈≈⋅⋅⋅⋅⋅⋅⋅⋅≈≈⋈⋅
⋅≈≈⋅⋅└───┘♙✿≈≈⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅≈♣⋅≈⋅⋅✿✿⋅♣⋅⋅⋈≈≈⋅
Chess is doing real work there, not decoration: white against black is how
the theme tells the two sides apart without leaning on colour, the same job
letter case does in ASCII. Every glyph in both themes is one terminal cell
wide, which is what keeps the map a grid — and which is why there is no
emoji theme, however good 🏰 looks in isolation. Emoji are two cells each,
so a row of them is twice as wide as the tiles underneath it and the whole
picture shears.
| ascii | medieval | what it is | ascii | medieval | what it is | |
|---|---|---|---|---|---|---|
v V |
♙ ♟ |
villager | . |
⋅ |
grass — walkable | |
s S |
♗ ♝ |
militia | T |
♣ |
trees — wood | |
a A |
♘ ♞ |
archer | $ |
♦ |
gold mine | |
x X |
⚐ ⚑ |
scout | % |
✿ |
berries — food | |
o O |
⬦ ⬥ |
fishing boat | = |
≡ |
farm — food | |
c C |
♔ ♚ |
town centre | * |
⋈ |
fish — food, boats only | |
h H |
☖ ☗ |
house | ~ |
≈ |
open water — boats only | |
b B |
♖ ♜ |
barracks | ||||
d D |
⟡ ⟠ |
dock | ||||
f F |
▫ ▪ |
farm being built |
Units are single letters. Buildings are blocks — a box with the letter in the middle, filling every tile it stands on:
+---+ +-+
| c | a town |h| a house, three by three
+---+ centre +-+
Point at any part of one to select or attack it, and nothing walks through it.
The blinking terminal cursor is your map pointer. Selected units show up in reverse video, and buildings still under construction are dimmed. The HUD shows the cursor's position on the map, since you are only ever looking at a slice of it.
You only see what your units and buildings can see. Ground you have walked
stays on the map but greys out, enemy buildings you have found are drawn from
memory until you go back and look, and anywhere you have never been is blank.
Your scout is how you fix that. (--no-fog, or the options screen, turns it
off if you would rather see everything.)
The sound effects honour the fog too: you only hear your own side. The computer trains units and loses buildings all match on ground you may never have scouted, and playing that through the speakers would hand you exactly what the fog is there to withhold.
Press ? in game for this list at any time.
| key | action |
|---|---|
arrows / hjkl |
move the cursor — the view scrolls when you reach the edge |
HJKL |
throw the cursor 10 tiles across, 5 up and down |
0 |
jump back to your own town centre |
space |
select whatever of yours is under the cursor |
enter |
order the selection at the cursor — move, gather or attack, whichever fits |
A |
attack-move: march there, stopping to fight anything on the way |
tab |
jump to the next idle villager |
a / v |
select all soldiers / all villagers |
s |
select everything of yours within five tiles of the cursor |
G then 1–9 |
put the selection in a control group |
g then 1–9 |
recall that control group |
esc |
clear the selection |
1 2 3 |
train village 807A r / militia / archer |
7 8 |
train scout (town centre) / fishing boat (dock) |
4 5 6 |
build house / barracks / farm at the cursor |
9 |
build a dock — only on grass touching open water |
r |
rally point for the selected building (rally onto berries and new villagers start gathering) |
+ / - |
game speed, 0.5x to 3x |
t |
switch the drawing theme (ASCII ⇄ medieval) |
? m n p q |
help, music, sound effects, pause, quit to the menu |
Destroy the enemy town centre (C) before it destroys yours.
Villagers gather from the tile you send them to and carry it back to the town centre on their own, so you only need to give the order once. Berries run out, which is what farms are for. Houses raise the population cap; without them you get stuck at 5. Soldiers come from a barracks and will pick fights on their own if an enemy wanders within about 6 tiles.
You start with three villagers and a scout (x) — the fastest thing you
own and hopeless in a fight. Send it out immediately; under fog you cannot
plan around a map you have not looked at, and finding the enemy base early is
most of knowing when to attack.
A dock (9) goes on grass touching open water and builds fishing boats (8),
which work the fish (*) and carry the catch back to the dock rather than to
your town centre. It is food nobody can walk over and take from you, and it is
usually the difference once the berries are gone.
A reasonable opening: v then enter on the berries to get everyone gathering,
select the scout and send it exploring, 1 a few times for more villagers, 4
for a house before you hit the cap, 5 for a barracks once you have ~150 wood,
then 2/3 on repeat.
Matches usually last three to six minutes. The computer opens the same way you should — gather, house, farm, barracks — and pushes once it has an army. It plays through exactly the same order API you do, so it cannot cheat; the difficulty setting changes how well it plays, not what it is allowed to do.
New to it? Pick Tutorial on the title screen. It is an ordinary match with a ten-step checklist along the bottom, and nothing blocks you if you wander off it.
Everything on the title screen has a flag, for when you would rather not click through:
./play.py --difficulty hard # easy, normal or hard
./play.py --seed 42 # same seed, same map
./play.py --theme medieval # chess pieces instead of letters
./play.py --no-music # start with the march off
./play.py --no-sfx # start with the effects off
./play.py --no-color # monochrome; NO_COLOR=1 does the same
./play.py --no-fog # see the whole map
./play.py --skip-menu # straight into a match, as older builds did
./play.py --no-save # do not remember any of it
./play.py --db /tmp/aoe.db # keep settings and history somewhere elseYour settings stick between runs, and so does your win/loss record, which the
title screen shows once you have finished a match. They live in one SQLite
file — ~/.local/share/aoe-cli/aoe.db, or wherever $AOE_DB or
$XDG_DATA_HOME point. A flag always beats what was saved, so
./play.py --difficulty easy is a one-off rather than a new preference.
If that file cannot be written — a read-only home, say — the game shrugs and plays anyway; it just forgets everything when you quit. Delete the file to start over.
python3 -m unittest discover -s tests # 168 tests, ~30 seconds
python3 -m aoe.headless 900 3 hard # 15 min of AI vs AI, no terminal
./play.py --seed 42 --no-music # reproducible map, silence--seed fixes the map, which is generated with 180° rotational symmetry so
neither side gets the better start, and is checked to leave the two bases
connected by land. The simulation knows nothing about curses, which is what
makes aoe.headless — and most of the test suite — possible.
The computer opponent plays through the same order API you do and, under fog, sees only what its own units see: it keeps its own map of what it has walked past, sends its scout out, and marches on the last place it saw you. There is no difficulty setting that hands it resources or vision.
CONTRIBUTING.md has the rest — how to check a balance change resolves, and
the handful of structural rules (no dependencies, no curses below the render
layer, no cheating AI) that keep the project the shape it is in. Bug reports
and pull requests are welcome.
MIT — see LICENSE.