battlecode.common
Interface RobotController


public interface RobotController

A RobotController allows contestants to make their robot sense and interact with the game world. When a contestant's RobotPlayer is constructed, it is passed an instance of RobotController that controls the newly created robot.


Method Summary
 void addMatchObservation(String observation)
          Adds a custom observation to the match file, such that when it is analyzed, this observation will appear.
 void attackSquare(MapLocation loc)
          ARTILLERY only Attacks the given location and height.
 void breakpoint()
          If breakpoints are enabled, calling this method causes the game engine to pause execution at the end of this round, until the user decides to resume execution.
 void broadcast(int channel, int data)
          Broadcasts a message to the global message board.
 boolean canAttackSquare(MapLocation loc)
          ARTILLERY only
 boolean canMove(Direction dir)
          Tells whether this robot can move in the given direction.
 boolean canSenseObject(GameObject o)
           
 boolean canSenseSquare(MapLocation loc)
          Returns true if the given location is within the team's shared sensor range
 void captureEncampment(RobotType type)
          Captures the encampment soldier is standing on.
 int checkResearchProgress(Upgrade upgrade)
          HQ ONLY.
 void defuseMine(MapLocation loc)
          SOLDIER only Defuses a mine on the target square.
 long getControlBits()
          Gets this robot's 'control bits' for debugging purposes.
 double getEnergon()
           
 MapLocation getLocation()
           
 int getMapHeight()
           
 int getMapWidth()
           
 Robot getRobot()
          Use this method to access your robot.
 double getShields()
           
 Team getTeam()
          Gets the Team of this robot.
 long[] getTeamMemory()
          Returns the team memory from the last game of the match.
 double getTeamPower()
           
 RobotType getType()
          Gets this robot's type (SOLDIER, HQ, etc.)
 boolean hasUpgrade(Upgrade upgrade)
          Checks whether a given upgrade has been researched and is available.
 boolean isActive()
           
 void layMine()
          SOLDIER only Lays mines.
 void move(Direction dir)
          Move in the given direction if possible.
 int readBroadcast(int channel)
          Retrieves the message stored at the given radio channel.
 void researchUpgrade(Upgrade upgrade)
          HQ ONLY.
 void resign()
          Causes your team to lose the game.
 int roundsUntilActive()
           
 MapLocation[] senseAllEncampmentSquares()
           
 MapLocation[] senseAlliedEncampmentSquares()
           
 double senseCaptureCost()
          Checks how much power it costs to start a capture an encampment on this turn
 boolean senseEncampmentSquare(MapLocation loc)
          Checks if the given map location is an encampment square.
 MapLocation[] senseEncampmentSquares(MapLocation center, int radiusSquared, Team team)
          Senses all encampment squares owned by the given team within the given circular area Allows a team-based filter which can be one of the following parameters: Null - Senses _all_ encampments on the map Neutral - Senses all encampments not owned by the allied team, so neutral or enemy Allied Team - Senses all encampments owned by the allied team Note that you cannot sense all enemy-owned encampments
 MapLocation senseEnemyHQLocation()
           
 boolean senseEnemyNukeHalfDone()
          Senses the enemy team's NUKE research progress - only HQ can do this
 MapLocation senseHQLocation()
           
 MapLocation senseLocationOf(GameObject o)
          Sense the location of the given object.
 Team senseMine(MapLocation location)
          Senses whether a mine exists at a given location
 MapLocation[] senseMineLocations(MapLocation center, int radiusSquared, Team team)
          Returns all mines within a given search radius specified by the parameters
 int senseMineRoundsLeft()
          SOLDIER only Checks how many rounds are left for the current mine being laid, if any.
<T extends GameObject>
T[]
senseNearbyGameObjects(Class<T> type)
          Returns all game objects of a given type nearby the robot
<T extends GameObject>
T[]
senseNearbyGameObjects(Class<T> type, int radiusSquared)
          Returns all game objects of a given type nearby the robot
<T extends GameObject>
T[]
senseNearbyGameObjects(Class<T> type, int radiusSquared, Team team)
          Returns all game objects of a given type nearby the robot of a given team
<T extends GameObject>
T[]
senseNearbyGameObjects(Class<T> type, MapLocation center, int radiusSquared, Team team)
          Senses all game objects of a given type within a given search area specified by the parameters
 MapLocation[] senseNonAlliedMineLocations(MapLocation center, int radiusSquared)
          Similar to senseMineLocations(MapLocation, int, Team) except the team is "non-allied" which includes both known enemy and neutral mines.
 GameObject senseObjectAtLocation(MapLocation loc)
          Returns the object at the given location, or null if there is no object there.
 RobotInfo senseRobotInfo(Robot r)
          Sense the RobotInfo for the given robot.
 TerrainTile senseTerrainTile(MapLocation loc)
          Senses the terrain at the given location.
 void setIndicatorString(int stringIndex, String newString)
          Sets one of this robot's 'indicator strings' for debugging purposes.
 void setTeamMemory(int index, long value)
          Sets the team's "memory", which is saved for the next game in the match.
 void setTeamMemory(int index, long value, long mask)
          Sets this team's "memory".
 void spawn(Direction dir)
          HQ ONLY.
 void suicide()
          Kills your robot and ends the current round.
 void wearHat()
          Puts a hat on the robot.
 void yield()
          Ends the current round.
 

