TEXT_INSTEAD_OF_A_MANUAL.txt rcssserver3D provides a platform for programming simulated robots playing soccer in a physical environment. Contents -------- 1. System Overview 1.1. Server 1.2. Monitor 2. Soccer Simulation 2.1. Soccer Team 2.2 Environment 2.3 Players 2.3.1 Create Effector 2.3.2 Init Effector 2.3.3 Beam Effector 2.3.4 Drive Effector 2.3.5 Kick Effector 2.3.6 Catch Effector 2.3.7 Say Effector 2.3.8 PanTilt Effector 2.3.9 Vision Perceptor 2.3.10 GameState Perceptor 2.3.11 AgentState Perceptor 2.3.12 Hear Perceptor 2.3.13 GyroRate Perceptor 2.3.14 Touch Perceptor 2.3.15 ForceResistance Perceptor 3. Monitor and Trainer Protocol 4. External Links 5. References 1. System Overview ------------------ To get started you should be somewhat familiar with the components of the system. The soccer simulation consists of three important parts: the server, the monitor and the agents. 1.1. Server ----------- In order to work with the server you should be familiar with the SPADES[1] simulation middleware. Some important concepts you should know about: The server is responsible to start an agent process, i.e. it does not wait for an agent to connect as the 2D simulation does. The SPADES library uses a database that contains information how to start different agent types. It is called 'agentdb.xml', located in the ./app/simulator/ directory. Agents connect via UNIX pipes to a SPADES Commserver. The use a length prefixed format to exchange messages. The Commserver in turn communicates with the server. In the default setup of the soccer server an integrated Commserver is started. It is to possible start more than one Commserver in order to distribute agent processes across different systems. Please see the SPADES manual for further details about how to start and configure a remote Commserver. In this setup the 3D server has to be configured to wait until all Commservers are connected before it unpauses the simulation. The relevant settings are found in the server startup script rcssserver3D.rb. These settings are 'Spades.RunIntegratedCommserver' and 'Spades.CommServersWanted'. The first setting configures if the integrated Commserver is started. Its default value is 'true'. The second setting gives the number of Commservers the server will wait for, before the simulation is initially unpaused. The integrated Commserver counts as one, so the default value here is 1. 1.2 Monitor ----------- The default monitor is called 'rcssmonitor3D-lite'. It is located in the ./app/rcssmonitor3d/lite directory. It is also used to replay logfiles that the server automatically creates (use the --logfile <filename> option). The automatically generated logfile is called 'monitor.log'. You'll find it in the 'Logfiles/' directory below the directory in which you started the server. A set of logfiles from 2004 RoboCup can be found at [2]. The implemented monitor protocol supports a command set to implement a trainer, i.e to automatically recreate test situations on the field and to evaluate an agents behavior. A 'monitor library' is provided to help implementing custom monitor and trainer applications, please see the ./app/rcssmonitor3d/lib directory. The protocol between server and monitor is detailed further down in this text file. A good starting point for your own agent implementations is the 'agenttest' program in the ./app/agenttest/ directory. This agent implements a simple kick and run behavior. Because there is no manual for the simulator, this text tries to describe the features of the simulated robots. 2. Soccer Simulation -------------------- 2.1 Soccer Team --------------- Your soccer team consists of a number of robots with equal capabilities. The programs you should write to create a team exchange data with the (virtual) low level control system delivered with the robots. Both perceptors and effectors of your robots work with S-expressions, this is the syntax you know already from the 2D soccer simulator, or maybe also from your favorite programming language :). 2.2. Environment ---------------- Some technical data of the environment and of your new robots: The playing field is a plane with FIFA standard soccer field size (length between 100m and 110m, width between 64m and 75m). Goal boxes and the ball are also standard FIFA size: goals are 7.32m wide; the ball has got a diameter of 0.222m and weighs between 0.41kg and 0.45kg. Because our agents are small and cannot jump, goals are only 0.5m high -- the official FIFA height is 2.44m. FIFA does not say too much about gravity (probably because they can't change it anyway), but in our simulation, gravity is fixed to 9.81m/s. Simulator steps are 0.01 seconds long. Connected monitors receive an update every 15th simulator step. Many of the values contained in this text are subject to change and it is likely that this text does not always reflect the current state of affairs. You'll find the current set of constants in the setup script that the server executes at startup, please see ./app/simulator/rcssserver3D.rb. After the first run of the server this file is copied to a directory under your home directory, called ~/.rcssserver3d/ and is read back from there on subsequent runs. Any experimental changes should happen there. 2.3. Players ------------ In the current version of the simulator, robots are represented as spheres (until we can come up with a more sophisticated representation next year). The diameter of all robots is 0.44m, and each robots weighs 75kg. Robots possess a kind of omnidrive, which adds some physical force to the robot body. By using the omnidrive, it is possible to accelerate into any direction, and it is also possible to jump very little. However, the omnidrive does only work if the robot is actually touching the soccer field. If you stop accelerating, robots will still move for a while, and you also cannot suddenly stop when moving with full speed (but you can use it for breaking). The maximum speed and the maximum height for jumping up if yet to be discovered. When a player initially connects to the server you have to do two thing in order to get started. At first you must create the robot type you want to use during the game. Currently we are limited to the robot sphere described above. In later versions more sophisticated robot models may be available. It is the job of the create effector to select and create one robot type at startup. Further the player must receive a number and join a team. This is the job of the init effector. 2.3.1 Create effector --------------------- When you initially connect to the simulator, your agent does not have any physical representation. The only thing your agent has got is a "CreatEeffector". The idea of the CreatEeffector is that you can request different effectors, perceptors or robot types. Currently, there is only one fixed robot type, so the CreateEffector ignores all parameters. For now, you should simply do "(create)" at the beginning and you will get the default robot type. Example command: (create) 2.3.2. Init Effector -------------------- To set the team name and uniform number, you have to use the InitEffector. Prior to initializing, your effectors and perceptors will not work properly. (init (unum <number>) (teamname <string>)) Example: (init (unum 7) (teamname RoboLog)) 2.3.3. Beam Effector -------------------- Similar to the kickeffector, the initial plan was not to introduce any artificial actions like "beaming" agents from one place to another place, similar to the "move" command in 2d soccer server. Still, the plan is to develop the soccer simulation so that beaming can disappear from the set of effectors. However the problem was that due to limited time we had to do something about moving agents to their half in before kick off mode. To remove "beaming", the referee has to be extended to send yellow or red cards to players that don't behave properly... with your help :) we are going to work on this feature in the near future. Until then, beaming of agents is allowed in 'beforekickoff' mode. The beam effector expects three coordinates, but currently forces the third component to be zero, i.e. agents are only allow to move on the ground along the horizontal plane. (beam <x> <y> <z>) Example: (beam -6.6 0 0) 2.3.4 Drive Effector -------------------- To use the omnidrive of the agent, you have to use the so called "DriveEffector", which takes a cartesian vector (x y z) with a maximum length of 100 units. The x-coordinate points towards the opponents team side of the field, z points up. With the DriveEffector, you set a kind of motor force, i.e. if you want to drive full speed for a while, it is sufficient to use the DriveEffector *once*. The force you set is applied at each simulator step until you change it again. The DriveEffector works reliable, there is a small error for forces along each axis (each up to 2% of the applied force). The error is normally distributed around 0.0. Using the omnidrive consumes battery. You get to know of battery states by reading the AgentStatePerceptor. If the battery is empty, the omnidrive will stop working. It is also possible to push away other robots. Using this feature to push away opponents is discouraged :). (drive <x> <y> <z>) Example command: (drive 20.0 50.0 0.0) 2.3.5 Kick Effector ------------------- To move the ball, you have the option of simply using the robots to push the ball into a desired direction, or you can use the kickeffector to kick the ball. Originally, we did not intend to create an artificial kickeffector. However, to make use of the 3rd dimension, this was the easiest way. It is intended to remove this kind of kick effector in future versions (not this years' competition) in favor of a real physical device. The kickeffector can accelerate the ball radially away from the robot body. The kickeffector takes an angle as first argument. This is the latitudal angle (in degrees) for accelerating the ball. It is restricted to a number between 0 and 50. The second argument indicates the kicking power and this is a number between 0 and 100. It is interpreted as the percentile% of the maximum available power. The kickeffector adds a force and a torque to the ball. This happens over a fixed number of simulation steps. Currently 10 cycles are used. This corresponds to 1/10s simulation time. To kick the ball, the ball has to be very close to the robot, i.e. it has to be within the so called kickable margin of the player. Currently 0.04m are configured. You cannot change the kicking angle in the horizontal plane. This means that you have to move the robot so that it can kick into the desired direction. Right now, the kickeffector is not very strong, because something like an offside rule is missing. It should also not be possible to move other robots by kicking the ball against them anymore. (at least not very much :) Like the DriveEffector, the kickeffector does only work if the robot touches the soccer field. The kickeffector noise has the following parameters: - The angle error in the x-y plane is quite low and normally distributed around 0.0 with sigma = 0.02. The - The latitudal angle error is normally distributed around 0.0. This angle error is low with sigma = 0.9 at both extreme positions, i.e. 0 and at 50 degrees. Towards the middle of the range the angle error gets higher with sigma up to 4.5. - The kick power error is normally distributed around 0.0 with sigma = 0.4 (kick <angle> <power>) Example command: (kick 20.0 80.0) 2.3.6. Catch Effector ------------------- The goalie (agent number 1) is the only player with the ability to catch a ball. The goalie can catch the ball in play mode 'playe_on', if the ball is inside the penalty area and close to the robot, i.e. it has to be within the so called catch margin of the player. The current value of catch margin is 2 meters. The catcheffector puts the ball in front of the goalie on the ground and moves players away that are closer than 2 meters to the goalie by 5 meters. (catch) 2.3.7. Say Effector ------------------- To broadcast messages to other players, you have to use the SayEffector. Messages can be sayMsgSize(for now 20) characters long, where valid characters for say messages are the printing characters* except space and (). Messages players say can be heard within a distance of audioCutDist(for now 50 meters) by members of both teams. The use of the SayEffector is only restricted by limited capacity of the players of hearing messages. * In the seven-bit ASCII character set, the printing characters are 0x20 to 0x7E. (say <message>) Example command: (say player10_Pass) 2.3.8 PanTilt Effector ---------------------- The PanTilt Effector changes the view direction of the RestrictedVisionPerceptor (RVP), if the StaticPercept is used (this is default for the RVP). The command to change the view direction is (pantilt <panDelta> <tiltDelta>), where <panDelta> and <tiltDelta> are angle changes (in degrees) of the pan and tilt angle, respectively. The maximum pan and tilt angle deltas can be configured in rcssserver3D.rb with the pantilteffector methods setMaxPanAngleDelta and setMaxTiltAngleDelta. These values are standing for the maximum angle change at a time. The pan and tilt angles are reported with the agentstateperceptor, with the current angles rounded to the next integer. 2.3.9 Vision Perceptor ----------------------- Your robots possess a special omnicam with some smart image processing software attached :). If using the regular visionperceptor, Robots have a 360 degrees view. With the RestrictedVisionPerceptor (which became the default in version 0.5), the view field of the robot is restricted to 120 degrees (for Nao). The direction of the view (pan and tilt) can be changed with the pantilt effector. The camera can pan to any angle (the initial 0 degrees pan direction is the direction towards the opponent side), and tilt around the horizontal plane. The VisionPerceptor delivers lists of seen objects, where objects are either others robots, the ball, or markers on the field. Currently there are 8 markers on the field: one at each corner point of the field and one at each goal post. With each sensed object you get: - The distance between the player and the object. - The angle in the horizontal plane. Zero degree always points to the opponent goal. - The latitudal angle. Here zero degree means horizontal. Contrary to 2D soccer simulation, the vision system does not deliver object velocities. Objects can be occluded by other objects (this is not completely implemented yet). All distances and angles are given relative to the camera position. The camera is currently located at the center of the robot sphere. The noise parameters of the vision system are as follows: - A small calibration error is added to the camera position. For each axis, the error is uniformly distributed between -0.005m and 0.005m. The error is calculated once and remains constant during the complete match. - Dynamic noise normally distributed around 0.0 + distance error: sigma = 0.0965 (also, distance error is multiplied by distance/100) + angle error (x-y plane): sigma = 0.1225 + angle error (latitudal): sigma = 0.1480 (Vision (<Type> (team <teamname>) (id <id>) (pol <distance> <horizontal angle> <latitudal angle>) ) ) Possible types are: - 'Flag' with <id> one of '1_l', '2_l', '1_r', '2_r' - 'Goal' with <id> one of '1_l', '2_l', '2_l', '2_r' - 'Player' with <id> being the uniform number of the player Example Vision output: (Vision (Flag (id 1_l) (pol 54.3137 -148.083 -0.152227)) (Flag (id 2_l) (pol 59.4273 141.046 -0.131907)) (Flag (id 1_r) (pol 61.9718 -27.4136 -0.123048)) (Flag (id 2_r) (pol 66.4986 34.3644 -0.108964)) (Goal (id 1_l) (pol 46.1688 179.18 -0.193898)) (Goal (id 2_l) (pol 46.8624 170.182 -0.189786)) (Goal (id 1_r) (pol 54.9749 0.874504 -0.149385)) (Goal (id 2_r) (pol 55.5585 8.45381 -0.146933)) (Ball (pol 6.2928 45.0858 -0.94987)) (Player (team robolog) (id 1) (pol 7.33643 37.5782 5.86774))) 2.3.10 GameStatePerceptor ------------------------- The GameStatePerceptor tells you about the current status of the game. The first percept you get from this perceptor tells you about some of the game variables, like ball weight and field size additionally. (GameState (<Name> <Value>) ...) Possible <Name>s are: - 'time' gives the current simulation time (as a float value) passed in seconds - 'playmode' gives the current playmode as a string. Possible playmodes are "BeforeKickOff", "KickOff_Left", "KickOff_Right", "PlayOn", "KickIn_Left", "KickIn_Right", "corner_kick_left", "corner_kick_right", "goal_kick_left", "goal_kick_right", "offside_left", "offside_right", "GameOver", "Goal_Left", "Goal_Right", "free_kick_left", "free_kick_right", "unknown". For an up to day list of all playmodes refer to (./plugin/soccer/soccertypes.h) Example GameState output: (GameState (time 0) (playmode BeforeKickOff)) 2.3.11 AgentState perceptor --------------------------- The AgentStatePerecptor tells you about the current state of your agent, currently the pan/tilt angle of the camera (in degrees, rounded to the next integer value), the battery level and temperature. (AgentState (pan_tilt <pan in degrees> <tilt in degrees>) (battery <battery level in percent>) (temp <temperature in degree>) ) Example AgentState output: (AgentState (pan_tilt -89 -2) (battery 100) (temp 23)) 2.3.12 Hear Perceptor ---------------------- You get percepts from this perceptor when a player uses SayEffector and sends a message. The format of the aural sensor message from the is: (hear <time> <direction in degree> <message>) <time> indicates the current time. <direction in degree> is relative direction to sender (without noise) if it is another player, otherwise it is "self" (without quotation mark). <message> is the message. The maximum length is sayMsgSize bytes. The server parameters that affect the Hear perceptor are: Parameter Value --------------------------------------- audioCutDist 50.0 hearMax 2 hearInc 1 hearDecay 2 sayMsgSize 512 A player can only hear a message if the player's hear capacity is at least hearDecay, since the hear capacity of the player is decreased by that number when a message is heard. Every cycle the hear capacity is increased with hearInc. The maximum hear capacity is hearMax. To avoid a team from making the other team's communication useless by overloading the channel the players have separate hear capacities for each team. With the current values this means that a player can hear at most one message from each team every second perceptor update. If more messages arrive at the same time than the player can hear the messages actually heard are undefined (The current implementation choose the messages according to the order of arrival). This rule does not include messages from oneself. In other words, a player can hear a message from himself and hear a message from another player in the same perceptor output. A message said by a player is transmitted only to players within audioCutDist meters from that player. For example, a defender, who may be near his own goal, can hear a message from his goal-keeper but a striker who is near the opponent goal can not hear the message. Example Hear output: (hear 0.8 -179.99 Test_1) (hear 0.4 self Test_2) 2.3.13 GyroRate Perceptor ------------------------- The GyroRate perceptor will give information about the change in orientation of the body below its parent node (e.g. an ODE body below an AgentAspect node). The perceptor provides three values corresponding to change rates of angles around the X, Y, and Z axis respectively. Message format: (GYR (name <nodename>) (rt <x> <y> <z>)) <nodename> can be set arbitrarily <x> <y> <z> are the change rates of angles around the X, Y, and Z axis respectively. Example output: (GYR (name torsogyro) (rt 0.00 0.00 -0.00)) 2.3.14 Touch Perceptor ---------------------- The touch perceptor provides simple binary information of whether the collider below its parent node has been involved in a collision or not. Message format: (TCH (name <nodename>) (val <value>)) <nodename> can be set arbitrarily <value> is 1 in case of a collision and 0 in case no collision was detected Example output: (TCH (name footleft) (val 1)) 2.3.15 ForceResistance Perceptor -------------------------------- The ForceResistance perceptor provides information about the force applied to the collider below it's parent node when a collision occures. It also provides an average point (in local coordinates relative to the collider) as the force concentration point. When two surfaces are completely in touch, there are many contact points. As it is not practical to provide complete information about such a collision, the FRP provides only one contact point (the weighted average of all points to which a force is applied) and a force vector (total force applied to all of the contact points). So, the output is just an approximation about the applied force. Message format: (FRP (n <nodename>) (c <px> <py> <pz>) (f <fx> <fy> <fz>)) <nodename> can be set arbitrarily <px> <py> <pz> are the local coordinates of the force concentration point <fx> <fy> <fz> are components of the total force vector Example output: (FRP (n fl) (c 0.03 -0.13 0.00) (f 0.20 0.10 3.22)) 3. Monitor and Trainer Protocol ------------------------------- The default monitor port for the soccer simulation is 12001. The server periodically sends you lines of text that contain S-Expressions. The monitor log file, that contains the recorded sequence of all expressions sent to the monitor is further used as the log file format. It is automatically generated in Logfiles/monitor.log relative to the server directory. == INIT Expression == Initially one 'Init' expression is sent. An example init expression is given below. Note that S-Expressions from the server are received as a single line. Their are reformatted here for readability. (Init (FieldLength 104)(FieldWidth 68)(FieldHeight 40) (GoalWidth 7.32)(GoalDepth 2)(GoalHeight 0.5)(BorderSize 10) (FreeKickDistance 9.15)(WaitBeforeKickOff 2)(AgentMass 75) (AgentRadius 0.22)(AgentMaxSpeed 10)(BallRadius 0.111) (BallMass 0.425878)(RuleGoalPauseTime 3)(RuleKickInPauseTime 1) (RuleHalfTime 300) (play_modes BeforeKickOff KickOff_Left KickOff_Right PlayOn KickIn_Left KickIn_Right corner_kick_left corner_kick_right goal_kick_left goal_kick_right offside_left offside_right GameOver Goal_Left Goal_Right free_kick_left free_kick_right) ) Each subexpression of the init expression is a name value pair that gives one parameter that the current instance of the simulation uses. The meaning of the different parameters: - FieldLength,FieldWidth,FieldHeight: dimensions of the soccer field in meter - GoalWidth, GoalDepth, GoalHeight: dimensions of the goals in meter - BorderSize: the simulated soccer field is surrounded by an off field area. BorderSize gives the extra space in meters relative to the regular field dimensions in meters - FreeKickDistance: gives the distance in meters that agents of the opposite have to adhere when a player carries out a free kick. - WaitBeforeKickOff: gives the time in seconds the server waits before automatically starting the game - AgentMass: the mass of each agent in kg - AgentRadius: the radius of each agent in m - AgentMaxSpeed: the maximum speed of each agent in m/s - BallRadius: the radius if the ball in m - BallMass: the mass of the ball in kg - RuleGoalPauseTime: the time in seconds that the server waits after a goal is scored before switching to kick off playmode - RuleKickInPauseTime: the time in seconds that the server waits after the ball left the field before switching to the kick in playmode - RuleHalfTime: the length of one half time in seconds - play_modes: lists the the different play_modes of the soccer simulation. Later on play_modes are referenced by a zero based index into this list. == INFO Expression == After the initial init message is sent only Info expressions are sent. These expressions contain the full state of the current simulation state. An example Info expression is given below: (Info (time 0)(half 1)(score_left 0)(score_right 0)(play_mode 0) (P (pos 0 0 0))(P (pos 0 0 0))(P (pos 0 0 0))(P (pos 0 0 0)) (P (pos 0 0 0))(P (pos 0 0 0))(P (pos 0 0 0))(P (pos 0 0 0)) (P (pos 0 0 0))(P (pos 0 0 0))(F (id 1_l)(pos -52 -34 0)) (F (id 2_l)(pos -52 34 0))(F (id 1_r)(pos 52 -34 0))(F (id 2_r)(pos 52 34 0)) (G (id 1_l)(pos -52 -3.66 0))(G (id 2_l)(pos -52 3.66 0)) (G (id 1_r)(pos 52 -3.66 0))(G (id 2_r)(pos 52 3.66 0)) (B (pos 0 0 10)) ) Each subexpression of the info expression is a name value pair that contains information about one aspect of the current simulation state. Not all subexpressions are repeated. This concerns the positions of the field flags and the names of the two teams. This information is only sent once. Further game state information like the score count, and the current game state is only sent if it changed. The meaning of the different expressions: - Die: notifies the monitor that the soccer simulation is about to terminate - time: the current simulation time in seconds - half: the current game half, 0 means the first, 1 means the second game half - score_left, score_right: the score count of the left and right team respectively - team_left, team_right: gives the names of the left and right team respectively; the information is only sent once as it remains static - play_mode: the current play mode as 0 based index into the play_modes list given in the init expression - P: gives information about a player. This expression may contain further subexpressions. - s: gives the team the player belongs to; 0 for the left, 1 for the right team - id: gives the uniform number of the player - pos: gives the position of the player as a three component vector - last: if this subexpression is present, the player was the last to touch the ball - say: this expression gives the string the player sent using the optional SayEffector - F: gives information about a flag on the field. Information about a flag is only sent once, as it remains static - pos: gives the position of the flag as a three component vector - id: gives the name of the flag - B: gives information about the ball - pos: gives the position of the ball as a three component vector - ack: acknowledges a command that is carried out by the server; carries a user defined cooky string as parameter; see below for further explanation == Monitor Command Parser == A connected monitor can further send commands as S-Expressions to the server using the monitor connection. These commands allow a connected monitor to set the current playmode and to move players and the ball to arbitrary positions on the field. This allows for the implementation of trainer clients. Please note that sending a command may have no effect in certain playmodes. E.g moving the ball away from the center position in BeforeKickOff mode is immediately counteracted by the simulator. Supported expressions are: - (kickOff <side>): Start the soccer game with a kick-off for the team on the specified field side. <side> has to be either 'Left', 'Right', or 'None', where 'None' means that a coin is tossed to select a team. Example: (kickOff Left) - (playMode <play_mode>): Set the current playmode. Possible playmodes are given as strings in the play_modes expression of the init expression the monitor receives when it connects. Example: (playMode corner_kick_left). - (agent (team [Right,Left])(unum <n>)(pos <x y z>)): Set the position and velocity of the given player on the field. Example: (agent (team Left)(unum 1)(pos -52.0 0.0 0.3)) - (ball (pos <x y z>)): Set the position of the ball on the field. Example: (ball (pos 10 20 1)) - (dropBall): Drop ball at its current position and move all players away by the free kick radius. Example: (dropBall) - (getAck <cookie string>): Experimental feature, currently disabled. Requests an (ack <cookie>) reply from the server. The server will send the answer as soon as the command is carried out. This is used to synchronize a trainer implementation wit the server. The getAck expression is appended behind one of the above commands. Example: ((ball (pos 0.0 0.0 50.0))(getAck moved_ball_in_the_air)) 4. External Links ----------------- This section contains links to external resources that may be helpful. - http://www.ele.ita.br/~jackson/itandroids/guias.html This page contains startup guides for 3D and 2D soccer in English and Portuguese. 5. References ------------- [1] http://spades-sim.sourceforge.net/ [2] http://www.uni-koblenz.de/~maas/WWW/overview.html END OF TEXT. If you ever get close to a human And human behavior Be ready to get confused There's definitely, definitely, definitely no logic. (Bjork, Human Behaviour) "Duct tape is a lot like the Force... It has a dark side, it has a light side, and it binds the galaxy together...." (unknown author)