Tao of Soccer Manual

Related Background and History

Professor Alan Mackworth first proposed robotic soccer as a test bed for multi-agent robotics research in his paper "On Seeing Robots" in 1992. The world's first soccer-playing robots Dynamites were built in The Laboratory for Computational Intelligence (LCI) headed by professor Mackworth.

In June 1993, a group of researchers in Japan, including Minoru Asada, Yasuo Kuniyoshi, and Hiroaki Kitano, decided to launch a robotic soccer competition. They named it Robot World Cup, RoboCup for short. The first Robocup was held during the International Joint Conference on Artificial Intelligence (IJCAI) in 1997, in Nagoya, Japan.

To satisfy the need for a common environment, the Soccer Server was developed by Noda Itsuki to make it possible to compare various AI algorithms for multi-agent systems. Because the physical abilities of the players are all identical in the server, individual and team strategies are the focus of comparison. The Soccer Server is used by many researchers and has been chosen as the official simulator for the RoboCup Simulation League.

During his Master's thesis research, Yu Zhang has been wondering who would be the winner if a team of AI programs compete with a team of human players in a simulated virtual soccer game. Noda's Soccer Server has complicated client/server protocol which makes it very hard for a human player to have a fair competition with AI programs. In his Master's Thesis, Yu Zhang proposed to build a new soccer simulation environment which has a simplified client/server interface by letting the server do the low level actions, so human players can fairly compete with robots on a strategic multi-agent cooperation level. Encouraged by professor Mackworth, Yu started to write this new soccer simulation game "The Tao of Soccer".

Player's User Guide

TOS is a multi-player game. Up to 22 players can join two opposing teams against each other over the Internet by linking to a soccer server. You can control the player by mouse and keyboard, or you may write an AI program to fight for you.

You may also play it as a single-player game. The Game will set up some AI teammates and opponents for you.

Start a new game

1,
=======================================
LINUX
=======================================

Start game by typing in a Term:

sh soccer

=======================================
WINDOWS
=======================================

Start game by typing in a DOS window

soccer.bat

A SoccerMaster window opens up.

2, If you want to turn on or turn off the sound and music, or turn on or turn off the Player Id and chat display, or turn on or turn off the 3D/2D display, go to Settings menu item.

3, If you want to run the soccer server locally, click toolbar icon , or select Game menu item Set Up Local Server.
A Server dialog opens up.

4, The default soccer server port number is 7777. You may also change server properties by providing a property file. Take a look at this property file sample.

5, You can type server commands in the Input field. The Server output is shown in Output area. The current available server commands are:


  1. left_name XXX - Set left team name to XXX.
  2. right_name XXX - Set right team name to XXX.
  3. help - print out the available server commands.
  4. quit - Exits the server killing all game related processes.

6, Click OK to start the soccer server, some message appears in Output area indicating the successful server start up.
Click Close to close the server dialog. You can reopen it later by clicking toolbar icon or selecting Game menu item Set Up Local Server.
Click Off to stop the soccer server.

7, To join a game, click toolbar icon , or select Game menu item Play Game.
A Play dialog opens up.
Choose the side, also select the server controls if you want to step forward, fast forward the server simulation, and input the server name and port, then click OK.
A soccer player appears as a circle on the soccer field. The rear half of the circle is painted blue to represent that the player is under your control. The front half is painted yellow if the player is in the left team, otherwise it's painted red. In 3D display, the player under your control has a blue circle under him.

8, To set up AI players locally, click toolbar icon , or select Game menu item Set Up Local AI Players.
An AI Players dialog opens up.

9, Type an AI command in the Command Line field, click On to run the AI program. Now the excuted AI command appears in Current Active Command Combobox. You can type AI control commands for the Current Active Command in the Input field, and the feedback from the Current Active Command displays in the Output area.

10, Click Close to close the AI Players dialog. You can reopen it later by clicking toolbar icon or selecting Game menu item Set Up Local AI Players.
Click Off to stop the Current Active Command.

Play the game


