Extending Game Reasoning Arena

This guide covers how to extend Game Reasoning Arena with new features.

Adding New Games

To add support for a new game:

Create the game environment

Create a new file in src/game_reasoning_arena/arena/envs/:

# src/game_reasoning_arena/arena/envs/my_game_env.py
from .base_env import BaseEnv

class MyGameEnv(BaseEnv):
    def __init__(self, config):
        super().__init__(config)
        # Initialize game-specific state

    def reset(self):
        # Reset game to initial state
        pass

    def step(self, action):
        # Execute action and return new state
        pass

    def get_legal_actions(self, player):
        # Return list of legal actions for player
        pass

    def is_terminal(self):
        # Check if game is finished
        pass

    def get_winner(self):
        # Return winner if game is terminal
        pass

Register the game

Add your game to the environment initializer:

# In src/game_reasoning_arena/arena/envs/env_initializer.py
from .my_game_env import MyGameEnv

GAME_REGISTRY = {
    # ... existing games
    "my_game": MyGameEnv,
}

Add configuration support

Create a configuration template in src/game_reasoning_arena/configs/.
Add tests

Create tests in tests/ to verify your game works correctly.
Customize prompts (for LLM games)

If your game will be played by LLM agents, you’ll want to customize the prompting system to provide game-specific context. See the Prompting System guide for detailed instructions on creating effective prompts for your game.

Adding New Agent Types

To create a new agent type:

Implement the agent class

# src/game_reasoning_arena/arena/agents/my_agent.py
from .base_agent import BaseAgent

class MyAgent(BaseAgent):
    def __init__(self, name, **kwargs):
        super().__init__(name)
        # Initialize agent-specific parameters

    def get_action(self, state, legal_actions):
        # Your decision logic here
        return chosen_action

    def reset(self):
        # Reset agent state for new game
        pass

Register the agent

Add to the agent registry:

# In src/game_reasoning_arena/arena/agents/agent_registry.py
from .my_agent import MyAgent

AGENT_REGISTRY = {
    # ... existing agents
    "my_agent": MyAgent,
}

Adding New Backends

To add support for a new LLM backend:

Implement backend class

# src/game_reasoning_arena/backends/my_backend.py
from .base_backend import BaseBackend

class MyBackend(BaseBackend):
    def __init__(self, config):
        super().__init__(config)
        # Initialize backend-specific setup

    def generate(self, prompt, **kwargs):
        # Call your LLM service
        pass

Register the backend

Add to backend registry and configuration files.

Adding New Analysis Tools

To add new analysis capabilities:

Create analysis module

# analysis/my_analysis.py
def analyze_my_metric(game_logs):
    # Your analysis logic
    pass

Add visualization support

Integrate with existing plotting infrastructure.
Update analysis pipeline

Add to the main analysis workflow.

Development Guidelines

Code Style

Follow PEP 8 style guidelines
Use type hints where possible
Add comprehensive docstrings
Include unit tests for new features

Testing

Write tests for all new functionality
Ensure tests pass before submitting
Include integration tests for complex features

Documentation

Update relevant documentation pages
Add examples for new features
Include configuration examples
Update API reference as needed

Performance Considerations

Profile new code for performance bottlenecks
Consider memory usage for large-scale experiments
Optimize critical paths in game simulation
Test scalability with distributed execution

For more detailed guidelines, see the Contributing section.