Method Detail

getEnergon

double getEnergon()
Returns:
this robot's current energon level

getShields

double getShields()
Returns:
this robot's current shield level

getTeamPower

double getTeamPower()
Returns:
total amount of power in the team's power stockpile

getLocation

MapLocation getLocation()
Returns:
this robot's current location

getMapWidth

int getMapWidth()
Returns:
the current map's width

getMapHeight

int getMapHeight()
Returns:
the current map's height

getTeam

Team getTeam()
Gets the Team of this robot. Equivalent to this.getRobot().getTeam().

Returns:
this robot's Team
See Also:
Team

getRobot

Robot getRobot()
Use this method to access your robot.

Returns:
the Robot associated with this RobotController

getType

RobotType getType()
Gets this robot's type (SOLDIER, HQ, etc.)

Returns:
this robot's type.

senseObjectAtLocation

GameObject senseObjectAtLocation(MapLocation loc)
                                 throws GameActionException
Returns the object at the given location, or null if there is no object there.

Throws:
GameActionException - if loc is not within sensor range (CANT_SENSE_THAT)
Bytecode cost:
25

senseNearbyGameObjects

<T extends GameObject> T[] senseNearbyGameObjects(Class<T> type)
Returns all game objects of a given type nearby the robot

See Also:
senseNearbyGameObjects(Class, MapLocation, int, Team)
Bytecode cost:
100

senseNearbyGameObjects

<T extends GameObject> T[] senseNearbyGameObjects(Class<T> type,
                                                  int radiusSquared)
Returns all game objects of a given type nearby the robot

See Also:
senseNearbyGameObjects(Class, MapLocation, int, Team)
Bytecode cost:
100

senseNearbyGameObjects

<T extends GameObject> T[] senseNearbyGameObjects(Class<T> type,
                                                  int radiusSquared,
                                                  Team team)
Returns all game objects of a given type nearby the robot of a given team

See Also:
senseNearbyGameObjects(Class, MapLocation, int, Team)
Bytecode cost:
100

senseNearbyGameObjects

<T extends GameObject> T[] senseNearbyGameObjects(Class<T> type,
                                                  MapLocation center,
                                                  int radiusSquared,
                                                  Team team)
Senses all game objects of a given type within a given search area specified by the parameters

Parameters:
type - - type of game object to sense, eg: Robot.class
center - - center of the given search radius
radiusSquared - - return objects this distance away from the center
team - - filter game objects by the given team. If null is passed, objects from all teams are returned
Returns:
array of class type of game objects
Bytecode cost:
100

senseLocationOf

MapLocation senseLocationOf(GameObject o)
                            throws GameActionException
Sense the location of the given object.

Throws:
GameActionException - if object is not within sensor range (CANT_SENSE_THAT)
Bytecode cost:
25

senseRobotInfo

RobotInfo senseRobotInfo(Robot r)
                         throws GameActionException
Sense the RobotInfo for the given robot.

Throws:
GameActionException - if robot is not within sensor range (CANT_SENSE_THAT)
Bytecode cost:
25

canSenseObject

boolean canSenseObject(GameObject o)
Returns:
true if the given object is within the team's shared sensor range
Bytecode cost:
15

canSenseSquare

boolean canSenseSquare(MapLocation loc)
Returns true if the given location is within the team's shared sensor range

Bytecode cost:
15

senseAllEncampmentSquares

MapLocation[] senseAllEncampmentSquares()
Returns:
array of map location containing all encampment squares on the map
See Also:
senseEncampmentSquares(MapLocation, int, Team)
Bytecode cost:
100

senseAlliedEncampmentSquares

MapLocation[] senseAlliedEncampmentSquares()
Returns:
array of all encampment squares owned by the allied team
See Also:
senseEncampmentSquares(MapLocation, int, Team)
Bytecode cost:
100

senseEncampmentSquares

MapLocation[] senseEncampmentSquares(MapLocation center,
                                     int radiusSquared,
                                     Team team)
                                     throws GameActionException
Senses all encampment squares owned by the given team within the given circular area Allows a team-based filter which can be one of the following parameters:

senseMine