You can use both keyboard and mouse to control the player on the field.

  1. Keyborad Control Commands

    1. Force Control

      1. '1': set force to 0
      2. '2': set force to 15
      3. '3': set force to 30
      4. '4': set force to 45
      5. '5': set force to 60
      6. '6': set force to 70
      7. '7': set force to 80
      8. '8': set force to 90
      9. '9': set force to 100
      10. Up: add 15 to the force
      11. Shift+Up: add 30 to the force
      12. Down: minus 15 to the force
      13. Shift+Down: minus 30 to the force

    2. Direction Control

      1. Left: 10 degrees left turn
      2. Shift+Left: 40 degrees left turn
      3. Right: 10 degrees right turn
      4. Shift+Right: 40 degrees right turn

    3. Ball Control

      1. Space: If the player has the ball, kick the ball with full force to the player's facing direction; else, chase the ball.
      2. Enter: If the player has the ball, shoot the ball to the opponent's goal; else, this command has no effect.


  2. Mouse Control Commands

    1. Left Click at X,Y: the player runs to X,Y
    2. Right Click at X,Y: If the player has the ball, kick the ball to X,Y; else, this command has no effect.

You may communicate with your teammates by typing words in Chat.
The length of what you type can not be longer than 30. You are allowed to send out one message every 30 seconds. The message can be seen by both teams, wich will appear on the top of the displayed Soccer Field.

View the game


To view a game, click toolbar icon , or select Game menu item View Game.
A View dialog opens up.
Input the server name and port, then click OK.

End the game


To exit playing or viewing the current game, click toolbar icon , or select Game menu item Stop Playing/Viewing Game. You may restart playing by clicking toolbar icon or selecting Game menu item Play Game, you may also restart viewing by clicking toolbar icon or selecting
Game menu item View Game.

Record and Replay the game


To record a series of games, use '-lo' option to start the soccer server, then the server will record the games to files called "saved0", "saved1", ...

To replay the recorded games at the client side, use VCR like buttons on the tool bar to operate on the saved game file, such as "saved0".

Control the game simulation in Coach Mode


If you've turned on the coach ability when joing a game, you can also step forward, play, and fast forward the game simulation. This can be useful for debugging AI programs.

Soccer Server Simulation Guide

Rules Simulation

The Field of Play


The field of play in TOS is 2D rectangular. The touch line is 100 meters long. The goal line is 65 meters long. The field of play is divided into two halves by a halfway line. The centre mark is indicated at the midpoint of the halfway line. A circle with a radius of 9 meters is marked around it.

The width of the goal is 8 meters. The depth of the goal is 2 meters. The width of the goal area is 18 meters. The depth of the goal area is 6 meters. The width of the penalty area is 40 meters. The depth of the penalty area is 16 meters. Within each penalty area a penalty mark is made 12 meters from the midpoint between the goalposts and equidistant to them. An arc of a circle with a radius of 9 meters from each penalty mark is drawn outside the penalty area.

A quarter circle with a radius of 1 meter from each corner is drawn inside the field of play.

Players and Ball

Number of Players


A match is played by two teams, each consisting of not more than eleven players. Each player is controlled by a client process or thread.

Physics Simulation


The players and the ball are treated as circles. All distances and angles used and reported are to the centers of the circles. The time model is discrete, at the end of the time step, the server takes all action commands received and applies them to the objects on the field, using the current position and velocity information to calculate a new position and velocity for each object, then the server sends visual information back to clients. The default time step is 50 ms.

A client only needs to send one control command (kick or drive) for every INERTIA steps. The default value of INERTIA is 1. This command will be used at each of these INERTIA steps to calculate the dynamics of the player and the ball.

In each simulation step, movement of each player is calculated in the following manner:

P1 is player's current position, P0 is player's previous position.
V1 is player's current velocity, V0 is player's previous velocity.
A1 is player's current acceleration, A0 is player's previous acceleration.

FORCE is set by client.

Coefficient K1 is the force factor. K2 is the friction factor.
They are calculated by setting constant MaxSpeed and TimeToMax.

MaxSpeed is the maximum speed the player can reach. TimeToMax is the amount of time a player needs to reach full speed without friction. TimeStep is the length of one simulation step, defaulted to 0.1 sec.
MaxForce is the maximum force a player can apply, defaulted to 100.

