A Python and Pygame implementation of the classic NES game Battle City, featuring all 35 stages, four enemy tank types, power-ups, two-player co-op, a computer-controlled partner, sound effects, gamepad support, and more.
Download the latest build from the Releases page. Each release also has a SHA256SUMS file to check your download against.
- Download
BattleCitySetup-<version>.exe. - Run it. It installs for your user only, so it doesn't need administrator rights.
- The installer isn't code-signed, so Windows SmartScreen may warn you. Choose More info, then Run anyway.
- Start Battle City from the Start menu.
To check the download in PowerShell, compare the hash with the one in SHA256SUMS:
Get-FileHash .\BattleCitySetup-<version>.exe -Algorithm SHA256The game ships as a Flatpak bundle. It needs Flatpak and the Flathub remote, which provides the runtime it's built on:
flatpak remote-add --user --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
flatpak install --user BattleCity-v<version>.flatpak
flatpak run com.battlecity.BattleCityThe game also appears in your desktop's application menu. To remove it, run flatpak uninstall --user com.battlecity.BattleCity.
There's no packaged macOS build yet, so run the game from source. uv downloads the right Python version for you:
curl -LsSf https://astral.sh/uv/install.sh | sh
git clone https://github.com/StefanBS/battle-city-clone.git
cd battle-city-clone
uv sync
uv run python main.pyThe same steps work on Linux. On Windows, install uv with powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" and then run the same git clone, uv sync and uv run commands.
- 35 stages authored in Tiled with varied enemy compositions
- 4 enemy tank types — basic, fast, power, and armor — each with unique sprites and stats
- 6 power-ups — helmet, star, grenade, clock, shovel, extra life
- Game modes: 1 Player, 2 Players (co-op), and 1 Player + CPU, where a CPU Partner drives P2 by the same rules as a human
- Gamepad/controller support — D-pad, analog sticks, hot-plug detection (SDL GameController API)
- Sound effects — shooting, explosions, power-ups, engine sounds, and more
- Difficulty levels — Easy (random Enemy AI) and Normal (directional bias, aligned shooting, type-specific tactics)
- Options menu — difficulty selection and master volume with persistent settings
- Stage transitions — curtain animations between stages
- Explosion animations — small and large explosions, spawn effects
- Shield animation — flicker effect on spawn invincibility
- Tile types — brick (destructible, with variants), steel, water, bush (overlay), ice (sliding physics), base
| Action | Key |
|---|---|
| Move | Arrow keys |
| Shoot | Space |
| Pause / back | Esc |
| Menu navigate | Arrow keys |
| Menu confirm | Enter / R |
| Action | Button |
|---|---|
| Move | D-pad / Left analog stick |
| Shoot | A / B |
| Pause / back | Start |
| Menu navigate | D-pad / Left analog stick |
| Menu confirm | A |
| Menu back | B |
| Mode | P1 | P2 |
|---|---|---|
| 1 Player | Keyboard or any controller | — |
| 1 Player + CPU | Keyboard or any controller | CPU Partner |
| 2 Players | Keyboard (first controller if two are connected) | First controller (second if two are connected) |
With no controller connected, both Players in 2 Players mode share the keyboard's keys.
- CONTEXT.md: the domain language used in code, tests and docs
- docs/cpu-partner.md: how the CPU Partner picks and pursues its Goals
- docs/adr/: architecture decisions
- 0001 CPU Partner is a PlayerInput, not a tank subclass
- 0002 Every tank goes through one stepping path
- 0003 Collision response returns outcomes
- 0004 A Battle owns one Stage
- 0005 Dodge is a reflex, not a Goal
- 0006 Spawning and the Enemies on the battlefield stay separate
- 0007 The Screen Flow never holds a Battle
- 0008 Four layered packages, with the World View between the Battle and the CPU Partner
Requires uv, which downloads Python 3.13+ for you.
uv sync --extra dev
uv run python main.pyuv run pytest
uv run pytest --cov=srcuv run ruff check src/ tests/
uv run ruff format src/ tests/
uv run mypy src
uv run lint-importsThe pre-commit hooks and CI run all four. lint-imports checks the package layers in pyproject.toml: shell → battle and cpu_partner → world_view → core (see ADR 0008).
To build a standalone executable:
uv sync --extra dev --extra build
uv run pyinstaller battle-city.specRelease builds are made by CI when a v* tag is pushed: a Windows installer (PyInstaller + Inno Setup, installer/windows/) and a Linux Flatpak (installer/linux/).

