5. Soccer Monitor

5.1. Introduction

Soccer monitor provides a visual interface. Using the monitor we can watch a game vividly and control the proceeding of the game. .. By cooperating with logplayer, soccermonitor can replay games, so that it .. becomes very convenient to analyze and debug clients.

5.2. Getting started

To connect the soccer monitor with the soccer server, you can use the command following:

$ rcssmonitor

By specifying the options, you can modify the parameters of soccer monitor instead of modifying monitor configuration file. You can find available options by:

$ rcssmonitor --help

If you use script rcsoccersim to start the server, a monitor will be automatically started and connected with the server:

$ rcsoccersim

5.2.1. Total number of monitor clients

By default, there is no restriction on the number of monitor clients. You can restrict the number of monitor connections by changing the value of server::max_monitor parameter. This feature is useful when you want to reduce the load by limiting arbitrary connections from others.

If the value of server::max_monitor is negative integer (default:-1), no restriction. If the value is positive integer, the total number of monitor clients that can connect to the rcssserver is restricted within that number.

Suppose a new monitor client tries to connect to the server after the number of connected monitors has reached the server limit (max_monitor). In that case, the server will refuse the connection and send (error no_more_monitor) back to the monitor’s client.

5.3. Communication from Server to Monitor

Soccer monitor and rcssserver are connected via UDP/IP on port 6000 (default). When the server is connected with the monitor, it will send information to the monitor every cycle. rcssserver-15 provides four different formats (version 1 ~ 4). The server will decide which format is used according to the initial command sent by the monitor (see Communication from Monitor to Server). The detailed data structure information can be found in appendix sec-appendixmonitorstructs.

5.3.1. Version 1

rcssserver sends dispinfo_t structs to the soccer monitor. dispinfo_t contains a union with three different types of information:

  • showinfo_t: information needed to draw the scene

  • msginfo_t : contains the messages from the players and the referee shown in the bottom windows

  • drawinfo_t: information for monitor to draw circles, lines or points (not used by the server)

The size of dispinfo_t is determined by its largest subpart (msg) and is 2052 bytes (the union causes some extra network load and may be changed in future versions). In order to keep compatibility between different platforms, values in dispinfo_t are represented by network byte order. Which information is included is determined by the mode information. NO_INFO indicates no valid info contained (never sent by the server), BLANK_MODE tells the monitor to show a blank screen (used by logplayer) (see rcssserver-*/src/types.h):

NO_INFO    0
SHOW_MODE  1
MSG_MODE   2
DRAW_MODE  3
BLANK_MODE 4

Following is a description of these structs and the ones contained:

Showinfo

A showinfo_t struct is passed every cycle (100 ms) to the monitor and contains the state and positions of players and the ball:

typedef struct {
   char   pmode ;
   team_t team[2] ;
   pos_t  pos[MAX_PLAYER * 2 + 1] ;
   short  time ;
} showinfo_t ;
  • pmode: currently active playmode of the game (see rcssserver-*/src/types.h):

    PM_Null,
    PM_BeforeKickOff,
    PM_TimeOver,
    PM_PlayOn,
    PM_KickOff_Left,
    PM_KickOff_Right,
    PM_KickIn_Left,
    PM_KickIn_Right,
    PM_FreeKick_Left,
    PM_FreeKick_Right,
    PM_CornerKick_Left,
    PM_CornerKick_Right,
    PM_GoalKick_Left,
    PM_GoalKick_Right,
    PM_AfterGoal_Left,
    PM_AfterGoal_Right,
    PM_Drop_Ball,
    PM_OffSide_Left,
    PM_OffSide_Right,
    PM_PK_Left,
    PM_PK_Right,
    PM_FirstHalfOver,
    PM_Pause,
    PM_Human,
    PM_Foul_Charge_Left,
    PM_Foul_Charge_Right,
    PM_Foul_Push_Left,
    PM_Foul_Push_Right,
    PM_Foul_MultipleAttacker_Left,
    PM_Foul_MultipleAttacker_Right,
    PM_Foul_BallOut_Left,
    PM_Foul_BallOut_Right,
    PM_Back_Pass_Left,
    PM_Back_Pass_Right,
    PM_Free_Kick_Fault_Left,
    PM_Free_Kick_Fault_Right,
    PM_CatchFault_Left,
    PM_CatchFault_Right,
    PM_IndFreeKick_Left,
    PM_IndFreeKick_Right,
    PM_PenaltySetup_Left,
    PM_PenaltySetup_Right,
    PM_PenaltyReady_Left,
    PM_PenaltyReady_Right,
    PM_PenaltyTaken_Left,
    PM_PenaltyTaken_Right,
    PM_PenaltyMiss_Left,
    PM_PenaltyMiss_Right,
    PM_PenaltyScore_Left,
    PM_PenaltyScore_Right,
        PM_Illegal_Defense_Left,
    PM_Illegal_Defense_Right,
    PM_MAX
    
  • team: information about the teams. Index 0 is for team playing from left to right:

    typedef struct {
      char  name[16];  /* name of the team */
      short score;     /* current score of the team */
    } team_t;
    
  • pos: position information of ball and players. Index 0 represents the ball, indices 1 to 11 is for team[0] (left to right) and 12 to 22 for team[1]:

    typedef struct {
      short enable;
      short side;
      short unum;
      short angle;
      short x;
      short y;
    } pos_t;
    
  • time: current game time.

Values of the elements can be

  • enable: state of the object. Players not on the field (and the ball) have state DISABLE. The other bits of enable allow monitors to draw the state and action of a player more detailed (see rcssserver-*/src/types.h):

    DISABLE         0x00000000
    STAND           0x00000001
    KICK            0x00000002
    KICK_FAULT      0x00000004
    GOALIE          0x00000008
    CATCH           0x00000010
    CATCH_FAULT     0x00000020
    BALL_TO_PLAYER  0x00000040
    PLAYER_TO_BALL  0x00000080
    DISCARD         0x00000100
    LOST            0x00000200
    BALL_COLLIDE    0x00000400
    PLAYER_COLLIDE  0x00000800
    TACKLE          0x00001000
    TACKLE_FAULT    0x00002000
    BACK_PASS       0x00004000
    FREE_KICK_FAULT 0x00008000
    POST_COLLIDE    0x00010000
    FOUL_CHARGED    0x00020000
    YELLOW_CARD     0x00040000
    RED_CARD        0x00080000
        ILLEGAL_DEFENSE 0x00100000
    
  • side: side the player is playing on. LEFT means from left to right, NEUTRAL is the ball (rcssserver-*/src/types.h):

    LEFT     1
    NEUTRAL  0
    RIGHT   -1
    
  • unum: uniform number of a player ranging from 1 to 11

  • angle: angle the agent is facing ranging from -180 to 180 degrees, where -180 is view to the left side of the screen, -90 to the top, 0 to the right and 90 to the bottom.

  • x, y: position of the ball or player on the screen. (0, 0) is the midpoint of the field, x increases to the right, y to the bottom of the screen. Values are multiplied by SHOWINFO_SCALE (16) to reduce aliasing, so field size is PITCH_LENGTH * SHOWINFO_SCALE in x direction and PITCH_WIDTH * SHOWINFO_SCALE in y direction.

Messageinfo

Information containing the messages of players and the referee:

typedef struct {
  short board ;
  char  message[2048] ;
} msginfo_t;
  • board: indicates the type of message. A message with type MSG_BOARD is a message of the referee, LOG_BOARD are messages from and to the players. (rcssserver-*/param.h):

    MSG_BOARD 1
    LOG_BOARD 2
    
  • message: zero terminated string containing the message.

Drawinfo

Allows to specify information for the monitor to draw circles, lines or points.

5.3.2. Version 2