In a similar way, movement of the ball is calculated as:

K1 is the kick force factor. It is calculated as:

MaxKick is the maximum kick force a player can apply, defaulted to 100.

When there are several players very close to the ball, one of them is randomly chosen as the controller of the ball. The controller of the ball can kick the ball by sending the kick command, or he can dribble the ball by sending normal drive command, but the acceleration is reduced as:

Collisions

When more than two players overlap, all of them are moved back until they do not overlap. Then their velocities are multiplied by -0.1.

Uncertainty

In order to reflect unexpected movements of objects in real world, TOS adds noise to the movement of objects and parameters of commands.

As for player movements, noise is added as follows:

As for the free ball movement, noise is added as follows:

When the player kicks the ball, noise is added to the kicking direction as follows:

The Duration of Play

Once the server starts, it enters a 4-period match cycle until it is turned off.

  1. Pre_Game: 0 - 5 min. Players enter the soccer field, move around, kick the ball.
    The referee is not activated. No score is recorded.

  2. First_Half: 5 - 15 min. The game starts. The referee is activated to enforce the soccer rule.
  3. Half_Time: 15 - 20 min. The referee is deactivated.
  4. Second_Half: 20 - 30 min. The game restarts. The referee is reactivated to enforce the soccer rule.

The Start of Play

A kick-off is a way of starting or restarting play:

When the kick-off mode is on, the opponents of the team taking the kick-off are at least 9 meters from the ball until it is in play.

Method of Scoring

A goal is scored when the whole of the ball passes over the goal line, between the goalposts. The team scoring the greater number of goals during a match is the winner. If both teams score an equal number of goals, or if no goals are scored, the match is drawn.

Throw-In

A throw-in is a method of restarting play. A throw-in is awarded when the whole of the ball passes over the touch line, from the point where it crossed the touch line to the opponents of the player who last touched the ball.

Goal Kick

A goal kick is a method of restarting play. A goal kick is awarded when the whole of the ball, having last touched a player of the attacking team, passes over the goal line, and a goal is not scored.

When the goal-kick mode is on, the ball is kicked from the corner of the penalty area by a player of the defending team. The opponents are at least 9 meters from the ball until it is in play.

Corner Kick

A corner kick is a method of restarting play. A corner kick is awarded when the whole of the ball, having last touched a player of the defending team, passes over th goal line, and a goal is not scored.

When the corner-kick mode is on, the ball is kicked from the inside of the corner arc by a player of the offending team. The opponents are at least 9 meters from the ball until it is in play.

Offside

A player is in an offside position if he is nearer to his opponent's goal line than both the ball and the second last opponent unless he or the ball is in his own half of the field of play.

A player in an offside position is only penalized if, at the moment the ball touches or is played by one of his team.

If a player is declared offside, the server awards an indirect free kick, which shall be taken by a player of the opposing team from the place where the infringement occurred.

This rule can be turned off by starting the server using "-no" option.

Client/Server Interface

The client communicates with the server by exchanging plain text over network through UDP sockets. The sever sends sensor information to clients so that clients know what is happening on the soccer field; in turn, clients send their commands to the server to react to the changing environment.

Player's Action

A client can send the following commands to the server:

Sensor Information

The server can send the following sensing information to clients:

Properties

The behaviour of the TOS can be tuned by properties. You can set properties
in the file 'properties'.

An example of this property file is shown here:

# properties for soccer server

# --------Player/Viewer Number allowed-------------
# the maximum number of clients for each team (default: 11)
team_full = 5

# the maximum number of viewer clients (default: 22)
viewer_full = 5
# --------------------------------------------------

# ---------Time Issue of the Match (in sec)---------
# the length of before_kick_off mode (default: 2)
kick_off_time = 2

# Heart rate, the time each beat (simulation step) spends (default 0.1)
heartrate = 0.1

# Start time, players enter the field and prepare the game (in min) (default: 5)
start = 5

# Half time, players can have a rest and prepare the second half (in min) (default: 15)
half_time = 15

