SoccerClient API

As a subclass of sockey.SoccerClient, you get a whole list of helping functions to control your player. Remember that each player runs in its own thread. To play fair, don't use any static class members to communicate between your players. Instead, use the sendMessage and receiveMessage methods provided.

Constants
[gamestate values, ping ids]
Variables
[gamestate, pt, v, size]
Methods
- Sensory
  [getVel, getAng, kickable, ping]
- Control
  [sendMessage, setAngGoal, accelerate, setReady]
- Convenience methods
  [getVersion, wannabe, runaway, cart2polar, polar2cart, anglesub, debugMsg]
- Game state
  [getScore, getPosition, getTime, weKick, getGameTime, getRadius, getBallRadius]
- Overridable thinking methods
  [init, step, receiveMessage, regroup, freekick]

Send suggestions/comments to wessler@ai.mit.edu.

Constants

The first set of constants describes the state of the game. Different action methods will be called depending on the value of gamestate.

int GAME_STARTING (See gamestate) The period is about to start. The server is waiting for every player to signal they are ready. regroup() is called.

int GAME_PLAYING (See gamestate) Play is on. step() is called.

int GAME_GOALSCORED (See gamestate) Some team just scored a goal. The server is waiting for every player to signal that they are ready. regroup() is called.

int GAME_FREEKICK (See gamestate) A delay of game was triggered. The server is waiting for every player to signal that they are ready. freekick() is called.

int GAME_OVER (See gamestate) The game is over. Your players will automatically gather in the corner, and then "shake hands" with the other team. Your code will not be called.

The next set of constants are used in the ping() method. They identify specific players or locations on the field. You can get the distance and direction from your player to any of these locations. See a graphical depiction of the ping markers.

int ID_PCTR (See ping) The ping ID for the center player.

int ID_PFWDL (See ping) The ping ID for the left forward player.

int ID_PFWDR (See ping) The ping ID for the right forward player.

int ID_DEFL (See ping) The ping ID for the left defense player.

int ID_DEFR (See ping) The ping ID for the right defense player.

int ID_GOALIE (See ping) The ping ID for the goalie.

int OUR_TEAM (See ping) Add this to a player ping ID to get the player for our team. [optional]

int THEIR_TEAM (See ping) Add this to a player ping ID to get the player for the opposing team.

int ID_BALL (See ping) The ping ID for the ball.

int ID_CENTER (See ping) The ping ID for the center of the field.

int ID_THEIR_GOAL_LEFT (See ping) The ping ID for the left edge of the opposing team's goal.

int ID_THEIR_GOAL (See ping) The ping ID for the center of the opposing team's goal.

int ID_THEIR_GOAL_RIGHT (See ping) The ping ID for the right edge of the opposing team's goal.

int ID_OUR_GOAL_LEFT (See ping) The ping ID for the left edge of our team's goal.

int ID_OUR_GOAL (See ping) The ping ID for the center of our team's goal.

int ID_OUR_GOAL_RIGHT (See ping) The ping ID for the right edge of our team's goal.

