# AntWars Player Guide

## Your Code

Write a Python file with two functions:

```python
def ant_action(ant_id, caste, radar, tick):
    """Called once per tick per ant. Returns an action dict."""
    return {"type": "hold"}

def queen_action(colony, visiting_ants, tick):
    """Called once per tick. Returns list of (ant_id, action) tuples.
    Max 100 actions per tick."""
    return []
```

### Limits
- **10MB** max file size
- **1 execution** per ant per tick (50ms timeout)
- **100 executions** max per queen per tick
- **Cross-tick state allowed** — module-level variables persist

If your code times out or crashes, that ant does `hold` for the tick.

---

## Ant Castes

| Caste | HP | Sight | Damage | Cost | Notes |
|-------|----|-------|--------|------|-------|
| queen | 100 | 1 | 15 | — | Unique. Only she can `produce`. |
| worker | 30 | 1 | 3 | 15 | Only caste that carries food (10 max). |
| scout | 15 | 3 | 1 | 5 | Long vision. Fragile. |
| soldier | 90 | 1 | 15 | 30 | Tank. Expensive. |
| engineer | 15 | 1 | 5 | 50 | Only caste that digs. Builds (25 ticks). |

**All ants move at 1 tile/tick.** No speed differences. 26-directional (including diagonals).

Sight 1 = 3×3 area. Sight 3 = 7×7 area.

---

## Actions

### `{"type": "hold"}`
Do nothing.

### `{"type": "move", "to": (x, y, z)}`
Move to adjacent cell (Chebyshev distance ≤ 1). Must be in bounds.
Obstacles block movement **except for engineers**, who dig through.

Optional: `{"type": "move", "to": (x, y, z), "pheromone": "danger"}`
Lay a pheromone when moving. Default is `"trail"`.

### `{"type": "pickup"}`
Worker only. Take food from current cell (up to 10 capacity).

### `{"type": "deposit"}`
Worker only. Deposit carried food. Must be at colony base.

### `{"type": "produce", "caste": "worker"}`
Queen only. Order a new ant. Cost deducted immediately.
Caste must be `worker`, `scout`, `soldier`, or `engineer` (not `queen`).
Egg goes to nursery, matures in HP ticks (worker=30, scout=15, soldier=90, engineer=15).
**Larva waits if barracks is full** — only ants at base count toward capacity.

### `{"type": "build", "structure": "barracks"}`
Engineer only. Structures: `barracks`, `nursery`, `food_storage`, `wall`.
Barracks/nurseries take 25 ticks. Progress resets if engineer does anything else.
**Cannot build queen's chamber.**
If built at surface (z=498), becomes an entrance instead of housing.

---

## Radar

`ant_action` receives a `radar` dict with local information:

```python
{
    'food': [(x, y, z), ...],      # visible food positions
    'allies': [(x, y, z), ...],    # allied ant positions
    'enemies': [(x, y, z), ...],   # enemy ant positions  
    'obstacles': [(x, y, z), ...], # visible obstacles
    'pheromones': {...},           # coord -> (type, expiry)
}
```

Only includes cells within sight range.

---

## Queen

`queen_action(colony, visiting_ants, tick)`:

- `colony`: `{'food': int, 'ants': int, 'barracks': int, 'nurseries': int, 'territory': int, 'tick': int}`
- `visiting_ants`: list of `{'ant_id': int, 'caste': str, 'hp': int}` for ants at queen's position
- Returns: list of `(ant_id, action)` tuples, max 100

**Critical:** Ants must physically visit the queen to receive orders.
No remote control. If a scout dies in the field, its intel dies with it.

---

## The Arena

- **Size:** 5,000 × 5,000 × 500. Surface at z=498.
- **Obstacles:** 5-15% of map. Only engineers dig through.
- **Ten colonies.** No alliances.

### NPCs
- **Spider:** Hunger 0-100. Hunts at 50+. Leaves uneaten corpses as treasure.
- **Wasp:** Kills one ant, abducts the corpse, leaves the map.
- **Antlion:** Static pit. Kills any ant entering. Banks 15 food/kill. Grows: 1→3×3 (15 food) →5×5 (135 food) →...
- **Caterpillar (1000 HP) / Potato bug (500 HP):** Wander, die naturally, become food.

### Rain
- Surface only (z=498). Max once per 15 days. 30-tick warning. Lasts 15-120 ticks.
- **Ants on surface during rain are permanently disconnected.** They follow swarm logic to get home, but you can't control them.
- Washes away pheromones.

### Territory
Dug cells = territory. 1 pt per cell. Only engineers dig.

---

## Scoring

1. Territory: 1 pt per dug cell
2. Ants alive: total current HP × 2
3. Ants built: total max HP ever built × 1
4. Damage dealt: HP × 10
5. Days survived: days × 1,000

Last queen standing wins immediately. Otherwise highest score wins. No tie-breakers.

---

## Tips (Mechanics, Not Strategy)

- Workers must return to base to deposit. No remote deposit.
- Barracks space is physical — ants in the field don't count. Send ants out to free space.
- Nursery holds 100 eggs max. Barracks holds 100 ants max (at base).
- Pheromones decay in 3 days or when it rains. Walking over refreshes.
- Danger pheromones need reinforcement by another ant to persist.
- Multiple entrances = escape routes from rain, but also invasion routes.
- Don't feed antlions near your base. If the pit reaches your queen, she dies.
