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, RobotLevel height) 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(Message msg) Adds a message for your robot to broadcast.
boolean	canAttackSquare(MapLocation loc) Returns true if the given location is within this robot's attack range.
boolean	canMove(Direction dir) Tells whether this robot can move in the given direction.
boolean	canSenseObject(GameObject o) Returns true if o is within sensor range.
boolean	canSenseSquare(MapLocation loc) Returns true if this robot can sense the location loc.
Message[]	getAllMessages() Retrieves an array of all the messages in your incoming message queue.
long	getControlBits() Gets this robot's 'control bits' for debugging purposes.
Direction	getDirection() Gets the direction this robot is currently facing.
double	getEnergon() Gets the current energon of this robot.
double	getFlux() Returns this robot's current flux level.
MapLocation	getLocation() Gets the current location of this robot.
double	getMaxEnergon() Gets the maximum energon of this robot.
Message	getNextMessage() Retrieve the next message waiting in your incoming message queue.
Robot	getRobot() Use this method to access your robot.
Team	getTeam() Gets the Team of this robot.
long[]	getTeamMemory() Returns the team memory from the last game of the match.
RobotType	getType() Gets this robot's type.
boolean	hasBroadcasted() Returns true if this robot has already broadcasted this turn.
boolean	isAttackActive() Returns true if this robot's attack cooldown is nonzero.
boolean	isMovementActive() Returns true if this robot's movement cooldown is nonzero.
void	moveBackward() Queues a backward movement to be performed at the end of this robot's turn.
void	moveForward() Queues a forward movement to be performed at the end of this robot's turn.
void	regenerate() Causes each allied robot within its attack radius to regenerate GameConstants.REGEN_AMOUNT energon at the beginning of its next turn.
void	resign() Causes your team to lose the game.
int	roundsUntilAttackIdle() Returns the number of rounds until this robot's attack cooldown reaches zero.
int	roundsUntilMovementIdle() Returns the number of rounds until this robot's movement cooldown reaches zero.
MapLocation[]	senseAlliedArchons() Returns the locations of all the archons on the calling robot's team.
PowerNode[]	senseAlliedPowerNodes() Returns an array containing all of the power nodes owned by this robot's team.
MapLocation[]	senseCapturablePowerNodes() Returns an array containing the locations of all of the nodes that this team can capture.
boolean	senseConnected(PowerNode p) Returns true if the node p is connected to this robot's team's power core.
MapLocation	senseLocationOf(GameObject o) Sense the location of the object o.
<T extends GameObject> T[]	senseNearbyGameObjects(Class<T> type) Sense objects of type type that are within this sensor's range.
GameObject	senseObjectAtLocation(MapLocation loc, RobotLevel height) Returns the object at the given location and height, or null if there is no object there.
boolean	senseOpponentConnected(PowerNode p) Returns true if the node p is connected to this robot's team's opponent's power core.
boolean	senseOwned(PowerNode p) Returns true if there is an allied tower at the power node p.
PowerNode	sensePowerCore() Returns this robot's team's power core.
RobotInfo	senseRobotInfo(Robot r) Sense the RobotInfo for the robot r.
TerrainTile	senseTerrainTile(MapLocation loc) Senses the terrain at loc, if loc was ever within this robot's sensor range.
void	setDirection(Direction dir) Queues a direction change to be performed at the end of this robot's turn.
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(RobotType type) Queues a spawn action to be performed at the end of this robot's turn.
void	suicide() Kills your robot and ends the current round.
void	transferFlux(MapLocation loc, RobotLevel height, double amount) Transfers the specified amount of flux to the robot at location loc and RobotLevel height.
void	yield() Ends the current round.

Method Detail

getEnergon

double getEnergon()

Gets the current energon of this robot.

Returns:

this robot's current energon level

getMaxEnergon

double getMaxEnergon()

Gets the maximum energon of this robot.

Returns:

this robot's maximum energon level

getFlux

double getFlux()

Returns this robot's current flux level.

getLocation

MapLocation getLocation()

Gets the current location of this robot.

Returns:

this robot's current location

getDirection

Direction getDirection()

Gets the direction this robot is currently facing.

Returns:

this robot's current Direction

getNextMessage

Message getNextMessage()

Retrieve the next message waiting in your incoming message queue. Also removes the message from the queue.

Returns:

