Referee Box User’s Manual

This page describes the operation of the referee box. It is intended to serve as a reference for referees and referee box operators. It will hopefully also be helpful to teams, as it explains the sequence of events that take place in a game and describes the different commands and stages. For specific details on the protocol, see protocol; this page instead describes the commands at a high level and explains how they relate to each other and what sequences of commands occur during a game.

Big Four Buttons

At the top of the window are the big four buttons: halt, stop, force start, and normal start. These are some of the most frequently used buttons in the referee box.

  • The halt button sends the HALT command, which orders all robots to completely stop moving immediately. Ideally, teams should implement HALT by braking or coasting their motors, so that robots will stop moving even if vision is not working properly. In the halt state, no time passes: if halt is entered from a game stage which has a clock, the game clock stops; if halt is entered from a timeout, the timeout clock stops. If entered from a timeout, the halt state can be exited by resuming the timeout or by stopping (which ends the timeout); otherwise, the halt state can be exited by stopping. The halt state is used when the referee needs to take a long time to retrieve and place the ball (e.g. if it was chipped beyond the field walls), when the referee needs to talk to the teams, when the vision expert notices a vision problem, or in an emergency (e.g. robot out of control, foreign object on the field, robot tipped over, robot on fire).
  • The stop button sends the STOP command, which takes the ball out of play and orders all robots to stay at least 50 centimetres from the ball. This is the most commonly used button in the referee box: stop is used to get ready to start play at the end of a halt or timeout, to get ready to start play at the beginning of a new game stage, and to stop play when the ball exits the field or after a goal is scored. In the stop state, the game clock continues to run; during this time, teams’ designated robot handlers are allowed to manipulate their robots (with the referee’s permission).
  • The force start button sends the FORCE_START command, which indicates a neutral restart—both teams are allowed to approach and grab the ball immediately. This is used if lack of progress occurs (e.g. the robots get stuck and fail to move significantly during play, or a team fails to grab the ball when given a favourable restart) or if the game was halted while in play due to an emergency or vision problem and needs to be restarted without favouring either team.
  • The normal start button sends the NORMAL_START command. This is used only following a PREPARE_* command, that is to say, a kickoff or penalty kick. These two types of restarts have distinct prepare and execute phases, with the individual restart button starting the prepare phase and the normal start button actually putting the ball in play and allowing the favoured team to touch the ball.

Goals and Team Names

Below the big four buttons are two large indicators showing the number of goals scored by each team (excluding penalty shootout goals when in the penalty shootout game stage). Below each indicator is a coloured bar showing which team the number applies to; these bars are editable drop-down boxes in which the teams’ names should be selected or typed (these can only be changed in halt). The button labelled “←→” swaps all attributes of the two teams (goals, names, timeouts, and cards), and is used in the rare case where a team wants to swap colour at half-time; this button is also available only in halt.

Game Status

The left part of this section shows, from top to bottom, the current game stage, the time elapsed in the game stage, the time left in the game stage, and the current state of play. As the referee box operator, it is your responsibility to monitor the time left in the current game stage (whether play or half-time) and notify the referee when this reaches zero. For a play stage, the referee will likely allow the current play to end after the time expires, and may allocate some extra time if excessive time was wasted during play for some reason. Also, should play stop in a way that leads to a penalty kick, the penalty kick is always taken even if no time is left in the stage.

The middle part provides a few additional buttons. The goal buttons award goals to the specified team and are available in stop. Each goal button has an adjacent minus button which subtracts a goal, to be used if a goal is accidentally awarded to the wrong team or when it should not have been. The cancel card or timeout button is available immediately after issuing a yellow or red card or starting a timeout and reverts all effects of the action: for a red card (usable in stop), the card count is decremented; for a yellow card (also usable in stop), the card is deissued and the timers are updated appropriately; for a timeout (usable while inside the timeout), the number of timeouts remaining is incremented and the timeout clock is reset to the value it had when the timeout was started, and the game is moved to the stop state. Thus, this button should be used immediately after accidentally issuing a card or timeout inappropriately (for cards, the button remains available throughout state and even stage changes, but obviously the card should be cancelled as soon as possible to minimize impact on gameplay).

