amogus/docs/development.md

Development Guide

Running Tests

# 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:

class TriggerType(Enum):
    NEW_TRIGGER = auto()

2. Add to appropriate category:

STANDARD_TRIGGERS = {..., TriggerType.NEW_TRIGGER}

3. Fire trigger in game engine:

self._fire_trigger(TriggerType.NEW_TRIGGER, agent_id, {"data": "value"})

Adding New Actions

1. Add action handler in src/engine/game.py:

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/:

{
  "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)