next Message object in your queue, or null if your queue is empty.

Bytecode cost:

15

getAllMessages

Message[] getAllMessages()

Retrieves an array of all the messages in your incoming message queue. All messages will be removed from the queue. If there are no messages in the queue, this method returns a zero-length array.

Returns:

all the Messages in your message queue

Bytecode cost:

25

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.

Returns:

this robot's type.

senseObjectAtLocation

GameObject senseObjectAtLocation(MapLocation loc,
                                 RobotLevel height)
                                 throws GameActionException

Returns the object at the given location and height, 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)

Sense objects of type type that are within this sensor's range.

Bytecode cost:

100

senseLocationOf

MapLocation senseLocationOf(GameObject o)
                            throws GameActionException

Sense the location of the object o.

Throws:

GameActionException - if o is not within sensor range (CANT_SENSE_THAT)

Bytecode cost:

25

senseRobotInfo

RobotInfo senseRobotInfo(Robot r)
                         throws GameActionException

Sense the RobotInfo for the robot r.

Throws:

GameActionException - if r is not within sensor range (CANT_SENSE_THAT)

Bytecode cost:

25

canSenseObject

boolean canSenseObject(GameObject o)

Returns true if o is within sensor range.

Bytecode cost:

15

canSenseSquare

boolean canSenseSquare(MapLocation loc)

Returns true if this robot can sense the location loc.

Bytecode cost:

15

senseAlliedArchons

MapLocation[] senseAlliedArchons()

Returns the locations of all the archons on the calling robot's team. The length of the returned array is equal to the number of allied archons on the map. The order of archons in the returned array is the same between different calls to this method.

Returns:

the locations of all the allied archons

Bytecode cost:

25

senseAlliedPowerNodes

PowerNode[] senseAlliedPowerNodes()

Returns an array containing all of the power nodes owned by this robot's team.

Bytecode cost:

40

senseCapturablePowerNodes

MapLocation[] senseCapturablePowerNodes()

Returns an array containing the locations of all of the nodes that this team can capture.

Bytecode cost:

40

senseConnected

boolean senseConnected(PowerNode p)

Returns true if the node p is connected to this robot's team's power core. Note that p does not need to be within sensor range.

Bytecode cost:

20

senseOwned

boolean senseOwned(PowerNode p)

Returns true if there is an allied tower at the power node p. Note that p does not need to be within sensor range.

Bytecode cost:

20

senseOpponentConnected

boolean senseOpponentConnected(PowerNode p)
                               throws GameActionException

Returns true if the node p is connected to this robot's team's opponent's power core.

Throws:

GameActionException - if p is not within this robot's sensor range (CANT_SENSE_THAT)

Bytecode cost:

30

sensePowerCore

PowerNode sensePowerCore()

Returns this robot's team's power core.

roundsUntilMovementIdle

int roundsUntilMovementIdle()

Returns the number of rounds until this robot's movement cooldown reaches zero.

isMovementActive

boolean isMovementActive()

Returns true if this robot's movement cooldown is nonzero.

moveForward

void moveForward()
                 throws GameActionException

Queues a forward movement to be performed at the end of this robot's turn. When this action is executed, the robot will attempt to move forward one square in its current direction. If the move succeeds, this robot's new location will immediately change to the destination square, but this robot motor will not be able to move or change direction again for some number of rounds (type().moveDelayOrthogonal for orthogonal movement and type().moveDelayDiagonal for diagonal movement).

Throws:

GameActionException - if this robot is already moving (ALREADY_ACTIVE)

GameActionException - if this robot does not have enough flux to move (NOT_ENOUGH_FLUX)

GameActionException - if the destination terrain is not traversable by this robot (CANT_MOVE_THERE)

GameActionException - if the destination is occupied by another GameObject at the same height (CANT_MOVE_THERE)

Bytecode cost:

25

moveBackward

void moveBackward()
                  throws GameActionException

Queues a backward movement to be performed at the end of this robot's turn. Moving backward does not change this robot's direction.

Throws:

GameActionException

See Also:

moveForward()

Bytecode cost:

25

setDirection

void setDirection(Direction dir)
                  throws GameActionException

Queues a direction change to be performed at the end of this robot's turn. When the action is executed, the robot will change its direction.

Parameters:

dir - the direction the robot should face

Throws:

GameActionException - if this robot is already moving (ALREADY_ACTIVE)

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 whether this robot is currently active or otherwise incapable of moving.

Returns:

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

Bytecode cost:

25

roundsUntilAttackIdle

int roundsUntilAttackIdle()

Returns the number of rounds until this robot's attack cooldown reaches zero.

isAttackActive

boolean isAttackActive()

Returns true if this robot's attack cooldown is nonzero.

canAttackSquare

boolean canAttackSquare(MapLocation loc)

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,
                  RobotLevel height)
                  throws GameActionException

Attacks the given location and height. If this robot is a SCORCHER, attacks every square in the robot's attack range at ground level instead; loc and height are ignored.

Throws:

GameActionException - if this robot's attack cooldown is not zero (ALREADY_ACTIVE)

GameActionException - if this robot is not a SCORCHER and it cannot attack the given height or location (OUT_OF_RANGE)

Bytecode cost:

25

hasBroadcasted

boolean hasBroadcasted()

Returns true if this robot has already broadcasted this turn.

broadcast

void broadcast(Message msg)
               throws GameActionException

Adds a message for your robot to broadcast. At the end of your robot's execution block, if a broadcast has been set, the message is removed and immediately added to the incoming message queues of all robots in your broadcast range (except for the sending robot). Note that robots are thus limited to sending at most one message per round.

You are charged a small amount of flux for every message that you broadcast. The cost of sending a message is equal to (GameConstants.BROADCAST_FIXED_COST + GameConstants.BROADCAST_COST_PER_BYTE*sizeBytes) where sizeBytes is the size of the message, in bytes.

Each robot can only broadcast one message per round.

Parameters:

msg - the message you want to broadcast; cannot be null.

Throws:

GameActionException - if this robot already has a message queued in the current round (ALREADY_ACTIVE).

GameActionException - if this robot does not have enough flux to pay for the broadcast (NOT_ENOUGH_FLUX).

Bytecode cost:

25

spawn

void spawn(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 robot will be created at directly in front of this robot. The square must not already be occupied. The new robot is created and starts executing bytecodes immediately, but it will not be able to perform any actions for GameConstants.WAKE_DELAY rounds.

Parameters:

type - the type of robot to spawn; cannot be null.

Throws:

IllegalStateException - if this robot is not an ARCHON

GameActionException - if this robot is currently moving (ALREADY_ACTIVE)

GameActionException - if this robot does not have enough flux to spawn a robot of type type (NOT_ENOUGH_FLUX)

GameActionException - if loc is already occupied (CANT_MOVE_THERE)

Bytecode cost:

25

transferFlux

void transferFlux(MapLocation loc,
                  RobotLevel height,
                  double amount)
                  throws GameActionException

Transfers the specified amount of flux to the robot at location loc and RobotLevel height. The robot receiving the transfer must be adjacent to or in the same location as the robot giving the transfer. Robots may not transfer more flux than they currently have.

Parameters:

amount - the amount of flux to transfer to the specified robot

loc - the MapLocation of the robot to transfer to

height - the RobotLevel of the robot to transfer to

Throws:

IllegalArgumentException - if amount is negative, zero, or NaN.

GameActionException - if the robot does not have amount flux (NOT_ENOUGH_FLUX).

GameActionException - if loc is not the same as or adjacent to this robot's location (CANT_SENSE_THAT).

GameActionException - if there is no robot at the given location and height (NO_ROBOT_THERE).

Bytecode cost:

25

yield

void yield()

Ends the current round. This robot will receive a flux bonus of GameConstants.YIELD_BONUS * GameConstants.UNIT_UPKEEP * Clock.getBytecodesLeft() / GameConstants.BYTECODE_LIMIT. 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. Mainly for testing purposes.

regenerate

void regenerate()
                throws GameActionException

Causes each allied robot within its attack radius to regenerate GameConstants.REGEN_AMOUNT energon at the beginning of its next turn. Each robot may only regenerate once per turn. This action can only be activated by scouts and costs GameConstants.REGEN_COST flux.

Throws:

IllegalStateException - if this robot is not a scout

GameActionException - if this robot does not have GameConstants.REGEN_COST flux (NOT_ENOUGH_FLUX)

Bytecode cost:

40

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 loc, if loc was ever within this robot's sensor range. Otherwise, returns null.

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)

Bytecode cost:

15

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.