rcssserver sends dispinfo_t2 structs to the soccer monitor instead of dispinfo_t structs which is used in version 1. dispinfo_t2 contains a union with five different types of information (the data structures are printed in appendix :ref”sec-appendixmonitorstructs:

  • showinfo_t2: information needed to draw the scene. It includes all information on coordinates and speed of players and the ball, teamnames, scores, etc.

  • msginfo_t : contains the messages from the players and the referee. It also contains information on team’s images and information on player exchanges.

  • team graphic: The team graphic format requires a 256x64 image to be broken up into 8x8 tiles and has the form:

    (team_graphic_{l|r} (<X> <Y> "<XPM line>" ... "<XPM line>"))
    

    Where X and Y are the co-ordinates of the 8x8 tile in the complete 256x64 image, starting at 0 and ranging upto 31 and 7 respectively. Each XPM line is a line from the 8x8 xpm tile.

  • substitutions: substitutions are now explicitly recorded in the message board in the form:

    (change_player_type {l|r} <unum> <player_type>)
    
  • player_type_t: information describing different player’s abilities and tradeoffs

  • server_params_t: parameters and configurations of soccerserver

  • player_params_t: parameters of players

Which information is contained in the union is determined by the mode field. NO_INFO indicates no valid info contained (never sent by the server). BLANK_MODE tells the monitor to show a blank screen:

NO_INFO     0
SHOW_MODE   1
MSG_MODE    2
BLANK_MODE  4
PT_MODE     7
PARAM_MODE  8
PPARAM_MODE 9

5.3.3. Version 3

From the monitor protocol version 3, transferred data are represented by human readable text messages. Each data is represented by S-expression and sent to monitors as one UDP packet. This protocol is also used for recording the game log format version 4. Please note that PlayMode and Score in the show type message are separately recorded in the game log.

Below is a list of data types sent by the version 3 protocol:

  • server_param

  • player_param

  • player_type

  • show

  • msg

The format of server_param, player_param, and player_type messages are the same as the v8+ format for players and coaches. The msg type message may contain team_graphic data, as in the version 2 format.

The following table shows the format of other types of messages.

From server to monitor

(show Time PlayMode Score Ball *Player*+)
Time ::= simulation cycle of rcssserver
PlayMode ::= (pm PlayModeID)
Score ::= (tm LeftName RightName LeftScore RightScore [PenaltyScore])
PenaltyScore ::= LeftPenaltyScore LeftPenaltyMiss RightPenaltyScore RightPenaltyMiss
Ball ::= ((b) X Y VelX VelY)
Player ::=
((Side Unum) Type State X Y VelX VelY Body Neck [PointX PointY]
(v ViewQuality ViewWidth) (s *Stamina Effort Recovery [Capacity]))
[(f FocusSide FocusUnum)]
(c KickCount DashCount TurnCount CatchCount MoveCount TurnNeckCount ChangeViewCount)
SayCount TackleCount PointtoCount AttentiontoCount))
(msg Time BoardMessage”+)
Time ::= simulation cycle of rcssserver
Board ::= message board type id
Message ::= message string

5.3.4. Version 4

The version 4 protocol is almost same as the version 3. The information of players’ stamina capacity is contained in each player data of the show type message.

5.4. Communication from Monitor to Server

The monitor can send to the server the following commands (in all commands, <variable> has to be replaced with proper values):

(dispinit) | (dispinit version <version>)

sent to the server as first message to register as monitor (opposed to a player, that connects on port 6000 as well) . “(dispinit)” is for information version 1, while “(dispinit version 2)” is for version 2. You can change the version by setting the according monitor parameter. (See Settings and Parameters)

(dispstart)

sent to start (kick off) a game, start the second half or extended time. Ignored, when the game is already running.

(dispfoul <x> <y> <side>)

sent to indicate a foul situation. x and y are the coordinates of the foul, side is LEFT (1) for a free kick for the left team, NEUTRAL (0) for a drop ball and RIGHT (-1) for a free kick for the right team.

