🐜 AntWars Player Guide

Program your colony • No GPS • Queen is cell 0

Contents

1. Code Sections 2. Action Commands 3. Radar — What Your Ants See 4. Queen API 5. Navigation — No GPS 6. Command Hierarchy 7. The Queen Is Not Psychic 8. Base Structures 9. Egg Logistics 10. Pheromones 11. Food & Hunting 12. Death Reporting 13. Threat Identification 14. Starting Ants & Costs 15. Rules

1. Code Sections

Your colony is programmed in six sections in the Portal's Play tab.

SectionFunctionCalled
👑 Queenqueen_action(colony, radar, visiting_ants, tick)Once per tick
(up to 100 orders)
🐜 Workerworker_action(ant_id, radar, tick)Per worker, per tick
🔍 Scoutscout_action(ant_id, radar, tick)Per scout, per tick
⚔️ Soldiersoldier_action(ant_id, radar, tick)Per soldier, per tick
🛠️ Engineerengineer_action(ant_id, radar, tick)Per engineer, per tick
🕸️ Swarm Logicswarm_logic(colony_state, tick)Once per tick
⚠️ Use module-level dicts for memory across ticks. The sandbox loads your code once, then calls your functions every tick. If your function crashes, the ant does nothing that tick.

2. Action Commands

{'type': 'hold'}

Do nothing. All castes.

{'type': 'move', 'direction': (dx, dy, dz)}

Step one cell in any of 26 directions. Relative — (1,0,0) means one cell east of where you're standing.

return {'type': 'move', 'direction': (1, 0, 0)}   # east
return {'type': 'move', 'direction': (0, 1, 1)}   # north + up

With optional pheromone: {'type': 'move', 'direction': (1,0,0), 'pheromone': 'food'}

Illegal moves degrade to hold. All moves resolve simultaneously.

{'type': 'pickup'} — workers

Pick up food or egg from current cell. Workers carry up to 10 food units.

{'type': 'deposit'} — workers

Deposit carried food (→ stockpile at base) or egg (→ nursery). Must be at the right structure.

{'type': 'produce', 'caste': 'worker'} — queen only

Queen lays an egg at her chamber. Costs food immediately. Worker must carry it to the nursery before it hatches.

{'type': 'build', 'structure': 'nursery'} — engineers

Build a structure. 1 tick per cell. Barracks and nursery are 25 cells (25 ticks). Valid: 'nursery', 'barracks', 'entrance'. Queen assigns the location.

{'type': 'report', 'data': {...}} — at base

Tell the queen what you saw. Only works at base (in her sight).

return {'type': 'report', 'data': {
    'food_found': [(dx, dy, dz), ...],
    'deaths': [15],
    'threats': [{'type': 'wasp', 'at': (dx, dy, dz)}],
}}

{'type': 'route', 'steps': [...]} — queen orders

Multi-step waypoint sequence. Engine executes natively.

(ant_id, {'type': 'route', 'steps': [
    {'direction': (1, 0, 0), 'repeat': 5},
    {'go_to': 'nursery_4'},
    {'action': 'deposit'},
]})

3. Radar — What Your Ants See

All coordinates relative to the ant. (+1,0,0) = one cell east of you.

radar = {
    'food':       [((dx,dy,dz), amount), ...],
    'enemies':    [{'at': (dx,dy,dz), 'type': 'spider',
                   'hp': 150, 'damage': 100}, ...],
    'allies':     [(dx,dy,dz), ...],
    'obstacles':  [(dx,dy,dz), ...],
    'structures': [((dx,dy,dz), 'nursery_2'), ...],
    'pheromones': [((dx,dy,dz), ['food', 'danger']), ...],
    'deaths':     [{'ant_id': 15, 'cause': 'antlion',
                   'at': (dx,dy,dz)}, ...],
    'current_structure': 'nursery_2',  # or None
}
CasteSightHPDamageCost
Queen110015—
Worker130315
Scout31515
Soldier1901530
Engineer115550
⚠️ Combat is automatic on shared cells. No attack command — just get there.

4. Queen API

def queen_action(colony, radar, visiting_ants, tick):
    return []  # list of (ant_id, action) tuples

Colony

colony = {
    'food': 1234, 'barracks': 2,
    'nurseries': 1, 'territory': 47, 'tick': 5000,
}

