# mnbvmnbv2/simple-rts-rl architecture

> Architecture diagram of the GitHub repository mnbvmnbv2/simple-rts-rl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mnbvmnbv2/simple-rts-rl
- Repository: https://github.com/mnbvmnbv2/simple-rts-rl

## Overview

##### Project type and purpose
- From the README and file tree, this is an open-source Python library (“simple‐rts‐rl”) that provides:
- A grid-based real-time strategy (RTS) game environment
- Reinforcement-learning (RL) algorithms (PQN and CARBS-PQN) for training agents
- Utilities for evaluation, benchmarking, visualization, and documentation
- The primary purpose is to enable RL experiments on a minimalist RTS game.

##### File structure
- Top-level:
- src/ – main package
– src/playable.py – CLI runner for interactive play
– src/rl/ – RL algorithms & evaluation
· pqn.py – PQN algorithm
· carbs_pqn.py – CARBS-PQN integration
· eval.py – evaluation metrics
– src/rts/ – game environment
· config.py – game parameters
· env.py – environment API (reset, step, render)
· state.py – grid/state representation
· utils.py – helper functions
· visualization.py – rendering support
- docs/ – Sphinx documentation sources
- tests/ – unit and benchmark tests
- notebook.ipynb, train.ipynb – Jupyter demos
- pyproject.toml, .python-version – build and dependency config

##### README for additional insights
- Architecture is not explicitly diagrammed, but key flows:
- Agents (PQN/CARBS) interact with Env via step/reset
- Env uses state+config for game logic and visuals
- Docs built with Sphinx
- Playable interface invokes the environment for manual play
- Benchmark tests simulate episodes to measure performance