The right part provides buttons for moving between game stages:

  • The first half, second half, overtime1, and overtime2 buttons require some explanation: these buttons do not actually enter the specified game stage. Instead, they move to the associated *_PRE stage and place the game in halt. These special stages count time but do not have proper game clocks. The operator, at the referee’s instruction, must then issue stop followed by kickoff. At the instant the normal start command is issued for the kickoff, the referee box automatically transitions to the main stage and starts the game clock for that stage; thus, time spent lining up robots before the first kickoff is not counted against the game clock. Note that the second half, overtime1, and overtime2 buttons must be pressed to move from half-time to the specified *_PRE stage, but the first half button is normally never used because the referee box starts in the NORMAL_FIRST_HALF_PRE stage.
  • The penalty shootout button transitions to the PENALTY_SHOOTOUT stage (there is no PENALTY_SHOOTOUT_PRE stage as the penalty shootout does not have a game clock), in which special procedures are followed and the referee box is substantially reconfigured; see below for details.
  • The half-time button always enters the next specified break, whether half-time between normal halves, the break between normal second half and overtime1, the half-time between overtime1 and overtime2, or the break between overtime2 and penalty shootout. The half-time button automatically chooses the proper break to enter, configures the game clock to count time in that break, and enables the proper stage button for moving to the next stage. The game is by defaulted halted during breaks, but stop and force start can be issued if desired for testing purposes. Half-time is unusual in that the game clock continues counting even in halt. Also, no matter what command is sent, yellow cards do not count down during half-time.
  • The end game button sends the POST_GAME stage and locks all controls, allowing the game results to be displayed for as long as desired after the game. The end game button should be used in all official games as logging systems may benefit from being informed of the end of a game. Be careful when clicking the end game button; because it disables all UI controls, there is no way to switch to any other game stage! However, the crash state recorder stops in end game, so if it is absolutely necessary to escape from an end game stage, close the referee box and use the crash recovery option described below.

Team Controls

At the top of each team’s control rectangle are the controls and indicators for the team’s timeouts. A team can enter timeout only from the stop state. The referee box records the amount of timeout time and the number of timeouts each team has left, but it does not prevent the operator from starting a timeout when that should be impossible—it is at the referee’s discretion to permit additional timeouts in exceptional circumstances, and the referee box allows this. Timeouts can be taken during normal play stages or during *_PRE stages, but not during breaks. Once a timeout is issued, the game clock stops, a timeout is subtracted from the team’s stock, and the team’s timeout clock starts counting down. There are three actions available within a timeout: the stop button finishes the timeout and resumes the game (the normal way to end a timeout), the halt button stops the timeout clock from counting (to be used if the referee needs to consult with teams without penalizing them for timeout time) and allows either resuming the timeout (with the timeout resume button) or ending it (with the stop button), and the cancel card or timeout button reverts the timeout as if it never happened, resetting the timeout count and clock to their original values.

Below the timeout controls is the goalie selector. This field, which can be adjusted in halt and stop, must be set to the SSL-Vision index of the team’s goalie. This value is sent to the teams and can be used to detect a second defender in the defence area. This value must be adjusted using the mouse buttons on the spinner arrows or the up and down arrow keys; direct numerical entry is disabled to avoid confusion between typing numbers and pressing command hotkeys.

Below the goalie selector are the four favourable restart buttons:

  • Kickoff orders the team to prepare to take a kickoff. The normal start button is used to execute the kickoff.
  • Penalty orders the team to prepare to take a penalty kick. The normal start button is used to execute the penalty kick.
  • Freekick orders the team to immediately execute a direct free kick. The normal start button is not used. In addition to direct free kicks explicitly awarded due to offences, this button is also used for goal kicks and corner kicks.
  • Indirect orders the team to immediately execute an indirect free kick. The normal start button is not used. In addition to indirect free kicks explicitly awarded due to offences, this button is also used for throw-ins.

Finally, at the bottom of each team’s rectangle are the card buttons. The yellow card button issues a yellow card to the team and displays the time remaining on the card; additional cards will be represented by a count in brackets (e.g. “(+1)” means there are two yellow cards issued, the one whose time is shown plus one more) and will display their time once the first card expires. It is the responsibility of the referee box operator to watch the yellow card timer and inform the referee when it reaches zero, thus allowing a robot to be placed back on the field at the next stoppage of play. Red cards do not have timers, but a count of issued red cards is shown on the button. In both cases, the last issued card can be cancelled using the cancel card or timeout button.