Note: there is no 'ants' key. The true ant count is for game statistics only — player access is blocked to prevent telepathic queens.

Radar

Same format as ant radar, centered on the queen's chamber. 9-cell block (3×3).

Game-start exception: at tick 0, the queen's radar reveals her full randomly-generated base layout (all structures, tunnels). She memorizes this. After game start, her radar is normal 9-cell sight — ongoing base awareness comes from ant reports, like everything else.

Visiting ants

[{'ant_id': 5, 'caste': 'worker', 'hp': 30,
  'report': {...}},  # if ant used report action
 ...]

You are in this list. Find caste == 'queen' to get your own ID for produce orders.

Production

CasteCostHatch
Scout515 ticks
Worker1530 ticks
Soldier3090 ticks
Engineer5015 ticks

Egg appears at queen's chamber. Worker must carry to nursery. Blocked only if can't afford the food cost.

Nursery capacity is for eggs (unhatched). Barracks capacity is for live ants. They are separate — nursery holds eggs waiting to hatch, barracks houses ants once hatched.

6. Command Hierarchy

Binary. No exceptions.

She's not telepathic. Once you leave, you're on your own until you return.

7. The Queen Is Not Psychic

She only knows about ants that physically visit her. No live census. Scouts far away are invisible until they return.

How you track your colony — who's alive, what castes are in the field — is your problem to solve. Every player develops their own system.

⚠️ visiting_ants has castes but only who's home. There is no true total available to player code. Bridging that gap is part of the game.

8. Base Structures

4 structures, connected by tunnels. At startup, the random base layout fits within 100×100×100 cells. After startup, bases are not restricted to this footprint — build outward as needed. Queen knows the layout from the start.

StructurePurpose
Queen's chamberQueen lives here. Eggs are laid here.
NurseryEggs hatch here. 100 eggs per nursery. Workers deliver eggs.
BarracksHousing. 100 ants each.
EntranceSurface access. Ants at the entrance get sight range 10.

New structures are assigned locations by the queen. Ants know which structure they're in via radar['current_structure'].

9. Egg Logistics

Queen lays eggs at her chamber. Workers must carry them to the nursery before they hatch.

Queen's chamber capacity: 1,000 eggs max. If the chamber is full, the queen cannot lay more eggs until workers carry some away. Keep the supply line moving or production stalls.

No nurse visits = eggs pile up unhatched = no reinforcements. Kill the supply line, stall the colony.

# Worker at queen's chamber
return {'type': 'pickup'}   # picks up egg
# ... navigate to nursery ...
return {'type': 'deposit'}  # egg -> nursery

10. Pheromones

Three types. All three can coexist on one cell. Each decays independently after 3 days (4320 ticks).

TypeMeaning
foodFood here — come forage
dangerThreat here — avoid or bring soldiers
depletedSource exhausted — don't bother

Lay with move: {'type': 'move', 'direction': (1,0,0), 'pheromone': 'food'}

Unlimited laying. No cost.

11. Food & Hunting

Food is alive. Calipers are creatures that move and must be killed.

Everyone can hunt. Damage ratings:

CasteDamageTicks vs 1000 HP
Soldier15~67
Worker3~334
Scout1~1000

5 workers = 1 soldier's DPS. Swarm tactics: pack hunting beats solo efficiency.

12. Death Reporting

If an ant sees a colony-mate die, it can report it. Includes antlion kills.

Radar deaths gives cause and location. Witness should lay a danger pheromone at antlion pits — static threat, mark once, avoid forever.

Report relays to queen. She prunes dead ants from her tracking immediately and marks pit locations on her map.

13. Threat Identification

Radar enemies includes type. Reports include caste + enemy flag.

ThreatHPDamage
Wasp300100
Spider150100
Antlion∞999
Enemy soldier9015
Enemy worker303

Report format: {'type': 'ant', 'caste': 'soldier', 'enemy': True, 'at': (dx,dy,dz)}

No counts, no colony IDs. Derive estimates through creative programming.

14. Starting Ants & Costs

Pick 9. Queen automatic and free. Starting food: 5000 minus costs.

CasteCostRole
Worker15Forage, carry eggs, nurse
Scout5Explore (3× sight), report
Soldier30Hunt, defend
Engineer50Dig, build

15. Rules