GameController

This is the GameController software for robot soccer games in the RoboCup Standard Platform League.

Compilation

Prerequisites

• Rust and other platform-specific tauri dependencies as listed here
• nodejs and npm (or a compatible package manager)
• libclang (for bindgen)
  • On Windows:

  winget install LLVM
  set LIBCLANG_PATH 'C:\Program Files\LLVM\bin\'
  

Commands

First, the frontend must be compiled:

cd frontend
npm ci
npm run build

The Rust code is compiled with cargo:

cargo build [-r]

Dev

First, thank you for contributing to development.

This will install the tauri CLI:

cargo install tauri-cli

This will start the frontend and backend in dev mode:

cargo tauri dev

Creating Binary Distributions

For Linux, macOS and Windows, there are scripts in the directory dist/ to create binary distributions. They all expect a version number as first argument, and can optionally take the target as second argument (otherwise the host target is assumed on Linux and Windows, while macOS creates a Universal binary). They build a special profile called release-dist which mainly tries to create a small binary. It is recommended to run the script only on a clean working tree.

Configuration

Configuration files that are read at runtime are located in the directory config. The global teams.yaml is a list of all teams in the SPL, their names, and their available jersey colors both for field players and goalkeepers. Each (sub)competition has a subdirectory with two files: params.yaml corresponds to the Rust struct game_controller_core::types::CompetitionParams and sets (mostly numeric) constants for the competition. teams.yaml is a list of team numbers of the teams that participate in the competition. Only those teams can be selected when playing in this competition. Therefore, for a new team to appear in the UI, an entry must be added both to the global teams.yaml (with an unused team number) and in the competition's teams.yaml (referencing the team number).

Network Communication

Currently, all network communication with the GameController uses IPv4, although most parts of the code can also handle IPv6.

The GameController communicates with robot players via three channels:

• It sends control messages at a rate of 2 hertz (UDP broadcast on port 3838, format specified in the struct RoboCupGameControlData in game_controller_msgs/headers/RoboCupGameControlData.h). These control messages do not always represent the true game state, specifically after a goal or a transition to the playing state. After these events, they continue to maintain the state before the event for up to 15 seconds, or until another event happens that could not have happened in this "fake" state. Note that this behavior differs from the old GameController, which would always keep the state attribute (and some others) at the old value for 15 seconds, even when other attributes already clearly indicated that it was the new state (e.g. players are unpenalized although their timers aren't at zero yet, or set plays starting during the "fake" set state when it is actually already playing).
• It receives status messages from the robot players which must send them at a rate between 0.5 hertz and 2 hertz (UDP unicast on port 3939, format specified in the struct RoboCupGameControlReturnData in game_controller_msgs/headers/RoboCupGameControlData.h).
• It receives team messages from the robot players (UDP broadcast on port 10000 + team number, up to 128 bytes of payload with arbitrary format).

In addition, the GameController offers an interface for monitor applications (such as the TeamCommunicationMonitor or the EventRecorder):

• It receives monitor requests (UDP unicast on port 3636, 4 bytes header magic RGTr + 1 byte version number 0). It refuses to accept monitor requests from hosts that have previously sent status messages, as those are presumed to be robot players which should not get true data. Similarly, if a host that had previously sent a monitor request sends a status message, it will not receive monitor data anymore.
• Each registered monitor host will get:
  • control messages with the true game state at a rate of 2 hertz (UDP unicast on port 3838, with the same format as regular control messages, but with the header magic RGTD).
  • forwarded status messages (UDP unicast on port 3940, prefixed by the IPv4 address of the original sender). The forwarded payload has not been validated.

The user must ensure that all of the aforementioned network communication channels are allowed to be used by the firewall. The GameController runs on a specific network interface, which generally specifies where packets are sent and from where they are received. The exceptions are that control messages can be configured to be sent to the limited broadcast address (255.255.255.255) instead of the interface's broadcast address, and that monitor requests and team messages are received from any address.

Usage

Start

The binary distributions on the GitHub releases page come with scripts that can be executed in a platform-typical way. On macOS, you may want to call xattr -c <path to GameController.app> before the first run to clear the quarantine flag.

If the GameController should be run from the source code, the most convenient way to do it is by executing

cargo run [-r]

from a command line within any directory of this workspace. The program accepts command line arguments which can be passed to cargo after --. They override the defaults of the launcher. A list of arguments (that is always up to date, in contrast to what would be written here) can be obtained by running with the -h option:

cargo run -- -h

Note that release builds on Windows do not output any text.

Launcher

When the GameController is started, a launcher is shown first. Some fields will be pre-filled by command line arguments, if they were specified.

The following settings are exposed via the launcher:

• Competition: This box selects the competition type of the game. It influences the behavior and constants of the GameController and narrows down the set of teams that can be selected.
• Play-off: This checkbox selects if the game time stops during all Ready and Set states. Should be checked if the game is a quarterfinal, semifinal, final or 3rd place game.
• Teams:
  • Kick-off for (home / away) team: This box selects which team has the first kick-off, as a result of the coin tosses before the game.
  • The main box selects the team on the respective side.
  • Field player color and goalkeeper color: These boxes select the jersey colors of the team.
• Testing:
  • No Delay: This checkbox disables the delay of game state transitions.
  • Penalty Shoot-out: This checkbox allows to start/continue a penalty shoot-out even though the game is actually decided.
  • Unpenalize: This checkbox allows to unpenalize players before their time is over.
• Mirror: This checkbox selects if the home (first on the schedule) team defends the right side (from the GameController's perspective) instead of the left side, as a result of the coin tosses before the game.
• Fullscreen: This checkbox selects if the window should be switched to fullscreen mode when started.
• Interface: This box selects the network interface to run on (see above). Not all interfaces that are listed will necessarily work.
• Broadcast: This checkbox selects if control messages are sent to the limited broadcast address (255.255.255.255) instead of the interface's broadcast address. Should only be used when it is required that those messages are sent on all interfaces.
• Multicast: This checkbox selects whether team communication is also received from a certain multicast group. Should only be used for simulated games, never for real competition games.

The launcher allows to start a game only if the two teams are distinct and their jersey colors don't conflict, i.e. all four colors must be pairwise distinct, except for the goalkeeper colors which may be the same for both teams. Note that changing the sides or the kick-off team is not possible afterwards, so the switch to the main interface can only be done after the coin tosses.

Main Interface

The team panels (i.e. the left and right columns of the layout) should be aligned with the goals the teams are defending (from the perspective of the GameController operator). That is, the GameController operator's view defines what the left and the right team is, as it has been selected in the launcher.

The main interface is sometimes context-sensitive, i.e. some buttons only appear when they are useful in the current state of the game. However, it is generally avoided that the layout or meaning of buttons changes without user interaction (because it would be bad if a button which the user is about to press changed its meaning in that instant).

Penalties

Penalties are applied by clicking the button labeled with the penalty call first and then clicking the button of the penalized player. This will start a timer on the respective player's button which starts flashing once there are only 10 seconds remaining. Players are not unpenalized automatically. Instead they must be unpenalized by clicking their button once their penalty time is over and they have been placed correctly by the assistant referees. If a player has been penalized by mistake, and some actions have followed so that in cannot be simply undone, penalties can be removed early by pressing the Shift key while clicking the player. This will, however, not remove any effects on the team's penalty counter and the penalty times of other