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

Methods

Modifier and Type	Method and Description
void	addMatchObservation(String observation) Adds a custom observation to the match file, such that when it is analyzed, this observation will appear.
void	attackLocation(MapLocation loc) Queues an attack on the given location to be performed at the end of this turn.
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.
void	build(Direction dir, RobotType type) Builds a structure in the given direction, queued for the end of the turn.
boolean	canAttackLocation(MapLocation loc) Returns whether the given location is within the robot's attack range.
boolean	canBuild(Direction dir, RobotType type) Returns whether the robot can build a structure of the given type in the given direction, without taking delays into account.
boolean	canLaunch(Direction dir) Returns whether the direction is valid for launching (LAUNCHER only).
boolean	canMine() Returns whether the robot is able to mine, without taking delays into account.
boolean	canMove(Direction dir) Tells whether this robot can move in the given direction, without taking any sort of delays into account.
boolean	canSenseLocation(MapLocation loc) Returns true if the given location is within the robot's sensor range, or within the sensor range of some ally.
boolean	canSenseRobot(int id) Returns true if the given robot is within the robot's sensor range.
boolean	canSpawn(Direction dir, RobotType type) Returns whether the spawn action is valid, without taking delays into account.
void	castFlash(MapLocation loc) Casts Flash at the given location (COMMANDER only).
DependencyProgress	checkDependencyProgress(RobotType type) Gets the current progress of a dependency (relevant for building structures).
void	disintegrate() Kills your robot and ends the current round.
void	explode() Attacks all surrounding enemies (MISSILE only).
long	getControlBits() Gets this robot's 'control bits' for debugging purposes.
double	getCoreDelay() Returns the amount of core delay a robot has accumulated.
int	getFlashCooldown() Returns the current cooldown of FLASH (COMMANDER only).
double	getHealth() Gets the robot's current health.
int	getID() Use this method to access your ID.
MapLocation	getLocation() Gets the robot's current location.
int	getMissileCount() Returns how many missiles the robot has.
int	getRoundLimit() Gets the number of rounds in the game.
double	getSupplyLevel() Gets the robot's current supply level.
Team	getTeam() Gets the Team of this robot.
long[]	getTeamMemory() Returns the team memory from the last game of the match.
double	getTeamOre() Gets the team's total ore.
RobotType	getType() Gets this robot's type (SOLDIER, HQ, etc.).
double	getWeaponDelay() Returns the amount of weapon delay a robot has accumulated.
int	getXP() Gets the experience a robot has.
boolean	hasBuildRequirements(RobotType type) Returns whether you have the ore and the dependencies to build the given robot, and that the robot can build structures.
boolean	hasCommander() Returns whether the team currently has a commander.
boolean	hasLearnedSkill(CommanderSkillType skill) Returns whether the robot has learned a skill (only relevant if used by a COMMANDER).
boolean	hasSpawnRequirements(RobotType type) Checks to make sure you have the ore requirements to spawn, and that the structure can actually spawn the specified RobotType.
boolean	isBuildingSomething() Returns whether this robot is currently building anything.
boolean	isCoreReady() Returns whether the core delay is strictly less than 1 (whether the robot can perform a core action in the given turn).
boolean	isLocationOccupied(MapLocation loc) Returns whether there is a robot at the given location.
boolean	isPathable(RobotType type, MapLocation loc) Returns whether a robot of the given type can move into the given location, without taking any sort of delays into account.
boolean	isWeaponReady() Returns whether the weapon delay is less than 1 (whether the robot can attack in the given turn).
void	launchMissile(Direction dir) Launches a missile in the given direction (LAUNCHER only).
void	mine() Mines the current square for ore.
void	move(Direction dir) Queues a move in the given direction to be performed at the end of this turn.
int	readBroadcast(int channel) Retrieves the message stored at the given radio channel.
void	resign() Causes your team to lose the game.
MapLocation	senseEnemyHQLocation() Returns location of the enemy team's HQ (unconstrained by sensor range or distance).
MapLocation[]	senseEnemyTowerLocations() Returns the locations of surviving enemy towers, unconstrained by sensor range or distance.
MapLocation	senseHQLocation() Returns location of the allied team's HQ (unconstrained by sensor range or distance).
RobotInfo[]	senseNearbyRobots() Returns all robots that can be sensed on the map.
RobotInfo[]	senseNearbyRobots(int radiusSquared) Returns all robots that can be sensed within a certain radius of the robot.
RobotInfo[]	senseNearbyRobots(int radiusSquared, Team team) Returns all robots of a given team that can be sensed within a certain radius of the robot.
RobotInfo[]	senseNearbyRobots(MapLocation center, int radiusSquared, Team team) Returns all robots of a givin team that can be sensed within a certain radius of a specified location.
double	senseOre(MapLocation loc) Returns the amount of ore at a given location (to within sensor capabilities).
RobotInfo	senseRobot(int id) Senses information about a particular robot given its ID.
RobotInfo	senseRobotAtLocation(MapLocation loc) Returns the robot at the given location, or null if there is no object there.
TerrainTile	senseTerrainTile(MapLocation loc) Senses the terrain at the given location.
MapLocation[]	senseTowerLocations() Returns the locations of your own towers, unconstrained by sensor range or distance.
void	setIndicatorDot(MapLocation loc, int red, int green, int blue) Draws a dot on the game map, for debugging purposes.
void	setIndicatorLine(MapLocation from, MapLocation to, int red, int green, int blue) Draws a line on the game map, for debugging purposes.
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, RobotType type) Queues a spawn action to be performed at the end of this robot's turn.
void	transferSupplies(int amount, MapLocation loc) Transfers supplies to a robot in a nearby location (queued for the end of the turn).
void	yield() Ends the current round.