# Start the second half (in min) (default: 20)
second_start = 20

# End time (in min) (default: 30)
end = 30

# Idle time needed for deleting a non-active client (in min) (default: 2)
idle = 2
# --------------------------------------------------

# -------------Team names---------------------------
# left team name (default: left)
left_name = canada

# right team name (default: right)
right_name = united_states
# --------------------------------------------------

# -------------Networking---------------------------

# server listening port (default: 7777)
port = 7777
# --------------------------------------------------

# -------------Player properties--------------------
# player's maximum speed (in m/s) (default: 7)
maxspeed_p = 7

# the time a player needs to reach full speed (in sec)
# without friction (default: 1)
timetomax_p = 1

# player's maximum dash force (default: 100)
maxdash = 100

# player's minimum dash force (default: -30)
mindash = -30

# player's maximum kick force (default: 100)
maxkick = 100

# player's minimum kick force (default: 0)
minkick = 0

# max random factor for player movement (default: 0.05)
random_p = 0.01

# max dribble force factor for dash (default: 0.4)
dribble_factor = 0.4

# kick direction random factor. When you decide to kick the ball to X direction,
# the actual ball moving direction will be X +/- 10 degrees. So, the closer to the
# goal, the better chance to score. (default: 10)
kick_random = 10

# Once the player has kicked the ball, he has to wait some time to have  
# the ball under his control again. (default: 2)
noball = 2

# Once the player has sent the message, he has to wait some time to   
# communicate again. (default: 30)
noword = 30

# players collide when their relative distance is smaller than COLLIDERANGE
# (default: 1)
collide_range = 1

# Once a player makes up his mind to do an action, the action will
# be carried out for next INERTIA steps. So this means, the client
# does not need to send a command every step, he only needs to send
# a command every INERTIA steps.
# This will also give a client more time to think before to actually 
# do something. (default: 3)
inertia = 3
# --------------------------------------------------

# -------------Ball properties----------------------
# player will have chance to get the ball when 
# ball-player distance is under control range
# (default: 1.5)
control_range = 1.5

# maximum ball speed in m/s (default: 16)
maxspeed_b = 20

# max random factor for ball movement (default: 0.05)
random_b = 0.02

# ball friction factor, such as a1 = -FRICTIONFACTOR * v0
# (default: 0.065)
friction_factor = 0.065

AI Client Guide

It's very easy to implement a simple AI player for TOS, but centainly not easy to implement a smart AI team player. In this section, we describe how to implement a simple AI player in Java, whose only strategy is to chase the ball and kick the ball to the goal. Readers may also implement the client in any other language.

Parsing and Networking Java APIs

TOS provides parsing and networking APIs in Java Package soccer.common.

Source Code of a Simple AI Program

The complete source code of a simple AI program called AI.java is listed in this section.
To compile it, type:
javac -classpath .:soccer.jar AI.java
To run it, type:
java -cp .:soccer.jar AI

/* AI.java
* A simple AI program for TOS. The only strategy is to chase ball 
* and kick the ball to opponent's goal.
*  
* Yu Zhang, Copyright (C) 2001
*
*/

import java.io.*;
import java.util.*;
import java.net.*;
import java.util.StringTokenizer;
import soccer.common.*;

public class AI
{
  // default soccer server address settings
  static InetAddress address;
  static String      host = "localhost";
  static int         port = 7777;
       
  private Transceiver transceiver = null;
  private Packet      packet      = null;
       
  private InitData       init = null; // Initialization information from server.
  private SeeData        see  = null; // Visual information from server.
  private static int     side = 2;    // the side that the AI wants to join. 0 -> left, 
                                      // 1-> right, 2 ->anyside

  private boolean  IHaveBall  = false;
  
  // Constructs a simple AI player
  public AI()
  {
    // sets the server address.
    try
    {
      address = InetAddress.getByName(host);
    }
    catch(Exception e)
    {
      System.out.println("Network error:" + e);
      System.exit(1);
    }
             
    // sets up UDP networking utility;
    transceiver = new Transceiver(false);
  }     
      
