Your colony is programmed in six sections in the Portal's Play tab.
| Section | Function | Called |
|---|---|---|
| 👑 Queen | queen_action(colony, radar, visiting_ants, tick) | Once per tick (up to 100 orders) |
| 🐜 Worker | worker_action(ant_id, radar, tick) | Per worker, per tick |
| 🔍 Scout | scout_action(ant_id, radar, tick) | Per scout, per tick |
| ⚔️ Soldier | soldier_action(ant_id, radar, tick) | Per soldier, per tick |
| 🛠️ Engineer | engineer_action(ant_id, radar, tick) | Per engineer, per tick |
| 🕸️ Swarm Logic | swarm_logic(colony_state, tick) | Once per tick |
{'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'} — workersPick up food or egg from current cell. Workers carry up to 10 food units.
{'type': 'deposit'} — workersDeposit carried food (→ stockpile at base) or egg (→ nursery). Must be at the right structure.
{'type': 'produce', 'caste': 'worker'} — queen onlyQueen lays an egg at her chamber. Costs food immediately. Worker must carry it to the nursery before it hatches.
{'type': 'build', 'structure': 'nursery'} — engineersBuild 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 baseTell 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 ordersMulti-step waypoint sequence. Engine executes natively.
(ant_id, {'type': 'route', 'steps': [
{'direction': (1, 0, 0), 'repeat': 5},
{'go_to': 'nursery_4'},
{'action': 'deposit'},
]})
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
}
| Caste | Sight | HP | Damage | Cost |
|---|---|---|---|---|
| Queen | 1 | 100 | 15 | — |
| Worker | 1 | 30 | 3 | 15 |
| Scout | 3 | 15 | 1 | 5 |
| Soldier | 1 | 90 | 15 | 30 |
| Engineer | 1 | 15 | 5 | 50 |
def queen_action(colony, radar, visiting_ants, tick):
return [] # list of (ant_id, action) tuples
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.
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.
[{'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.
| Caste | Cost | Hatch |
|---|---|---|
| Scout | 5 | 15 ticks |
| Worker | 15 | 30 ticks |
| Soldier | 30 | 90 ticks |
| Engineer | 50 | 15 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.
Binary. No exceptions.
She's not telepathic. Once you leave, you're on your own until you return.
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.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.
| Structure | Purpose |
|---|---|
| Queen's chamber | Queen lives here. Eggs are laid here. |
| Nursery | Eggs hatch here. 100 eggs per nursery. Workers deliver eggs. |
| Barracks | Housing. 100 ants each. |
| Entrance | Surface 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'].
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
Three types. All three can coexist on one cell. Each decays independently after 3 days (4320 ticks).
| Type | Meaning |
|---|---|
food | Food here — come forage |
danger | Threat here — avoid or bring soldiers |
depleted | Source exhausted — don't bother |
Lay with move: {'type': 'move', 'direction': (1,0,0), 'pheromone': 'food'}
Unlimited laying. No cost.
Food is alive. Calipers are creatures that move and must be killed.
Everyone can hunt. Damage ratings:
| Caste | Damage | Ticks vs 1000 HP |
|---|---|---|
| Soldier | 15 | ~67 |
| Worker | 3 | ~334 |
| Scout | 1 | ~1000 |
5 workers = 1 soldier's DPS. Swarm tactics: pack hunting beats solo efficiency.
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.
Radar enemies includes type. Reports include caste + enemy flag.
| Threat | HP | Damage |
|---|---|---|
| Wasp | 300 | 100 |
| Spider | 150 | 100 |
| Antlion | ∞ | 999 |
| Enemy soldier | 90 | 15 |
| Enemy worker | 30 | 3 |
Report format: {'type': 'ant', 'caste': 'soldier', 'enemy': True, 'at': (dx,dy,dz)}
No counts, no colony IDs. Derive estimates through creative programming.
Pick 9. Queen automatic and free. Starting food: 5000 minus costs.
| Caste | Cost | Role |
|---|---|---|
| Worker | 15 | Forage, carry eggs, nurse |
| Scout | 5 | Explore (3× sight), report |
| Soldier | 30 | Hunt, defend |
| Engineer | 50 | Dig, build |