How robocup-junior/rcj-soccersim works
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