  // establishs the connection to server, if it's sucessful, return true. 
  private boolean init()
  {
    try
    {

      // sends the connect packet to server
      ConnectData connect;
      if(side == 0) connect = new ConnectData(ConnectData.PLAYER, ConnectData.LEFT);
      else if(side == 1) connect = new ConnectData(ConnectData.PLAYER, ConnectData.RIGHT);
      else connect = new ConnectData(ConnectData.PLAYER, ConnectData.ANYSIDE);
               
      packet = new Packet(Packet.CONNECT, connect, address, port);
      transceiver.send(packet);
             
      // wait for the initialization message from server
      transceiver.setTimeout(1000);
      int limit = 0;
      packet = null;
      while(limit<60) try
      {
        packet = transceiver.receive();
        break;
      }
      catch(Exception e) {limit++;}
      transceiver.setTimeout(0);
      if(packet == null) 
      {
        System.out.println("waiting for server: Timeout.");
        return false;
      }
               
      if(packet.packetType == Packet.INIT)
      {
        init = (InitData) packet.data;
        return true;
      }
      else
      {
        System.out.println("Error: Packet type wrong. Can not INIT:-(");
        return false;
      }
    }
    catch(Exception e)
    {
      System.out.println("Error during start up: " + e);
      return false;
    }

  }  

  // an endless loop of observing and reacting.
  private void react() throws IOException
  {
    while(true)
    {
      sensing(transceiver.receive());
      if(IHaveBall) shootGoal();
      else chaseBall();
    }
  }      

  private void sensing(Packet info)
  {
    IHaveBall = false;
    // process the info
    if(info.packetType == Packet.SEE)
    {
      see = (SeeData)info.data;
      // Do I have the ball?
      if(see.ball.controllerType == see.player.side
         && see.ball.controllerId == see.player.id) IHaveBall = true;
    }
  }
              
  private void chaseBall() throws IOException
  {
    double force;
    if(see.player.position.distance(see.ball.position) >= 10) force = 100;
    else force = 50;

    DriveData driver = new DriveData(see.player.position.direction(see.ball.position), force);
    packet = new Packet(Packet.DRIVE, driver, address, port);
    transceiver.send(packet);
  }  

  private void shootGoal() throws IOException
  {
    Vector2d goal = null;

    if(see.player.side == 'l')
      goal = new Vector2d(50, 0);
    else goal = new Vector2d(-50, 0);

    double dir = see.player.position.direction(goal);
             
    KickData kicker = new KickData(dir, 100);
    packet = new Packet(Packet.KICK, kicker, address, port);
    transceiver.send(packet);
  }    
             
  public static void main(String argv[]) throws IOException
  {
    try
    {                                       
      // First look for parameters
      for( int c = 0 ; c < argv.length ; c += 2 )
      {
        if( argv[c].compareTo("-h") == 0 )
        {
          host = argv[c+1];
        }
        else if( argv[c].compareTo("-p") == 0 )
        {
          port = Integer.parseInt(argv[c+1]);
        }
        else if( argv[c].compareTo("-s") == 0 )
        {
          side = Integer.parseInt(argv[c+1]);
        }
        else
        {
           throw new Exception();
        }
      }
    }
    catch(Exception e)
    {
      System.err.println("");
      System.err.println("USAGE: AI [-parameter value]");
      System.err.println("");
      System.err.println("Parameters              value              default");
      System.err.println("--------------------------------------------------");
      System.err.println("h                      host_name         localhost");
      System.err.println("p                     port_number             7777");
      System.err.println("s         the side that the AI wants to join     0");     
      System.err.println("");
      System.err.println("Example:");
      System.err.println("AI -h lcivs2 -p 7777");
      System.err.println("or");
      System.err.println("AI -s 1");
      return;
    }

    AI ai = new AI();

    if(ai.init()) ai.react();

  }      
}

Developer's Guide

Environment

TOS is OS independent, TOS development is also OS independent, tools we use:

TOS Server Architecture


TOS Server has five main classes.

TOS runs on internet using the client-server architecture.

TOS GUI Architecture


Suggestions, Ideas and Bug Tracking at
TOS project page at sourceforge.net