##### Detailed capture of essential elements
- Break “RTS Environment” into sub-modules: Config, State, Utils, Visualization
- RL algorithms under a single “Agent” umbrella but annotate each algorithm
- Test suites as separate flows that import and validate the core modules
- CLI and notebook runners as entry points for both demonstration and training

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces
    subgraph "User Interfaces"
        UI_CLI["CLI Runner"]:::ui
        UI_NOTE1["Notebook: notebook.ipynb"]:::ui
        UI_NOTE2["Notebook: train.ipynb"]:::ui
    end

    %% RL Module
    subgraph "RL Module"
        PQN["PQN Agent"]:::rl
        CARBS["CARBS-PQN Agent"]:::rl
        EVAL["Evaluation Utilities"]:::rl
    end

    %% RTS Environment
    subgraph "RTS Environment"
        ENV["RTS Environment API"]:::env
        CONFIG["Game Configuration"]:::env
        STATE["State Representation"]:::env
        UTILS_RTS["Helper Utilities"]:::env
        VIS["Visualization Support"]:::env
    end

    %% Utilities & Tests
    subgraph "Utilities & Tests"
        UTIL["Utilities"]:::util
        UNIT["Unit Tests"]:::util
        BENCH["Benchmark Tests"]:::util
    end

    %% Documentation System
    subgraph "Documentation System"
        DOCSRC["Sphinx Source"]:::docs
        CONF["Sphinx Configuration"]:::docs
        GAMERULES["Game Rules Doc"]:::docs
        INDEX["Index Doc"]:::docs
        BUILDSCRIPTS["Build Scripts"]:::docs
    end

    %% Build Config
    BUILD["Build & Dependency Config"]:::util

    %% Relationships
    UI_CLI -->|triggers| PQN
    UI_CLI -->|triggers| CARBS
    UI_NOTE1 -->|triggers| PQN
    UI_NOTE1 -->|triggers| CARBS
    UI_NOTE2 -->|triggers| PQN
    UI_NOTE2 -->|triggers| CARBS

    PQN <-->|actions/obs| ENV
    CARBS <-->|actions/obs| ENV
    EVAL -->|evaluates| PQN
    EVAL -->|evaluates| CARBS
    EVAL -->|collects metrics| ENV

    ENV -->|uses| CONFIG
    ENV -->|uses| STATE
    ENV -->|uses| UTILS_RTS
    ENV -->|renders via| VIS

    UNIT -->|tests| PQN
    UNIT -->|tests| CARBS
    UNIT -->|tests| ENV
    UNIT -->|tests| UTILS_RTS

    BENCH -->|benchmarks| PQN
    BENCH -->|benchmarks| CARBS
    BENCH -->|benchmarks| ENV

    DOCSRC -->|documents| PQN
    DOCSRC -->|documents| CARBS
    DOCSRC -->|documents| ENV

    DOCSRC --> CONF
    DOCSRC --> GAMERULES
    DOCSRC --> INDEX
    DOCSRC --> BUILDSCRIPTS

    BUILD ---|configuration| PQN
    BUILD ---|configuration| ENV

    %% Click Events
    click UI_CLI "https://github.com/mnbvmnbv2/simple-rts-rl/blob/main/src/playable.py"
    click UI_NOTE1 "https://github.com/mnbvmnbv2/simple-rts-rl/blob/main/notebook.ipynb"
    click UI_NOTE2 "https://github.com/mnbvmnbv2/simple-rts-rl/blob/main/train.ipynb"
    click PQN "https://github.com/mnbvmnbv2/simple-rts-rl/blob/main/src/rl/pqn.py"
    click CARBS "https://github.com/mnbvmnbv2/simple-rts-rl/blob/main/src/rl/carbs_pqn.py"
    click EVAL "https://github.com/mnbvmnbv2/simple-rts-rl/blob/main/src/rl/eval.py"
    click ENV "https://github.com/mnbvmnbv2/simple-rts-rl/blob/main/src/rts/env.py"
    click CONFIG "https://github.com/mnbvmnbv2/simple-rts-rl/blob/main/src/rts/config.py"
    click STATE "https://github.com/mnbvmnbv2/simple-rts-rl/blob/main/src/rts/state.py"
    click UTILS_RTS "https://github.com/mnbvmnbv2/simple-rts-rl/blob/main/src/rts/utils.py"
    click VIS "https://github.com/mnbvmnbv2/simple-rts-rl/blob/main/src/rts/visualizaiton.py"
    click DOCSRC "https://github.com/mnbvmnbv2/simple-rts-rl/tree/main/docs/source"
    click CONF "https://github.com/mnbvmnbv2/simple-rts-rl/blob/main/docs/source/conf.py"
    click GAMERULES "https://github.com/mnbvmnbv2/simple-rts-rl/blob/main/docs/source/gamerules.md"
    click INDEX "https://github.com/mnbvmnbv2/simple-rts-rl/blob/main/docs/source/index.md"
    click BUILDSCRIPTS "https://github.com/mnbvmnbv2/simple-rts-rl/tree/main/docs/Makefile"
    click BUILDSCRIPTS "https://github.com/mnbvmnbv2/simple-rts-rl/blob/main/docs/make.bat"
    click UNIT "https://github.com/mnbvmnbv2/simple-rts-rl/tree/main/tests/unit/"
    click BENCH "https://github.com/mnbvmnbv2/simple-rts-rl/tree/main/tests/benchmark/"
    click BUILD "https://github.com/mnbvmnbv2/simple-rts-rl/blob/main/pyproject.toml"
    click BUILD "https://github.com/mnbvmnbv2/simple-rts-rl/blob/main/.python-version"

    %% Styles
    classDef ui fill:#FFA500,stroke:#333,stroke-width:1px
    classDef rl fill:#1E90FF,stroke:#333,stroke-width:1px
    classDef env fill:#32CD32,stroke:#333,stroke-width:1px
    classDef util fill:#A9A9A9,stroke:#333,stroke-width:1px
    classDef docs fill:#D2691E,stroke:#333,stroke-width:1px
```
