# robocup-junior/rcj-soccersim architecture

> Architecture diagram of the GitHub repository robocup-junior/rcj-soccersim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/robocup-junior/rcj-soccersim
- Repository: https://github.com/robocup-junior/rcj-soccersim

## Overview

##### Project Type and Purpose
- Type: A robotics simulation tool built on top of the Webots engine.
- Purpose:
– Provide a simulated soccer environment (world file + physics)
– Run multiple Python “controllers” (automatic referee, soccer ball, two teams)
– Let users develop and test robot controllers under the RoboCupJunior Soccer rules

##### File Structure
- Top-level:
– worlds/: Webots world definitions (.wbt + directory)
– controllers/: Python code for various simulation actors
– scripts/: auxiliary scripts (e.g., generate world templates)
– docs/: user and developer documentation (MkDocs site)
– CI/workflows: GitHub Actions for code checks/docs build
- controllers/ sub-folders:
– rcj_soccer_ball: “ball” controller logic
– rcj_soccer_referee_supervisor: automatic referee & recorder modules
– rcj_soccer_team_blue & …_yellow: sample team controllers (robot1.py, etc.)
- Config & tooling:
– pyproject.toml, setup.cfg, requirements/ for dependency management
– run-in-docker.sh for containerized runs

##### README for Architectural Insights
- Core components are the Webots world (soccer.wbt) and Python controllers.
- Controllers run inside Webots as independent processes, each attached to a scene node.
- Communication with Webots is through its Python API (sensor readings → control commands).
- The referee implements event handlers, penalty checks, progress checks, and a recorder.