(dispdiscard <side> <unum>)

sent to show a player the red card (kick him out). side can be LEFT or RIGHT, unum is the number of the player (1 - 11).

(dispplayer <side> <unum> <posx> <posy> <ang>)

sent to place player at certain position with certain body angle, side can be LEFT (1) or RIGHT (-1), unum is the number of the player(1 - 11). Posx and posy indicate the new position of the player, which will be divided by SHOWINFO_SCALE. And ang indicate the new angle of a player in degrees. This command is added in the server 7.02.

(compression <level>)

The server supports compression of communication with its clients and monitors (since version 8.03). A monitor can send the above compression request to the server to start compressed communication. If the server is compiled without ZLib, the server will respond with (warning compression_unsupported) else <level> is not a number between 0 and 9 inclusive, the server will respond with (error illegal_command_form) else the server will respond with (ok compression <level>) and all subsequent messages to that client will be compressed at that level, until a new compression command is received. If a compression level above zero is selected, then the monitor is expected to compress its commands to the server. Specifying a level of zero turns off compression completely (default).

TODO: [12.0.0 pre-20071217] accept some coach commands from monitor

5.5. How to record and playback a game

To record games, you can call server with the argument:

server::game_logging = true

This parameter can be set in server.conf file. The logfile is recorded under server::game_log_dir directory. The default logfile name contains the datetime and the result of the game. You can use the fixed file name by using server::game_log_fixed and server::game_log_fixed_name.

server::game_log_fixed : true
server::game_log_fixed_name : 'rcssserver'

To specify the logfile version, you can call server with the argument:

server::game_log_version [1/2/3/4/5]

or set the parameter in server.conf file:

server::game_log_version : 5

You can replay recorded games using logplayer applications. The latest rcssmonitor (version 16 or later) can work as a logplayer. To replay logfiles just call rcssmonitor with the logfile name as argument, and then use the buttons on the window to start, stop, play backward, play stepwise.

5.5.1. Version 1 Protocol

Logfiles of version 1 (server versions up to 4.16) are a stream of consecutive dispinfo_t chunks. Due to the structure of dispinfo_t as a union, a lot of bytes have been wasted leading to impractical logfile sizes. This lead to the introduction of a new logfile format 2.

5.5.2. Version 2 Protocol

Version 2 logfile protocol tries to avoid redundant or unused data for the price of not having uniform data structs. The format is as follows:

  • head of the file: the head of the file is used to autodetect the version of the logfile. If there is no head, Unix-version 1 is assumed. 3 chars ‘ULG’ : indicating that this is a Unix logfile (to distinguish from Windows format)

  • char version : version of the logfile format

  • body: the rest of the file contains the data in chunks of the following format:

  • short mode: this is the mode part of the dispinfo_t struct (see Version 1 Protocol Version 1) SHOW_MODE for showinfo_t information MSG_MODE for msginfo_t information

  • If mode is SHOW_MODE, a showinfo_t struct is following.

  • If mode is MSG_MODE, next bytes are
    • short board: containing the board info

    • short length: containing the length of the message (including zero terminator)

    • string msg: length chars containing the message

Other info such as DRAW_MODE and BLANK_MODE are not saved to log files. There is still room for optimization of space. The team names could be part of the head of the file and only stored once. The unum part of a player could be implicitly taken from array indices.

Be aware of, that information chunks in version 2 do not have the same size, so you can not just seek SIZE bytes back in the stream when playing log files backward. You have to read in the whole file at once or (as is done) have at least to save stream positions of the showinfo_t chunks to be able to play log files backward.

In order to keep compatibility between different platforms, values are represented by network byte order.

5.5.3. Version 3 Protocol

