# Development Guide

## Running Tests

```bash
# All tests
python3 -m unittest discover -v tests/

# Specific test file
python3 -m unittest tests/test_game.py -v

# Specific test
python3 -m unittest tests.test_game.TestKill.test_successful_kill
```

## Adding New Triggers

1. Add trigger type to `src/engine/triggers.py`:
```python
class TriggerType(Enum):
    NEW_TRIGGER = auto()
```

2. Add to appropriate category:
```python
STANDARD_TRIGGERS = {..., TriggerType.NEW_TRIGGER}
```

3. Fire trigger in game engine:
```python
self._fire_trigger(TriggerType.NEW_TRIGGER, agent_id, {"data": "value"})
```

## Adding New Actions

1. Add action handler in `src/engine/game.py`:
```python
def _handle_new_action(self, player_id: str, params: dict) -> dict:
    # Validate + execute
    return {"success": True, "action": "NEW_ACTION"}
```

2. Add to `_execute_action` switch.

3. Add to priority order in `resolve_actions`.

## Adding New Maps

Create JSON in `data/maps/`:
```json
{
  "rooms": [
    {
      "id": "room_id",
      "name": "Display Name",
      "tasks": [{"id": "task_id", "name": "Task Name", "duration": 3.0}],
      "vent": {"id": "vent_id", "connects_to": ["other_vent"]}
    }
  ],
  "edges": [
    {"id": "edge_id", "room_a": "room1", "room_b": "room2", "distance": 5.0}
  ]
}
```

## Environment Variables

| Variable | Purpose |
|----------|---------|
| `OPENROUTER_API_KEY` | LLM API authentication |

## Code Style

- Python 3.10+ features (type hints, dataclasses)
- JSON for all config (YAML optional, falls back to JSON)
- Tests mirror source structure (`src/engine/game.py` → `tests/test_game.py`)