Method Detail

getRoundLimit

int getRoundLimit()

Gets the number of rounds in the game. After this many rounds, if neither team has destroyed the enemy HQ, then the tiebreakers will be used.

Returns:

the number of rounds in the game.

Bytecode cost:

1

getTeamOre

double getTeamOre()

Gets the team's total ore.

Returns:

the team's total ore.

Bytecode cost:

2

getID

int getID()

Use this method to access your ID.

Returns:

the ID of the robot.

Bytecode cost:

1

getTeam

Team getTeam()

Gets the Team of this robot.

Returns:

this robot's Team

Bytecode cost:

1

getType

RobotType getType()

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

Returns:

this robot's type.

Bytecode cost:

1

getLocation

MapLocation getLocation()

Gets the robot's current location.

Returns:

this robot's current location.

Bytecode cost:

1

getCoreDelay

double getCoreDelay()

Returns the amount of core delay a robot has accumulated. If the result is strictly less than 1, then the robot can perform a core action.

Returns:

the amount of core delay a robot has accumulated.

Bytecode cost:

1

getWeaponDelay

double getWeaponDelay()

Returns the amount of weapon delay a robot has accumulated. If the result is strictly less than 1, then the robot can attack.

Returns:

the number of weapon delay a robot has accumulated.

Bytecode cost:

1

getHealth

double getHealth()

Gets the robot's current health.

Returns:

this robot's current health.

Bytecode cost:

1

getSupplyLevel

double getSupplyLevel()

Gets the robot's current supply level.

Returns:

this robot's supply level.

Bytecode cost:

1

getXP

int getXP()

Gets the experience a robot has. Only meaningful for COMMANDER.

Returns:

the number of XP the robot has.

Bytecode cost:

1

getMissileCount

int getMissileCount()

Returns how many missiles the robot has. Only useful for LAUNCHER.

Returns:

the number of missiles the robot has.

Bytecode cost:

1

isBuildingSomething

boolean isBuildingSomething()

Returns whether this robot is currently building anything.

Returns:

whether this robot is currently building anything.

Bytecode cost:

1

senseHQLocation

MapLocation senseHQLocation()

Returns location of the allied team's HQ (unconstrained by sensor range or distance).

Returns:

the team's HQ location.

Bytecode cost:

10

senseEnemyHQLocation

MapLocation senseEnemyHQLocation()

Returns location of the enemy team's HQ (unconstrained by sensor range or distance).

Returns:

the enemy team's HQ location.

Bytecode cost:

50

senseTowerLocations

MapLocation[] senseTowerLocations()