The version 3 logfile protocol contains player parameter information for heterogenous players and optimizes space. The format is as follows:

  • head of the file: Just like version 2, the file starts with the magic characters ‘ULG’.

  • char version : version of the logfile format, i.e. 3

  • body: The rest of the file contains shorts that specify which data structures will follow.
    • If the short is PM_MODE,
      • a char specifying the play mode follows. This is only written when the playmode changes.

    • If the short is TEAM_MODE,
      • a team_t struct for the left side and

      • a team_t struct for the right side follow. Team data is only written if a new team connects or the score changes.

    • If the short is SHOW_MODE,
      • a short_showinfo_t2 struct specifying ball and player positions and states follows.

    • If the short is MSG_MODE,
      • a short specifying the message board,

      • a short specifying the length of the message,

      • a string containing the message will follow.

    • If the short is PARAM_MODE,
      • a server_params_t struct specifying the current server parameters follows. This is only written once at the beginning of the logfile.

    • If the short is PPARAM_MODE,
      • a player_params_t struct specifying the current hetro player parameters. This is only written once at the beginning of the logfile.

    • If the short is PT_MODE,
      • a player_type_t struct specifying the parameters of a specific player type follows. This is only written once for each player type at the beginning of the logfile.

Data Conversion:

  • Values such as x, y positions are meters multiplied by SHOWINFO_SCALE2.

  • Values such as deltax, deltay are meters/cycle multiplied by SHOWINFO_SCALE2.

  • Values such as body_angle, head_angle and view_width are in radians multiplied by SHOWINFO_SCALE2.

  • Other values such as stamina, effort and recovery have also been multiplied by SHOWINFO_SCALE2.

5.5.4. Version 4 Protocol

The version 4 logfile protocol is a text-based format, that may be readable for humans, adopted in rcssserver version 12 or later. Each line contains one data in S-expression like sensory messages. Its grammar is almost the same as monitor protocol version 3.

  • head of the file: Just like older versions, the file starts with the magic characters ‘ULG’.

  • char version : version of the logfile format, i.e. 4

  • new line

  • body: In the rest of the file, one of the following data is recorded on each line:
    • server_param

    • player_param

    • player_type

    • msg

    • playmode

    • team

    • show

msg may contain various string data, such as team_graphic, the result of the game, and so on. Starting with the server version 12.1.0, the game result is recorded using msg data at the end of the game log. See Version 3 in detail.

5.5.5. Version 5 Protocol

The version 5 logfile protocol is adopted in rcssserver version 13 or later. Its grammar is almost the same as the version 4 protocol, except adding stamina_capacity information to each player data.

5.5.6. Settings and Parameters

rcssmonitor has various modifiable parameters. You can check available options by calling rcssmonitor with --help argument:

rcssmonitor --help

Several parameters can be modified from View menu after invoking rcssmonitor.

Some parameters are recorded in ~/.rcssmonitor.conf, and rcssmonitor will reuse them in the next execution. Of course, you can directly edit this configuration file.

5.6. Team Graphic

TODO

5.7. What’s New

16.0:
  • Support illegal defense information.

  • Integrate a log player feature.

  • Implement a time-shift reply feature.

  • Remove a buffering mode.

  • Change the default tool kit to Qt5.

  • Support CMake.

15.0:
  • Support v15 server parameters.

14.1:
  • Support an auto reconnection feature.

14.0:
  • Reimplement using Qt4.

  • Support players’ card status.

  • Implement a buffering mode.

13.1:
  • Support a team_graphic message.

13.0:
  • Support the monitor protocl version 4.

  • Support a stamina capacity information.

12.1:
  • Support pointto information.

  • Implement an auto reconnection feature.

12.0:
  • Support the monitor protocl version 3.

11.0.2:
  • Support the penalty kick scores.

11.0:
  • Support 64bits OS.

10.0:
  • Ported to OS X.

9.1:
  • Support a keepaway field.

8.03:

  • The server supports compressed communication to monitors as described in section 5.4

  • Player substitution information is added to the message log

  • Team graphics information is added to the message log