Team senseMine(MapLocation location)
Senses whether a mine exists at a given location

Parameters:
location - to scan
Returns:
either the TEAM of the mine at the given location or null if sensors think there is no mine
Bytecode cost:
10

senseMineLocations

MapLocation[] senseMineLocations(MapLocation center,
                                 int radiusSquared,
                                 Team team)
Returns all mines within a given search radius specified by the parameters

Parameters:
center - - center of the search area
radiusSquared - - radius around the center to include mines
team - - only return mines of this team. If null is passed, all team's mines are returned
Returns:
An array of MapLocations containing mine locations
Bytecode cost:
100

senseNonAlliedMineLocations

MapLocation[] senseNonAlliedMineLocations(MapLocation center,
                                          int radiusSquared)
Similar to senseMineLocations(MapLocation, int, Team) except the team is "non-allied" which includes both known enemy and neutral mines.

Parameters:
center - - center of the search area
radiusSquared - - radius around the center to include
Returns:
Array of MapLocations containing non-allied mines
See Also:
senseMineLocations(MapLocation, int, Team)
Bytecode cost:
100

senseHQLocation

MapLocation senseHQLocation()
Returns:
location of the allied team's HQ
Bytecode cost:
10

senseEnemyHQLocation

MapLocation senseEnemyHQLocation()
Returns:
location of the enemy team's HQ
Bytecode cost:
10

senseEnemyNukeHalfDone

boolean senseEnemyNukeHalfDone()
                               throws GameActionException
Senses the enemy team's NUKE research progress - only HQ can do this

Returns:
true if the enemy team's NUKE is at least halfway researched.
Throws:
GameActionException - if not HQ
Bytecode cost:
50

senseEncampmentSquare

boolean senseEncampmentSquare(MapLocation loc)
Checks if the given map location is an encampment square. Returns true if an encampment can be built on the square regardless of whether there already exists an encampment on the square

Bytecode cost:
10

roundsUntilActive

int roundsUntilActive()
Returns:
the number of rounds until this robot's action cooldown ends, or 0 if it is already active.
Bytecode cost:
10

isActive

boolean isActive()
Returns:
true if this robot is active. If a robot is active, it can move, mine, defuse, capture, and attack.
Bytecode cost:
5

move

void move(Direction dir)
          throws GameActionException
Move in the given direction if possible.

Parameters:
dir -
Throws:
GameActionException - if the robot cannot move in this direction
Bytecode cost:
25

canMove

boolean canMove(Direction dir)
Tells whether this robot can move in the given direction. Takes into account only the map terrain and positions of other robots. Does not take into account this robot's type or whether this robot is currently active.

Returns:
true if there are no robots or walls preventing this robot from moving in the given direction; false otherwise
Bytecode cost:
25

canAttackSquare

boolean canAttackSquare(MapLocation loc)
ARTILLERY only

Returns:
true if the given location is within this robot's attack range. Does not take into account whether the robot is currently attacking
Bytecode cost:
15

attackSquare

void attackSquare(MapLocation loc)
                  throws GameActionException
ARTILLERY only Attacks the given location and height.

Throws:
GameActionException
Bytecode cost:
25

broadcast

void broadcast(int channel,
               int data)
               throws GameActionException
Broadcasts a message to the global message board. The data is not written until the end of the robot's turn.

Parameters:
channel - - the channel to write to, from 0 to MAX_RADIO_CHANNELS
data - - one int's worth of data to write
Throws:
GameActionException
Bytecode cost:
1

readBroadcast

int readBroadcast(int channel)
                  throws GameActionException
Retrieves the message stored at the given radio channel.

Parameters:
channel - - radio channel to query, from 0 to MAX_RADIO_CHANNELS
Returns:
data currently stored on the channel
Throws:
GameActionException
Bytecode cost:
1

spawn

void spawn(Direction dir)
           throws GameActionException
HQ ONLY. Queues a spawn action to be performed at the end of this robot's turn. When the action is executed, a new robot will be created adjacent to the HQ in the given direction. The square must not already be occupied. The new robot is created and starts executing bytecodes immediately

Parameters:
dir - the direction to spawn robot in
Throws:
IllegalStateException - if this robot is not the HQ
GameActionException - if this robot is currently inactive (NOT_ACTIVE)
GameActionException - if location is already occupied (CANT_MOVE_THERE)
Bytecode cost:
25

hasUpgrade

boolean hasUpgrade(Upgrade upgrade)
Checks whether a given upgrade has been researched and is available.

Parameters:
upgrade - cannot be null
Bytecode cost:
15

layMine

void layMine()
             throws GameActionException
SOLDIER only Lays mines. A robot cannot move until the mine is laid

Throws:
GameActionException
Bytecode cost:
25

senseMineRoundsLeft

