A programming challenge with a patient on the table

They're too small to pilot.
So you write their mind.

A treatment is failing somewhere past the skin. The medicine has to be carried, molecule by molecule, to receptor sites buried deep in living tissue — by a swarm smaller than a red blood cell, in a window shorter than a held breath. You can't drive them. You write the code they carry in, and then you let go.

The immune system doesn't know you're helping. The bloodstream only runs one way. And another team's protocol is in the same body, racing you for the same sites — because only one of them gets used on a real patient.

🧬 Read the briefing Start the tutorial View on GitHub
Nanobots navigating living tissue
The mission

Every rule is something the body is actually doing

Nothing here is an arbitrary game mechanic. Each one is the patient — or your rival — behaving exactly as they should.

💊

Carry the dose

AZN breaks down before it reaches deep tissue, so it has to be hauled molecule by molecule to receptor sites and held there by an implant. An empty needle barely treats anything — a fed one does the real work.

🛡️

The body fights you

White blood cells can't tell a nanobot from a bacterium. It isn't malice — it's the patient's own defences working correctly, with your swarm in the way. Route around them, wall them out, or burn them down; they don't come back.

🩸

One-way rivers

Bloodstreams are the fastest roads in the body and they run in exactly one direction. Riding one crosses the map in a fraction of the time — and you can't turn around on it.

👁️

You can barely see

Your bots sense only what's near them. The rival swarm is out there somewhere and you won't know where until something of yours stops reporting — unless you spend the mass on an Explorer and buy eyes.

⏱️

1500 turns, 50 milliseconds

That's the treatment window before the compound denatures. And your code gets 50 ms to decide each turn — how long the swarm can wait for orders before the moment has passed. Take longer and the turn is simply gone.

🏁

Only one protocol gets used

Two candidate swarms run in the same simulated body, on the same failing tissue, against the same clock. Whoever holds more of the patient stable when the window closes is the one that goes to a real patient.

🧬

Read the full briefing

The patient, the immune system, the window — and the part nobody tells you at the start: underneath the tissue, this is one of the most useful problems in computer science. Autonomous agents doing the right thing when you aren't there to tell them.

Open the briefing →
Platform features

Everything you need to compete

Built in Python + pygame — one script sets up a virtualenv and launches the app.

🗺️

Visual map editor

Paint terrain, place streams, habitats, AZN nodes, and zones. Save/load maps as JSON. Full undo support.

🧬

A body that fights back

Tissue density, bloodstream currents, bone barriers — and patrolling white cells that attack both sides. Route around the immune system, wall it off, or gun it down.

🤖

8 programmable bot types

Scouts that see through the fog of war, walls that block shots, collectors that double as artillery — every stat matters, from a 150 AZN starting budget.

▶️

Full replay viewer

Scrub 1 500 turns with a jump-to-turn slider, watch attack tracers and event effects, follow the match story in the events feed, and rerun any seed exactly.

⚡

Headless runner

Run matches at hundreds of turns per second from the command line. Iterate fast without opening the app.

🏆

Tournament bracket

Hand-pick your field of competitors (multi-select supported) and run a round-robin tournament with live standings.

🎯

Simple one-file API

Your entire strategy lives in a single Python file. Two methods to override, a clean read-only map snapshot each turn.

Fleet

8 bot types, one starting budget

You begin every match with one NanoAI and 150 AZN in the bank. Everything else you build.

NanoAI

NanoAI

Free — spawns at start
Command unit. The only bot that can build others.
NanoCollector

NanoCollector

20 AZN
Collects & delivers AZN. Has a light attack (range 12).
NanoContainer

NanoContainer

25 AZN
High-capacity storage for long supply chains.
NanoNeedle

NanoNeedle

40 AZN
Stationary implant. Claims a Habitas Point and scores.
NanoExplorer

NanoExplorer

15 AZN
Ignores density — same speed everywhere. Great scout.
NanoIPCreator

NanoIPCreator

30 AZN
Creates a new injection point mid-map. Auto-destructs in 500 turns.
NanoBlocker

NanoBlocker

20 AZN
Adds +6 turns to every enemy step through its cell.
NanoWall