7.07:

  • The logplayer did not send server param, player param, and player type messages. This has been fixed.

  • The monitor would crash on some logfiles because stamina max seemed to be set to 0. The monitor will no longer crash this way.

Parameter Name
Used Value
Default
Explanation

host

localhost

Localhost

hostname of soccerserver

port

6000

6000

port number of soccerserver

version

2

1

monitor protocol version

length magnify

6.0

6.0

magnification of size of field

goal width

14.02

7.32

goal width

print log

off

On

flag for display log of communication [on/off]

Log line

6

6

size of log window

Print mark

on

On

flag for display mark on field [on/off]

mark file name

mark.RoboCup.grey.xbm

Mark.xbm

mark on field use file name

ball_file_name

ball-s.xbm

Ball.xbm

ball use file name

player_widget_size

9.0

1.0

size of player widget

player_widget_font

5x8

Fixed

font(uniform number) of player widget

Uniform_num_pos_x

2

2

position (X) of player uniform number

Uniform_num_pos_y

8

8

position (Y) of player uniform number

team_l_color

Gold

Gold

Team_L color

team_r_color

Red

Red

Team_R color

goalie_l_color

Green

Green

Team_L Goalie color

goalie_r_color

Purple

Purple

Team_R Goalie color

neck_l_color

Black

Black

Team_L Neck color

neck_r_color

Black

Black

Team_R Neck color

Goalie_neck_l_color

Black

Black

Team_L Goalie Neck color

Goalie_neck_r_color

Black

Black

Team_R Goalie Neck color

status_font

7x14bold

Fixed

status line font [team name and score, time, play_mode]

popup_msg

off

Off

flag for pop up and down “GOAL!!” and “Offside!” [on/off]

Goal_label_width

120

120

pop up and down “GOAL!!” label width

Goal_label_font

-adobe-times bold-r---34--- ----*

Fixed

pop up and down “GOAL!!” label font

Goal_score_width

40

40

pop up and down “GOAL!!” score width

Goal_score_font

-adobe-times bold-r---25--- ----*

Fixed

pop up and down “GOAL!!” score font

Offside_label_width

120

120

pop up and down“Offside!” label width

Offside_label_font

-adobe-times bold-r---34--- ----*

Fixed

pop up and down “Offside!” label font

eval

off

Off

flag for evaluation mode

redraw_player

on

Off

always redraw player (needed for RH 5.2)

7.05:

  • For quite some time, the logplayer has occasionally “skipped” so that certain cycles were never displayed by the logplayer. This seems to be caused by the logplayer sending too many UDP packets for the monitor to receive. Therefore, a new parameter has been added to the logplayer ’message delay interval’. After sending that many messages, the logplayer sleeps for 1 microsecond, giving the monitor a chance to catch up. This is not a guaranteed to work, but it seems to help significantly. If you still have a problem with the logplayer/monitor “skipping”, try reducing message delay interval from it’s default value of 10. Setting message delay interval to a negative number causes there to be no delay.

  • The server used to truncate messages received from the players and coach to 128 characters before recording them in the logfile. This has been fixed.

7.04:

  • If a client connects with version > 7.0, all angles sent out by the server are rounded instead of truncated (as they were previously) This makes the error from quantization of angles (i.e. conversion of floats to ints) both uniform throughout the domain and two sided. This change was also made to all values put into the dispinfo t structure for the monitors and logfiles.

7.02:

7.00:

  • Included the head angle into the display of the soccermonitor. (source contributed by Ken Nguyen)

  • Included visualization effect when the player collided with the ball or the player collided with another player. The monitor displays both cases with a black circle around the player.

  • Introduced new monitor protocol version 2. (See 5.5.2 Version 2 and 5.4 Commands From Monitor to Server)

  • Introduced new logging protocol version 3. (See 5.5.3 Version 3 Protocol)

  • Fixed logging so that the last cycle of a game is logged.