Penalty Shootout

The penalty shootout game stage changes the operation of the referee box quite a lot:

  • There is no game clock in penalty shootout. Because there is no game clock, there is also no pre-game stage.
  • The only available restart is a penalty kick; force start, kickoff, and (direct and indirect) free kick are not available.
  • Timeouts are not available.
  • Goals are shown in a separate field in game status, starting from zero, rather than being added to the main goal count—they are added to the main goal count in the end game stage and in the network packets sent to teams, however.

A Typical Game

A typical game would begin with pre-game setup. Here, the referee box operator sets the names of the two teams in the name fields (immediately below the score indicators), and also sets the initial goalie indices for the two teams.

To start the game, the operator will first issue stop, noting that the referee box is already in the pre-game state. The robots will now start moving. The referee will call for a kickoff of the appropriate team, which must be entered. Finally, once the referee is satisfied the robots are in position, a normal start is issued and the first half begins. Normal gameplay proceeds as a series of stops followed by restarts (force starts, direct and indirect free kicks, and kickoffs and penalty kicks with normal starts), interleaved with occasional goals, cards, and timeouts.

When the game clock reaches zero, the referee box operator communicates this fact to the referee. Once the referee is ready to enter half-time, the referee box operator pushes the half time button. At the end of half time, the referee acknowledges the end of half time and the operator pushes the second half button. From here, play starts with a kickoff just as at the start of the game.

At the end of the second half, if the scores are different or if a round-robin game is being played, the operator pushes end game; otherwise, the operator pushes half time and a break occurs before the start of first overtime period. This break, the two overtime periods, and the break between them run just like normal time, the second overtime period again ending with either end game (if the scores are different) or half time (if they are the same and a penalty shootout is needed).

If a penalty shootout is taken, the penalty shootout button starts the stage, after which the shootout is executed as a series of stop, penalty, normal start sequences. Once the necessary goal difference is obtained, the operator pushes end game.

Crash Recovery

On every game stage change, every new command, every five seconds, and whenever the referee box is closed, the complete state of the referee box is written to disk in a file called “referee.sav” (the filename can be changed with the SAVE directive in referee.conf, in the “files” section). In case the referee box crashes, or even a power failure brings down the entire computer, the state can be reloaded by adding the “-r” flag on the referee box command line. This always leaves the referee box in the halt state, for safety reasons; in the case of a timeout, the timeout resume button is available. This is also the only way to recover from accidentally pressing the end game button: post-game states are never saved to the recovery file, so closing the referee box and running it with “-r” will return it to the state it was in before ending the game.

Be careful: only one file is used (“referee.sav”), so if you run the referee box without “-r”, the recovery data from the previous run is gone forever!

Ignoring the Rules

If you need to do something extremely unorthodox, or you get into a very bad state and need to get out of it, you can use the Config / Ignore Rules option. This enables every single button in the referee box no matter what game state and stage are active. Many of the buttons will still not do anything, and some of them may do unexpected things, but this may be useful as a last resort—for example, all the game stage buttons are enabled, allowing you to go backwards in the stage progression if necessary (even using the first half button to go back to pre-game). The ignore rules command should almost certainly not be used during an official game, at least not without consulting an expert first, but it may be convenient for testing. In any case, it should be turned off as soon as possible once the job is done. Inappropriate use of the ignore rules command may seriously confuse the referee box and/or teams’ AIs.


The referee box ships with a scoreboard suitable for showing to spectators on an overhead projector or large TV, in the “scoreboard” directory, which you can compile separately. The scoreboard should be run from that directory, with the command “./scoreboard”. If your network interface is not named “eth0”, you will need to specify it on the scoreboard commandline, e.g. “./scoreboard -i eth1”. The scoreboard can be run on the same computer as the referee box or on another computer; its only input is the referee box packets on the network.

By default the scoreboard will show the name of a team in plain text, but if you add files to the “flags” or “logos” directory (or both), the team’s logo and/or national flag will be shown instead—there is no mapping database between team names and files; rather, the name of the file must be exactly the name of the team from the referee box plus the extension “.png”.

The scoreboard can be made full-screen by pressing F on the keyboard.