##### Main Components & Interactions
a. Components
1. Webots Simulation Engine
– Loads “worlds/soccer.wbt”
– Manages physics, rendering, node lifecycle
2. Controllers (each a Python process)
– Ball Controller
– Referee Supervisor
- Sub-modules: eventer, referee logic, penalty & progress checkers, recorder
– Team Blue (3 robot controllers + team manager)
– Team Yellow (3 robot controllers + team manager)
3. External Dependencies
– Python 3.7+ runtime
– Webots native application + Python API
– RoboCupJunior Soccer simulated rules (data driving referee logic)
b. Relationships & Data Flows
– Simulation Engine → Controllers: provides sensor data & API hooks
– Controllers → Simulation Engine: actuator commands (wheel motors, lights)
– Referee Supervisor reads global state → applies rule logic → may disable/penalize robots
– Recorder logs events from Referee → writes to local storage or streams to console
– Team controllers use utils modules to process sensor data → generate movement strategy
c. Architectural Patterns & Principles
– Modular controllers: each actor has its own process for isolation
– Event-driven design inside referee (handlers respond to on-field events)
– Clear separation: simulation core vs. controller logic vs. documentation/scripts
d. Key Technologies & Frameworks
– Webots simulator (C++ engine + Python API)
– Pure Python for controllers (uses standard libs + custom utils)
– MkDocs for docs, GitHub Actions for CI

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Runtime Components"
        WS["Webots Simulation Engine"]:::runtime
        VR[(Soccer World Resources)]:::runtime
    end

    subgraph "Controllers"
        Ball["Ball Controller"]:::runtime
        RefSup["Referee Supervisor"]:::runtime
        subgraph "Referee Modules"
            Eventer["Event Dispatcher"]:::runtime
            RefereeCore["Referee Core Logic"]:::runtime
            SupervisorMod["Supervisor Submodule"]:::runtime
            PenaltyChecker["Penalty Area Checker"]:::runtime
            ProgressChecker["Progress Checker"]:::runtime
            RecorderMod["Recorder Module"]:::runtime
            ConstsRec["Recorder Constants"]:::runtime
            EnumsConsts["Referee Enums & Consts"]:::runtime
            UtilsRef["Referee Utilities"]:::runtime
            EventHandlers["Event Handlers"]:::runtime
        end
        BlueMgr["Team Blue Manager"]:::runtime
        BlueBase["Team Blue Base Class"]:::runtime
        Blue1["Blue Robot1"]:::runtime
        Blue2["Blue Robot2"]:::runtime
        Blue3["Blue Robot3"]:::runtime
        BlueUtils["Team Blue Utilities"]:::runtime
        YellowMgr["Team Yellow Manager"]:::runtime
        YellowBase["Team Yellow Base Class"]:::runtime
        Yellow1["Yellow Robot1"]:::runtime
        Yellow2["Yellow Robot2"]:::runtime
        Yellow3["Yellow Robot3"]:::runtime
        YellowUtils["Team Yellow Utilities"]:::runtime
    end

    WS -->|loads| VR
    WS -->|provides sensor data| Ball
    Ball -->|actuator commands| WS
    WS -->|provides sensor data| RefSup
    RefSup -->|actuator commands| WS
    RefSup -->|"uses"| Eventer
    RefSup -->|"uses"| RefereeCore
    RefSup -->|"uses"| SupervisorMod
    RefSup -->|"uses"| PenaltyChecker
    RefSup -->|"uses"| ProgressChecker
    RefSup -->|"uses"| RecorderMod
    RefereeCore -->|"reads"| EnumsConsts
    RecorderMod -->|"reads"| ConstsRec
    RefereeCore -->|"uses"| UtilsRef
    Eventer -->|"invokes"| EventHandlers
    WS -->|provides sensor data| BlueMgr
    BlueMgr -->|manages| Blue1
    BlueMgr -->|manages| Blue2
    BlueMgr -->|manages| Blue3
    BlueMgr -->|"uses"| BlueBase
    BlueMgr -->|"uses"| BlueUtils
    Blue1 -->|actuator commands| WS
    Blue2 -->|actuator commands| WS
    Blue3 -->|actuator commands| WS
    WS -->|provides sensor data| YellowMgr
    YellowMgr -->|manages| Yellow1
    YellowMgr -->|manages| Yellow2
    YellowMgr -->|manages| Yellow3
    YellowMgr -->|"uses"| YellowBase
    YellowMgr -->|"uses"| YellowUtils
    Yellow1 -->|actuator commands| WS
    Yellow2 -->|actuator commands| WS
    Yellow3 -->|actuator commands| WS

    subgraph "Supporting Tools"
        ScriptGen["World Generation Script"]:::tools
        Template["World Template"]:::tools
        DocsCfg["Docs Site Config"]:::tools
        DocsMD["User & Developer Docs"]:::tools
        DockerScript["Docker Run Script"]:::tools
    end

    subgraph "CI & Config"
        CIWF["CI Workflows"]:::ci
        DepMan["Dependency Management"]:::ci
    end

    ScriptGen -->|generates| VR
    Template -->|template for| ScriptGen
    CIWF -->|validates| DepMan
    DockerScript -->|runs| WS

    click WS "https://github.com/robocup-junior/rcj-soccersim/blob/master/worlds/soccer.wbt"
    click VR "https://github.com/robocup-junior/rcj-soccersim/tree/master/worlds/soccer/"
    click Ball "https://github.com/robocup-junior/rcj-soccersim/blob/master/controllers/rcj_soccer_ball/rcj_soccer_ball.py"
    click RefSup "https://github.com/robocup-junior/rcj-soccersim/blob/master/controllers/rcj_soccer_referee_supervisor/rcj_soccer_referee_supervisor.py"
    click RecorderMod "https://github.com/robocup-junior/rcj-soccersim/blob/master/controllers/rcj_soccer_referee_supervisor/recorder/recorder.py"
    click ConstsRec "https://github.com/robocup-junior/rcj-soccersim/blob/master/controllers/rcj_soccer_referee_supervisor/recorder/consts.py"
    click RefereeCore "https://github.com/robocup-junior/rcj-soccersim/blob/master/controllers/rcj_soccer_referee_supervisor/referee/referee.py"
    click SupervisorMod "https://github.com/robocup-junior/rcj-soccersim/blob/master/controllers/rcj_soccer_referee_supervisor/referee/supervisor.py"
    click Eventer "https://github.com/robocup-junior/rcj-soccersim/blob/master/controllers/rcj_soccer_referee_supervisor/referee/eventer.py"
    click EventHandlers "https://github.com/robocup-junior/rcj-soccersim/blob/master/controllers/rcj_soccer_referee_supervisor/referee/event_handlers.py"
    click PenaltyChecker "https://github.com/robocup-junior/rcj-soccersim/blob/master/controllers/rcj_soccer_referee_supervisor/referee/penalty_area_checker.py"
    click ProgressChecker "https://github.com/robocup-junior/rcj-soccersim/blob/master/controllers/rcj_soccer_referee_supervisor/referee/progress_checker.py"
    click EnumsConsts "https://github.com/robocup-junior/rcj-soccersim/blob/master/controllers/rcj_soccer_referee_supervisor/referee/enums.py"
    click UtilsRef "https://github.com/robocup-junior/rcj-soccersim/blob/master/controllers/rcj_soccer_referee_supervisor/referee/utils.py"
    click BlueMgr "https://github.com/robocup-junior/rcj-soccersim/blob/master/controllers/rcj_soccer_team_blue/rcj_soccer_team_blue.py"
    click BlueBase "https://github.com/robocup-junior/rcj-soccersim/blob/master/controllers/rcj_soccer_team_blue/rcj_soccer_robot.py"
    click Blue1 "https://github.com/robocup-junior/rcj-soccersim/blob/master/controllers/rcj_soccer_team_blue/robot1.py"
    click Blue2 "https://github.com/robocup-junior/rcj-soccersim/blob/master/controllers/rcj_soccer_team_blue/robot2.py"
    click Blue3 "https://github.com/robocup-junior/rcj-soccersim/blob/master/controllers/rcj_soccer_team_blue/robot3.py"
    click BlueUtils "https://github.com/robocup-junior/rcj-soccersim/blob/master/controllers/rcj_soccer_team_blue/utils.py"
    click YellowMgr "https://github.com/robocup-junior/rcj-soccersim/blob/master/controllers/rcj_soccer_team_yellow/rcj_soccer_team_yellow.py"
    click YellowBase "https://github.com/robocup-junior/rcj-soccersim/blob/master/controllers/rcj_soccer_team_yellow/rcj_soccer_robot.py"
    click Yellow1 "https://github.com/robocup-junior/rcj-soccersim/blob/master/controllers/rcj_soccer_team_yellow/robot1.py"
    click Yellow2 "https://github.com/robocup-junior/rcj-soccersim/blob/master/controllers/rcj_soccer_team_yellow/robot2.py"
    click Yellow3 "https://github.com/robocup-junior/rcj-soccersim/blob/master/controllers/rcj_soccer_team_yellow/robot3.py"
    click YellowUtils "https://github.com/robocup-junior/rcj-soccersim/blob/master/controllers/rcj_soccer_team_yellow/utils.py"
    click ScriptGen "https://github.com/robocup-junior/rcj-soccersim/blob/master/scripts/generate-soccer-world.py"
    click Template "https://github.com/robocup-junior/rcj-soccersim/blob/master/scripts/templates/soccer.wbt.template"
    click DocsCfg "https://github.com/robocup-junior/rcj-soccersim/blob/master/docs/mkdocs.yml"
    click DocsMD "https://github.com/robocup-junior/rcj-soccersim/blob/master/docs/docs/*.md"
    click CIWF "https://github.com/robocup-junior/rcj-soccersim/blob/master/.github/workflows/check.yml"
    click CIWF "https://github.com/robocup-junior/rcj-soccersim/blob/master/.github/workflows/docs.yml"
    click DepMan "https://github.com/robocup-junior/rcj-soccersim/blob/master/pyproject.toml"
    click DepMan "https://github.com/robocup-junior/rcj-soccersim/blob/master/setup.cfg"
    click DepMan "https://github.com/robocup-junior/rcj-soccersim/blob/master/requirements/development.in"
    click DepMan "https://github.com/robocup-junior/rcj-soccersim/blob/master/requirements/development.txt"
    click DockerScript "https://github.com/robocup-junior/rcj-soccersim/blob/master/run-in-docker.sh"

    classDef runtime fill:#ADD8E6,stroke:#0000FF,color:#000000
    classDef tools fill:#98FB98,stroke:#008000,color:#000000
    classDef ci fill:#D3D3D3,stroke:#696969,color:#000000
```