NanoWall

25 AZN
Fully blocks enemy movement. Auto-destructs in 50 turns.
Technology

Built with Python + pygame

nano-bot runs on Python 3.10+ with pygame for the map editor and replay viewer. The simulation engine itself has no pygame dependency at all — it runs identically headless, in the GUI, or inside a unit test. Your strategy is also plain Python, so there's no second language or engine to learn.

⬇️

Install Python 3.10+

Most systems already have it. Check with python3 --version.

Download Python →
📚

Know basic Python?

That's all you need — the strategy API is two methods on a plain class.

API reference →
🎮

Run the app

Clone the project and run ./run.sh — it creates a virtualenv and installs dependencies on first run automatically.

See setup →

Why Python?

This started as a Godot/GDScript project. The simulation rules, scoring, and JSON formats are unchanged — but GDScript's per-file class-name resolution and silently-ignored duplicate function definitions kept causing friction during development. Plain Python has neither problem, no engine to install, and is a language most participants already know.

Getting started

Competing in 3 steps

1

Clone the repository and run it

run.sh creates a virtualenv and installs dependencies the first time you run it.

git clone https://github.com/Habitas-Games/nano-bot-python.git
cd nano-bot-python
./run.sh

📖 README — full setup & CLI tools

2

Create your strategy file

Copy the starter and override two methods. That's your entire interface with the simulation.

cp strategies/example_strategy.py strategies/my_strategy.py
from nanobot.api.nano_strategy import NanoStrategy

class MyStrategy(NanoStrategy):
    def choose_injection_point(self, map_info):
        return (0, 0)   # pick a cell in your zone

    def what_to_do_next(self, map_info, my_bots):
        pass   # command your bots here
3

Run a match and watch the replay

Hit Run Match in the main menu. The match window opens with a first match already simulated — pick your map and both strategies right there and press Restart to re-simulate in place. Each full 1 500-turn match computes in seconds.

🌱

Never programmed before? Start here.

Learn to code from zero — variables, decisions, loops, functions — with every concept introduced because your swarm needs it. Eight lessons, ending in a real working strategy that wins on every map.

Learn to program →
🎓

Tutorial — build a competitive strategy in 4 stages

Runnable code at every step, from "plants one needle" to a strategy that beats an aggressor — with the measured result each time (Stage 1 → 2 is a 43× scoring jump; Stage 3 goes from 0/24 to 20/24 against example_combat).

Start the tutorial →
📖

Full participant guide

Complete API reference, scoring formulas, map mechanics, bot stats, strategy tips, and a line-by-line walkthrough of the example strategy.

Open the guide →
🤖

Writing your strategy with an AI assistant?

Paste docs/STRATEGY_API.md into the chat — the entire API in one plain-text page with a verified working example, written so an assistant can't invent a different one. Paste the contents, not a link.

Open the API spec →
Open source

Contribute

nano-bot is on GitHub at Habitas-Games/nano-bot-python — contributions of all kinds are welcome.

🐛

Report a bug

Found something broken in the simulation or viewer? Open an issue.

→ Issue tracker
💡

Suggest a feature

New bot type, map mechanic, or viewer improvement? Ideas are welcome.

→ Open an issue
🔀

Submit a pull request

Fork the repo, make your changes, and open a PR. Small focused changes merge fastest.

→ Pull requests
📝

Write a strategy

Share your strategy as an example. A diverse library of approaches helps participants learn faster.

→ Browse strategies/
Support the project

Keep nano-bot alive

nano-bot is built and maintained as a side project — no company, no VC, no team. If it's been useful to you, any contribution helps cover the time it takes to keep it going.

💖

GitHub Sponsors

Monthly or one-time. Processed securely through GitHub.

Sponsor on GitHub
💳

PayPal

One-time contribution via PayPal. Any amount is appreciated.

Send via PayPal
🏦

De Una

Banco Pichincha (Ecuador). Scan the QR with your banking app.

Not in a position to donate? These help just as much.

Most of what keeps a project like this alive isn't money — it's people using it and saying so.

All contributions go directly toward development time. Thank you 🙏