Ants Game Engine for CodeClash

This repository contains the game engine and starter bot for the Ants arena in CodeClash, in the spirit of the 2010 Google/Waterloo Ants AI Challenge.

Overview

Each player commands a swarm of ants on a toroidal (wrap-around) grid. Every turn all ants move one cell at once. Key mechanics:

• Fog of war — you only see the map within your ants' view radius; you must remember what you've discovered.
• Combat (focus fire) — an ant dies unless it has strictly fewer enemies within attack range than every enemy attacking it. Locally outnumbered ants die, so ganging up wins fights.
• Food → growth — food within spawn radius of exactly one player's ants is gathered and spawns a new ant on one of that player's hills.
• Hills & razing — you spawn from your hills; move an ant onto an enemy hill to raze it. Razing enemy hills is the main objective.

Winning: most enemy hills razed, tiebroken by ants alive (then food gathered), or be the last player with ants standing.

Repository Structure

Ants/
├── engine.py    # Game engine — runs games between bots (do not edit for the contest)
├── main.py      # Starter bot implementation (EDIT THIS)
└── README.md

Quick Start

1. Edit main.py to implement your bot logic.
2. Test locally: python engine.py main.py main.py -r 5 -o /tmp/ants_out
3. Submit main.py to CodeClash.

Bot Interface

do_turn(obs: dict) -> list

Return a list of moves, each [row, col, dir] where dir is "N", "S", "E", or "W": the ant currently at (row, col) steps one cell that way (N = row−1). Rules:

• Ants you don't give a move to stay put.
• Moving into water is ignored (you stay).
• Two ants ending on the same cell both die — don't order two of your own ants into one square. (do_turn runs in one long-lived process, so you can keep state — a map, plans — in module globals across turns.)

The observation (fog-limited)

obs = {
    "turn": 42, "max_turns": 500,
    "rows": 32, "cols": 32,          # grid is toroidal: (row % rows, col % cols)
    "viewradius2": 77,               # squared radii (use for planning / combat)
    "attackradius2": 5,
    "spawnradius2": 1,
    "you": 0,                        # your player id
    "my_ants":  [[r, c], ...],       # your ants (you always see these)
    "my_hills": [[r, c], ...],       # your living hills
    "enemy_ants":  [[r, c, owner], ...],   # only where your ants can see
    "enemy_hills": [[r, c, owner], ...],   # only where your ants can see
    "food":  [[r, c], ...],          # only where your ants can see
    "water": [[r, c], ...],          # only where your ants can see (remember it!)
}

Distances are toroidal: dr = min(|r1−r2|, rows−|r1−r2|), likewise dc, and the squared distance is dr*dr + dc*dc. Compare against the *radius2 constants directly.

Turn resolution (in order)

1. Moves applied (water/off-nothing blocks → stay; the grid wraps so nothing is "off").
2. Collisions: any cell 2+ ants land on — all of them die.
3. Combat: focus-fire deaths (see above), computed from post-move positions.
4. Razing: an ant on an enemy hill razes it (scores for the razer).
5. Food: food within spawnradius2 of exactly one player is gathered → a new ant spawns on a free hill of that player.
6. New food is seeded (symmetrically) to top the board up.

Running Games Locally

python engine.py path/to/bot1.py path/to/bot2.py -r 5 -o /tmp/ants_out
python engine.py bot1.py bot2.py -r 1 -s 123      # fixed seed

Options: -r rounds, -o replay output dir, -s base seed (game g uses seed+g).

The engine prints a FINAL_RESULTS block the tournament parses:

FINAL_RESULTS
Bot_1: 6 games won (player1)
Bot_2: 4 games won (player2)
Draws: 0

Maps, water, and food are seeded (so sims differ) but otherwise the game is fully deterministic given the bots. Maps use half-shift symmetry, so 2-player games are fair.

Strategy Tips

• Grow first: shepherd ants to food to out-produce your opponent.
• Fight with the focus-fire rule in mind — only engage when you'll outnumber the enemy at the point of contact; back off when you're the one outnumbered.
• Explore the fog to locate enemy hills, then mass ants to raze them.
• Don't park ants on your own hills — that blocks new spawns.

Credits & reference

This arena is a clean-room reimplementation of the 2010 Google/Waterloo Ants AI Challenge, adapted for CodeClash. The canonical rules and original source are here:

https://github.com/aichallenge/aichallenge — see the ants/ game.

The core mechanics (fog of war, the focus-fire combat rule, food-spawns-an-ant, hill razing, and the squared view/attack/spawn radii) follow that original. What differs, for a fair automated benchmark: turns are a deterministic tick-synced simulation (the original ran in real time over TCP, where latency mattered), maps/water/food are symmetric and seeded, and food top-ups are simplified. Consult the reference above for the authoritative spec.

License

MIT License — see the CodeClash repository for details.