Skip to content

Home

Jump to bottom
Fred Huang edited this page Nov 10, 2025 · 24 revisions

Utama-Core Overview

Utama‑Core is the central software stack used by Team Utama for RoboCup’s Small Size League (SSL). It provides high‑level strategies, low‑level skills, motion‑planning algorithms, simulator interfaces and a team controller for both simulation and real robots. The codebase is designed around modular folders with clear responsibilities and uses the pixi environment manager. The sections below summarise each module, describe how they interact and reference the relevant source files.

Field conventions

  • All coordinates and velocities will be in meters or meters per second.
  • All angular properties will be in radians or radians per second, normalised between [pi, -pi]. A heading of radian 0 indicates a robot facing towards the positive x-axis (ie left to right).
  • Unless otherwise stated, the coordinate system is aligned such that blue robots are on the left and yellow robots are on the right.

Robot IDs

Folder hierarchy

The repository follows a clear folder structure with each directory serving a distinct purpose:

Folder Description Key files
strategy Implements high‑level decision making via behaviour trees (coach AI, plays and tactics). It controls role assignment and team strategy. utama_core/strategy/README.md explains roles, tactics and plays; see below.
skills Contains low‑level actions for individual robots (move to the ball, receive passes, shoot, clear ball, etc.). Each skill is stateless and operates on one robot. e.g., go_to_ball.py, score_goal.py
motion_planning Provides motion‑planning algorithms for path generation and collision avoidance, including RRT* and Dynamic Window approaches. planning/path_planner.py (WORK IN PROGRESS)
team_controller Interfaces with vision, referee and robots; processes network packets and sends commands to the hardware or simulator. utama_core/team_controller/README.md
run Contains the main running loop, combining refiners and predictors for the game state. main.py
global_utils Utility functions and classes used across modules (math utilities, network helpers). global_utils/math_utils.py
entities Data structures representing game state (ball, robots, field, referee data) and namedtuples for vision and command packets. entities/data, entities/game, entities/referee
rsoccer_simulator A lightweight simulator environment adapted from RobôCIn’s rSoccer for reinforcement‑learning and testing. SSLStandardEnv class and environment definitions
replay Handles saving and replaying games; stores .pkl files that can be reconstructed in the simulator.
tests Unit tests covering various modules.

Clone this wiki locally