int senseMineRoundsLeft()
                        throws GameActionException
SOLDIER only Checks how many rounds are left for the current mine being laid, if any.

Throws:
GameActionException

defuseMine

void defuseMine(MapLocation loc)
                throws GameActionException
SOLDIER only Defuses a mine on the target square. A robot cannot move until the defusion is complete.

Throws:
GameActionException
Bytecode cost:
25

captureEncampment

void captureEncampment(RobotType type)
                       throws GameActionException
Captures the encampment soldier is standing on. After a capture delay, kills the soldier and spawns a robot of the given encampment type

Parameters:
type -
Throws:
GameActionException
Bytecode cost:
25

senseCaptureCost

double senseCaptureCost()
Checks how much power it costs to start a capture an encampment on this turn

Bytecode cost:
25

researchUpgrade

void researchUpgrade(Upgrade upgrade)
                     throws GameActionException
HQ ONLY. Researches the given upgrade for a turn.

Parameters:
upgrade -
Throws:
GameActionException
Bytecode cost:
25

checkResearchProgress

int checkResearchProgress(Upgrade upgrade)
                          throws GameActionException
HQ ONLY. Checks the total number of rounds a given research has been researched

Parameters:
upgrade -
Returns:
the number of rounds that have been spent upgrading
Throws:
GameActionException
Bytecode cost:
15

yield

void yield()
Ends the current round. The team will receive a power refund of GameConstants.POWER_COST_PER_BYTECODE * (GameConstants.BYTECODE_LIMIT - RobotMonitor.getBytecodesUsed()). Never fails.


suicide

void suicide()
Kills your robot and ends the current round. Never fails.


resign

void resign()
Causes your team to lose the game. It's like typing "gg."


wearHat

void wearHat()
             throws GameActionException
Puts a hat on the robot. You require the BATTLECODE-HATS DLC, which charges you GameConstants.HAT_POWER_COST per hat. You also cannot be moving while putting on your hat.

Throws:
GameActionException
Bytecode cost:
5000

setIndicatorString

void setIndicatorString(int stringIndex,
                        String newString)
Sets one of this robot's 'indicator strings' for debugging purposes. These strings are displayed in the client. This method has no effect on gameplay (aside from the number of bytecodes executed to call this method).

Parameters:
stringIndex - the index of the indicator string to set. Must satisfy stringIndex >= 0 && stringIndex < GameConstants.NUMBER_OF_INDICATOR_STRINGS
newString - the value to which the indicator string should be set

senseTerrainTile

TerrainTile senseTerrainTile(MapLocation loc)
Senses the terrain at the given location.

Bytecode cost:
10

getControlBits

long getControlBits()
Gets this robot's 'control bits' for debugging purposes. These bits can be set manually by the user, so a robot can respond to them.

Returns:
this robot's control bits

addMatchObservation

void addMatchObservation(String observation)
Adds a custom observation to the match file, such that when it is analyzed, this observation will appear.

Parameters:
observation - the observation you want to inject into the match file

setTeamMemory

void setTeamMemory(int index,
                   long value)
Sets the team's "memory", which is saved for the next game in the match. The memory is an array of GameConstants.TEAM_MEMORY_LENGTH longs. If this method is called more than once with the same index in the same game, the last call is what is saved for the next game.

Parameters:
index - the index of the array to set
value - the data that the team should remember for the next game
Throws:
ArrayIndexOutOfBoundsException - if index is less than zero or greater than or equal to GameConstants.TEAM_MEMORY_LENGTH
See Also:
getTeamMemory(), setTeamMemory(int, long, long)
Bytecode cost:
15

setTeamMemory

void setTeamMemory(int index,
                   long value,
                   long mask)
Sets this team's "memory". This function allows for finer control than setTeamMemory(int, long) provides. For example, if mask == 0xFF then only the eight least significant bits of the memory will be set.

Parameters:
index - the index of the array to set
value - the data that the team should remember for the next game
mask - indicates which bits should be set
Throws:
ArrayIndexOutOfBoundsException - if index is less than zero or greater than or equal to GameConstants.TEAM_MEMORY_LENGTH
See Also:
getTeamMemory(), setTeamMemory(int, long)
Bytecode cost:
15

getTeamMemory

long[] getTeamMemory()
Returns the team memory from the last game of the match. The return value is an array of length GameConstants.TEAM_MEMORY_LENGTH. If setTeamMemory was not called in the last game, or there was no last game, the corresponding long defaults to 0.

Returns:
the team memory from the the last game of the match
See Also:
setTeamMemory(int, long), setTeamMemory(int, long, long)

breakpoint

void breakpoint()
If breakpoints are enabled, calling this method causes the game engine to pause execution at the end of this round, until the user decides to resume execution.