Returns the locations of your own towers, unconstrained by sensor range or distance.

Returns:

an array of the locations of your living towers.

Bytecode cost:

20

senseEnemyTowerLocations

MapLocation[] senseEnemyTowerLocations()

Returns the locations of surviving enemy towers, unconstrained by sensor range or distance.

Returns:

an array of the locations of living enemy towers.

Bytecode cost:

100

senseTerrainTile

TerrainTile senseTerrainTile(MapLocation loc)

Senses the terrain at the given location. Returns TerrainTile.UNKNOWN for a terrain tile that has never been in sensor range.

Parameters:

loc - the location to check.

Returns:

the TerrainTile at the location.

Bytecode cost:

10

canSenseLocation

boolean canSenseLocation(MapLocation loc)

Returns true if the given location is within the robot's sensor range, or within the sensor range of some ally.

Parameters:

loc - the location to check.

Returns:

whether the given location is within the robot's sensor range.

Bytecode cost:

5

isLocationOccupied

boolean isLocationOccupied(MapLocation loc)
                           throws GameActionException

Returns whether there is a robot at the given location.

Parameters:

loc - the location to check.

Returns:

whether there is a robot at the given location.

Throws:

GameActionException - if loc is not within sensor range (CANT_SENSE_THAT).

Bytecode cost:

20

senseRobotAtLocation

RobotInfo senseRobotAtLocation(MapLocation loc)
                               throws GameActionException

Returns the robot at the given location, or null if there is no object there.

Parameters:

loc - the location to check.

Returns:

the robot at the given location.

Throws:

GameActionException - if loc is not within sensor range (CANT_SENSE_THAT).

Bytecode cost:

25

canSenseRobot

boolean canSenseRobot(int id)

Returns true if the given robot is within the robot's sensor range.

Parameters:

id - the ID of the robot to query.

Returns:

whether the given robot is within the robot's sensor range.

Bytecode cost:

5

senseRobot

RobotInfo senseRobot(int id)
                     throws GameActionException

Senses information about a particular robot given its ID.

Parameters:

id - the ID of the robot to query.

Returns:

a RobotInfo object for the sensed robot.

Throws:

GameActionException - if the robot cannot be sensed (for example, if it doesn't exist or is out of sight range).

Bytecode cost:

25

senseNearbyRobots

RobotInfo[] senseNearbyRobots()

Returns all robots that can be sensed on the map.

Returns:

array of class type of game objects.

Bytecode cost:

100

senseNearbyRobots

RobotInfo[] senseNearbyRobots(int radiusSquared)

Returns all robots that can be sensed within a certain radius of the robot.

Parameters:

radiusSquared - return objects this distance away from the center.

Returns:

array of class type of game objects.

Bytecode cost:

100

senseNearbyRobots

RobotInfo[] senseNearbyRobots(int radiusSquared,
                            Team team)

Returns all robots of a given team that can be sensed within a certain radius of the robot.

Parameters:

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

senseNearbyRobots

RobotInfo[] senseNearbyRobots(MapLocation center,
                            int radiusSquared,
                            Team team)

Returns all robots of a givin team that can be sensed within a certain radius of a specified location.

Parameters:

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

isCoreReady

boolean isCoreReady()

Returns whether the core delay is strictly less than 1 (whether the robot can perform a core action in the given turn).

Returns:

whether the robot can perform a core action in this turn.

Bytecode cost:

10

isWeaponReady

boolean isWeaponReady()

Returns whether the weapon delay is less than 1 (whether the robot can attack in the given turn).

Returns:

whether the robot is able to attack in the current turn.

Bytecode cost:

10

isPathable

boolean isPathable(RobotType type,
                 MapLocation loc)

Returns whether a robot of the given type can move into the given location, without taking any sort of delays into account. Takes into account only the robot type and the terrain of the location, and whether the location is occupied. Does not take into account any sort of core delays. Ignores whether the robot is capable of movement or not. Always returns false for locations out of sight range.

Parameters:

type - the type of the robot.

loc - the location to test.

Returns:

true if a robot of the given type can be placed onto the given location on this turn.

Bytecode cost:

20

canMove

boolean canMove(Direction dir)

Tells whether this robot can move in the given direction, without taking any sort of delays into account. Takes into account only the map terrain, positions of other robots, and the current robot's type (MISSILE and DRONE can move over VOID). Does not take into account whether this robot is currently active, but will only return true for units that are capable of movement. Returns false for the OMNI and NONE directions.

Parameters:

dir - the direction to move in.

Returns:

true if there are no robots or voids preventing this robot from moving in the given direction; false otherwise.

Bytecode cost:

10

move

void move(Direction dir)
          throws GameActionException

Queues a move in the given direction to be performed at the end of this turn.

Parameters:

dir - the direction to move in.

Throws:

GameActionException - if the robot cannot move in this direction.

canAttackLocation

boolean canAttackLocation(MapLocation loc)

Returns whether the given location is within the robot's attack range. Does not take into account whether the robot is currently attacking or has the delay to do so.

Parameters:

loc - the location to attempt to attack.

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:

10

attackLocation

void attackLocation(MapLocation loc)
                    throws GameActionException

Queues an attack on the given location to be performed at the end of this turn.

Parameters:

loc - the location to attack.

Throws:

GameActionException - if the robot cannot attack the given square.

explode

void explode()
             throws GameActionException

Attacks all surrounding enemies (MISSILE only). Other robots can call this but will just result in the same result as disintegrate().

Throws:

GameActionException - if the robot cannot explode.

hasCommander

boolean hasCommander()

Returns whether the team currently has a commander.

Returns:

whether the team has a commander.

Bytecode cost:

25

castFlash

void castFlash(MapLocation loc)
               throws GameActionException

Casts Flash at the given location (COMMANDER only).

Parameters:

loc - the target location.

Throws:

GameActionException - if the robot has not learned the spell or cannot cast at the given square.

hasLearnedSkill

boolean hasLearnedSkill(CommanderSkillType skill)
                        throws GameActionException

Returns whether the robot has learned a skill (only relevant if used by a COMMANDER).

Parameters:

skill - the skill being checked.

Returns:

whether the robot has that skill.

Throws:

GameActionException - if there is no commander.

Bytecode cost:

5

getFlashCooldown

int getFlashCooldown()
                     throws GameActionException

Returns the current cooldown of FLASH (COMMANDER only).

Returns:

the cooldown of FLASH.

Throws:

GameActionException - if there is no commander.

Bytecode cost:

1

broadcast

void broadcast(int channel,
             int data)
               throws GameActionException

Broadcasts a message to the global message board.

Parameters:

channel - the channel to write to, from 0 to BROADCAST_MAX_CHANNELS.

data - one int's worth of data to write.

Throws:

GameActionException - if the channel is invalid.

Bytecode cost:

25

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 BROADCAST_MAX_CHANNELS.

Returns:

data currently stored on the channel.

Throws:

GameActionException - if the channel is invalid.

Bytecode cost:

5

transferSupplies

void transferSupplies(int amount,
                    MapLocation loc)
                      throws GameActionException

Transfers supplies to a robot in a nearby location (queued for the end of the turn). If you specify more supply than the robot has, all its supply will be transferred.

Parameters:

amount - the amount of supply to transfer.

loc - the location to transfer the supply to.

Throws:

GameActionException - if there is no one to transfer to, or if the distance is too far for a supply transfer.

Bytecode cost:

500

canMine

boolean canMine()

Returns whether the robot is able to mine, without taking delays into account. This only checks whether the robot is a mining unit. Does not check the core delay.

Returns:

whether the robot is able to mine.

Bytecode cost:

10

senseOre

double senseOre(MapLocation loc)

Returns the amount of ore at a given location (to within sensor capabilities). If the location is out of sensor range, this returns the last known ore amount at that location. If the location is off the map or is void, then 0 is returned. If the location has never been in sensor range, then -1 is returned.

Parameters:

loc - the MapLocation to sense ore at.

Returns:

the amount of ore at a given location. If the location is out of sensor range, then the last known ore amount is returned.

Bytecode cost:

5

mine

void mine()
          throws GameActionException

Mines the current square for ore.

Throws:

GameActionException - if the current robot is not one that can collect ore

GameActionException - if there is currently movement delay and if the robot cannot mine

canLaunch

boolean canLaunch(Direction dir)

Returns whether the direction is valid for launching (LAUNCHER only). The location must be on the map and unoccupied, and must not have already been launched to during this turn, and the launcher must not have moved already during this turn.

Parameters:

dir - the direction to check.

Returns:

whether the direction is valid for launching.

Bytecode cost:

10

launchMissile

void launchMissile(Direction dir)
                   throws GameActionException

Launches a missile in the given direction (LAUNCHER only). You cannot launch if you have already moved in the given turn.

Parameters:

dir - the direction to launch a missile.

Throws:

GameActionException - if not enough missiles or otherwise can't attack.

checkDependencyProgress

DependencyProgress checkDependencyProgress(RobotType type)

Gets the current progress of a dependency (relevant for building structures).

Parameters:

type - the dependency to check.

Returns:

a DependencyProgress (DONE if the RobotType exists and is active on the map, INPROGRESS if the RobotType is not fully constructed, and NONE otherwise).

Bytecode cost:

40

hasSpawnRequirements

boolean hasSpawnRequirements(RobotType type)

Checks to make sure you have the ore requirements to spawn, and that the structure can actually spawn the specified RobotType.

Parameters:

type - the type to check.

Returns:

whether the spawn requirements are met.

Bytecode cost:

50

canSpawn

boolean canSpawn(Direction dir,
               RobotType type)

Returns whether the spawn action is valid, without taking delays into account. Checks ore requirements, structure types, and that the given direction is not blocked.

Parameters:

dir - the direction to spawn in.

type - the type to spawn.

Returns:

whether the spawn is valid.

Bytecode cost:

10

spawn

void spawn(Direction dir,
         RobotType type)
           throws GameActionException

Queues a spawn action to be performed at the end of this robot's turn. When the action is executed, a new unit will be created adjacent to the calling robot 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 the robot in.

type - the robot type to spawn.

Throws:

GameActionException - if the spawn is bad.

hasBuildRequirements

boolean hasBuildRequirements(RobotType type)

Returns whether you have the ore and the dependencies to build the given robot, and that the robot can build structures.

Parameters:

type - the type to build.

Returns:

whether the requirements to build are met.

Bytecode cost:

50

canBuild

boolean canBuild(Direction dir,
               RobotType type)

Returns whether the robot can build a structure of the given type in the given direction, without taking delays into account. Checks dependencies, ore costs, whether the robot can build, and that the given direction is not blocked. Does not check if a robot has sufficiently low coreDelay or not.

Parameters:

dir - the direction to build in.

type - the robot type to spawn.

Returns:

whether it is possible to build a building of the given type in the given direction.

Bytecode cost:

10

build

void build(Direction dir,
         RobotType type)
           throws GameActionException

Builds a structure in the given direction, queued for the end of the turn. The structure will initially be inactive for a number of turns (during which this robot cannot move or attack). After a number of turns, the structure will become active.

Parameters:

dir - the direction to bulid in.

type - the type to build.

Throws:

GameActionException - if the build is bad.

yield

void yield()

Ends the current round. Never fails.

disintegrate

void disintegrate()

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."

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)

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)

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)

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 be between 0 and GameConstants.NUMBER_OF_INDICATOR_STRINGS.

newString - the value to which the indicator string should be set.

setIndicatorDot

void setIndicatorDot(MapLocation loc,
                   int red,
                   int green,
                   int blue)

Draws a dot on the game map, for debugging purposes. Press V in the client to toggle which team's indicator dots are displayed.

Parameters:

loc - the location to draw the dot.

red - the red component of the dot's color.

green - the green component of the dot's color.

blue - the blue component of the dot's color.

setIndicatorLine

void setIndicatorLine(MapLocation from,
                    MapLocation to,
                    int red,
                    int green,
                    int blue)

Draws a line on the game map, for debugging purposes. Press V in the client to toggle which team's indicator lines are displayed.

Parameters:

from - the location to draw the line from.

to - the location to draw the line to.

red - the red component of the line's color.

green - the green component of the line's color.

blue - the blue component of the line's color.

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.

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.