int ID_LEFT_WALL (See ping) The ping ID for the closest point on the left wall (as you face the opposing team's goal).

int ID_RIGHT_WALL (See ping) The ping ID for the closest point on the right wall (as you face the opposing team's goal).

int ID_FWD_WALL (See ping) The ping ID for the closest point on the opposing team's goal line.

int ID_BACK_WALL (See ping) The ping ID for the closest point on our team's goal line.

int ID_KICKOFF_LOC (See ping) The ping ID for the location the ball will be placed at the next kickoff or free kick.

Variables

int gamestate Holds a copy of the current game state. This variable gets updated each time your code is called, so feel free to use it. See game state constants for the possible values.

Point pt A general purpose pre-allocated Point object for you to use.

Point v Another general purpose pre-allocated Point object for you to use.

Dimension size The width and height of the playing field.

Methods

Sense methods:

void getVel(Point v) Get this player's current velocity

int getAng() Get this player's current angle, in degrees.

boolean kickable() Returns true if the ball is currently within this player's open half.

void ping(int loc, Point pt, boolean asAngle) Fills the x and y values of pt with the distance from this player to location loc. If asAngle is false, the x and y distance to loc are given. If asAngle is true, the x field of pt is filled with the actual distance to loc, and the y field of pt is filled with the angle from this player to loc. See ping IDs for a list of possible values for loc.

Control methods

void sendMessage(int toWhom, String msg, int a, int b, int c) Send a text string and three integers to other players on our team. toWhom is a bit mask, identifying which players to send the message to. To send a message to the center and the goalie, toWhom should be: (1<<ID_PCTR | 1<<ID_GOALIE)
Note: the message is processed by the receiving player's receiveMessage method in this player's thread!

void setAngGoal(int angle) Set the desired angle of this player to angle, in degrees. The player will turn until getAng() returns this value.

void accelerate(int angle, int strength) Set the acceleration for this player to be angle degrees at the given strength. strength is a percentage from -100 to 100. This acceleration will remain in effect until you call accelerate again.

void setReady(boolean ready) Signal the referee that you are in your desired position for GAME_STARTING, GAME_FREEKICK, or GAME_GOALSCORED. If you are knocked out of position, you may signal yourself unready until you are in position again. Play will resume when all players signal ready for a certain amount of time.

Convenience methods

int getVersion() Returns the version of SoccerClient. This API corresponds to version 2

int wannabe(int loc, int dx, int dy) This method will call accelerate and setReady as appropriate to move this player to (dx, dy) offset from the ping ID loc. Returns the angle of acceleration, or 90 (forward) if this player is close to loc.

int runaway(int loc, int dist) This method will call accelerate and setReady as appropriate to move this player at least a distance dist away from the ping location loc. If this player is backed against a wall or otherwise blocked, runaway will try to move the player to the opposite side of loc. Returns the angle to loc.

void cart2polar(Point from, Point to) This method converts the (x, y) cartesian coordinates in from to (distance, angle) polar coordinates in to. The from and to Points may be the same object.

void polar2cart(Point from, Point to) This method converts the (distance, angle) polar coordinates in from to (x, y) cartesian coordinates in to. The from and to Points may be the same object.

int anglesub(int a, int b) This method subtracts angle b from angle a, where a and b range from 0 to 360. The result is guaranteed to be between -179 and 180.

void debugMsg(String msg) Display a text string below the playing field area. This is useful for debugging, celebrating, or taunting. Mind your language, please. Display is limited in size, and calling this too often will degrade performance.

Game state methods

int getScore() Get the current difference in score: positive if we're winning, negative if we're losing

int getPosition() Get the position ID (ping ID) of this player.

int getTime() Returns the current simulation frame number. This is not the same as the gameTime, which counts down only during GAME_PLAYING

boolean weKick() Returns true if we are the kicking team for a kickoff during GAME_GOALSCORED, GAME_STARTING, or GAME_FREEKICK.

int getGameTime() Returns the time remaining (in 60ths of a second) to the end of the game. This time counts down only during GAME_PLAYING, unlike getTime(), which counts up during all game states.

int getRadius() Returns the radius of your player.

int getBallRadius() Returns the radius of the ball.

Overridable thinking methods

void init() This function gets called after the client has been created, but before any simulation starts. Use this function to initialize any variables that you need. Anything that you might have wanted to put in the constructor for your class should go here instead. Be sure to call super.init() as the first line of the init code.
void step() Called during GAME_PLAYING. This is your main thinking method. The SoccerClient implementation does nothing, so you must override this to make an interesting team.

void regroup() Called during GAME_STARTING and GAME_GOALSCORED. This function moves the players to their standard start positions, using wannabe (so that setReady is set appropriately). You may override this method if you want your players to start somewhere different. Make sure your players are on your half of the field, and at least size.height/4 away from the kickoff location if you are recieving.

void freekick() Called during GAME_FREEKICK. This function calls runaway(ID_KICKOFF_LOC, size.height/3) for every player except the goalie. One player from the receiving team (either left or right defender or the center) will approach the ball. You may override this method to do something smarter, but be sure to call setReady as appropriate, and make sure your players are at least size.height/3 away from the kickoff location.

void receiveMessage(int from, String message, int a, int b, int c) This method does nothing. Override it to do something useful with the information you receive. from is the ping ID of the player on your team who sent the message.
Warning! receiveMessage runs in the thread of the player that called sendMessage, not the thread of the receiver. Synchronize appropriately!

void
void
void initStep()
initRegroup()
initFreekick() Called once when gamestate has changed and the corresponding method (step(), regroup(), or freekick()) is about to be called for the first time. If you override any of these methods, be sure to call the superclass's method in your code by calling (for example) super.initStep().

Constants
The first set of constants describes the state of the game. Different action methods will be called depending on the value of gamestate.
int	GAME_STARTING	(See `gamestate`) The period is about to start. The server is waiting for every player to signal they are ready. regroup() is called.
int	GAME_PLAYING	(See `gamestate`) Play is on. step() is called.
int	GAME_GOALSCORED	(See `gamestate`) Some team just scored a goal. The server is waiting for every player to signal that they are ready. regroup() is called.
int	GAME_FREEKICK	(See `gamestate`) A delay of game was triggered. The server is waiting for every player to signal that they are ready. freekick() is called.
int	GAME_OVER	(See `gamestate`) The game is over. Your players will automatically gather in the corner, and then "shake hands" with the other team. Your code will not be called.
The next set of constants are used in the ping() method. They identify specific players or locations on the field. You can get the distance and direction from your player to any of these locations. See a graphical depiction of the ping markers.
int	ID_PCTR	(See `ping`) The ping ID for the center player.
int	ID_PFWDL	(See `ping`) The ping ID for the left forward player.
int	ID_PFWDR	(See `ping`) The ping ID for the right forward player.
int	ID_DEFL	(See `ping`) The ping ID for the left defense player.
int	ID_DEFR	(See `ping`) The ping ID for the right defense player.
int	ID_GOALIE	(See `ping`) The ping ID for the goalie.
int	OUR_TEAM	(See `ping`) Add this to a player ping ID to get the player for our team. [optional]
int	THEIR_TEAM	(See `ping`) Add this to a player ping ID to get the player for the opposing team.
int	ID_BALL	(See `ping`) The ping ID for the ball.
int	ID_CENTER	(See `ping`) The ping ID for the center of the field.
int	ID_THEIR_GOAL_LEFT	(See `ping`) The ping ID for the left edge of the opposing team's goal.
int	ID_THEIR_GOAL	(See `ping`) The ping ID for the center of the opposing team's goal.
int	ID_THEIR_GOAL_RIGHT	(See `ping`) The ping ID for the right edge of the opposing team's goal.
int	ID_OUR_GOAL_LEFT	(See `ping`) The ping ID for the left edge of our team's goal.
int	ID_OUR_GOAL	(See `ping`) The ping ID for the center of our team's goal.
int	ID_OUR_GOAL_RIGHT	(See `ping`) The ping ID for the right edge of our team's goal.
int	ID_LEFT_WALL	(See `ping`) The ping ID for the closest point on the left wall (as you face the opposing team's goal).
int	ID_RIGHT_WALL	(See `ping`) The ping ID for the closest point on the right wall (as you face the opposing team's goal).
int	ID_FWD_WALL	(See `ping`) The ping ID for the closest point on the opposing team's goal line.
int	ID_BACK_WALL	(See `ping`) The ping ID for the closest point on our team's goal line.
int	ID_KICKOFF_LOC	(See `ping`) The ping ID for the location the ball will be placed at the next kickoff or free kick.
Variables
int	gamestate	Holds a copy of the current game state. This variable gets updated each time your code is called, so feel free to use it. See game state constants for the possible values.
Point	pt	A general purpose pre-allocated Point object for you to use.
Point	v	Another general purpose pre-allocated Point object for you to use.
Dimension	size	The width and height of the playing field.

Methods
Sense methods:
void	getVel(Point v)	Get this player's current velocity
int	getAng()	Get this player's current angle, in degrees.
boolean	kickable()	Returns true if the ball is currently within this player's open half.
void	ping(int loc, Point pt, boolean asAngle)	Fills the x and y values of `pt` with the distance from this player to location `loc`. If `asAngle` is false, the x and y distance to `loc` are given. If `asAngle` is true, the x field of `pt` is filled with the actual distance to `loc`, and the y field of `pt` is filled with the angle from this player to `loc`. See ping IDs for a list of possible values for `loc`.
Control methods
void	sendMessage(int toWhom, String msg, int a, int b, int c)	Send a text string and three integers to other players on our team. `toWhom` is a bit mask, identifying which players to send the message to. To send a message to the center and the goalie, `toWhom` should be: (1<<ID_PCTR \| 1<<ID_GOALIE) Note: the message is processed by the receiving player's receiveMessage method in this player's thread!
void	setAngGoal(int angle)	Set the desired angle of this player to `angle`, in degrees. The player will turn until `getAng()` returns this value.
void	accelerate(int angle, int strength)	Set the acceleration for this player to be `angle` degrees at the given strength. `strength` is a percentage from -100 to 100. This acceleration will remain in effect until you call `accelerate` again.
void	setReady(boolean ready)	Signal the referee that you are in your desired position for GAME_STARTING, GAME_FREEKICK, or GAME_GOALSCORED. If you are knocked out of position, you may signal yourself unready until you are in position again. Play will resume when all players signal ready for a certain amount of time.
Convenience methods
int	getVersion()	Returns the version of SoccerClient. This API corresponds to version 2
int	wannabe(int loc, int dx, int dy)	This method will call `accelerate` and `setReady` as appropriate to move this player to (dx, dy) offset from the ping ID `loc`. Returns the angle of acceleration, or 90 (forward) if this player is close to `loc`.
int	runaway(int loc, int dist)	This method will call `accelerate` and `setReady` as appropriate to move this player at least a distance `dist` away from the ping location `loc`. If this player is backed against a wall or otherwise blocked, `runaway` will try to move the player to the opposite side of `loc`. Returns the angle to `loc`.
void	cart2polar(Point from, Point to)	This method converts the (x, y) cartesian coordinates in `from` to (distance, angle) polar coordinates in `to`. The `from` and `to` Points may be the same object.
void	polar2cart(Point from, Point to)	This method converts the (distance, angle) polar coordinates in `from` to (x, y) cartesian coordinates in `to`. The `from` and `to` Points may be the same object.
int	anglesub(int a, int b)	This method subtracts angle b from angle a, where a and b range from 0 to 360. The result is guaranteed to be between -179 and 180.
void	debugMsg(String msg)	Display a text string below the playing field area. This is useful for debugging, celebrating, or taunting. Mind your language, please. Display is limited in size, and calling this too often will degrade performance.
Game state methods
int	getScore()	Get the current difference in score: positive if we're winning, negative if we're losing
int	getPosition()	Get the position ID (ping ID) of this player.
int	getTime()	Returns the current simulation frame number. This is not the same as the gameTime, which counts down only during `GAME_PLAYING`
boolean	weKick()	Returns true if we are the kicking team for a kickoff during GAME_GOALSCORED, GAME_STARTING, or GAME_FREEKICK.
int	getGameTime()	Returns the time remaining (in 60ths of a second) to the end of the game. This time counts down only during GAME_PLAYING, unlike getTime(), which counts up during all game states.
int	getRadius()	Returns the radius of your player.
int	getBallRadius()	Returns the radius of the ball.
Overridable thinking methods
void	init()	This function gets called after the client has been created, but before any simulation starts. Use this function to initialize any variables that you need. Anything that you might have wanted to put in the constructor for your class should go here instead. Be sure to call `super.init()` as the first line of the init code.
void	step()	Called during GAME_PLAYING. This is your main thinking method. The SoccerClient implementation does nothing, so you must override this to make an interesting team.
void	regroup()	Called during GAME_STARTING and GAME_GOALSCORED. This function moves the players to their standard start positions, using `wannabe` (so that `setReady` is set appropriately). You may override this method if you want your players to start somewhere different. Make sure your players are on your half of the field, and at least `size.height/4` away from the kickoff location if you are recieving.
void	freekick()	Called during GAME_FREEKICK. This function calls `runaway(ID_KICKOFF_LOC, size.height/3)` for every player except the goalie. One player from the receiving team (either left or right defender or the center) will approach the ball. You may override this method to do something smarter, but be sure to call `setReady` as appropriate, and make sure your players are at least `size.height/3` away from the kickoff location.
void	receiveMessage(int from, String message, int a, int b, int c)	This method does nothing. Override it to do something useful with the information you receive. `from` is the ping ID of the player on your team who sent the message. Warning! receiveMessage runs in the thread of the player that called sendMessage, not the thread of the receiver. Synchronize appropriately!
void void void	initStep() initRegroup() initFreekick()	Called once when `gamestate` has changed and the corresponding method (`step()`, `regroup()`, or `freekick()`) is about to be called for the first time. If you override any of these methods, be sure to call the superclass's method in your code by calling (for example) `super.initStep()`.