This is the GameController software for robot soccer games in the RoboCup Standard Platform League.
winget install LLVM
set LIBCLANG_PATH 'C:\Program Files\LLVM\bin\'First, the frontend must be compiled:
cd frontend
npm ci
npm run buildThe Rust code is compiled with cargo:
cargo build [-r]First, thank you for contributing to development.
This will install the tauri CLI:
cargo install tauri-cliThis will start the frontend and backend in dev mode:
cargo tauri devFor 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 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).
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:
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).RoboCupGameControlReturnData in game_controller_msgs/headers/RoboCupGameControlData.h).In addition, the GameController offers an interface for monitor applications (such as the TeamCommunicationMonitor or the EventRecorder):
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.RGTD).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.
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 -- -hNote that release builds on Windows do not output any text.
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:
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.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.
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 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.
Some penalties are special:
As per the rule book, team messages are counted (based on the port that they are sent on) during the Ready, Set, and Playing states (but not in penalty shoot-outs). When a team message arrives that is either too large or beyond the team's message budget, the score resets to 0 and future goals will not be counted. The score and the message counter change to a different color then.
A timeout can be taken both by the teams and by the referee. When a timeout is taken during the Ready or Set state, the clock is reset to the beginning of the stoppage of play, but not the message budget.
When a timeout is taken while the half-time break timer counts down, the timer is adjusted by the duration of a timeout. This can cause confusion in so-called interleaved games because the half-time break is often longer than usual, so that even after taking a timeout that half-time break timer can still be negative.
A minute of extra time can be added by pressing the "+" button next to the main clock. This button becomes available during stoppages of play once a minute of play has elapsed in the half. Adding a minute of extra time also increases the message budget for both teams, unless a team had communicated illegally before.
To substitute players, first click the "Substitute" button on the team's side. Then, click the player which should be removed from play. The list of players will now change to the list of available substitutes (note that this list is scrollable). From this list, the player that shall replace the previously selected player is clicked. Depending on the game state, the new player gets a penalty or inherits the penalty of the substituted player. The goalkeeper property is tranferred to the substitute, i.e. when the goalkeeper is substituted, the substitute is expected to wear a goalkeeper jersey and inherits the privileges of the goalkeeper.
This feature must also be used before the start of a half in order to match the set of players in the GameController to the players that are actually on the field. If a team wants to play with a goalkeeper with a number from 2-7 (or 2-5 in the Challenge Shield), this must be done using three substitutions (e.g. if a team wants to play with players 1-7, but have the 3 be the goalkeeper, it must substitute 8 for 1, 1 for 3, 3 for 8).
A penalty shoot-out can only be started after two halves have been played and the score is equal. However, it does not depend on the game mode, because penalty shoot-outs can already be needed in games in which the clock does not stop during the Ready and Set states. It is only allowed to switch to the next shot as long as the result of the game is not clear yet.
The Playing state can be entered once players on both sides are selected. This is done by clicking the "Select" button (in place of the "Substitute" button). First, the color of the selected player must be selected. This is because in a penalty shoot-out, the jersey color does not necessarily match the designation as goalkeeper or kicker, and the GameController cannot know which players are wearing which jersey. After the color has been selected, a scrollable list of players appears (similar to substitution).
At the bottom of the window, a timeline of the last five actions applied by the user is filled from right to left. Clicking on one of the actions there restores the entire game to the state immediately before that action was applied. It is not possible to undo individual actions that have been followed by other actions. The undo history is actually not limited to the last five actions, i.e. previous actions appear once some actions are undone.
Actions that were applied automatically (e.g. because a timer elapsed) do not appear in the undo history. This is because they would be applied again immediately if they were undone.
The GameController writes log files to the directory logs.
They can get quite large because they are YAML.
The main reason for YAML is that it is human-readable and can be appended (in contrast to JSON which requires a closing bracket in the end to be well-formed).
These log files can be analyzed by the programs from the game_controller_logs package or replayed using the TeamCommunicationMonitor.