bot_api package

Subpackages

Submodules

bot_api.base_bot module

class BaseBot(bot_info: BotInfo | None = None, server_url: str | None = None, server_secret: str | None = None)[source]

Bases: BaseBotABC

BaseBot is a base class for creating Robocode Tank Royale bots.

Configuration and defaults:

  • By default, the constructor attempts to load a bot config JSON named <ClassName>.json located next to your bot class. If not found or incomplete, environment variables are used instead.

  • SERVER_URL can be set to the WebSocket URL of the server. If not set, ws://localhost:7654 is used.

  • SERVER_SECRET is optional. Set it only if the server requires a secret for connecting bots. If the server enforces secrets and none is provided, the server will disconnect the bot.

  • When no config file is used, these BotInfo environment variables must be provided: BOT_NAME, BOT_VERSION, BOT_AUTHORS. Optional vars include: BOT_DESCRIPTION, BOT_HOMEPAGE, BOT_COUNTRY_CODES, BOT_GAME_TYPES, BOT_PLATFORM, BOT_PROG_LANG, BOT_INITIAL_POS.

You can also pass bot_info, server_url, and server_secret explicitly via the constructor.

start() → None[source]

The method used to start running the bot. You should call this method from the main method or similar.

Example

if __name__ == “__main__”:

# create my_bot … my_bot.start()

go() → None[source]

Commits the current commands (actions), which finalizes the current turn for the bot.

This method must be called once per turn to send the bot actions to the server and must be called before the turn timeout occurs. A turn timer is started when the GameStartedEvent and TickEvent occurs. If the go() method is called too late, a turn timeout will occur and the SkippedTurnEvent will occur, which means that the bot has skipped all actions for the last turn. In this case, the server will continue executing the last actions received. This could be fatal for the bot due to loss of control over the bot. So make sure that go() is called before the turn ends.

The commands executed when go() is called are set by calling the various setter methods prior to calling the go() method: turn_rate, gun_turn_rate, radar_turn_rate, target_speed, and set_fire().

See also

turn_timeout

property my_id: int

Unique id of this bot, which is available when the game has started.

Returns:

The unique id of this bot.

property variant: str

The game variant, which is “Tank Royale”.

Returns:

The game variant of Robocode.

property version: str

Game version, e.g. “1.0.0”.

Returns:

The game version.

property game_type: str

Game type, e.g. “melee” or “1v1”.

First available when the game has started.

Returns:

The game type.

property arena_width: int

Width of the arena measured in units.

First available when the game has started.

Returns:

The arena width measured in units.

property arena_height: int

Height of the arena measured in units.

First available when the game has started.

Returns:

The arena height measured in units.

property number_of_rounds: int

The number of rounds in a battle.

First available when the game has started.

Returns:

The number of rounds in a battle.

property gun_cooling_rate: float

Gun cooling rate. The gun needs to cool down to a gun heat of zero before the gun can fire. The gun cooling rate determines how fast the gun cools down. That is, the gun cooling rate is subtracted from the gun heat each turn until the gun heat reaches zero.

First available when the game has started.

Returns:

The gun cooling rate.

See also

gun_heat

property max_inactivity_turns: int

The maximum number of inactive turns allowed the bot will become zapped by the game for being inactive. Inactive means that the bot has taken no action in several turns in a row.

First available when the game has started.

Returns:

The maximum number of allowed inactive turns.

property turn_timeout: int

The turn timeout is important as the bot needs to take action by calling go() before the turn timeout occurs. As soon as the TickEvent is triggered, i.e. when on_tick() is called, you need to call go() to take action before the turn timeout occurs. Otherwise, your bot will skip a turn and receive a on_skipped_turn() for each turn where go() is called too late.

First available when the game has started.

Returns:

The turn timeout in microseconds (1 / 1,000,000 second).

See also

time_left, go

property time_left: int

The number of microseconds left of this turn before the bot will skip the turn. Make sure to call go() before the time runs out.

Returns:

The amount of time left in microseconds.

See also

turn_timeout, go

property round_number: int

Current round number.

Returns:

The current round number.

property turn_number: int

Current turn number.

Returns:

The current turn number.

property enemy_count: int

Number of enemies left in the round.

Returns:

The number of enemies left in the round.

property energy: float

Current energy level. When the energy level is positive, the bot is alive and active. When the energy level is 0, the bot is still alive but disabled. If the bot becomes disabled it will not be able to move or take any action. If negative, the bot has been defeated.

Returns:

The current energy level.

property disabled: bool

Specifies if the bot is disabled, i.e., when the energy is zero. When the bot is disabled, it is not able to take any action like movement, turning, and firing.

Returns:

True if the bot is disabled; False otherwise.

property x: float

Current X coordinate of the center of the bot.

Returns:

The current X coordinate of the bot.

property y: float

Current Y coordinate of the center of the bot.

Returns:

The current Y coordinate of the bot.

property direction: float

Current driving direction of the bot in degrees.

Returns:

The current driving direction of the bot.

property gun_direction: float

Current direction of the gun in degrees.

Returns:

The current gun direction of the bot.

property radar_direction: float

Current direction of the radar in degrees.

Returns:

The current radar direction of the bot.

property speed: float

The current speed measured in units per turn. If the speed is positive, the bot moves forward. If negative, the bot moves backward. Zero speed means that the bot is not moving from its current position.

Returns:

The current speed.

property gun_heat: float

Current gun heat. When the gun is fired it gets heated and will not be able to fire before it has been cooled down. The gun is cooled down when the gun heat is zero.

When the gun has fired the gun heat is set to 1 + (firepower / 5) and will be cooled down by the gun cooling rate.

Returns:

The current gun heat.

See also

gun_cooling_rate

property bullet_states: Sequence[BulletState | None] | None

Current bullet states. Keeps track of all the bullets fired by the bot, which are still active on the arena.

Returns:

The current bullet states.

property events: Sequence[BotEvent | None] | None

Returns an ordered list containing all events currently in the bot’s event queue. You might, for example, call this while processing another event.

Returns:

An ordered list containing all events currently in the bot’s event queue.

See also

clear_events

clear_events() → None[source]

Clears out any pending events in the bot’s event queue immediately.

See also

events

property turn_rate: float

Returns the turn rate of the bot in degrees per turn.

Returns:

The turn rate of the bot.

property max_turn_rate: float

Returns the maximum turn rate of the bot in degrees per turn.

Returns:

The maximum turn rate of the bot.

property gun_turn_rate: float

Returns the gun turn rate in degrees per turn.

Returns:

The gun turn rate.

property max_gun_turn_rate: float

Returns the maximum gun turn rate in degrees per turn.

Returns:

The maximum gun turn rate.

property radar_turn_rate: float

Returns the radar turn rate in degrees per turn.

Returns:

The radar turn rate.

property max_radar_turn_rate: float

Returns the maximum radar turn rate in degrees per turn.

Returns:

The maximum radar turn rate.

property target_speed: float

Returns the target speed in units per turn.

Returns:

The target speed.

property max_speed: float

Returns the maximum speed in units per turn.

Returns:

The maximum speed.

set_fire(firepower: float) → bool[source]

Sets the gun to fire in the direction the gun is pointing with the specified firepower.

Parameters:

firepower – The firepower to use for firing.

Returns:

True if the gun will fire; False otherwise.

property firepower: float

Returns the firepower set for firing the gun.

Returns:

The firepower.

set_rescan() → None[source]

Sets the radar to rescan with the radar.

set_fire_assist(enable: bool) → None[source]

Enables or disables fire assistance.

Parameters:

enable – True to enable fire assist; False to disable.

set_interruptible(interruptible: bool) → None[source]

Sets whether the bot’s event handlers are interruptible.

When set to True, the bot’s event handlers can be interrupted by higher-priority events. When set to False, event handlers will run to completion before other events are processed.

Parameters:

interruptible (bool) – If True, event handlers are interruptible; otherwise, they are not.

property adjust_gun_for_body_turn: bool

Returns whether the gun adjusts for the bot’s body turn.

property adjust_radar_for_body_turn: bool

Returns whether the radar adjusts for the bot’s body turn.

property adjust_radar_for_gun_turn: bool

Returns whether the radar adjusts for the gun’s turn.

add_custom_event(condition: Condition) → bool[source]

Adds a custom event based on a condition. When the condition is met, the on_custom_event() handler is triggered with a CustomEvent containing the condition.

Parameters:

condition – The condition that must be met to trigger the custom event.

Returns:

True if the condition was added; False if it already exists.

remove_custom_event(condition: Condition) → bool[source]

Removes a custom event that was previously added with add_custom_event().

Parameters:

condition – The condition to remove.

Returns:

True if the condition was removed; False if it was not found.

set_stop(overwrite: bool = False) → None[source]

Sets the bot to stop all movement including turning the gun and radar. The remaining movement is saved for a call to set_resume() or resume().

Parameters:

overwrite – True to override a previously saved movement from stop() or set_stop().

set_resume() → None[source]

Sets the bot to resume the movement prior to calling set_stop() or stop().

property teammate_ids: set[int]

Returns the IDs of all teammates.

Returns:

A set of teammate IDs.

is_teammate(bot_id: int) → bool[source]

Checks if the specified bot ID is a teammate.

Parameters:

bot_id – The bot ID to check.

Returns:

True if the bot is a teammate; False otherwise.

broadcast_team_message(message: Any) → None[source]

Broadcasts a message to all teammates.

Parameters:

message – The message to broadcast.

send_team_message(teammate_id: int, message: Any) → None[source]

Sends a message to a specific teammate.

Parameters:

  • teammate_id – The ID of the teammate to send the message to.

  • message – The message to send.

property stopped: bool

Checks if the bot is currently stopped.

Returns:

True if the bot is stopped; False otherwise.

property body_color: Color | None

Returns the color of the body.

Returns:

The body color or None if not set.

MAX_NUMBER_OF_TEAM_MESSAGES_PER_TURN: int = 10

The maximum number of team messages that can be sent per turn, which is 10 messages.

TEAM_MESSAGE_MAX_SIZE: int = 32768

Maximum size of a team message, which is 32 KB.

bearing_to(x: float, y: float) → float

Calculates the bearing (delta angle) between the bot’s current direction and the direction to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

A bearing to the point (x, y) in the range [-180, 180).

Return type:

float

calc_bearing(direction: float) → float

Calculates the bearing (delta angle) between the input direction and the bot’s direction.

Example

bearing = calc_bearing(direction) = normalize_relative_degrees(direction - self.direction)

Parameters:

direction (float) – The input direction to calculate the bearing from.

Returns:

A normalized bearing (delta angle) in the range [-180, 180).

Return type:

float

See also

direction, normalize_relative_angle.

calc_delta_angle(target_angle: float, source_angle: float) → float

Calculates the difference between two angles, i.e., the number of degrees from a source angle to a target angle.

Parameters:

  • target_angle (float) – The target angle.

  • source_angle (float) – The source angle.

Returns:

The delta angle in the range [-180, 180].

Return type:

float

calc_gun_bearing(direction: float) → float

Calculates the bearing (delta angle) between the input direction and the gun’s direction.

Example

bearing = calc_gun_bearing(direction) =

normalize_relative_degrees(direction - self.gun_direction)

Parameters:

direction (float) – The input direction to calculate the bearing from.

Returns:

A normalized bearing (delta angle) in the range [-180, 180).

Return type:

float

See also

gun_direction, normalize_relative_angle.

calc_radar_bearing(direction: float) → float

Calculates the bearing (delta angle) between the input direction and the radar’s direction.

Example

bearing = calc_radar_bearing(direction) =

normalize_relative_degrees(direction - self.radar_direction)

Parameters:

direction (float) – The input direction to calculate the bearing from.

Returns:

A normalized bearing (delta angle) in the range [-180, 180).

Return type:

float

See also

radar_direction, normalize_relative_angle.

direction_to(x: float, y: float) → float

Calculates the direction (angle) from the bot’s coordinates to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

The direction to the point (x, y) in the range [0, 360).

Return type:

float

distance_to(x: float, y: float) → float

Calculates the distance from the bot’s coordinates to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

The distance to the point (x, y).

Return type:

float

gun_bearing_to(x: float, y: float) → float

Calculates the bearing (delta angle) between the gun’s current direction and the direction to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

A bearing to the point (x, y) in the range [-180, 180).

Return type:

float

normalize_absolute_angle(angle: float) → float

Normalizes an angle to an absolute angle in the range [0, 360).

Parameters:

angle (float) – The angle to normalize.

Returns:

The normalized absolute angle.

Return type:

float

normalize_relative_angle(angle: float) → float

Normalizes the given angle to the range [-180, 180] degrees.

Parameters:

angle (float) – The angle to normalize.

Returns:

The normalized angle in degrees.

Return type:

float

on_bot_death(bot_death_event: BotDeathEvent) → None

The event handler triggered when another bot has died.

Parameters:

bot_death_event – The event details from the game.

on_bullet_fired(bullet_fired_event: BulletFiredEvent) → None

The event handler triggered when the bot has fired a bullet.

Parameters:

bullet_fired_event – The event details from the game.

on_bullet_hit(bullet_hit_bot_event: BulletHitBotEvent) → None

The event handler triggered when the bot has hit another bot with a bullet.

Parameters:

bullet_hit_bot_event – The event details from the game.

on_bullet_hit_bullet(bullet_hit_bullet_event: BulletHitBulletEvent) → None

The event handler triggered when a bullet fired from the bot has collided with another bullet.

Parameters:

bullet_hit_bullet_event – The event details from the game.

on_bullet_hit_wall(bullet_hit_wall_event: BulletHitWallEvent) → None

The event handler triggered when a bullet has hit a wall.

Parameters:

bullet_hit_wall_event – The event details from the game.

static on_connected(connected_event: ConnectedEvent) → None

The event handler triggered when connected to the server.

Parameters:

connected_event – The event details from the game.

static on_connection_error(connection_error_event: ConnectionErrorEvent) → None

The event handler triggered when a connection error occurs.

Parameters:

connection_error_event – The event details from the game.

on_custom_event(custom_event: CustomEvent) → None

The event handler triggered when some condition has been met. Use the name of the condition when you need to differentiate between different types of conditions received with this event handler.

Parameters:

custom_event – The event details from the game.

on_death(death_event: DeathEvent) → None

The event handler triggered when this bot has died.

Parameters:

death_event – The event details from the game.

static on_disconnected(disconnected_event: DisconnectedEvent) → None

The event handler triggered when disconnected from the server.

Parameters:

disconnected_event – The event details from the game.

on_game_ended(game_ended_event: GameEndedEvent) → None

The event handler triggered when a game has ended.

Parameters:

game_ended_event – The event details from the game.

on_game_started(game_started_event: GameStartedEvent) → None

The event handler triggered when a game has started.

Parameters:

game_started_event – The event details from the game.

on_hit_bot(bot_hit_bot_event: HitBotEvent) → None

The event handler triggered when the bot has collided with another bot.

Parameters:

bot_hit_bot_event – The event details from the game.

on_hit_by_bullet(hit_by_bullet_event: HitByBulletEvent) → None

The event handler triggered when the bot has been hit by a bullet.

Parameters:

hit_by_bullet_event – The event details from the game.

on_hit_wall(bot_hit_wall_event: HitWallEvent) → None

The event handler triggered when the bot has hit a wall.

Parameters:

bot_hit_wall_event – The event details from the game.

on_round_ended(round_ended_event: RoundEndedEvent) → None

The event handler triggered when a round has ended.

Parameters:

round_ended_event – The event details from the game.

on_round_started(round_started_event: RoundStartedEvent) → None

The event handler triggered when a new round has started.

Parameters:

round_started_event – The event details from the game.

on_scanned_bot(scanned_bot_event: ScannedBotEvent) → None

The event handler triggered when the bot has skipped a turn. This event occurs if the bot did not take any action in a specific turn. That is, go() was not called before the turn timeout occurred for the turn. If the bot does not take action for multiple turns in a row, it will receive a SkippedTurnEvent for each turn where it did not take action. When the bot is skipping a turn, the server did not receive the message from the bot, and the server will use the newest received instructions for target speed, turn rates, firing, etc.

Parameters:

scanned_bot_event – The event details from the game.

on_skipped_turn(skipped_turn_event: SkippedTurnEvent) → None

Handles the event triggered when the bot skips a turn.

A turn is skipped if the bot does not send any instructions to the server (via the go() method) before the turn timeout occurs. When this happens, the server continues using the last received set of actions, such as movement, turning rates, or firing commands.

Reasons for skipped turns may include:

  • Excessive processing or delays in the bot’s logic, leading to a timeout.

  • Failure to invoke the go() method in the current turn.

  • Misaligned or unintended logic in the bot’s turn-handling code.

This method can be overridden to define custom behavior for handling skipped turns, such as logging the event, debugging performance issues, or modifying the bot’s logic to avoid future skips.

Parameters:

skipped_turn_event – An event containing details about the skipped turn.

on_team_message(team_message_event: TeamMessageEvent) → None

The event handler triggered when the bot has received a message from a teammate.

Parameters:

team_message_event – The event details from the game.

on_tick(tick_event: TickEvent) → None

The event handler triggered when a game tick event occurs, i.e., when a new turn in a round has started.

Parameters:

tick_event – The event details from the game.

on_won_round(won_round_event: WonRoundEvent) → None

The event handler triggered when the bot has won a round.

Parameters:

won_round_event – The event details from the game.

radar_bearing_to(x: float, y: float) → float

Calculates the bearing (delta angle) between the radar’s current direction and the direction to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

A bearing to the point (x, y) in the range [-180, 180).

Return type:

float

property turret_color: Color | None

Returns the color of the turret.

Returns:

The turret color or None if not set.

property radar_color: Color | None

Returns the color of the radar.

Returns:

The radar color or None if not set.

property bullet_color: Color | None

Returns the color of the bullets.

Returns:

The bullet color or None if not set.

property scan_color: Color | None

Returns the color of the scan arc.

Returns:

The scan color or None if not set.

property tracks_color: Color | None

Returns the color of the tracks.

Returns:

The tracks color or None if not set.

property gun_color: Color | None

Returns the color of the gun.

Returns:

The gun color or None if not set.

property debugging_enabled: bool

Checks if debugging is enabled for this bot.

Returns:

True if debugging is enabled; False otherwise.

property graphics: GraphicsABC

Returns the graphics context for drawing debug graphics.

Returns:

The graphics context.

calc_max_turn_rate(speed: float) → float[source]

Calculates the maximum turn rate for a given speed.

Parameters:

speed – The speed.

Returns:

The maximum turn rate at the given speed.

calc_bullet_speed(firepower: float) → float[source]

Calculates the bullet speed for a given firepower.

Parameters:

firepower – The firepower.

Returns:

The bullet speed.

calc_gun_heat(firepower: float) → float[source]

Calculates the gun heat generated by firing with a given firepower.

Parameters:

firepower – The firepower.

Returns:

The gun heat generated.

get_event_priority(event_class: type) → int[source]

Returns the priority of an event class.

Parameters:

event_class – The event class.

Returns:

The priority of the event class.

set_event_priority(event_class: type, priority: int) → None[source]

Sets the priority of an event class.

Parameters:

  • event_class – The event class.

  • priority – The new priority.

bot_api.base_bot_abc module

class BaseBotABC[source]

Bases: ABC

Interface containing the core API for a bot.

TEAM_MESSAGE_MAX_SIZE: int = 32768

Maximum size of a team message, which is 32 KB.

MAX_NUMBER_OF_TEAM_MESSAGES_PER_TURN: int = 10

The maximum number of team messages that can be sent per turn, which is 10 messages.

abstractmethod start() → None[source]

The method used to start running the bot. You should call this method from the main function or a similar entry point.

This method blocks until the bot disconnects from the server.

Example:

if __name__ == "__main__":
    # create my_bot
    ...
    my_bot.start()
abstractmethod go() → None[source]

Commits the current commands (actions), which finalizes the current turn for the bot.

This method must be called once per turn to send the bot actions to the server and must be called before the turn timeout occurs. A turn timer is started when the GameStartedEvent and TickEvent occurs. If the go() method is called too late, a turn timeout will occur and the SkippedTurnEvent will occur, which means that the bot has skipped all actions for the last turn. In this case, the server will continue executing the last actions received. This could be fatal for the bot due to loss of control over the bot. So make sure that go() is called before the turn ends.

The commands executed when go() is called are set by calling the various setter methods prior to calling the go() method: turn_rate, gun_turn_rate, radar_turn_rate, target_speed, and set_fire().

See also

turn_timeout

abstract property my_id: int

The bot’s unique identifier.

abstract property variant: str

The game variant, which is “Tank Royale”.

Returns:

The game variant of Robocode.

Return type:

str

abstract property version: str

Game version, e.g. “1.0.0”.

Returns:

The game version.

Return type:

str

abstract property game_type: str

Game type, e.g. “melee” or “1v1”.

First available when the game has started.

Returns:

The game type.

Return type:

str

abstract property arena_width: int

Width of the arena measured in units.

First available when the game has started.

Returns:

The arena width measured in units

Return type:

int

abstract property arena_height: int

Height of the arena measured in units.

First available when the game has started.

Returns:

The arena height measured in units

Return type:

int

abstract property number_of_rounds: int

The number of rounds in a battle.

First available when the game has started.

Returns:

The number of rounds in a battle.

Return type:

int

abstract property gun_cooling_rate: float

Gun cooling rate.

The gun needs to cool down to a gun heat of zero before the gun can fire. The gun cooling rate determines how fast the gun cools down. That is, the gun cooling rate is subtracted from the gun heat each turn until the gun heat reaches zero.

First available when the game has started.

Returns:

The gun cooling rate.

Return type:

float

abstract property max_inactivity_turns: int

The maximum number of inactive turns allowed.

The bot will become zapped by the game for being inactive. Inactive means that the bot has taken no action in several turns in a row.

First available when the game has started.

Returns:

The maximum number of allowed inactive turns.

Return type:

int

abstract property turn_timeout: int

The turn timeout in microseconds.

The turn timeout is important as the bot needs to take action by calling go() before the turn timeout occurs. As soon as the TickEvent() is triggered, i.e. when onTick() is called, you need to call go() to take action before the turn timeout occurs. Otherwise, your bot will skip a turn and receive a onSkippedTurn for each turn where go() is called too late.

First available when the game has started.

Returns:

The turn timeout in microseconds.

Return type:

int

abstract property time_left: int

The number of microseconds left of this turn before the bot will skip the turn.

Make sure to call go() before the time runs out.

Returns:

The amount of time left in microseconds.

Return type:

int

abstract property round_number: int

Current round number.

Returns:

The current round number.

Return type:

int

abstract property turn_number: int

Current turn number.

Returns:

The current turn number.

Return type:

int

abstract property enemy_count: int

Number of enemies left in the round.

Returns:

The number of enemies left in the round.

Return type:

int

abstract property energy: float

Current energy level.

When the energy level is positive, the bot is alive and active. When the energy level is 0, the bot is still alive but disabled. If the bot becomes disabled it will not be able to move or take any action. If negative, the bot has been defeated.

Returns:

The current energy level.

Return type:

float

abstract property disabled: bool

Specifies if the bot is disabled, i.e., when the energy is zero.

When the bot is disabled, it is not able to take any action like movement, turning, and firing.

Returns:

True if the bot is disabled; False otherwise.

Return type:

bool

abstract property x: float

Current X coordinate of the center of the bot.

Returns:

The current X coordinate of the bot.

Return type:

float

abstract property y: float

Current Y coordinate of the center of the bot.

Returns:

The current Y coordinate of the bot.

Return type:

float

abstract property direction: float

Current driving direction of the bot in degrees.

Returns:

The current driving direction of the bot.

Return type:

float

abstract property gun_direction: float

Current direction of the gun in degrees.

Returns:

The current gun direction of the bot.

Return type:

float

abstract property radar_direction: float

Current direction of the radar in degrees.

Returns:

The current radar direction of the bot.

Return type:

float

abstract property speed: float

The current speed measured in units per turn.

If the speed is positive, the bot moves forward. If negative, the bot moves backward. Zero speed means that the bot is not moving from its current position.

Returns:

The current speed.

Return type:

float

abstract property gun_heat: float

Current gun heat.

When the gun is fired it gets heated and will not be able to fire before it has been cooled down. The gun is cooled down when the gun heat is zero. When the gun has fired the gun heat is set to 1 + (firepower / 5) and will be cooled down by the gun cooling rate.

Returns:

The current gun heat.

Return type:

float

abstract property bullet_states: Sequence[BulletState | None] | None

Current bullet states.

Keeps track of all the bullets fired by the bot, which are still active on the arena.

Returns:

The current bullet states.

Return type:

list[BulletState]

abstract property events: Sequence[BotEvent | None] | None

Returns an ordered list containing all events currently in the bot’s event queue.

You might, for example, call this while processing another event.

Returns:

An ordered list containing all events currently in the bot’s event queue.

Return type:

list[BotEvent]

abstractmethod clear_events() → None[source]

Clears out any pending events in the bot’s event queue immediately.

abstract property turn_rate: float

Returns the turn rate of the bot in degrees per turn.

Returns:

The turn rate of the bot.

Return type:

float

abstract property max_turn_rate: float

Returns the maximum turn rate of the bot in degrees per turn.

Returns:

The maximum turn rate of the bot.

Return type:

float

abstract property gun_turn_rate: float

Returns the gun turn rate in degrees per turn.

Returns:

The turn rate of the gun.

Return type:

float

abstract property max_gun_turn_rate: float

Returns the maximum gun turn rate in degrees per turn.

Returns:

The maximum turn rate of the gun.

Return type:

float

abstract property radar_turn_rate: float

Returns the radar turn rate in degrees per turn.

Returns:

The turn rate of the radar.

Return type:

float

abstract property max_radar_turn_rate: float

Returns the maximum radar turn rate in degrees per turn.

Returns:

The maximum turn rate of the radar.

Return type:

float

abstract property target_speed: float

Returns the target speed in units per turn.

Returns:

The target speed.

Return type:

float

abstract property max_speed: float

Returns the maximum speed in units per turn.

Returns:

The maximum speed.

Return type:

float

abstractmethod set_fire(firepower: float) → bool[source]

Sets the gun to fire in the direction that the gun is pointing with the specified firepower.

Firepower is the amount of energy your bot will spend on firing the gun. This means that the bot will lose power on firing the gun, where the energy loss is equal to the firepower. You cannot spend more energy than is available from your bot.

The bullet power must be greater than the minimum firepower and gun heat must be zero before the gun can fire.

If the bullet hits an opponent bot, you will gain energy from the bullet hit. When hitting another bot, your bot will be rewarded and retrieve an energy boost of 3x the firepower.

The gun will only fire when the firepower is at or above the minimum firepower. If the firepower is greater than the maximum firepower, the power will be truncated to the maximum firepower.

Whenever the gun is fired, the gun becomes heated and needs to cool down before it can fire again. The gun heat must be zero before the gun can fire again. The gun heat generated by firing the gun is calculated as 1 + (firepower / 5). Hence, the more firepower used, the longer it takes to cool down the gun. The gun cooling rate can be retrieved using the get_gun_cooling_rate() function.

The amount of energy used for firing the gun is subtracted from the bot’s total energy. The amount of damage dealt by a bullet hitting another bot is 4x firepower. If the firepower is greater than 1, it will deal an additional 2 x (firepower - 1) damage.

Note that the gun will automatically keep firing each turn as soon as the gun heat reaches zero. It is possible to disable the gun firing by setting the firepower to zero.

The firepower is truncated between 0 and the maximum firepower if the provided value exceeds this range.

If this property is set multiple times, the last value set before calling go() is used.

Parameters:

firepower (float) – The new firepower.

Returns:

True if the cannon can fire (i.e., if there is no gun heat), False otherwise.

Return type:

bool

See also

  • on_bullet_fired()

  • get_firepower()

  • get_gun_heat()

  • get_gun_cooling_rate()

abstract property firepower: float

Returns the firepower.

Returns:

The firepower.

Return type:

float

abstractmethod set_rescan() → None[source]

Sets the bot to rescan with the radar.

This method is useful if the radar has not turned, and hence will not automatically scan bots. The last radar direction and sweep angle will be used for scanning for bots.

abstractmethod set_fire_assist(enable: bool) → None[source]

Enables or disables fire assistance explicitly. Fire assistance is useful for bots with limited aiming capabilities as it helps the bot by firing directly at a scanned bot when the gun is fired, which is a very simple aiming strategy.

When fire assistance is enabled, the gun will fire towards the center of the scanned bot when all these conditions are met:

  1. The gun is fired (via set_fire or fire()).

  2. The radar is scanning a bot when firing the gun (e.g., in the on_scanned_bot() event, after calling set_rescan() or rescan()).

  3. The gun and radar are pointing in the exact same direction. You can disable radar and gun movement alignment using set_adjust_radar_for_gun_turn(False) to ensure the gun and radar stay aligned while avoiding radar turning independently of the gun.

The fire assistance feature is provided for backwards compatibility with the original Robocode, where bots that were not considered AdvancedRobot had fire assistance enabled by default, as their gun and radar could not move independently of each other. In contrast, AdvancedRobot allows the body, gun, and radar to move independently.

Parameters:

enable (bool) – Enables fire assistance when set to True, and disables it otherwise.

abstractmethod set_interruptible(interruptible: bool) → None[source]

Sets whether the bot’s event handlers are interruptible.

When set to True, event handlers can be interrupted by higher-priority events. When set to False, handlers run to completion before other events are processed.

Parameters:

interruptible (bool) – If True, event handlers are interruptible; otherwise, they are not.

abstract property adjust_gun_for_body_turn: bool

Returns whether the gun adjusts for the bot’s body turn.

Returns:

True if the gun adjusts for body turn; False otherwise.

Return type:

bool

abstract property adjust_radar_for_body_turn: bool

Returns whether the radar adjusts for the bot’s body turn.

Returns:

True if the radar adjusts for body turn; False otherwise.

Return type:

bool

abstract property adjust_radar_for_gun_turn: bool

Returns whether the radar adjusts for the gun’s turn.

Returns:

True if the radar adjusts for gun turn; False otherwise.

Return type:

bool

abstractmethod is_teammate(bot_id: int) → bool[source]

Checks if the specified bot ID is a teammate.

Parameters:

bot_id (int) – The bot ID to check.

Returns:

True if the bot is a teammate; False otherwise.

Return type:

bool

abstract property teammate_ids: set[int]

The IDs of all teammates.

Returns:

A set of IDs of all teammates if the bot is participating in a team, or an empty set if the bot is not in a team.

Return type:

Set[int]

See also

is_teammate: Checks if a bot is a teammate. send_team_message: Sends a message to the team.

abstractmethod broadcast_team_message(message: Any) → None[source]

Broadcasts a message to all teammates.

When the message is sent, it is serialized into a JSON representation. This means that all public fields, and only public fields, are serialized into a JSON representation as a data transfer object (DTO).

The maximum team message size limit is defined by TEAM_MESSAGE_MAX_SIZE, which is set to 32,768 bytes. This size is calculated after serializing the message into a JSON representation.

The maximum number of messages that can be broadcast per turn is limited to MAX_NUMBER_OF_TEAM_MESSAGES_PER_TURN, which is set to 10.

Parameters:

message – The message to broadcast.

Raises:

ValueError – If the size of the message exceeds the size limit.

See also

send_team_message: Method to send a message to teammates. get_teammate_ids: Method to retrieve IDs of all teammates.

abstractmethod send_team_message(teammate_id: int, message: Any) → None[source]

Sends a message to a specific teammate.

When the message is sent, it is serialized into a JSON representation, meaning that all public fields, and only public fields, are being serialized into a JSON representation as a DTO (data transfer object).

The maximum team message size limit is defined by TEAM_MESSAGE_MAX_SIZE, which is set to TEAM_MESSAGE_MAX_SIZE bytes. This size is the size of the message when it is serialized into a JSON representation.

The maximum number of messages that can be sent/broadcast per turn is limited to MAX_NUMBER_OF_TEAM_MESSAGES_PER_TURN.

Parameters:

  • teammate_id – The id of the teammate to send the message to.

  • message – The message to send.

Raises:

ValueError – If the size of the message exceeds the size limit.

abstract property stopped: bool

Checks if the movement has been stopped.

Returns:

True if the movement has been stopped by set_stop(), False otherwise.

Return type:

bool

See also

set_resume: Resumes the movement. set_stop(): Stops the movement. set_stop(flag: bool): Stops the movement, with a flag to specify additional behavior.

abstract property body_color: Color | None

Returns the color of the body.

Returns:

The color of the body, or None if no color has been set yet.

In that case, the default color will be used.

Return type:

Color

abstract property turret_color: Color | None

Returns the color of the gun turret.

Returns:

The color of the turret or None if no color has been set yet, meaning that the default color will be used.

abstract property radar_color: Color | None

Returns the color of the radar.

Returns:

The color of the radar. If no color has been set yet, returns None, which indicates that the default radar color will be used.

Return type:

Color

abstract property bullet_color: Color | None

Returns the color of the fired bullets.

Returns:

The color of the bullets, or None if no color has been set yet, meaning that the default color will be used.

Return type:

Color

abstract property scan_color: Color | None

Returns the color of the scan arc.

Returns:

The color of the scan arc, or None if no color has been set, meaning the default color will be used.

Return type:

Color

abstract property tracks_color: Color | None

Returns the color of the tank tracks.

Returns:

The color of the tank tracks, or None if no color has been set yet, meaning that the default color will be used.

Return type:

Color

abstract property gun_color: Color | None

Returns the color of the gun.

Returns:

The color of the gun, or None if no color has been set yet. If None, the default color will be used.

Return type:

Color

abstract property debugging_enabled: bool

Indicates whether graphical debugging is enabled. If enabled, the graphics property can be used for debug painting.

Returns:

True if graphical debugging is enabled, False otherwise.

Return type:

bool

abstract property graphics: GraphicsABC

Gets a graphics object for debug painting.

Example

g = self.graphics g.set_fill_color(Color.from_rgb(0, 0, 255)) g.fill_rectangle(50, 50, 100, 100) # A blue filled rect

Returns:

A graphics canvas to use for painting graphical objects, making debugging easier.

static on_connected(connected_event: ConnectedEvent) → None[source]

The event handler triggered when connected to the server.

Parameters:

connected_event – The event details from the game.

static on_disconnected(disconnected_event: DisconnectedEvent) → None[source]

The event handler triggered when disconnected from the server.

Parameters:

disconnected_event – The event details from the game.

static on_connection_error(connection_error_event: ConnectionErrorEvent) → None[source]

The event handler triggered when a connection error occurs.

Parameters:

connection_error_event – The event details from the game.

on_game_started(game_started_event: GameStartedEvent) → None[source]

The event handler triggered when a game has started.

Parameters:

game_started_event – The event details from the game.

on_game_ended(game_ended_event: GameEndedEvent) → None[source]

The event handler triggered when a game has ended.

Parameters:

game_ended_event – The event details from the game.

on_round_started(round_started_event: RoundStartedEvent) → None[source]

The event handler triggered when a new round has started.

Parameters:

round_started_event – The event details from the game.

on_round_ended(round_ended_event: RoundEndedEvent) → None[source]

The event handler triggered when a round has ended.

Parameters:

round_ended_event – The event details from the game.

on_tick(tick_event: TickEvent) → None[source]

The event handler triggered when a game tick event occurs, i.e., when a new turn in a round has started.

Parameters:

tick_event – The event details from the game.

on_bot_death(bot_death_event: BotDeathEvent) → None[source]

The event handler triggered when another bot has died.

Parameters:

bot_death_event – The event details from the game.

on_death(death_event: DeathEvent) → None[source]

The event handler triggered when this bot has died.

Parameters:

death_event – The event details from the game.

on_hit_bot(bot_hit_bot_event: HitBotEvent) → None[source]

The event handler triggered when the bot has collided with another bot.

Parameters:

bot_hit_bot_event – The event details from the game.

on_hit_wall(bot_hit_wall_event: HitWallEvent) → None[source]

The event handler triggered when the bot has hit a wall.

Parameters:

bot_hit_wall_event – The event details from the game.

on_bullet_fired(bullet_fired_event: BulletFiredEvent) → None[source]

The event handler triggered when the bot has fired a bullet.

Parameters:

bullet_fired_event – The event details from the game.

on_hit_by_bullet(hit_by_bullet_event: HitByBulletEvent) → None[source]

The event handler triggered when the bot has been hit by a bullet.

Parameters:

hit_by_bullet_event – The event details from the game.

on_bullet_hit(bullet_hit_bot_event: BulletHitBotEvent) → None[source]

The event handler triggered when the bot has hit another bot with a bullet.

Parameters:

bullet_hit_bot_event – The event details from the game.

on_bullet_hit_bullet(bullet_hit_bullet_event: BulletHitBulletEvent) → None[source]

The event handler triggered when a bullet fired from the bot has collided with another bullet.

Parameters:

bullet_hit_bullet_event – The event details from the game.

on_bullet_hit_wall(bullet_hit_wall_event: BulletHitWallEvent) → None[source]

The event handler triggered when a bullet has hit a wall.

Parameters:

bullet_hit_wall_event – The event details from the game.

on_scanned_bot(scanned_bot_event: ScannedBotEvent) → None[source]

The event handler triggered when the bot has skipped a turn. This event occurs if the bot did not take any action in a specific turn. That is, go() was not called before the turn timeout occurred for the turn. If the bot does not take action for multiple turns in a row, it will receive a SkippedTurnEvent for each turn where it did not take action. When the bot is skipping a turn, the server did not receive the message from the bot, and the server will use the newest received instructions for target speed, turn rates, firing, etc.

Parameters:

scanned_bot_event – The event details from the game.

on_skipped_turn(skipped_turn_event: SkippedTurnEvent) → None[source]

Handles the event triggered when the bot skips a turn.

A turn is skipped if the bot does not send any instructions to the server (via the go() method) before the turn timeout occurs. When this happens, the server continues using the last received set of actions, such as movement, turning rates, or firing commands.

Reasons for skipped turns may include:

  • Excessive processing or delays in the bot’s logic, leading to a timeout.

  • Failure to invoke the go() method in the current turn.

  • Misaligned or unintended logic in the bot’s turn-handling code.

This method can be overridden to define custom behavior for handling skipped turns, such as logging the event, debugging performance issues, or modifying the bot’s logic to avoid future skips.

Parameters:

skipped_turn_event – An event containing details about the skipped turn.

on_won_round(won_round_event: WonRoundEvent) → None[source]

The event handler triggered when the bot has won a round.

Parameters:

won_round_event – The event details from the game.

on_custom_event(custom_event: CustomEvent) → None[source]

The event handler triggered when some condition has been met. Use the name of the condition when you need to differentiate between different types of conditions received with this event handler.

Parameters:

custom_event – The event details from the game.

on_team_message(team_message_event: TeamMessageEvent) → None[source]

The event handler triggered when the bot has received a message from a teammate.

Parameters:

team_message_event – The event details from the game.

abstractmethod calc_max_turn_rate(speed: float) → float[source]

Calculates the maximum turn rate for a specific speed.

Parameters:

speed (float) – The speed.

Returns:

The maximum turn rate determined by the given speed.

Return type:

float

abstractmethod calc_bullet_speed(firepower: float) → float[source]

Calculates the bullet speed given a firepower.

Parameters:

firepower (float) – The firepower.

Returns:

The bullet speed determined by the given firepower.

Return type:

float

abstractmethod calc_gun_heat(firepower: float) → float[source]

Calculates gun heat after having fired the gun.

Parameters:

firepower (float) – The firepower used when firing the gun.

Returns:

The gun heat produced when firing the gun with the given firepower.

Return type:

float

abstractmethod get_event_priority(event_class: type) → int[source]

Returns the event priority for a specific event class.

Example

scanned_bot_event_priority = get_priority(ScannedBotEvent)

Parameters:

event_class – The event class to get the event priority for.

Returns:

The event priority for a specific event class.

Return type:

int

See also

DefaultEventPriority set_event_priority

abstractmethod set_event_priority(event_class: type, priority: int) → None[source]

Changes the event priority for an event class. The event priority determines which event types (classes) must be fired and handled before others. Events with higher priorities will be handled before events with lower priorities.

Note

You should normally not need to change the event priority.

Parameters:

  • event_class (Type[BotEvent]) – The event class to change the priority for.

  • priority (int) – The new priority, typically a positive number from 1 to 150. The higher the value, the higher the priority.

See also

DefaultEventPriority, get_event_priority.

calc_bearing(direction: float) → float[source]

Calculates the bearing (delta angle) between the input direction and the bot’s direction.

Example

bearing = calc_bearing(direction) = normalize_relative_degrees(direction - self.direction)

Parameters:

direction (float) – The input direction to calculate the bearing from.

Returns:

A normalized bearing (delta angle) in the range [-180, 180).

Return type:

float

See also

direction, normalize_relative_angle.

calc_gun_bearing(direction: float) → float[source]

Calculates the bearing (delta angle) between the input direction and the gun’s direction.

Example

bearing = calc_gun_bearing(direction) =

normalize_relative_degrees(direction - self.gun_direction)

Parameters:

direction (float) – The input direction to calculate the bearing from.

Returns:

A normalized bearing (delta angle) in the range [-180, 180).

Return type:

float

See also

gun_direction, normalize_relative_angle.

calc_radar_bearing(direction: float) → float[source]

Calculates the bearing (delta angle) between the input direction and the radar’s direction.

Example

bearing = calc_radar_bearing(direction) =

normalize_relative_degrees(direction - self.radar_direction)

Parameters:

direction (float) – The input direction to calculate the bearing from.

Returns:

A normalized bearing (delta angle) in the range [-180, 180).

Return type:

float

See also

radar_direction, normalize_relative_angle.

direction_to(x: float, y: float) → float[source]

Calculates the direction (angle) from the bot’s coordinates to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

The direction to the point (x, y) in the range [0, 360).

Return type:

float

bearing_to(x: float, y: float) → float[source]

Calculates the bearing (delta angle) between the bot’s current direction and the direction to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

A bearing to the point (x, y) in the range [-180, 180).

Return type:

float

gun_bearing_to(x: float, y: float) → float[source]

Calculates the bearing (delta angle) between the gun’s current direction and the direction to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

A bearing to the point (x, y) in the range [-180, 180).

Return type:

float

radar_bearing_to(x: float, y: float) → float[source]

Calculates the bearing (delta angle) between the radar’s current direction and the direction to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

A bearing to the point (x, y) in the range [-180, 180).

Return type:

float

distance_to(x: float, y: float) → float[source]

Calculates the distance from the bot’s coordinates to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

The distance to the point (x, y).

Return type:

float

normalize_absolute_angle(angle: float) → float[source]

Normalizes an angle to an absolute angle in the range [0, 360).

Parameters:

angle (float) – The angle to normalize.

Returns:

The normalized absolute angle.

Return type:

float

normalize_relative_angle(angle: float) → float[source]

Normalizes the given angle to the range [-180, 180] degrees.

Parameters:

angle (float) – The angle to normalize.

Returns:

The normalized angle in degrees.

Return type:

float

calc_delta_angle(target_angle: float, source_angle: float) → float[source]

Calculates the difference between two angles, i.e., the number of degrees from a source angle to a target angle.

Parameters:

  • target_angle (float) – The target angle.

  • source_angle (float) – The source angle.

Returns:

The delta angle in the range [-180, 180].

Return type:

float

bot_api.bot module

class Bot(bot_info: None | BotInfo = None, server_url: None | str = None, server_secret: None | str = None)[source]

Bases: BaseBot, BotABC

Base class for a bot in Robocode Tank Royale.

This class provides the basic structure and methods that all bots must implement. It inherits from BaseBot and BotABC, which define the core functionality and abstract methods that must be overridden by any specific bot implementation.

run() → None[source]

Runs the bot program.

Example

def run(self) -> None:
while self.running:

self.forward(100) self.turn_gun_left(360) self.back(100) self.turn_gun_right(360)

Note

When running a loop that could potentially run forever, the best practice is to check if the bot is still running to stop and exit the loop. This gives the game a chance to stop the thread running the loop. If the thread is not stopped correctly, the bot may behave strangely in new rounds.

See also

running

on_event(event: Condition) → None[source]

Handle events that occur during the bot’s execution.

property turn_rate: float

Get the turn rate of the bot.

property gun_turn_rate: float

Returns the gun turn rate in degrees per turn.

Returns:

The gun turn rate.

property radar_turn_rate: float

Returns the radar turn rate in degrees per turn.

Returns:

The radar turn rate.

property target_speed: float

Returns the target speed in units per turn.

Returns:

The target speed.

property running: bool

Check if this bot is running.

Returns:

True when the bot is running, False otherwise.

set_forward(distance: float) → None[source]

Set the bot to move forward until it has traveled a specific distance from its current position.

The speed is limited by max_speed. While moving forward, ACCELERATION determines the acceleration (+1 unit per turn), and DECELERATION determines braking (-2 units per turn).

This method is executed when go() is called, making it possible to call other setter methods and run them in parallel in the same turn. If this method is called multiple times, the last call before go() is executed counts.

This method cancels the effect of prior calls to target_speed, as set_forward and set_back call target_speed each turn until distance_remaining reaches 0.

Parameters:

distance – Distance to move forward. If negative, the bot moves backward. If positive or negative infinity, the bot moves infinitely in that direction.

forward(distance: float) → None[source]

Move the bot forward until it has traveled a specific distance from its current position.

The speed is limited by max_speed. While moving forward, ACCELERATION determines the acceleration (+1 unit per turn), and DECELERATION determines braking (-2 units per turn).

This call executes immediately by calling go() internally and blocks until completed, which can take one to several turns. New commands take place after this method completes. To run multiple commands in parallel, use setter methods instead of this blocking method.

This method cancels the effect of prior calls to target_speed, set_forward, and set_back.

Parameters:

distance – Distance to move forward. If negative, the bot moves backward. If positive or negative infinity, the bot moves infinitely in that direction.

set_back(distance: float) → None[source]

Set the bot to move backward until it has traveled a specific distance from its current position.

The speed is limited by max_speed. While moving forward, ACCELERATION determines the acceleration (+1 unit per turn), and DECELERATION determines braking (-2 units per turn).

This method is executed when go() is called, making it possible to call other setter methods and run them in parallel in the same turn. If this method is called multiple times, the last call before go() is executed counts.

This method cancels the effect of prior calls to target_speed, as set_forward and set_back call target_speed each turn until distance_remaining reaches 0.

Parameters:

distance – Distance to move backward. If negative, the bot moves forward. If positive or negative infinity, the bot moves infinitely in that direction.

back(distance: float) → None[source]

Move the bot backward until it has traveled a specific distance from its current position.

The speed is limited by max_speed. While moving forward, ACCELERATION determines the acceleration (+1 unit per turn), and DECELERATION determines braking (-2 units per turn).

This call executes immediately by calling go() internally and blocks until completed, which can take one to several turns. New commands take place after this method completes. To run multiple commands in parallel, use setter methods instead of this blocking method.

This method cancels the effect of prior calls to target_speed, set_forward, and set_back.

Parameters:

distance – Distance to move backward. If negative, the bot moves forward. If positive or negative infinity, the bot moves infinitely in that direction.

property distance_remaining: float

Return the remaining distance before the current movement is completed.

When the remaining distance is positive, the bot is moving forward. When negative, the bot is moving backward. Positive/negative infinity means infinite movement in that direction.

set_turn_left(degrees: float) → None[source]

Set the bot to turn left (following the increasing degrees of the unit circle).

The bot turns until turn_remaining is 0. The amount of degrees to turn each turn is limited by max_turn_rate.

This method is executed when go() is called, making it possible to call other setter methods and run them in parallel in the same turn. If this method is called multiple times, the last call before go() is executed counts.

This method cancels the effect of prior calls to set_turn_right.

Parameters:

degrees – Degrees to turn left. If negative, the bot turns right. If positive or negative infinity, the bot turns infinitely in that direction.

turn_left(degrees: float) → None[source]

Turn the bot left (following the increasing degrees of the unit circle).

The bot turns until turn_remaining is 0. The amount of degrees to turn each turn is limited by max_turn_rate.

This call executes immediately by calling go() internally and blocks until completed, which can take one to several turns. New commands take place after this method completes. To run multiple commands in parallel, use setter methods instead of this blocking method.

This method cancels the effect of prior calls to set_turn_left and set_turn_right.

Parameters:

degrees – Degrees to turn left. If negative, the bot turns right. If positive or negative infinity, the bot turns infinitely in that direction.

set_turn_right(degrees: float) → None[source]

Set the bot to turn right (following the decreasing degrees of the unit circle).

The bot turns until turn_remaining is 0. The amount of degrees to turn each turn is limited by max_turn_rate.

This method is executed when go() is called, making it possible to call other setter methods and run them in parallel in the same turn. If this method is called multiple times, the last call before go() is executed counts.

This method cancels the effect of prior calls to set_turn_left.

Parameters:

degrees – Degrees to turn right. If negative, the bot turns left. If positive or negative infinity, the bot turns infinitely in that direction.

turn_right(degrees: float) → None[source]

Turn the bot right (following the increasing degrees of the unit circle).

The bot turns until turn_remaining is 0. The amount of degrees to turn each turn is limited by max_turn_rate.

This call executes immediately by calling go() internally and blocks until completed, which can take one to several turns. New commands take place after this method completes. To run multiple commands in parallel, use setter methods instead of this blocking method.

This method cancels the effect of prior calls to set_turn_left and set_turn_right.

Parameters:

degrees – Degrees to turn right. If negative, the bot turns left. If positive or negative infinity, the bot turns infinitely in that direction.

property turn_remaining: float

Return the remaining degrees before the current turn is completed.

Positive means turning left along the unit circle; negative means turning right. Positive or negative infinity means infinite turning in that direction.

set_turn_gun_left(degrees: float) → None[source]

Set the gun to turn left (following the increasing degrees of the unit circle).

The gun turns until gun_turn_remaining is 0. The amount of degrees to turn each turn is limited by max_gun_turn_rate.

This method is executed when go() is called, making it possible to call other setter methods and run them in parallel in the same turn. If this method is called multiple times, the last call before go() is executed counts.

This method cancels the effect of prior calls to set_turn_gun_right.

Parameters:

degrees – Degrees to turn left. If negative, the gun turns right. If positive or negative infinity, the gun turns infinitely in that direction.

turn_gun_left(degrees: float) → None[source]

Turn the gun left (following the increasing degrees of the unit circle).

The gun turns until gun_turn_remaining is 0. The amount of degrees to turn each turn is limited by max_gun_turn_rate.

This call executes immediately by calling go() internally and blocks until completed, which can take one to several turns. New commands take place after this method completes. To run multiple commands in parallel, use setter methods instead of this blocking method.

This method cancels the effect of prior calls to set_turn_gun_left and set_turn_gun_right.

Parameters:

degrees – Degrees to turn left. If negative, the gun turns right. If positive or negative infinity, the gun turns infinitely in that direction.

set_turn_gun_right(degrees: float) → None[source]

Set the gun to turn right (following the decreasing degrees of the unit circle).

The gun turns until gun_turn_remaining is 0. The amount of degrees to turn each turn is limited by max_gun_turn_rate.

This method is executed when go() is called, making it possible to call other setter methods and run them in parallel in the same turn. If this method is called multiple times, the last call before go() is executed counts.

This method cancels the effect of prior calls to set_turn_gun_left.

Parameters:

degrees – Degrees to turn right. If negative, the gun turns left. If positive or negative infinity, the gun turns infinitely in that direction.

turn_gun_right(degrees: float) → None[source]

Turn the gun right (following the decreasing degrees of the unit circle).

The gun turns until gun_turn_remaining is 0. The amount of degrees to turn each turn is limited by max_gun_turn_rate.

This call executes immediately by calling go() internally and blocks until completed, which can take one to several turns. New commands take place after this method completes. To run multiple commands in parallel, use setter methods instead of this blocking method.

This method cancels the effect of prior calls to set_turn_gun_left and set_turn_gun_right.

Parameters:

degrees – Degrees to turn right. If negative, the gun turns left. If positive or negative infinity, the gun turns infinitely in that direction.

property gun_turn_remaining: float

Return the remaining degrees before the current gun turn is completed.

Positive means turning left along the unit circle; negative means turning right. Positive or negative infinity means infinite turning in that direction.

set_turn_radar_left(degrees: float) → None[source]

Set the radar to turn left (following the increasing degrees of the unit circle).

The radar turns until radar_turn_remaining is 0. The amount of degrees to turn each turn is limited by max_radar_turn_rate.

This method is executed when go() is called, making it possible to call other setter methods and run them in parallel in the same turn. If this method is called multiple times, the last call before go() is executed counts.

This method cancels the effect of prior calls to set_turn_radar_right.

Parameters:

degrees – Degrees to turn left. If negative, the radar turns right. If positive or negative infinity, the radar turns infinitely in that direction.

turn_radar_left(degrees: float) → None[source]

Turn the radar left (following the increasing degrees of the unit circle).

The radar turns until radar_turn_remaining is 0. The amount of degrees to turn each turn is limited by max_radar_turn_rate.

This call executes immediately by calling go() internally and blocks until completed, which can take one to several turns. New commands take place after this method completes. To run multiple commands in parallel, use setter methods instead of this blocking method.

This method cancels the effect of prior calls to set_turn_radar_left and set_turn_radar_right.

Parameters:

degrees – Degrees to turn left. If negative, the radar turns right. If positive or negative infinity, the radar turns infinitely in that direction.

set_turn_radar_right(degrees: float) → None[source]

Set the radar to turn right (following the decreasing degrees of the unit circle).

The radar turns until radar_turn_remaining is 0. The amount of degrees to turn each turn is limited by max_radar_turn_rate.

This method is executed when go() is called, making it possible to call other setter methods and run them in parallel in the same turn. If this method is called multiple times, the last call before go() is executed counts.

This method cancels the effect of prior calls to set_turn_radar_left.

Parameters:

degrees – Degrees to turn right. If negative, the radar turns left. If positive or negative infinity, the radar turns infinitely in that direction.

turn_radar_right(degrees: float) → None[source]

Turn the radar right (following the increasing degrees of the unit circle).

The radar turns until radar_turn_remaining is 0. The amount of degrees to turn each turn is limited by max_radar_turn_rate.

This call executes immediately by calling go() internally and blocks until completed, which can take one to several turns. New commands take place after this method completes. To run multiple commands in parallel, use setter methods instead of this blocking method.

This method cancels the effect of prior calls to set_turn_radar_left and set_turn_radar_right.

Parameters:

degrees – Degrees to turn right. If negative, the radar turns left. If positive or negative infinity, the radar turns infinitely in that direction.

property radar_turn_remaining: float

Return the remaining degrees before the current radar turn is completed.

Positive means turning left along the unit circle; negative means turning right. Positive or negative infinity means infinite turning in that direction.

fire(firepower: float) → None[source]

Fire the gun in the direction the gun is pointing.

Firing spends energy from the bot. The energy loss equals firepower, and hitting another bot rewards energy equal to 3x firepower. The gun can fire only when firepower is at least MIN_FIREPOWER. If firepower exceeds MAX_FIREPOWER, it is truncated to MAX_FIREPOWER.

The gun heats when firing and must cool down before it can fire again. Gun heat generated by firing is 1 + (firepower / 5). The gun cooling rate is read from gun_cooling_rate.

Damage dealt is 4x firepower, and if firepower > 1, it adds 2 * (firepower - 1).

This call executes immediately by calling go() internally and blocks until completed, which can take one to several turns. New commands take place after this method completes. To run multiple commands in parallel, use setter methods instead of this blocking method.

This method cancels the effect of prior calls to set_fire.

Parameters:

firepower – Energy to spend on firing. Must be at least MIN_FIREPOWER.

MAX_NUMBER_OF_TEAM_MESSAGES_PER_TURN: int = 10

The maximum number of team messages that can be sent per turn, which is 10 messages.

TEAM_MESSAGE_MAX_SIZE: int = 32768

Maximum size of a team message, which is 32 KB.

add_custom_event(condition: Condition) → bool

Adds a custom event based on a condition. When the condition is met, the on_custom_event() handler is triggered with a CustomEvent containing the condition.

Parameters:

condition – The condition that must be met to trigger the custom event.

Returns:

True if the condition was added; False if it already exists.

property adjust_gun_for_body_turn: bool

Returns whether the gun adjusts for the bot’s body turn.

property adjust_radar_for_body_turn: bool

Returns whether the radar adjusts for the bot’s body turn.

property adjust_radar_for_gun_turn: bool

Returns whether the radar adjusts for the gun’s turn.

property arena_height: int

Height of the arena measured in units.

First available when the game has started.

Returns:

The arena height measured in units.

property arena_width: int

Width of the arena measured in units.

First available when the game has started.

Returns:

The arena width measured in units.

bearing_to(x: float, y: float) → float

Calculates the bearing (delta angle) between the bot’s current direction and the direction to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

A bearing to the point (x, y) in the range [-180, 180).

Return type:

float

property body_color: Color | None

Returns the color of the body.

Returns:

The body color or None if not set.

broadcast_team_message(message: Any) → None

Broadcasts a message to all teammates.

Parameters:

message – The message to broadcast.

property bullet_color: Color | None

Returns the color of the bullets.

Returns:

The bullet color or None if not set.

property bullet_states: Sequence[BulletState | None] | None

Current bullet states. Keeps track of all the bullets fired by the bot, which are still active on the arena.

Returns:

The current bullet states.

calc_bearing(direction: float) → float

Calculates the bearing (delta angle) between the input direction and the bot’s direction.

Example

bearing = calc_bearing(direction) = normalize_relative_degrees(direction - self.direction)

Parameters:

direction (float) – The input direction to calculate the bearing from.

Returns:

A normalized bearing (delta angle) in the range [-180, 180).

Return type:

float

See also

direction, normalize_relative_angle.

calc_bullet_speed(firepower: float) → float

Calculates the bullet speed for a given firepower.

Parameters:

firepower – The firepower.

Returns:

The bullet speed.

calc_delta_angle(target_angle: float, source_angle: float) → float

Calculates the difference between two angles, i.e., the number of degrees from a source angle to a target angle.

Parameters:

  • target_angle (float) – The target angle.

  • source_angle (float) – The source angle.

Returns:

The delta angle in the range [-180, 180].

Return type:

float

calc_gun_bearing(direction: float) → float

Calculates the bearing (delta angle) between the input direction and the gun’s direction.

Example

bearing = calc_gun_bearing(direction) =

normalize_relative_degrees(direction - self.gun_direction)

Parameters:

direction (float) – The input direction to calculate the bearing from.

Returns:

A normalized bearing (delta angle) in the range [-180, 180).

Return type:

float

See also

gun_direction, normalize_relative_angle.

calc_gun_heat(firepower: float) → float

Calculates the gun heat generated by firing with a given firepower.

Parameters:

firepower – The firepower.

Returns:

The gun heat generated.

calc_max_turn_rate(speed: float) → float

Calculates the maximum turn rate for a given speed.

Parameters:

speed – The speed.

Returns:

The maximum turn rate at the given speed.

calc_radar_bearing(direction: float) → float

Calculates the bearing (delta angle) between the input direction and the radar’s direction.

Example

bearing = calc_radar_bearing(direction) =

normalize_relative_degrees(direction - self.radar_direction)

Parameters:

direction (float) – The input direction to calculate the bearing from.

Returns:

A normalized bearing (delta angle) in the range [-180, 180).

Return type:

float

See also

radar_direction, normalize_relative_angle.

clear_events() → None

Clears out any pending events in the bot’s event queue immediately.

See also

events

property debugging_enabled: bool

Checks if debugging is enabled for this bot.

Returns:

True if debugging is enabled; False otherwise.

property direction: float

Current driving direction of the bot in degrees.

Returns:

The current driving direction of the bot.

direction_to(x: float, y: float) → float

Calculates the direction (angle) from the bot’s coordinates to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

The direction to the point (x, y) in the range [0, 360).

Return type:

float

property disabled: bool

Specifies if the bot is disabled, i.e., when the energy is zero. When the bot is disabled, it is not able to take any action like movement, turning, and firing.

Returns:

True if the bot is disabled; False otherwise.

distance_to(x: float, y: float) → float

Calculates the distance from the bot’s coordinates to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

The distance to the point (x, y).

Return type:

float

property enemy_count: int

Number of enemies left in the round.

Returns:

The number of enemies left in the round.

property energy: float

Current energy level. When the energy level is positive, the bot is alive and active. When the energy level is 0, the bot is still alive but disabled. If the bot becomes disabled it will not be able to move or take any action. If negative, the bot has been defeated.

Returns:

The current energy level.

property events: Sequence[BotEvent | None] | None

Returns an ordered list containing all events currently in the bot’s event queue. You might, for example, call this while processing another event.

Returns:

An ordered list containing all events currently in the bot’s event queue.

See also

clear_events

property firepower: float

Returns the firepower set for firing the gun.

Returns:

The firepower.

property game_type: str

Game type, e.g. “melee” or “1v1”.

First available when the game has started.

Returns:

The game type.

get_event_priority(event_class: type) → int

Returns the priority of an event class.

Parameters:

event_class – The event class.

Returns:

The priority of the event class.

go() → None

Commits the current commands (actions), which finalizes the current turn for the bot.

This method must be called once per turn to send the bot actions to the server and must be called before the turn timeout occurs. A turn timer is started when the GameStartedEvent and TickEvent occurs. If the go() method is called too late, a turn timeout will occur and the SkippedTurnEvent will occur, which means that the bot has skipped all actions for the last turn. In this case, the server will continue executing the last actions received. This could be fatal for the bot due to loss of control over the bot. So make sure that go() is called before the turn ends.

The commands executed when go() is called are set by calling the various setter methods prior to calling the go() method: turn_rate, gun_turn_rate, radar_turn_rate, target_speed, and set_fire().

See also

turn_timeout

property graphics: GraphicsABC

Returns the graphics context for drawing debug graphics.

Returns:

The graphics context.

gun_bearing_to(x: float, y: float) → float

Calculates the bearing (delta angle) between the gun’s current direction and the direction to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

A bearing to the point (x, y) in the range [-180, 180).

Return type:

float

property gun_color: Color | None

Returns the color of the gun.

Returns:

The gun color or None if not set.

property gun_cooling_rate: float

Gun cooling rate. The gun needs to cool down to a gun heat of zero before the gun can fire. The gun cooling rate determines how fast the gun cools down. That is, the gun cooling rate is subtracted from the gun heat each turn until the gun heat reaches zero.

First available when the game has started.

Returns:

The gun cooling rate.

See also

gun_heat

property gun_direction: float

Current direction of the gun in degrees.

Returns:

The current gun direction of the bot.

property gun_heat: float

Current gun heat. When the gun is fired it gets heated and will not be able to fire before it has been cooled down. The gun is cooled down when the gun heat is zero.

When the gun has fired the gun heat is set to 1 + (firepower / 5) and will be cooled down by the gun cooling rate.

Returns:

The current gun heat.

See also

gun_cooling_rate

is_teammate(bot_id: int) → bool

Checks if the specified bot ID is a teammate.

Parameters:

bot_id – The bot ID to check.

Returns:

True if the bot is a teammate; False otherwise.

property max_gun_turn_rate: float

Returns the maximum gun turn rate in degrees per turn.

Returns:

The maximum gun turn rate.

property max_inactivity_turns: int

The maximum number of inactive turns allowed the bot will become zapped by the game for being inactive. Inactive means that the bot has taken no action in several turns in a row.

First available when the game has started.

Returns:

The maximum number of allowed inactive turns.

property max_radar_turn_rate: float

Returns the maximum radar turn rate in degrees per turn.

Returns:

The maximum radar turn rate.

property max_speed: float

Returns the maximum speed in units per turn.

Returns:

The maximum speed.

property max_turn_rate: float

Returns the maximum turn rate of the bot in degrees per turn.

Returns:

The maximum turn rate of the bot.

property my_id: int

Unique id of this bot, which is available when the game has started.

Returns:

The unique id of this bot.

normalize_absolute_angle(angle: float) → float

Normalizes an angle to an absolute angle in the range [0, 360).

Parameters:

angle (float) – The angle to normalize.

Returns:

The normalized absolute angle.

Return type:

float

normalize_relative_angle(angle: float) → float

Normalizes the given angle to the range [-180, 180] degrees.

Parameters:

angle (float) – The angle to normalize.

Returns:

The normalized angle in degrees.

Return type:

float

property number_of_rounds: int

The number of rounds in a battle.

First available when the game has started.

Returns:

The number of rounds in a battle.

on_bot_death(bot_death_event: BotDeathEvent) → None

The event handler triggered when another bot has died.

Parameters:

bot_death_event – The event details from the game.

on_bullet_fired(bullet_fired_event: BulletFiredEvent) → None

The event handler triggered when the bot has fired a bullet.

Parameters:

bullet_fired_event – The event details from the game.

on_bullet_hit(bullet_hit_bot_event: BulletHitBotEvent) → None

The event handler triggered when the bot has hit another bot with a bullet.

Parameters:

bullet_hit_bot_event – The event details from the game.

on_bullet_hit_bullet(bullet_hit_bullet_event: BulletHitBulletEvent) → None

The event handler triggered when a bullet fired from the bot has collided with another bullet.

Parameters:

bullet_hit_bullet_event – The event details from the game.

on_bullet_hit_wall(bullet_hit_wall_event: BulletHitWallEvent) → None

The event handler triggered when a bullet has hit a wall.

Parameters:

bullet_hit_wall_event – The event details from the game.

static on_connected(connected_event: ConnectedEvent) → None

The event handler triggered when connected to the server.

Parameters:

connected_event – The event details from the game.

static on_connection_error(connection_error_event: ConnectionErrorEvent) → None

The event handler triggered when a connection error occurs.

Parameters:

connection_error_event – The event details from the game.

on_custom_event(custom_event: CustomEvent) → None

The event handler triggered when some condition has been met. Use the name of the condition when you need to differentiate between different types of conditions received with this event handler.

Parameters:

custom_event – The event details from the game.

on_death(death_event: DeathEvent) → None

The event handler triggered when this bot has died.

Parameters:

death_event – The event details from the game.

static on_disconnected(disconnected_event: DisconnectedEvent) → None

The event handler triggered when disconnected from the server.

Parameters:

disconnected_event – The event details from the game.

on_game_ended(game_ended_event: GameEndedEvent) → None

The event handler triggered when a game has ended.

Parameters:

game_ended_event – The event details from the game.

on_game_started(game_started_event: GameStartedEvent) → None

The event handler triggered when a game has started.

Parameters:

game_started_event – The event details from the game.

on_hit_bot(bot_hit_bot_event: HitBotEvent) → None

The event handler triggered when the bot has collided with another bot.

Parameters:

bot_hit_bot_event – The event details from the game.

on_hit_by_bullet(hit_by_bullet_event: HitByBulletEvent) → None

The event handler triggered when the bot has been hit by a bullet.

Parameters:

hit_by_bullet_event – The event details from the game.

on_hit_wall(bot_hit_wall_event: HitWallEvent) → None

The event handler triggered when the bot has hit a wall.

Parameters:

bot_hit_wall_event – The event details from the game.

on_round_ended(round_ended_event: RoundEndedEvent) → None

The event handler triggered when a round has ended.

Parameters:

round_ended_event – The event details from the game.

on_round_started(round_started_event: RoundStartedEvent) → None

The event handler triggered when a new round has started.

Parameters:

round_started_event – The event details from the game.

on_scanned_bot(scanned_bot_event: ScannedBotEvent) → None

The event handler triggered when the bot has skipped a turn. This event occurs if the bot did not take any action in a specific turn. That is, go() was not called before the turn timeout occurred for the turn. If the bot does not take action for multiple turns in a row, it will receive a SkippedTurnEvent for each turn where it did not take action. When the bot is skipping a turn, the server did not receive the message from the bot, and the server will use the newest received instructions for target speed, turn rates, firing, etc.

Parameters:

scanned_bot_event – The event details from the game.

on_skipped_turn(skipped_turn_event: SkippedTurnEvent) → None

Handles the event triggered when the bot skips a turn.

A turn is skipped if the bot does not send any instructions to the server (via the go() method) before the turn timeout occurs. When this happens, the server continues using the last received set of actions, such as movement, turning rates, or firing commands.

Reasons for skipped turns may include:

  • Excessive processing or delays in the bot’s logic, leading to a timeout.

  • Failure to invoke the go() method in the current turn.

  • Misaligned or unintended logic in the bot’s turn-handling code.

This method can be overridden to define custom behavior for handling skipped turns, such as logging the event, debugging performance issues, or modifying the bot’s logic to avoid future skips.

Parameters:

skipped_turn_event – An event containing details about the skipped turn.

on_team_message(team_message_event: TeamMessageEvent) → None

The event handler triggered when the bot has received a message from a teammate.

Parameters:

team_message_event – The event details from the game.

on_tick(tick_event: TickEvent) → None

The event handler triggered when a game tick event occurs, i.e., when a new turn in a round has started.

Parameters:

tick_event – The event details from the game.

on_won_round(won_round_event: WonRoundEvent) → None

The event handler triggered when the bot has won a round.

Parameters:

won_round_event – The event details from the game.

radar_bearing_to(x: float, y: float) → float

Calculates the bearing (delta angle) between the radar’s current direction and the direction to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

A bearing to the point (x, y) in the range [-180, 180).

Return type:

float

property radar_color: Color | None

Returns the color of the radar.

Returns:

The radar color or None if not set.

property radar_direction: float

Current direction of the radar in degrees.

Returns:

The current radar direction of the bot.

remove_custom_event(condition: Condition) → bool

Removes a custom event that was previously added with add_custom_event().

Parameters:

condition – The condition to remove.

Returns:

True if the condition was removed; False if it was not found.

property round_number: int

Current round number.

Returns:

The current round number.

property scan_color: Color | None

Returns the color of the scan arc.

Returns:

The scan color or None if not set.

send_team_message(teammate_id: int, message: Any) → None

Sends a message to a specific teammate.

Parameters:

  • teammate_id – The ID of the teammate to send the message to.

  • message – The message to send.

set_event_priority(event_class: type, priority: int) → None

Sets the priority of an event class.

Parameters:

  • event_class – The event class.

  • priority – The new priority.

set_fire(firepower: float) → bool

Sets the gun to fire in the direction the gun is pointing with the specified firepower.

Parameters:

firepower – The firepower to use for firing.

Returns:

True if the gun will fire; False otherwise.

set_fire_assist(enable: bool) → None

Enables or disables fire assistance.

Parameters:

enable – True to enable fire assist; False to disable.

set_interruptible(interruptible: bool) → None

Sets whether the bot’s event handlers are interruptible.

When set to True, the bot’s event handlers can be interrupted by higher-priority events. When set to False, event handlers will run to completion before other events are processed.

Parameters:

interruptible (bool) – If True, event handlers are interruptible; otherwise, they are not.

set_rescan() → None

Sets the radar to rescan with the radar.

set_resume() → None

Sets the bot to resume the movement prior to calling set_stop() or stop().

set_stop(overwrite: bool = False) → None

Sets the bot to stop all movement including turning the gun and radar. The remaining movement is saved for a call to set_resume() or resume().

Parameters:

overwrite – True to override a previously saved movement from stop() or set_stop().

property speed: float

The current speed measured in units per turn. If the speed is positive, the bot moves forward. If negative, the bot moves backward. Zero speed means that the bot is not moving from its current position.

Returns:

The current speed.

start() → None

The method used to start running the bot. You should call this method from the main method or similar.

Example

if __name__ == “__main__”:

# create my_bot … my_bot.start()

stop(overwrite: bool = False) → None[source]

Stop all movement including turning the gun and radar.

Remaining movement is saved for a call to set_resume or resume. This call executes immediately by calling go() internally and blocks until completed, which can take one to several turns. New commands take place after this method completes.

Parameters:

overwrite – True to override a previously saved movement from stop or set_stop. If False, this method is identical to set_stop.

property stopped: bool

Checks if the bot is currently stopped.

Returns:

True if the bot is stopped; False otherwise.

property teammate_ids: set[int]

Returns the IDs of all teammates.

Returns:

A set of teammate IDs.

property time_left: int

The number of microseconds left of this turn before the bot will skip the turn. Make sure to call go() before the time runs out.

Returns:

The amount of time left in microseconds.

See also

turn_timeout, go

property tracks_color: Color | None

Returns the color of the tracks.

Returns:

The tracks color or None if not set.

property turn_number: int

Current turn number.

Returns:

The current turn number.

property turn_timeout: int

The turn timeout is important as the bot needs to take action by calling go() before the turn timeout occurs. As soon as the TickEvent is triggered, i.e. when on_tick() is called, you need to call go() to take action before the turn timeout occurs. Otherwise, your bot will skip a turn and receive a on_skipped_turn() for each turn where go() is called too late.

First available when the game has started.

Returns:

The turn timeout in microseconds (1 / 1,000,000 second).

See also

time_left, go

property turret_color: Color | None

Returns the color of the turret.

Returns:

The turret color or None if not set.

property variant: str

The game variant, which is “Tank Royale”.

Returns:

The game variant of Robocode.

property version: str

Game version, e.g. “1.0.0”.

Returns:

The game version.

property x: float

Current X coordinate of the center of the bot.

Returns:

The current X coordinate of the bot.

property y: float

Current Y coordinate of the center of the bot.

Returns:

The current Y coordinate of the bot.

resume() → None[source]

Resume the movement prior to calling set_stop or stop.

This call executes immediately by calling go() internally and blocks until completed, which can take one to several turns. New commands take place after this method completes.

rescan() → None[source]

Scan again with the radar.

This is useful when the radar is not turning and cannot automatically scan bots, e.g. after stop has been called. The last radar direction and sweep angle are used for rescanning.

wait_for(condition: Callable[[], bool]) → None[source]

Block until a condition is met (condition returns True).

Parameters:

condition – Callable that returns True when the condition is met.

bot_api.bot_abc module

class BotABC[source]

Bases: BaseBotABC

Interface for a bot that extends the core API with convenient methods for movement, turning, and firing the gun.

run() → None[source]

The run() method is used for running a program for the bot like:

Example

def run(self):
while self.is_running():

self.forward(100) self.turn_gun_left(360) self.back(100) self.turn_gun_right(360)

Notes

  • Note that the program runs in a loop in this example (as long as the bot is running), meaning that it will start moving forward as soon as turn_gun_right has executed.

  • When running a loop that could potentially run forever, the best practice is to check if the bot is still running to stop and exit the loop. This gives the game a chance of stopping the thread running the loop in the code behind. If the thread is not stopped correctly, the bot may behave strangely in new rounds.

References

  • running

abstract property running: bool

Checks if this bot is running.

Returns:

True when the bot is running, False otherwise.

Return type:

bool

abstractmethod set_forward(distance: float) → None[source]

Sets the bot to move forward until it has traveled a specific distance from its current position or reached an obstacle.

The movement speed is limited by set_max_speed.

Acceleration/Deceleration:
  • The bot’s acceleration and deceleration are controlled by constants:

    • Constants.ACCELERATION: Adds 1 unit to the speed per turn while accelerating.

    • Constants.DECELERATION: Subtracts 2 units from speed per turn while decelerating.

Behavior:

  • The method is executed when go() is called, allowing you to combine other methods (e.g., turning, firing) to occur in parallel in a single turn.

  • For multiple calls to this method, the most recent call before go() is executed.

  • Cancels the effect of prior calls to set_target_speed, as this method adjusts the target speed for each turn until distance_remaining is 0.

Parameters:

distance (float) – Distance to move forward. - If negative, the bot will move backward. - If float(‘inf’), the bot will move forward infinitely. - If float(‘-inf’), the bot will move backward infinitely.

References

  • forward, set_back, back, distance_remaining, set_target_speed

abstractmethod forward(distance: float) → None[source]

Moves the bot forward until it has traveled a specific distance or reached an obstacle.

The movement speed is limited by set_max_speed.

Acceleration/Deceleration:
  • The bot’s acceleration and deceleration are controlled by constants:

    • Constants.ACCELERATION: Adds 1 unit to the speed per turn while accelerating.

    • Constants.DECELERATION: Subtracts 2 units from speed per turn while decelerating.

Behavior:

  • This method executes immediately by internally calling go() and blocks execution until the movement is complete. Subsequent commands will execute only after this. Use setter methods if parallel execution is needed.

  • Cancels the effect of previous calls to set_target_speed, set_forward, and set_back.

Parameters:

distance (float) – Distance to move forward. - If negative, the bot will move backward. - If float(‘inf’), the bot will move forward infinitely. - If float(‘-inf’), the bot will move backward infinitely.

References

  • set_forward, set_back, back, distance_remaining, set_target_speed

abstractmethod set_back(distance: float) → None[source]

Sets the bot to move backward until it has traveled a specific distance from its current position or reached an obstacle.

The movement speed is limited by set_max_speed.

Acceleration/Deceleration:
  • The bot’s acceleration and deceleration are controlled by constants:

    • Constants.ACCELERATION: Adds 1 unit to the speed per turn while accelerating.

    • Constants.DECELERATION: Subtracts 2 units from speed per turn while decelerating.

Behavior:

  • The method is executed when go() is called, allowing you to combine other methods (e.g., turning, firing) to occur in parallel in a single turn.

  • For multiple calls to this method, the most recent call before go() is executed.

  • Cancels the effect of prior calls to set_target_speed, as this method adjusts the target speed for each turn until distance_remaining is 0.

Parameters:

distance (float) – Distance to move backward. - If negative, the bot will move forward. - If float(‘inf’), the bot will move backward infinitely. - If float(‘-inf’), the bot will move forward infinitely.

References

  • back, set_forward, forward, distance_remaining, set_target_speed

abstractmethod back(distance: float) → None[source]

Moves the bot backward until it has traveled a specific distance from its current position, or it is moving into an obstacle. The speed is limited by setMaxSpeed.

When the bot is moving forward, the Constants.ACCELERATION determines the acceleration of the bot that adds 1 additional unit to the speed per turn while accelerating. However, the bot is faster at braking. The Constants.DECELERATION determines the deceleration of the bot that subtracts 2 units from the speed per turn.

This call is executed immediately by calling go in the code behind. This method will block until it has been completed, which can take one to several turns. New commands will first take place after this method is completed. If you need to execute multiple commands in parallel, use setter methods instead of this blocking method.

This method will cancel the effect of prior calls to setTargetSpeed, setForward, and setBack methods.

Parameters:

distance (float) – The distance to move backward. If negative, the bot will move forward. If float(‘inf’), the bot will move backward infinitely. If float(‘-inf’), the bot will move forward infinitely.

See also

setForward: Method to set the bot to move forward. setBack: Method to set the bot to move backward. forward: Method to immediately move the bot forward. getDistanceRemaining: Method to get the remaining travel distance. setTargetSpeed: Method to set the target speed of the bot.

property distance_remaining: float

Returns the distance remaining until the bot has finished moving after calling set_forward, set_back, forward, or back. When the distance remaining reaches 0, the bot has finished its current movement.

When the distance remaining is positive, the bot is moving forward. When the distance remaining is negative, the bot is moving backward.

Returns:

The remaining distance to move before the current movement is completed.

  • If float(‘inf’), the bot will move forward infinitely.

  • If float(‘-inf’), the bot will move backward infinitely.

Return type:

float

See also

set_forward, set_back, forward, back

set_turn_left(degrees: float) → None[source]

Set the bot to turn to the left (following the increasing degrees of the unit circle) until it has turned the specified amount of degrees. This completes when turn_remaining returns 0. The amount of degrees to turn each turn is limited by set_max_turn_rate().

This method will first be executed when go() is called, making it possible to call other set methods after execution. This allows the bot to move, turn the body, radar, gun, and fire the gun in parallel during a single turn when go() is called. Note that executing multiple methods in parallel is only possible by using setter methods prior to calling go().

If this method is called multiple times, only the last call before go() is executed is honored.

This method cancels the effect of prior calls to set_turn_right().

Parameters:

degrees (float) – The amount of degrees to turn left. If negative, the bot will turn right. If float(‘inf’), the bot will turn left infinitely. If float(‘-inf’), the bot will turn right infinitely.

See:

  • unit circle

  • set_turn_right

  • turn_right

  • turn_left

  • turn_remaining

  • set_turn_rate

turn_left(degrees: float) → None[source]

Turn the bot to the left (following the increasing degrees of the unit circle) until it has turned the specified amount of degrees. That is, when turn_remaining is 0. The amount of degrees to turn each turn is limited by set_max_turn_rate().

This call is executed immediately by invoking go() in the code behind. This method will block until it has been completed, which can take one to several turns. New commands will first take place after this method is completed.

If you need to execute multiple commands in parallel, use setter methods instead of this blocking method.

This method will cancel the effect of prior calls to set_turn_left() and set_turn_right().

Parameters:

degrees (float) – The amount of degrees to turn left. - If negative, the bot will turn right. - If float(‘inf’), the bot will turn left infinitely. - If float(‘-inf’), the bot will turn right infinitely.

See also

  • Unit circle

  • set_turn_left()

  • set_turn_right()

  • turn_right()

  • turn_remaining

  • set_turn_rate()

set_turn_right(degrees: float) → None[source]

Set the bot to turn to the right (following the decreasing degrees of the unit circle) until it turned the specified amount of degrees. That is, when turn_remaining returns 0. The amount of degrees to turn each turn is limited by set_max_turn_rate().

This method will first be executed when go() is called, making it possible to call other set methods after execution. This makes it possible to set the bot to move, turn the body, radar, gun, and fire the gun in parallel in a single turn when calling go(). But notice that this is only possible to execute multiple methods in parallel by using setter methods only prior to calling go().

If this method is called multiple times, the last call before go() is executed counts.

This method will cancel the effect of prior calls to set_turn_left().

Parameters:

degrees (float) – The amount of degrees to turn right. If negative, the bot will turn left. If float(‘inf’), the bot will turn right infinitely. If float(‘-inf’), the bot will turn left infinitely.

See also

set_turn_left turn_right turn_left turn_remaining set_turn_rate

turn_right(degrees: float) → None[source]

Turn the bot to the right (following the increasing degrees of the unit circle) until it turned the specified amount of degrees. That is, when turn_remaining returns 0. The amount of degrees to turn each turn is limited by set_max_turn_rate().

This call is executed immediately, and it will block until it has been completed, which can take one to several turns. New commands will first take place after this method is completed. If you need to execute multiple commands in parallel, use setter methods instead of this blocking method.

This method will cancel the effect of prior calls to set_turn_left() and set_turn_right().

Parameters:

degrees (float) – The amount of degrees to turn right. If negative, the bot will turn left. If float(‘inf’), the bot will turn right infinitely. If float(‘-inf’), the bot will turn left infinitely.

See also

Unit circle set_turn_left set_turn_right turn_left turn_remaining set_turn_rate

property turn_remaining: float

Returns the remaining turn in degrees until the bot has finished turning after having called set_turn_left(), set_turn_right(), turn_left(), or turn_right(). When the turn remaining has reached 0, the bot has finished turning.

When the turn remaining is positive, the bot is turning to the left (along the unit circle). When the turn remaining is negative, the bot is turning to the right.

Returns:

The remaining degrees to turn before its current turning is completed. If float(‘inf’), the bot will turn left infinitely. If float(‘-inf’), the bot will turn right infinitely.

Return type:

float

See also

set_turn_left set_turn_right turn_left turn_right

set_turn_gun_left(degrees: float) → None[source]

Set the gun to turn to the left (following the increasing degrees of the unit circle) until it turned the specified amount of degrees. That is, when gun_turn_remaining returns 0. The amount of degrees to turn each turn is limited by set_max_gun_turn_rate().

This method will first be executed when go() is called, making it possible to call other set methods after execution. This makes it possible to set the bot to move, turn the body, radar, gun, and fire the gun in parallel in a single turn when calling go(). But notice that this is only possible to execute multiple methods in parallel by using setter methods only prior to calling go().

If this method is called multiple times, the last call before go() is executed counts.

This method will cancel the effect of prior calls to set_turn_gun_right().

Parameters:

degrees (float) – The amount of degrees to turn left. If negative, the gun will turn right. If float(‘inf’), the gun will turn left infinitely. If float(‘-inf’), the gun will turn right infinitely.

See also

Unit circle set_turn_gun_right turn_gun_right turn_gun_left gun_turn_remaining set_gun_turn_rate

turn_gun_left(degrees: float) → None[source]

Rotates the gun to the left (increasing degrees of the unit circle) until it has turned the specified number of degrees.

This method is executed immediately and will block until the action is completed, which might take several turns. During this time, new commands will not take effect. To execute multiple commands in parallel, use the corresponding “set” methods instead of this blocking method.

The turn rate per tick is limited by set_max_gun_turn_rate.

If called, this method cancels any prior calls to set_turn_gun_left or set_turn_gun_right.

Parameters:

degrees (float) – The number of degrees to turn the gun left. - If negative, the gun will turn right. - If float(‘inf’), the gun will turn left indefinitely. - If float(‘-inf’), the gun will turn right indefinitely.

set_turn_gun_right(degrees: float) → None[source]

Schedules the gun to turn to the right (decreasing degrees of the unit circle) until it has turned the specified number of degrees.

This method will execute when go() is called, allowing you to chain multiple commands such as moving, turning, and firing together for simultaneous execution in a single turn.

The turn rate per tick is limited by set_max_gun_turn_rate.

If this method is called multiple times before go(), only the last call will be executed. It also cancels any prior calls to set_turn_gun_left.

Parameters:

degrees (float) – The number of degrees to turn the gun right. - If negative, the gun will turn left. - If float(‘inf’), the gun will turn right indefinitely. - If float(‘-inf’), the gun will turn left indefinitely.

turn_gun_right(degrees: float) → None[source]

Rotates the gun to the right (decreasing degrees of the unit circle) until it has turned the specified number of degrees.

This method is executed immediately and will block until the action is completed, which might take several turns. During this time, new commands will not take effect. To execute multiple commands in parallel, use the corresponding “set” methods instead of this blocking method.

The turn rate per tick is limited by set_max_gun_turn_rate.

If called, this method cancels any prior calls to set_turn_gun_left or set_turn_gun_right.

Parameters:

degrees (float) – The number of degrees to turn the gun right. - If negative, the gun will turn left. - If float(‘inf’), the gun will turn right indefinitely. - If float(‘-inf’), the gun will turn left indefinitely.

property gun_turn_remaining: float

Gets the remaining turn angle in degrees for the gun to finish its current turning action.

Positive values indicate the gun is turning left (increasing degrees of the unit circle), while negative values indicate it is turning right (decreasing degrees of the unit circle).

Returns:

The remaining degrees for the gun to complete the turn.

  • If float(‘inf’), the gun is turning left indefinitely.

  • If float(‘-inf’), the gun is turning right indefinitely.

Return type:

float

set_turn_radar_left(degrees: float) → None[source]

Schedules the radar to turn to the left (increasing degrees of the unit circle) until it has turned the specified number of degrees.

This method will execute when go() is called, allowing you to chain multiple commands such as moving, turning, and scanning together for simultaneous execution in a single turn.

The turn rate per tick is limited by set_max_radar_turn_rate.

If this method is called multiple times before go(), only the last call will be executed. It also cancels any prior calls to set_turn_radar_right.

Parameters:

degrees (float) – The number of degrees to turn the radar left. - If negative, the radar will turn right. - If float(‘inf’), the radar will turn left indefinitely. - If float(‘-inf’), the radar will turn right indefinitely.

turn_radar_left(degrees: float | int) → None[source]

Turn the radar to the left (following the increasing degrees of the unit circle) until it has turned the specified amount of degrees. This method will block until completed.

Parameters:

degrees (Union[float, int]) – The amount of degrees to turn left. If negative, the radar will turn right. If positive infinity, the radar will turn left infinitely. If negative infinity, the radar will turn right infinitely.

Notes

  • The amount of degrees to turn per turn is limited by the maximum radar turn rate.

  • New commands will only be processed after this call completes.

  • This will cancel any prior calls to set_turn_radar_left() or set_turn_radar_right().

set_turn_radar_right(degrees: float | int) → None[source]

Set the radar to turn right (following the decreasing degrees of the unit circle) until it has turned the specified amount of degrees. This method does not block but will execute when go() is called.

Parameters:

degrees (Union[float, int]) – The amount of degrees to turn right. If negative, the radar will turn left. If positive infinity, the radar will turn right infinitely. If negative infinity, the radar will turn left infinitely.

Notes

  • The amount of degrees turned per turn is limited by the maximum radar turn rate.

  • The last call to this method before go() is executed will override any previous ones.

  • This cancels prior calls to set_turn_radar_left() and itself.

turn_radar_right(degrees: float | int) → None[source]

Turn the radar to the right (following the increasing degrees of the unit circle) until it has turned the specified amount of degrees. This method will block until completed.

Parameters:

degrees (Union[float, int]) – The amount of degrees to turn right. If negative, the radar will turn left. If positive infinity, the radar will turn right infinitely. If negative infinity, the radar will turn left infinitely.

Notes

  • The amount of degrees to turn per turn is limited by the maximum radar turn rate.

  • New commands will only be processed after this call completes.

  • This will cancel any prior calls to set_turn_radar_left() or set_turn_radar_right().

property radar_turn_remaining: float

Get the remaining turn in degrees until the radar has finished its current turn.

Returns:

The remaining degrees to turn the radar. Positive values indicate the radar is turning left (along the unit circle), and negative values indicate it is turning right. If positive infinity, the radar will turn left infinitely. If negative infinity, the radar will turn right infinitely.

Return type:

float

Notes

  • This applies to the current turn initiated by methods like set_turn_radar_left(), set_turn_radar_right(), turn_radar_left(), or turn_radar_right().

fire(firepower: float) → None[source]

Fires the gun in the direction the gun is pointing.

Note

  • Firing the gun spends energy. The energy loss is equal to the firepower used.

  • If the bullet hits an opponent bot, the bot gains energy from the bullet hit. Specifically, the bot is rewarded with an energy boost of 3 times the firepower.

Rules:

  • The gun will only fire if the firepower is at or above the minimum (Constants.MIN_FIREPOWER).

  • If the firepower exceeds the maximum (Constants.MAX_FIREPOWER), it is truncated to the maximum allowed value.

Gun Heat:

  • The gun heats up whenever it is fired and must cool down to zero heat before it can fire again.

  • The heat generated is calculated as 1 + (firepower / 5), meaning higher firepower increases cooling time.

  • The gun’s cooling rate can be retrieved via get_gun_cooling_rate().

Energy Usage and Damage:

  • The energy used for firing is subtracted from the bot’s total energy.

  • Damage dealt by the bullet is 4 * firepower. Additionally, if firepower exceeds 1, extra damage is calculated as 2 * (firepower - 1).

Execution:

  • This method is executed immediately and blocks until completion, taking one or several turns.

  • New commands will only take effect after the completion of this method.

  • For executing multiple commands in parallel, it is recommended to use setter methods instead of this blocking method.

Side Effects:

  • Cancels prior calls to set_fire.

Parameters:

firepower (float) – The amount of energy spent on firing the gun. - Must be greater than Constants.MIN_FIREPOWER. - Cannot exceed the energy available to the bot.

See also

  • on_bullet_fired()

  • set_fire()

  • get_gun_heat()

  • get_gun_cooling_rate()

abstractmethod stop(overwrite: bool = False) → None[source]

Immediately stops all motion, including the robot’s movement, gun rotation, and radar movement. Any remaining movement is preserved for future execution via set_resume or resume.

This is a blocking call and will only return after the stop operation is completed. New commands will take effect after this method finishes. To perform multiple commands concurrently, use the non-blocking setter methods.

Parameters:

overwrite (bool) – If True, overwrites previously saved movement data from a prior call to stop_with_overwrite or set_stop. If False, behaves equivalently to stop_with_overwrite(False).

abstractmethod resume() → None[source]

Resume the movement prior to calling the set_stop or stop method. This method has no effect if it has already been called.

This call is executed immediately and blocks until completed. New commands will take effect only after this method is completed. To execute multiple commands in parallel, use non-blocking setter methods.

abstractmethod rescan() → None[source]

Scan again with the radar. This method is useful if the radar has not been turning and is unable to scan bots automatically.

The last radar direction and sweep angle will be used for rescanning for bots.

abstractmethod wait_for(condition: Callable[[], bool]) → None[source]

Blocks until a condition is met, i.e., when Condition.test() returns True.

Parameters:

condition – The condition to be met before this method stops waiting.

MAX_NUMBER_OF_TEAM_MESSAGES_PER_TURN: int = 10

The maximum number of team messages that can be sent per turn, which is 10 messages.

TEAM_MESSAGE_MAX_SIZE: int = 32768

Maximum size of a team message, which is 32 KB.

abstract property adjust_gun_for_body_turn: bool

Returns whether the gun adjusts for the bot’s body turn.

Returns:

True if the gun adjusts for body turn; False otherwise.

Return type:

bool

abstract property adjust_radar_for_body_turn: bool

Returns whether the radar adjusts for the bot’s body turn.

Returns:

True if the radar adjusts for body turn; False otherwise.

Return type:

bool

abstract property adjust_radar_for_gun_turn: bool

Returns whether the radar adjusts for the gun’s turn.

Returns:

True if the radar adjusts for gun turn; False otherwise.

Return type:

bool

abstract property arena_height: int

Height of the arena measured in units.

First available when the game has started.

Returns:

The arena height measured in units

Return type:

int

abstract property arena_width: int

Width of the arena measured in units.

First available when the game has started.

Returns:

The arena width measured in units

Return type:

int

bearing_to(x: float, y: float) → float

Calculates the bearing (delta angle) between the bot’s current direction and the direction to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

A bearing to the point (x, y) in the range [-180, 180).

Return type:

float

abstract property body_color: Color | None

Returns the color of the body.

Returns:

The color of the body, or None if no color has been set yet.

In that case, the default color will be used.

Return type:

Color

abstractmethod broadcast_team_message(message: Any) → None

Broadcasts a message to all teammates.

When the message is sent, it is serialized into a JSON representation. This means that all public fields, and only public fields, are serialized into a JSON representation as a data transfer object (DTO).

The maximum team message size limit is defined by TEAM_MESSAGE_MAX_SIZE, which is set to 32,768 bytes. This size is calculated after serializing the message into a JSON representation.

The maximum number of messages that can be broadcast per turn is limited to MAX_NUMBER_OF_TEAM_MESSAGES_PER_TURN, which is set to 10.

Parameters:

message – The message to broadcast.

Raises:

ValueError – If the size of the message exceeds the size limit.

See also

send_team_message: Method to send a message to teammates. get_teammate_ids: Method to retrieve IDs of all teammates.

abstract property bullet_color: Color | None

Returns the color of the fired bullets.

Returns:

The color of the bullets, or None if no color has been set yet, meaning that the default color will be used.

Return type:

Color

abstract property bullet_states: Sequence[BulletState | None] | None

Current bullet states.

Keeps track of all the bullets fired by the bot, which are still active on the arena.

Returns:

The current bullet states.

Return type:

list[BulletState]

calc_bearing(direction: float) → float

Calculates the bearing (delta angle) between the input direction and the bot’s direction.

Example

bearing = calc_bearing(direction) = normalize_relative_degrees(direction - self.direction)

Parameters:

direction (float) – The input direction to calculate the bearing from.

Returns:

A normalized bearing (delta angle) in the range [-180, 180).

Return type:

float

See also

direction, normalize_relative_angle.

abstractmethod calc_bullet_speed(firepower: float) → float

Calculates the bullet speed given a firepower.

Parameters:

firepower (float) – The firepower.

Returns:

The bullet speed determined by the given firepower.

Return type:

float

calc_delta_angle(target_angle: float, source_angle: float) → float

Calculates the difference between two angles, i.e., the number of degrees from a source angle to a target angle.

Parameters:

  • target_angle (float) – The target angle.

  • source_angle (float) – The source angle.

Returns:

The delta angle in the range [-180, 180].

Return type:

float

calc_gun_bearing(direction: float) → float

Calculates the bearing (delta angle) between the input direction and the gun’s direction.

Example

bearing = calc_gun_bearing(direction) =

normalize_relative_degrees(direction - self.gun_direction)

Parameters:

direction (float) – The input direction to calculate the bearing from.

Returns:

A normalized bearing (delta angle) in the range [-180, 180).

Return type:

float

See also

gun_direction, normalize_relative_angle.

abstractmethod calc_gun_heat(firepower: float) → float

Calculates gun heat after having fired the gun.

Parameters:

firepower (float) – The firepower used when firing the gun.

Returns:

The gun heat produced when firing the gun with the given firepower.

Return type:

float

abstractmethod calc_max_turn_rate(speed: float) → float

Calculates the maximum turn rate for a specific speed.

Parameters:

speed (float) – The speed.

Returns:

The maximum turn rate determined by the given speed.

Return type:

float

calc_radar_bearing(direction: float) → float

Calculates the bearing (delta angle) between the input direction and the radar’s direction.

Example

bearing = calc_radar_bearing(direction) =

normalize_relative_degrees(direction - self.radar_direction)

Parameters:

direction (float) – The input direction to calculate the bearing from.

Returns:

A normalized bearing (delta angle) in the range [-180, 180).

Return type:

float

See also

radar_direction, normalize_relative_angle.

abstractmethod clear_events() → None

Clears out any pending events in the bot’s event queue immediately.

abstract property debugging_enabled: bool

Indicates whether graphical debugging is enabled. If enabled, the graphics property can be used for debug painting.

Returns:

True if graphical debugging is enabled, False otherwise.

Return type:

bool

abstract property direction: float

Current driving direction of the bot in degrees.

Returns:

The current driving direction of the bot.

Return type:

float

direction_to(x: float, y: float) → float

Calculates the direction (angle) from the bot’s coordinates to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

The direction to the point (x, y) in the range [0, 360).

Return type:

float

abstract property disabled: bool

Specifies if the bot is disabled, i.e., when the energy is zero.

When the bot is disabled, it is not able to take any action like movement, turning, and firing.

Returns:

True if the bot is disabled; False otherwise.

Return type:

bool

distance_to(x: float, y: float) → float

Calculates the distance from the bot’s coordinates to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

The distance to the point (x, y).

Return type:

float

abstract property enemy_count: int

Number of enemies left in the round.

Returns:

The number of enemies left in the round.

Return type:

int

abstract property energy: float

Current energy level.

When the energy level is positive, the bot is alive and active. When the energy level is 0, the bot is still alive but disabled. If the bot becomes disabled it will not be able to move or take any action. If negative, the bot has been defeated.

Returns:

The current energy level.

Return type:

float

abstract property events: Sequence[BotEvent | None] | None

Returns an ordered list containing all events currently in the bot’s event queue.

You might, for example, call this while processing another event.

Returns:

An ordered list containing all events currently in the bot’s event queue.

Return type:

list[BotEvent]

abstract property firepower: float

Returns the firepower.

Returns:

The firepower.

Return type:

float

abstract property game_type: str

Game type, e.g. “melee” or “1v1”.

First available when the game has started.

Returns:

The game type.

Return type:

str

abstractmethod get_event_priority(event_class: type) → int

Returns the event priority for a specific event class.

Example

scanned_bot_event_priority = get_priority(ScannedBotEvent)

Parameters:

event_class – The event class to get the event priority for.

Returns:

The event priority for a specific event class.

Return type:

int

See also

DefaultEventPriority set_event_priority

abstractmethod go() → None

Commits the current commands (actions), which finalizes the current turn for the bot.

This method must be called once per turn to send the bot actions to the server and must be called before the turn timeout occurs. A turn timer is started when the GameStartedEvent and TickEvent occurs. If the go() method is called too late, a turn timeout will occur and the SkippedTurnEvent will occur, which means that the bot has skipped all actions for the last turn. In this case, the server will continue executing the last actions received. This could be fatal for the bot due to loss of control over the bot. So make sure that go() is called before the turn ends.

The commands executed when go() is called are set by calling the various setter methods prior to calling the go() method: turn_rate, gun_turn_rate, radar_turn_rate, target_speed, and set_fire().

See also

turn_timeout

abstract property graphics: GraphicsABC

Gets a graphics object for debug painting.

Example

g = self.graphics g.set_fill_color(Color.from_rgb(0, 0, 255)) g.fill_rectangle(50, 50, 100, 100) # A blue filled rect

Returns:

A graphics canvas to use for painting graphical objects, making debugging easier.

gun_bearing_to(x: float, y: float) → float

Calculates the bearing (delta angle) between the gun’s current direction and the direction to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

A bearing to the point (x, y) in the range [-180, 180).

Return type:

float

abstract property gun_color: Color | None

Returns the color of the gun.

Returns:

The color of the gun, or None if no color has been set yet. If None, the default color will be used.

Return type:

Color

abstract property gun_cooling_rate: float

Gun cooling rate.

The gun needs to cool down to a gun heat of zero before the gun can fire. The gun cooling rate determines how fast the gun cools down. That is, the gun cooling rate is subtracted from the gun heat each turn until the gun heat reaches zero.

First available when the game has started.

Returns:

The gun cooling rate.

Return type:

float

abstract property gun_direction: float

Current direction of the gun in degrees.

Returns:

The current gun direction of the bot.

Return type:

float

abstract property gun_heat: float

Current gun heat.

When the gun is fired it gets heated and will not be able to fire before it has been cooled down. The gun is cooled down when the gun heat is zero. When the gun has fired the gun heat is set to 1 + (firepower / 5) and will be cooled down by the gun cooling rate.

Returns:

The current gun heat.

Return type:

float

abstract property gun_turn_rate: float

Returns the gun turn rate in degrees per turn.

Returns:

The turn rate of the gun.

Return type:

float

abstractmethod is_teammate(bot_id: int) → bool

Checks if the specified bot ID is a teammate.

Parameters:

bot_id (int) – The bot ID to check.

Returns:

True if the bot is a teammate; False otherwise.

Return type:

bool

abstract property max_gun_turn_rate: float

Returns the maximum gun turn rate in degrees per turn.

Returns:

The maximum turn rate of the gun.

Return type:

float

abstract property max_inactivity_turns: int

The maximum number of inactive turns allowed.

The bot will become zapped by the game for being inactive. Inactive means that the bot has taken no action in several turns in a row.

First available when the game has started.

Returns:

The maximum number of allowed inactive turns.

Return type:

int

abstract property max_radar_turn_rate: float

Returns the maximum radar turn rate in degrees per turn.

Returns:

The maximum turn rate of the radar.

Return type:

float

abstract property max_speed: float

Returns the maximum speed in units per turn.

Returns:

The maximum speed.

Return type:

float

abstract property max_turn_rate: float

Returns the maximum turn rate of the bot in degrees per turn.

Returns:

The maximum turn rate of the bot.

Return type:

float

abstract property my_id: int

The bot’s unique identifier.

normalize_absolute_angle(angle: float) → float

Normalizes an angle to an absolute angle in the range [0, 360).

Parameters:

angle (float) – The angle to normalize.

Returns:

The normalized absolute angle.

Return type:

float

normalize_relative_angle(angle: float) → float

Normalizes the given angle to the range [-180, 180] degrees.

Parameters:

angle (float) – The angle to normalize.

Returns:

The normalized angle in degrees.

Return type:

float

abstract property number_of_rounds: int

The number of rounds in a battle.

First available when the game has started.

Returns:

The number of rounds in a battle.

Return type:

int

on_bot_death(bot_death_event: BotDeathEvent) → None

The event handler triggered when another bot has died.

Parameters:

bot_death_event – The event details from the game.

on_bullet_fired(bullet_fired_event: BulletFiredEvent) → None

The event handler triggered when the bot has fired a bullet.

Parameters:

bullet_fired_event – The event details from the game.

on_bullet_hit(bullet_hit_bot_event: BulletHitBotEvent) → None

The event handler triggered when the bot has hit another bot with a bullet.

Parameters:

bullet_hit_bot_event – The event details from the game.

on_bullet_hit_bullet(bullet_hit_bullet_event: BulletHitBulletEvent) → None

The event handler triggered when a bullet fired from the bot has collided with another bullet.

Parameters:

bullet_hit_bullet_event – The event details from the game.

on_bullet_hit_wall(bullet_hit_wall_event: BulletHitWallEvent) → None

The event handler triggered when a bullet has hit a wall.

Parameters:

bullet_hit_wall_event – The event details from the game.

static on_connected(connected_event: ConnectedEvent) → None

The event handler triggered when connected to the server.

Parameters:

connected_event – The event details from the game.

static on_connection_error(connection_error_event: ConnectionErrorEvent) → None

The event handler triggered when a connection error occurs.

Parameters:

connection_error_event – The event details from the game.

on_custom_event(custom_event: CustomEvent) → None

The event handler triggered when some condition has been met. Use the name of the condition when you need to differentiate between different types of conditions received with this event handler.

Parameters:

custom_event – The event details from the game.

on_death(death_event: DeathEvent) → None

The event handler triggered when this bot has died.

Parameters:

death_event – The event details from the game.

static on_disconnected(disconnected_event: DisconnectedEvent) → None

The event handler triggered when disconnected from the server.

Parameters:

disconnected_event – The event details from the game.

on_game_ended(game_ended_event: GameEndedEvent) → None

The event handler triggered when a game has ended.

Parameters:

game_ended_event – The event details from the game.

on_game_started(game_started_event: GameStartedEvent) → None

The event handler triggered when a game has started.

Parameters:

game_started_event – The event details from the game.

on_hit_bot(bot_hit_bot_event: HitBotEvent) → None

The event handler triggered when the bot has collided with another bot.

Parameters:

bot_hit_bot_event – The event details from the game.

on_hit_by_bullet(hit_by_bullet_event: HitByBulletEvent) → None

The event handler triggered when the bot has been hit by a bullet.

Parameters:

hit_by_bullet_event – The event details from the game.

on_hit_wall(bot_hit_wall_event: HitWallEvent) → None

The event handler triggered when the bot has hit a wall.

Parameters:

bot_hit_wall_event – The event details from the game.

on_round_ended(round_ended_event: RoundEndedEvent) → None

The event handler triggered when a round has ended.

Parameters:

round_ended_event – The event details from the game.

on_round_started(round_started_event: RoundStartedEvent) → None

The event handler triggered when a new round has started.

Parameters:

round_started_event – The event details from the game.

on_scanned_bot(scanned_bot_event: ScannedBotEvent) → None

The event handler triggered when the bot has skipped a turn. This event occurs if the bot did not take any action in a specific turn. That is, go() was not called before the turn timeout occurred for the turn. If the bot does not take action for multiple turns in a row, it will receive a SkippedTurnEvent for each turn where it did not take action. When the bot is skipping a turn, the server did not receive the message from the bot, and the server will use the newest received instructions for target speed, turn rates, firing, etc.

Parameters:

scanned_bot_event – The event details from the game.

on_skipped_turn(skipped_turn_event: SkippedTurnEvent) → None

Handles the event triggered when the bot skips a turn.

A turn is skipped if the bot does not send any instructions to the server (via the go() method) before the turn timeout occurs. When this happens, the server continues using the last received set of actions, such as movement, turning rates, or firing commands.

Reasons for skipped turns may include:

  • Excessive processing or delays in the bot’s logic, leading to a timeout.

  • Failure to invoke the go() method in the current turn.

  • Misaligned or unintended logic in the bot’s turn-handling code.

This method can be overridden to define custom behavior for handling skipped turns, such as logging the event, debugging performance issues, or modifying the bot’s logic to avoid future skips.

Parameters:

skipped_turn_event – An event containing details about the skipped turn.

on_team_message(team_message_event: TeamMessageEvent) → None

The event handler triggered when the bot has received a message from a teammate.

Parameters:

team_message_event – The event details from the game.

on_tick(tick_event: TickEvent) → None

The event handler triggered when a game tick event occurs, i.e., when a new turn in a round has started.

Parameters:

tick_event – The event details from the game.

on_won_round(won_round_event: WonRoundEvent) → None

The event handler triggered when the bot has won a round.

Parameters:

won_round_event – The event details from the game.

radar_bearing_to(x: float, y: float) → float

Calculates the bearing (delta angle) between the radar’s current direction and the direction to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

A bearing to the point (x, y) in the range [-180, 180).

Return type:

float

abstract property radar_color: Color | None

Returns the color of the radar.

Returns:

The color of the radar. If no color has been set yet, returns None, which indicates that the default radar color will be used.

Return type:

Color

abstract property radar_direction: float

Current direction of the radar in degrees.

Returns:

The current radar direction of the bot.

Return type:

float

abstract property radar_turn_rate: float

Returns the radar turn rate in degrees per turn.

Returns:

The turn rate of the radar.

Return type:

float

abstract property round_number: int

Current round number.

Returns:

The current round number.

Return type:

int

abstract property scan_color: Color | None

Returns the color of the scan arc.

Returns:

The color of the scan arc, or None if no color has been set, meaning the default color will be used.

Return type:

Color

abstractmethod send_team_message(teammate_id: int, message: Any) → None

Sends a message to a specific teammate.

When the message is sent, it is serialized into a JSON representation, meaning that all public fields, and only public fields, are being serialized into a JSON representation as a DTO (data transfer object).

The maximum team message size limit is defined by TEAM_MESSAGE_MAX_SIZE, which is set to TEAM_MESSAGE_MAX_SIZE bytes. This size is the size of the message when it is serialized into a JSON representation.

The maximum number of messages that can be sent/broadcast per turn is limited to MAX_NUMBER_OF_TEAM_MESSAGES_PER_TURN.

Parameters:

  • teammate_id – The id of the teammate to send the message to.

  • message – The message to send.

Raises:

ValueError – If the size of the message exceeds the size limit.

abstractmethod set_event_priority(event_class: type, priority: int) → None

Changes the event priority for an event class. The event priority determines which event types (classes) must be fired and handled before others. Events with higher priorities will be handled before events with lower priorities.

Note

You should normally not need to change the event priority.

Parameters:

  • event_class (Type[BotEvent]) – The event class to change the priority for.

  • priority (int) – The new priority, typically a positive number from 1 to 150. The higher the value, the higher the priority.

See also

DefaultEventPriority, get_event_priority.

abstractmethod set_fire(firepower: float) → bool

Sets the gun to fire in the direction that the gun is pointing with the specified firepower.

Firepower is the amount of energy your bot will spend on firing the gun. This means that the bot will lose power on firing the gun, where the energy loss is equal to the firepower. You cannot spend more energy than is available from your bot.

The bullet power must be greater than the minimum firepower and gun heat must be zero before the gun can fire.

If the bullet hits an opponent bot, you will gain energy from the bullet hit. When hitting another bot, your bot will be rewarded and retrieve an energy boost of 3x the firepower.

The gun will only fire when the firepower is at or above the minimum firepower. If the firepower is greater than the maximum firepower, the power will be truncated to the maximum firepower.

Whenever the gun is fired, the gun becomes heated and needs to cool down before it can fire again. The gun heat must be zero before the gun can fire again. The gun heat generated by firing the gun is calculated as 1 + (firepower / 5). Hence, the more firepower used, the longer it takes to cool down the gun. The gun cooling rate can be retrieved using the get_gun_cooling_rate() function.

The amount of energy used for firing the gun is subtracted from the bot’s total energy. The amount of damage dealt by a bullet hitting another bot is 4x firepower. If the firepower is greater than 1, it will deal an additional 2 x (firepower - 1) damage.

Note that the gun will automatically keep firing each turn as soon as the gun heat reaches zero. It is possible to disable the gun firing by setting the firepower to zero.

The firepower is truncated between 0 and the maximum firepower if the provided value exceeds this range.

If this property is set multiple times, the last value set before calling go() is used.

Parameters:

firepower (float) – The new firepower.

Returns:

True if the cannon can fire (i.e., if there is no gun heat), False otherwise.

Return type:

bool

See also

  • on_bullet_fired()

  • get_firepower()

  • get_gun_heat()

  • get_gun_cooling_rate()

abstractmethod set_fire_assist(enable: bool) → None

Enables or disables fire assistance explicitly. Fire assistance is useful for bots with limited aiming capabilities as it helps the bot by firing directly at a scanned bot when the gun is fired, which is a very simple aiming strategy.

When fire assistance is enabled, the gun will fire towards the center of the scanned bot when all these conditions are met:

  1. The gun is fired (via set_fire or fire()).

  2. The radar is scanning a bot when firing the gun (e.g., in the on_scanned_bot() event, after calling set_rescan() or rescan()).

  3. The gun and radar are pointing in the exact same direction. You can disable radar and gun movement alignment using set_adjust_radar_for_gun_turn(False) to ensure the gun and radar stay aligned while avoiding radar turning independently of the gun.

The fire assistance feature is provided for backwards compatibility with the original Robocode, where bots that were not considered AdvancedRobot had fire assistance enabled by default, as their gun and radar could not move independently of each other. In contrast, AdvancedRobot allows the body, gun, and radar to move independently.

Parameters:

enable (bool) – Enables fire assistance when set to True, and disables it otherwise.

abstractmethod set_interruptible(interruptible: bool) → None

Sets whether the bot’s event handlers are interruptible.

When set to True, event handlers can be interrupted by higher-priority events. When set to False, handlers run to completion before other events are processed.

Parameters:

interruptible (bool) – If True, event handlers are interruptible; otherwise, they are not.

abstractmethod set_rescan() → None

Sets the bot to rescan with the radar.

This method is useful if the radar has not turned, and hence will not automatically scan bots. The last radar direction and sweep angle will be used for scanning for bots.

abstract property speed: float

The current speed measured in units per turn.

If the speed is positive, the bot moves forward. If negative, the bot moves backward. Zero speed means that the bot is not moving from its current position.

Returns:

The current speed.

Return type:

float

abstractmethod start() → None

The method used to start running the bot. You should call this method from the main function or a similar entry point.

This method blocks until the bot disconnects from the server.

Example:

if __name__ == "__main__":
    # create my_bot
    ...
    my_bot.start()
abstract property stopped: bool

Checks if the movement has been stopped.

Returns:

True if the movement has been stopped by set_stop(), False otherwise.

Return type:

bool

See also

set_resume: Resumes the movement. set_stop(): Stops the movement. set_stop(flag: bool): Stops the movement, with a flag to specify additional behavior.

abstract property target_speed: float

Returns the target speed in units per turn.

Returns:

The target speed.

Return type:

float

abstract property teammate_ids: set[int]

The IDs of all teammates.

Returns:

A set of IDs of all teammates if the bot is participating in a team, or an empty set if the bot is not in a team.

Return type:

Set[int]

See also

is_teammate: Checks if a bot is a teammate. send_team_message: Sends a message to the team.

abstract property time_left: int

The number of microseconds left of this turn before the bot will skip the turn.

Make sure to call go() before the time runs out.

Returns:

The amount of time left in microseconds.

Return type:

int

abstract property tracks_color: Color | None

Returns the color of the tank tracks.

Returns:

The color of the tank tracks, or None if no color has been set yet, meaning that the default color will be used.

Return type:

Color

abstract property turn_number: int

Current turn number.

Returns:

The current turn number.

Return type:

int

abstract property turn_rate: float

Returns the turn rate of the bot in degrees per turn.

Returns:

The turn rate of the bot.

Return type:

float

abstract property turn_timeout: int

The turn timeout in microseconds.

The turn timeout is important as the bot needs to take action by calling go() before the turn timeout occurs. As soon as the TickEvent() is triggered, i.e. when onTick() is called, you need to call go() to take action before the turn timeout occurs. Otherwise, your bot will skip a turn and receive a onSkippedTurn for each turn where go() is called too late.

First available when the game has started.

Returns:

The turn timeout in microseconds.

Return type:

int

abstract property turret_color: Color | None

Returns the color of the gun turret.

Returns:

The color of the turret or None if no color has been set yet, meaning that the default color will be used.

abstract property variant: str

The game variant, which is “Tank Royale”.

Returns:

The game variant of Robocode.

Return type:

str

abstract property version: str

Game version, e.g. “1.0.0”.

Returns:

The game version.

Return type:

str

abstract property x: float

Current X coordinate of the center of the bot.

Returns:

The current X coordinate of the bot.

Return type:

float

abstract property y: float

Current Y coordinate of the center of the bot.

Returns:

The current Y coordinate of the bot.

Return type:

float

bot_api.bot_exception module

exception BotException(message, cause=None)[source]

Bases: Exception

Represents errors that occur with bot execution.

__init__(message, cause=None)[source]

Initializes a new instance of the BotException class.

Parameters:

  • message – The error message that describes the error.

  • cause – The exception that is the cause of this exception. Defaults to None.

add_note()

Exception.add_note(note) – add a note to the exception

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

bot_api.bot_info module

class BotInfo(name: str | None = None, version: str | None = None, authors: List[str] | None = None, description: str | None = None, homepage: str | None = None, country_codes: List[str] | None = None, game_types: Set[str] | None = None, platform: str | None = None, programming_lang: str | None = None, initial_position: InitialPosition | None = None)[source]

Bases: object

BotInfo class contains the properties of a bot. Implements validation and supports a builder pattern.

MAX_NAME_LENGTH = 30

Maximum number of characters accepted for the name.

MAX_VERSION_LENGTH = 20

Maximum number of characters accepted for the version.

MAX_AUTHOR_LENGTH = 50

Maximum number of characters accepted for an author name.

MAX_DESCRIPTION_LENGTH = 250

Maximum number of characters accepted for the description.

MAX_HOMEPAGE_LENGTH = 150

Maximum number of characters accepted for the link to the homepage.

MAX_GAME_TYPE_LENGTH = 20

Maximum number of characters accepted for a game type.

MAX_PLATFORM_LENGTH = 30

Maximum number of characters accepted for the platform name.

MAX_PROGRAMMING_LANG_LENGTH = 30

Maximum number of characters accepted for the programming language name.

MAX_NUMBER_OF_AUTHORS = 20

Maximum number of authors allowed.

MAX_NUMBER_OF_COUNTRY_CODES = 20

Maximum number of country codes allowed.

MAX_NUMBER_OF_GAME_TYPES = 10

Maximum number of game types allowed.

__init__(name: str | None = None, version: str | None = None, authors: List[str] | None = None, description: str | None = None, homepage: str | None = None, country_codes: List[str] | None = None, game_types: Set[str] | None = None, platform: str | None = None, programming_lang: str | None = None, initial_position: InitialPosition | None = None)[source]

Initializes a new instance of the BotInfo class.

Note

The recommended method for creating a BotInfo instance is to use the IBuilder interface provided with the BotInfo.builder() static method.

Variables:

  • name (str) – The name of the bot (optional).

  • version (str) – The version of the bot (optional).

  • authors (list) – The author(s) of the bot (optional).

  • description (str) – A short description of the bot (optional).

  • homepage (str) – A link to a homepage for the bot (optional).

  • country_codes (list) – The country code(s) for the bot (optional).

  • game_types (set) – The game types that this bot can handle (optional).

  • platform (str) – The platform used for running the bot (optional).

  • programming_lang (str) – The programming language used for developing the bot (optional).

  • initial_position (InitialPosition) – The initial position with starting coordinate and angle (optional).

classmethod from_json(json_data: str) → BotInfo[source]
classmethod from_file(file_path: str) → BotInfo[source]

Reads the bot info from a JSON file.

Parameters:

file_path (str) – The path to the JSON file containing bot info.

Returns:

An instance of BotInfo populated with data from the file.

Return type:

BotInfo

class Builder[source]

Bases: object

Builder interface for creating builder objects for constructing BotInfo instances. Supports method chaining.

game_types: set[str]
set_name(name: str) → Builder[source]

Sets the bot name. (required)

Note

The maximum length of the name is defined by MAX_NAME_LENGTH characters.

Example

“Rampage”

Parameters:

name (str) – The name of the bot.

Returns:

The IBuilder instance, allowing for method chaining.

Return type:

IBuilder

set_version(version: str) → Builder[source]

Sets the bot version. (required)

Note

The maximum length of the version is 20 characters.

Example

“1.0”

Parameters:

version (str) – The version of the bot.

Returns:

Self, for method chaining.

set_authors(authors: List[str]) → Builder[source]

Sets the names(s) of the author(s) of the bot. (required)

Note

  • The maximum length of an author name is 50 characters.

  • Maximum number of names is 5.

  • Providing None will remove all authors.

Example

[“John Doe”]

Parameters:

authors (list) – A list containing the names(s) of the author(s).

Returns:

Self, for method chaining.

add_author(author: str) → Builder[source]

Adds an author of the bot. (required)

See also

set_authors()

Parameters:

author (str) – The name of an author to add.

Returns:

Self, for method chaining.

set_description(description: str) → Builder[source]

Sets a short description of the bot. (optional)

Note

  • The maximum length of the description is 250 characters.

  • Line-breaks (line-feed or newline) are supported, but expect up to 3 lines to be displayed on UI.

Example

“The rampage bot will try to ram bots that are very close.n”

“Sneaks around corners and shoots at bots that come too near.”

Parameters:

description (str) – A short description of the bot.

Returns:

Self, for method chaining.

set_homepage(homepage: str) → Builder[source]

Sets a link to the homepage for the bot. (optional)

Note

The maximum length of a link is 150 characters.

Example

“https://fictive-homepage.net/Rampage”

Parameters:

homepage (str) – A link to a homepage for the bot.

Returns:

Self, for method chaining.

set_country_codes(country_codes: List[str]) → Builder[source]

Sets the country codes for the bot. (optional)

Notes

  • Each country code uses a 2-character alpha-2 format from the ISO 3166 standard.

  • Maximum number of country codes is 5.

  • Providing None removes all country codes.

  • If no valid country code is specified, the default locale country code is used.

Example

[“dk”]

Parameters:

country_codes (list) – A list of country codes.

Returns:

Self, for method chaining.

add_country_code(country_code: str) → Builder[source]

Adds a country code for the bot. (optional)

See also

set_country_codes()

Parameters:

country_code (str) – The country code to add.

Returns:

Self, for method chaining.

set_game_types(game_types: Set[str]) → Builder[source]

Sets the game types that this bot is capable of participating in. (required)

Notes

  • Standard game types can be found at the referenced documentation or API spec.

  • More types may be added in the future.

  • Use the predefined strings from the GameType class when possible.

  • Maximum game type length is 20 characters.

  • Maximum number of game types is 10.

  • Providing None removes all game types.

Example

{“classic”, “melee”, “future-type”}

Parameters:

game_types (set) – A set of game types that the bot is capable of participating in.

Returns:

Self, for method chaining.

add_game_type(game_type: str) → Builder[source]

Adds a game type that this bot is capable of participating in. (required)

See also

set_game_types()

Example

“classic”

Parameters:

game_type (str) – A game type that the bot can participate in.

Returns:

Self, for method chaining.

set_platform(platform: str) → Builder[source]

Sets the name of the platform that this bot is built for. (optional)

Note

  • The maximum length of the platform name is 30 characters.

  • If None or a blank string is provided, the default string (Java Runtime Environment) is used.

Example

“Java Runtime Environment (JRE) [version]”

Parameters:

platform (str) – The name of the platform for this bot.

Returns:

Self, for method chaining.

set_programming_lang(language: str) → Builder[source]

Sets the name of the programming language used for developing this bot. (optional)

Note

The maximum length of the programming language’s name is 30 characters.

Example

Python 3.12

Parameters:

language (str) – The name of the programming language.

Returns:

Self, for method chaining.

set_initial_position(initial_position: str) → Builder[source]

Sets the initial position of the bot. (optional)

Note

Initial positions must be enabled or allowed by the game (server) to take effect.

Parameters:

initial_position – The initial position of the bot.

Returns:

Self, for method chaining.

build() → BotInfo[source]

Builds and returns the BotInfo instance based on the data set added to this builder so far.

This method is typically the final step in the builder’s workflow to extract the result of the building process.

Returns:

The resulting BotInfo instance.

Return type:

BotInfo

bot_api.bot_results module

class BotResults(rank: int, survival: float, last_survivor_bonus: float, bullet_damage: float, bullet_kill_bonus: float, ram_damage: float, ram_kill_bonus: float, total_score: float, first_places: int, second_places: int, third_places: int)[source]

Bases: object

Represents individual bot results.

rank: int

Rank/placement of the bot, where 1 means 1st place, 4 means 4th place etc.

survival: float

Accumulated survival score. Every bot still alive scores 50 points every time another bot is defeated.

last_survivor_bonus: float

Last survivor score. The last bot alive scores 10 points or each bot that has been defeated.

bullet_damage: float

Bullet damage score. A bot scores 1 point for each point of damage they do to other bots.

bullet_kill_bonus: float

Bullet kill-bonus. When a bot kills another bot, it scores an additional 20% points of the total damage it did to that bot.

ram_damage: float

Ram damage score. Bots score 2 points for each point of damage inflicted by ramming an enemy bot. Ramming is the act deliberately driving forward (not backward) and hitting another bot.

ram_kill_bonus: float

Ram kill-bonus. When a bot kills another bot due to ramming, it scores an additional 30% of the total ramming damage it did to that bot.

total_score: float

Total score is the sum of all scores and determines the ranking.

first_places: int

Number of 1st places for the bot.

second_places: int

Number of 2nd places for the bot.

third_places: int

Number of 3rd places for the bot.

bot_api.bot_state module

class BotState(droid: bool, energy: float, x: float, y: float, direction: float, gun_direction: float, radar_direction: float, radar_sweep: float, speed: float, turn_rate: float, gun_turn_rate: float, radar_turn_rate: float, gun_heat: float, enemy_count: int, body_color: bot_api.graphics.color.Color | None, turret_color: bot_api.graphics.color.Color | None, radar_color: bot_api.graphics.color.Color | None, bullet_color: bot_api.graphics.color.Color | None, scan_color: bot_api.graphics.color.Color | None, tracks_color: bot_api.graphics.color.Color | None, gun_color: bot_api.graphics.color.Color | None, debugging_enabled: bool)[source]

Bases: object

class Color(_value: int)

Bases: object

Represents an RGBA (red, green, blue, alpha) color used in the Tank Royale game.

This graphics Color implementation contains: - Internal 32-bit RGBA value - Factory methods from_rgb(), from_rgba(r,g,b,a), and from_rgba_value(rgba) - Read-only channel properties: red, green, blue, alpha (mapped to R,G,B,A) - to_rgba() for round-trip, to_hex_color() for hex string - Equality/hash based on RGBA value - Many predefined common colors

Note: For compatibility with existing Python code, to_color_schema() is preserved and uses lowercase hex values as before.

ALICE_BLUE = Color(_value=4042850303)
ANTIQUE_WHITE = Color(_value=4209760255)
AQUA = Color(_value=16777215)
AQUAMARINE = Color(_value=2147472639)
AZURE = Color(_value=4043309055)
BEIGE = Color(_value=4126530815)
BISQUE = Color(_value=4293182719)
BLACK = Color(_value=255)
BLANCHED_ALMOND = Color(_value=4293643775)
BLUE = Color(_value=65535)
BLUE_VIOLET = Color(_value=2318131967)
BROWN = Color(_value=2771004159)
BURLY_WOOD = Color(_value=3736635391)
CADET_BLUE = Color(_value=1604231423)
CHARTREUSE = Color(_value=2147418367)
CHOCOLATE = Color(_value=3530104575)
CORAL = Color(_value=4286533887)
CORNFLOWER_BLUE = Color(_value=1687547391)
CORNSILK = Color(_value=4294499583)
CRIMSON = Color(_value=3692313855)
CYAN = Color(_value=16777215)
DARK_BLUE = Color(_value=35839)
DARK_CYAN = Color(_value=9145343)
DARK_GOLDENROD = Color(_value=3095792639)
DARK_GRAY = Color(_value=2846468607)
DARK_GREEN = Color(_value=6553855)
DARK_KHAKI = Color(_value=3182914559)
DARK_MAGENTA = Color(_value=2332068863)
DARK_OLIVE_GREEN = Color(_value=1433087999)
DARK_ORANGE = Color(_value=4287365375)
DARK_ORCHID = Color(_value=2570243327)
DARK_RED = Color(_value=2332033279)
DARK_SALMON = Color(_value=3918953215)
DARK_SEA_GREEN = Color(_value=2411498495)
DARK_SLATE_BLUE = Color(_value=1211993087)
DARK_SLATE_GRAY = Color(_value=793726975)
DARK_TURQUOISE = Color(_value=13554175)
DARK_VIOLET = Color(_value=2483082239)
DEEP_PINK = Color(_value=4279538687)
DEEP_SKY_BLUE = Color(_value=12582911)
DIM_GRAY = Color(_value=1768516095)
DODGER_BLUE = Color(_value=512819199)
FIREBRICK = Color(_value=2988581631)
FLORAL_WHITE = Color(_value=4294635775)
FOREST_GREEN = Color(_value=579543807)
FUCHSIA = Color(_value=4278255615)
GAINSBORO = Color(_value=3705462015)
GHOST_WHITE = Color(_value=4177068031)
GOLD = Color(_value=4292280575)
GOLDENROD = Color(_value=3668254975)
GRAY = Color(_value=2155905279)
GREEN = Color(_value=8388863)
GREEN_YELLOW = Color(_value=2919182335)
HONEYDEW = Color(_value=4043305215)
HOT_PINK = Color(_value=4285117695)
INDIAN_RED = Color(_value=3445382399)
INDIGO = Color(_value=1258324735)
IVORY = Color(_value=4294963455)
KHAKI = Color(_value=4041641215)
LAVENDER = Color(_value=3873897215)
LAVENDER_BLUSH = Color(_value=4293981695)
LAWN_GREEN = Color(_value=2096890111)
LEMON_CHIFFON = Color(_value=4294626815)
LIGHT_BLUE = Color(_value=2916673279)
LIGHT_CORAL = Color(_value=4034953471)
LIGHT_CYAN = Color(_value=3774873599)
LIGHT_GOLDENROD_YELLOW = Color(_value=4210742015)
LIGHT_GRAY = Color(_value=3553874943)
LIGHT_GREEN = Color(_value=2431553791)
LIGHT_PINK = Color(_value=4290167295)
LIGHT_SALMON = Color(_value=4288707327)
LIGHT_SEA_GREEN = Color(_value=548580095)
LIGHT_SKY_BLUE = Color(_value=2278488831)
LIGHT_SLATE_GRAY = Color(_value=2005441023)
LIGHT_STEEL_BLUE = Color(_value=2965692159)
LIGHT_YELLOW = Color(_value=4294959359)
LIME = Color(_value=16711935)
LIME_GREEN = Color(_value=852308735)
LINEN = Color(_value=4210091775)
MAGENTA = Color(_value=4278255615)
MAROON = Color(_value=2147483903)
MEDIUM_AQUAMARINE = Color(_value=1724754687)
MEDIUM_BLUE = Color(_value=52735)
MEDIUM_ORCHID = Color(_value=3126187007)
MEDIUM_PURPLE = Color(_value=2473647103)
MEDIUM_SEA_GREEN = Color(_value=1018393087)
MEDIUM_SLATE_BLUE = Color(_value=2070474495)
MEDIUM_SPRING_GREEN = Color(_value=16423679)
MEDIUM_TURQUOISE = Color(_value=1221709055)
MEDIUM_VIOLET_RED = Color(_value=3340076543)
MIDNIGHT_BLUE = Color(_value=421097727)
MINT_CREAM = Color(_value=4127193855)
MISTY_ROSE = Color(_value=4293190143)
MOCCASIN = Color(_value=4293178879)
NAVAJO_WHITE = Color(_value=4292783615)
NAVY = Color(_value=33023)
OLD_LACE = Color(_value=4260751103)
OLIVE = Color(_value=2155872511)
OLIVE_DRAB = Color(_value=1804477439)
ORANGE = Color(_value=4289003775)
ORANGE_RED = Color(_value=4282712319)
ORCHID = Color(_value=3664828159)
PALE_GOLDENROD = Color(_value=4008225535)
PALE_GREEN = Color(_value=2566625535)
PALE_TURQUOISE = Color(_value=2951671551)
PALE_VIOLET_RED = Color(_value=3681588223)
PAPAYA_WHIP = Color(_value=4293907967)
PEACH_PUFF = Color(_value=4292524543)
PERU = Color(_value=3448061951)
PINK = Color(_value=4290825215)
PLUM = Color(_value=3718307327)
POWDER_BLUE = Color(_value=2967529215)
PURPLE = Color(_value=2147516671)
RED = Color(_value=4278190335)
ROSY_BROWN = Color(_value=3163525119)
ROYAL_BLUE = Color(_value=1097458175)
SADDLE_BROWN = Color(_value=2336560127)
SALMON = Color(_value=4202722047)
SANDY_BROWN = Color(_value=4104413439)
SEA_GREEN = Color(_value=780883967)
SEA_SHELL = Color(_value=4294307583)
SIENNA = Color(_value=2689740287)
SILVER = Color(_value=3233857791)
SKY_BLUE = Color(_value=2278484991)
SLATE_BLUE = Color(_value=1784335871)
SLATE_GRAY = Color(_value=1887473919)
SNOW = Color(_value=4294638335)
SPRING_GREEN = Color(_value=16744447)
STEEL_BLUE = Color(_value=1182971135)
TAN = Color(_value=3535047935)
TEAL = Color(_value=8421631)
THISTLE = Color(_value=3636451583)
TOMATO = Color(_value=4284696575)
TRANSPARENT = Color(_value=4294967040)
TURQUOISE = Color(_value=1088475391)
VIOLET = Color(_value=4001558271)
WHEAT = Color(_value=4125012991)
WHITE = Color(_value=4294967295)
WHITE_SMOKE = Color(_value=4126537215)
YELLOW = Color(_value=4294902015)
YELLOW_GREEN = Color(_value=2597139199)
property a: int
property alpha: int

Gets the alpha component value of this color.

Returns:

The alpha component value between 0 and 255.

property b: int
property blue: int

Gets the blue component value of this color.

Returns:

The blue component value between 0 and 255.

classmethod from_color_with_alpha(base_color: Color, a: int) → Color

Creates a color from the specified base color with a new alpha value.

Parameters:

  • base_color – The Color from which to derive the RGB values.

  • a – The alpha component value (0-255).

Returns:

A new Color with the RGB values from the base color and the specified alpha value.

classmethod from_hex(hex_triplet: str) → Color

Creates a color from a hex triplet (RGB, RRGGBB, or RRGGBBAA without hash).

A hex triplet is either three, six, or eight hexadecimal digits that represent an RGB or RGBA color. An example of a hex triplet is “09C” or “0099CC”, which both represent the same color.

Parameters:

hex_triplet – A string containing hex digits like “09C”, “0099CC”, or “0099CCFF”.

Returns:

A new Color.

Raises:

ValueError – If the string is not valid hex digits (3, 6, or 8 characters).

classmethod from_hex_color(hex_color: str | None) → Color | None

Creates a color from a hex color string (#RGB, #RRGGBB, or #RRGGBBAA).

This method works the same as from_hex() except that it requires a hash sign before the hex value. An example of a numeric RGB value is “#09C” or “#0099CC”, which both represent the same color.

Parameters:

hex_color – A string containing a hex color like “#09C”, “#0099CC”, or “#0099CCFF”.

Returns:

A new Color; None if the input is None.

Raises:

ValueError – If the string is not in valid numeric RGB format.

classmethod from_rgb(r: int, g: int, b: int) → Color

Creates a color from the specified red, green, and blue values with alpha 255 (fully opaque).

Parameters:

  • r – The red component value (0-255).

  • g – The green component value (0-255).

  • b – The blue component value (0-255).

Returns:

A new Color initialized with the specified RGB values and an alpha value of 255.

classmethod from_rgba(r: int, g: int, b: int, a: int) → Color

Creates a color from the specified red, green, blue, and alpha values.

Parameters:

  • r – The red component value (0-255).

  • g – The green component value (0-255).

  • b – The blue component value (0-255).

  • a – The alpha component value (0-255).

Returns:

A new Color initialized with the specified RGBA values.

classmethod from_rgba_value(rgba: int) → Color

Creates a color from a 32-bit RGBA value.

Parameters:

rgba – A 32-bit value specifying the RGBA components.

Returns:

A new Color initialized with the specified RGBA value.

property g: int
property green: int

Gets the green component value of this color.

Returns:

The green component value between 0 and 255.

property r: int
property red: int

Gets the red component value of this color.

Returns:

The red component value between 0 and 255.

to_color_schema() → Color

Converts this color to the schema Color representation used by the API.

Note

The returned hex string uses lowercase letters for compatibility with the Python schema representation.

Returns:

A Color schema object with the hex value set.

to_hex_color() → str

Converts the color to its hexadecimal representation.

Returns:

  • If alpha is 255 (fully opaque), returns “#RRGGBB”.

  • If alpha is not 255, returns “#RRGGBBAA”.

Return type:

A string representing the color in hexadecimal format

to_rgba() → int

Converts this Color to a 32-bit RGBA value.

Returns:

A 32-bit integer containing the RGBA representation of this color.

droid: bool

Flag specifying if the bot is a droid.

energy: float

Energy level. Typically starts at 100.

x: float

X coordinate.

y: float

Y coordinate.

direction: float

Driving direction in degrees.

gun_direction: float

Gun direction in degrees.

radar_direction: float

Radar direction in degrees.

radar_sweep: float

Radar sweep angle in degrees.

speed: float

Speed measured in units per turn.

turn_rate: float

Turn rate of the body in degrees per turn.

gun_turn_rate: float

Turn rate of the gun in degrees per turn.

radar_turn_rate: float

Turn rate of the radar in degrees per turn.

gun_heat: float

Gun heat.

enemy_count: int

Number of enemies left.

body_color: Color | None

Body color.

turret_color: Color | None

Gun turret color.

radar_color: Color | None

Radar color.

bullet_color: Color | None

Bullet color.

scan_color: Color | None

Scan arc color.

tracks_color: Color | None

Tracks color.

gun_color: Color | None

Gun color.

debugging_enabled: bool

Flag indicating if graphical debugging is enabled.

bot_api.bullet_state module

class BulletState(bullet_id: int, owner_id: int, power: float, x: float, y: float, direction: float, color: Color)[source]

Bases: object

Represents the state of a bullet that has been fired by a bot.

Variables:

  • bullet_id (int) – Unique identifier for the bullet.

  • owner_id (int) – Identifier of the bot that fired the bullet.

  • power (float) – Firepower level of the bullet, which also determines its speed.

  • x (float) – The X-coordinate of the bullet’s position.

  • y (float) – The Y-coordinate of the bullet’s position.

  • direction (float) – The direction of the bullet in degrees, where 0 points to the right.

  • color (Color) – The visual color of the bullet.

class Color(_value: int)

Bases: object

Represents an RGBA (red, green, blue, alpha) color used in the Tank Royale game.

This graphics Color implementation contains: - Internal 32-bit RGBA value - Factory methods from_rgb(), from_rgba(r,g,b,a), and from_rgba_value(rgba) - Read-only channel properties: red, green, blue, alpha (mapped to R,G,B,A) - to_rgba() for round-trip, to_hex_color() for hex string - Equality/hash based on RGBA value - Many predefined common colors

Note: For compatibility with existing Python code, to_color_schema() is preserved and uses lowercase hex values as before.

ALICE_BLUE = Color(_value=4042850303)
ANTIQUE_WHITE = Color(_value=4209760255)
AQUA = Color(_value=16777215)
AQUAMARINE = Color(_value=2147472639)
AZURE = Color(_value=4043309055)
BEIGE = Color(_value=4126530815)
BISQUE = Color(_value=4293182719)
BLACK = Color(_value=255)
BLANCHED_ALMOND = Color(_value=4293643775)
BLUE = Color(_value=65535)
BLUE_VIOLET = Color(_value=2318131967)
BROWN = Color(_value=2771004159)
BURLY_WOOD = Color(_value=3736635391)
CADET_BLUE = Color(_value=1604231423)
CHARTREUSE = Color(_value=2147418367)
CHOCOLATE = Color(_value=3530104575)
CORAL = Color(_value=4286533887)
CORNFLOWER_BLUE = Color(_value=1687547391)
CORNSILK = Color(_value=4294499583)
CRIMSON = Color(_value=3692313855)
CYAN = Color(_value=16777215)
DARK_BLUE = Color(_value=35839)
DARK_CYAN = Color(_value=9145343)
DARK_GOLDENROD = Color(_value=3095792639)
DARK_GRAY = Color(_value=2846468607)
DARK_GREEN = Color(_value=6553855)
DARK_KHAKI = Color(_value=3182914559)
DARK_MAGENTA = Color(_value=2332068863)
DARK_OLIVE_GREEN = Color(_value=1433087999)
DARK_ORANGE = Color(_value=4287365375)
DARK_ORCHID = Color(_value=2570243327)
DARK_RED = Color(_value=2332033279)
DARK_SALMON = Color(_value=3918953215)
DARK_SEA_GREEN = Color(_value=2411498495)
DARK_SLATE_BLUE = Color(_value=1211993087)
DARK_SLATE_GRAY = Color(_value=793726975)
DARK_TURQUOISE = Color(_value=13554175)
DARK_VIOLET = Color(_value=2483082239)
DEEP_PINK = Color(_value=4279538687)
DEEP_SKY_BLUE = Color(_value=12582911)
DIM_GRAY = Color(_value=1768516095)
DODGER_BLUE = Color(_value=512819199)
FIREBRICK = Color(_value=2988581631)
FLORAL_WHITE = Color(_value=4294635775)
FOREST_GREEN = Color(_value=579543807)
FUCHSIA = Color(_value=4278255615)
GAINSBORO = Color(_value=3705462015)
GHOST_WHITE = Color(_value=4177068031)
GOLD = Color(_value=4292280575)
GOLDENROD = Color(_value=3668254975)
GRAY = Color(_value=2155905279)
GREEN = Color(_value=8388863)
GREEN_YELLOW = Color(_value=2919182335)
HONEYDEW = Color(_value=4043305215)
HOT_PINK = Color(_value=4285117695)
INDIAN_RED = Color(_value=3445382399)
INDIGO = Color(_value=1258324735)
IVORY = Color(_value=4294963455)
KHAKI = Color(_value=4041641215)
LAVENDER = Color(_value=3873897215)
LAVENDER_BLUSH = Color(_value=4293981695)
LAWN_GREEN = Color(_value=2096890111)
LEMON_CHIFFON = Color(_value=4294626815)
LIGHT_BLUE = Color(_value=2916673279)
LIGHT_CORAL = Color(_value=4034953471)
LIGHT_CYAN = Color(_value=3774873599)
LIGHT_GOLDENROD_YELLOW = Color(_value=4210742015)
LIGHT_GRAY = Color(_value=3553874943)
LIGHT_GREEN = Color(_value=2431553791)
LIGHT_PINK = Color(_value=4290167295)
LIGHT_SALMON = Color(_value=4288707327)
LIGHT_SEA_GREEN = Color(_value=548580095)
LIGHT_SKY_BLUE = Color(_value=2278488831)
LIGHT_SLATE_GRAY = Color(_value=2005441023)
LIGHT_STEEL_BLUE = Color(_value=2965692159)
LIGHT_YELLOW = Color(_value=4294959359)
LIME = Color(_value=16711935)
LIME_GREEN = Color(_value=852308735)
LINEN = Color(_value=4210091775)
MAGENTA = Color(_value=4278255615)
MAROON = Color(_value=2147483903)
MEDIUM_AQUAMARINE = Color(_value=1724754687)
MEDIUM_BLUE = Color(_value=52735)
MEDIUM_ORCHID = Color(_value=3126187007)
MEDIUM_PURPLE = Color(_value=2473647103)
MEDIUM_SEA_GREEN = Color(_value=1018393087)
MEDIUM_SLATE_BLUE = Color(_value=2070474495)
MEDIUM_SPRING_GREEN = Color(_value=16423679)
MEDIUM_TURQUOISE = Color(_value=1221709055)
MEDIUM_VIOLET_RED = Color(_value=3340076543)
MIDNIGHT_BLUE = Color(_value=421097727)
MINT_CREAM = Color(_value=4127193855)
MISTY_ROSE = Color(_value=4293190143)
MOCCASIN = Color(_value=4293178879)
NAVAJO_WHITE = Color(_value=4292783615)
NAVY = Color(_value=33023)
OLD_LACE = Color(_value=4260751103)
OLIVE = Color(_value=2155872511)
OLIVE_DRAB = Color(_value=1804477439)
ORANGE = Color(_value=4289003775)
ORANGE_RED = Color(_value=4282712319)
ORCHID = Color(_value=3664828159)
PALE_GOLDENROD = Color(_value=4008225535)
PALE_GREEN = Color(_value=2566625535)
PALE_TURQUOISE = Color(_value=2951671551)
PALE_VIOLET_RED = Color(_value=3681588223)
PAPAYA_WHIP = Color(_value=4293907967)
PEACH_PUFF = Color(_value=4292524543)
PERU = Color(_value=3448061951)
PINK = Color(_value=4290825215)
PLUM = Color(_value=3718307327)
POWDER_BLUE = Color(_value=2967529215)
PURPLE = Color(_value=2147516671)
RED = Color(_value=4278190335)
ROSY_BROWN = Color(_value=3163525119)
ROYAL_BLUE = Color(_value=1097458175)
SADDLE_BROWN = Color(_value=2336560127)
SALMON = Color(_value=4202722047)
SANDY_BROWN = Color(_value=4104413439)
SEA_GREEN = Color(_value=780883967)
SEA_SHELL = Color(_value=4294307583)
SIENNA = Color(_value=2689740287)
SILVER = Color(_value=3233857791)
SKY_BLUE = Color(_value=2278484991)
SLATE_BLUE = Color(_value=1784335871)
SLATE_GRAY = Color(_value=1887473919)
SNOW = Color(_value=4294638335)
SPRING_GREEN = Color(_value=16744447)
STEEL_BLUE = Color(_value=1182971135)
TAN = Color(_value=3535047935)
TEAL = Color(_value=8421631)
THISTLE = Color(_value=3636451583)
TOMATO = Color(_value=4284696575)
TRANSPARENT = Color(_value=4294967040)
TURQUOISE = Color(_value=1088475391)
VIOLET = Color(_value=4001558271)
WHEAT = Color(_value=4125012991)
WHITE = Color(_value=4294967295)
WHITE_SMOKE = Color(_value=4126537215)
YELLOW = Color(_value=4294902015)
YELLOW_GREEN = Color(_value=2597139199)
property a: int
property alpha: int

Gets the alpha component value of this color.

Returns:

The alpha component value between 0 and 255.

property b: int
property blue: int

Gets the blue component value of this color.

Returns:

The blue component value between 0 and 255.

classmethod from_color_with_alpha(base_color: Color, a: int) → Color

Creates a color from the specified base color with a new alpha value.

Parameters:

  • base_color – The Color from which to derive the RGB values.

  • a – The alpha component value (0-255).

Returns:

A new Color with the RGB values from the base color and the specified alpha value.

classmethod from_hex(hex_triplet: str) → Color

Creates a color from a hex triplet (RGB, RRGGBB, or RRGGBBAA without hash).

A hex triplet is either three, six, or eight hexadecimal digits that represent an RGB or RGBA color. An example of a hex triplet is “09C” or “0099CC”, which both represent the same color.

Parameters:

hex_triplet – A string containing hex digits like “09C”, “0099CC”, or “0099CCFF”.

Returns:

A new Color.

Raises:

ValueError – If the string is not valid hex digits (3, 6, or 8 characters).

classmethod from_hex_color(hex_color: str | None) → Color | None

Creates a color from a hex color string (#RGB, #RRGGBB, or #RRGGBBAA).

This method works the same as from_hex() except that it requires a hash sign before the hex value. An example of a numeric RGB value is “#09C” or “#0099CC”, which both represent the same color.

Parameters:

hex_color – A string containing a hex color like “#09C”, “#0099CC”, or “#0099CCFF”.

Returns:

A new Color; None if the input is None.

Raises:

ValueError – If the string is not in valid numeric RGB format.

classmethod from_rgb(r: int, g: int, b: int) → Color

Creates a color from the specified red, green, and blue values with alpha 255 (fully opaque).

Parameters:

  • r – The red component value (0-255).

  • g – The green component value (0-255).

  • b – The blue component value (0-255).

Returns:

A new Color initialized with the specified RGB values and an alpha value of 255.

classmethod from_rgba(r: int, g: int, b: int, a: int) → Color

Creates a color from the specified red, green, blue, and alpha values.

Parameters:

  • r – The red component value (0-255).

  • g – The green component value (0-255).

  • b – The blue component value (0-255).

  • a – The alpha component value (0-255).

Returns:

A new Color initialized with the specified RGBA values.

classmethod from_rgba_value(rgba: int) → Color

Creates a color from a 32-bit RGBA value.

Parameters:

rgba – A 32-bit value specifying the RGBA components.

Returns:

A new Color initialized with the specified RGBA value.

property g: int
property green: int

Gets the green component value of this color.

Returns:

The green component value between 0 and 255.

property r: int
property red: int

Gets the red component value of this color.

Returns:

The red component value between 0 and 255.

to_color_schema() → Color

Converts this color to the schema Color representation used by the API.

Note

The returned hex string uses lowercase letters for compatibility with the Python schema representation.

Returns:

A Color schema object with the hex value set.

to_hex_color() → str

Converts the color to its hexadecimal representation.

Returns:

  • If alpha is 255 (fully opaque), returns “#RRGGBB”.

  • If alpha is not 255, returns “#RRGGBBAA”.

Return type:

A string representing the color in hexadecimal format

to_rgba() → int

Converts this Color to a 32-bit RGBA value.

Returns:

A 32-bit integer containing the RGBA representation of this color.

bullet_id: int
owner_id: int
power: float
x: float
y: float
direction: float
color: Color
property speed: float

Calculates and returns the speed of the bullet in units per turn. The speed decreases with higher firepower levels.

Formula:

speed = 20 - 3 * power

Returns:

The calculated speed of the bullet in units per turn.

Return type:

float

bot_api.color module

class Color(_value: int)[source]

Bases: object

Represents an RGBA (red, green, blue, alpha) color used in the Tank Royale game.

This graphics Color implementation contains: - Internal 32-bit RGBA value - Factory methods from_rgb(), from_rgba(r,g,b,a), and from_rgba_value(rgba) - Read-only channel properties: red, green, blue, alpha (mapped to R,G,B,A) - to_rgba() for round-trip, to_hex_color() for hex string - Equality/hash based on RGBA value - Many predefined common colors

Note: For compatibility with existing Python code, to_color_schema() is preserved and uses lowercase hex values as before.

classmethod from_rgba_value(rgba: int) → Color[source]

Creates a color from a 32-bit RGBA value.

Parameters:

rgba – A 32-bit value specifying the RGBA components.

Returns:

A new Color initialized with the specified RGBA value.

classmethod from_rgba(r: int, g: int, b: int, a: int) → Color[source]

Creates a color from the specified red, green, blue, and alpha values.

Parameters:

  • r – The red component value (0-255).

  • g – The green component value (0-255).

  • b – The blue component value (0-255).

  • a – The alpha component value (0-255).

Returns:

A new Color initialized with the specified RGBA values.

classmethod from_rgb(r: int, g: int, b: int) → Color[source]

Creates a color from the specified red, green, and blue values with alpha 255 (fully opaque).

Parameters:

  • r – The red component value (0-255).

  • g – The green component value (0-255).

  • b – The blue component value (0-255).

Returns:

A new Color initialized with the specified RGB values and an alpha value of 255.

classmethod from_color_with_alpha(base_color: Color, a: int) → Color[source]

Creates a color from the specified base color with a new alpha value.

Parameters:

  • base_color – The Color from which to derive the RGB values.

  • a – The alpha component value (0-255).

Returns:

A new Color with the RGB values from the base color and the specified alpha value.

classmethod from_hex_color(hex_color: str | None) → Color | None[source]

Creates a color from a hex color string (#RGB, #RRGGBB, or #RRGGBBAA).

This method works the same as from_hex() except that it requires a hash sign before the hex value. An example of a numeric RGB value is “#09C” or “#0099CC”, which both represent the same color.

Parameters:

hex_color – A string containing a hex color like “#09C”, “#0099CC”, or “#0099CCFF”.

Returns:

A new Color; None if the input is None.

Raises:

ValueError – If the string is not in valid numeric RGB format.

classmethod from_hex(hex_triplet: str) → Color[source]

Creates a color from a hex triplet (RGB, RRGGBB, or RRGGBBAA without hash).

A hex triplet is either three, six, or eight hexadecimal digits that represent an RGB or RGBA color. An example of a hex triplet is “09C” or “0099CC”, which both represent the same color.

Parameters:

hex_triplet – A string containing hex digits like “09C”, “0099CC”, or “0099CCFF”.

Returns:

A new Color.

Raises:

ValueError – If the string is not valid hex digits (3, 6, or 8 characters).

property red: int

Gets the red component value of this color.

Returns:

The red component value between 0 and 255.

property green: int

Gets the green component value of this color.

Returns:

The green component value between 0 and 255.

property blue: int

Gets the blue component value of this color.

Returns:

The blue component value between 0 and 255.

property alpha: int

Gets the alpha component value of this color.

Returns:

The alpha component value between 0 and 255.

property r: int
property g: int
property b: int
property a: int
to_rgba() → int[source]

Converts this Color to a 32-bit RGBA value.

Returns:

A 32-bit integer containing the RGBA representation of this color.

to_hex_color() → str[source]

Converts the color to its hexadecimal representation.

Returns:

  • If alpha is 255 (fully opaque), returns “#RRGGBB”.

  • If alpha is not 255, returns “#RRGGBBAA”.

Return type:

A string representing the color in hexadecimal format

to_color_schema() → Color[source]

Converts this color to the schema Color representation used by the API.

Note

The returned hex string uses lowercase letters for compatibility with the Python schema representation.

Returns:

A Color schema object with the hex value set.

ALICE_BLUE = Color(_value=4042850303)
ANTIQUE_WHITE = Color(_value=4209760255)
AQUA = Color(_value=16777215)
AQUAMARINE = Color(_value=2147472639)
AZURE = Color(_value=4043309055)
BEIGE = Color(_value=4126530815)
BISQUE = Color(_value=4293182719)
BLACK = Color(_value=255)
BLANCHED_ALMOND = Color(_value=4293643775)
BLUE = Color(_value=65535)
BLUE_VIOLET = Color(_value=2318131967)
BROWN = Color(_value=2771004159)
BURLY_WOOD = Color(_value=3736635391)
CADET_BLUE = Color(_value=1604231423)
CHARTREUSE = Color(_value=2147418367)
CHOCOLATE = Color(_value=3530104575)
CORAL = Color(_value=4286533887)
CORNFLOWER_BLUE = Color(_value=1687547391)
CORNSILK = Color(_value=4294499583)
CRIMSON = Color(_value=3692313855)
CYAN = Color(_value=16777215)
DARK_BLUE = Color(_value=35839)
DARK_CYAN = Color(_value=9145343)
DARK_GOLDENROD = Color(_value=3095792639)
DARK_GRAY = Color(_value=2846468607)
DARK_GREEN = Color(_value=6553855)
DARK_KHAKI = Color(_value=3182914559)
DARK_MAGENTA = Color(_value=2332068863)
DARK_OLIVE_GREEN = Color(_value=1433087999)
DARK_ORANGE = Color(_value=4287365375)
DARK_ORCHID = Color(_value=2570243327)
DARK_RED = Color(_value=2332033279)
DARK_SALMON = Color(_value=3918953215)
DARK_SEA_GREEN = Color(_value=2411498495)
DARK_SLATE_BLUE = Color(_value=1211993087)
DARK_SLATE_GRAY = Color(_value=793726975)
DARK_TURQUOISE = Color(_value=13554175)
DARK_VIOLET = Color(_value=2483082239)
DEEP_PINK = Color(_value=4279538687)
DEEP_SKY_BLUE = Color(_value=12582911)
DIM_GRAY = Color(_value=1768516095)
DODGER_BLUE = Color(_value=512819199)
FIREBRICK = Color(_value=2988581631)
FLORAL_WHITE = Color(_value=4294635775)
FOREST_GREEN = Color(_value=579543807)
FUCHSIA = Color(_value=4278255615)
GAINSBORO = Color(_value=3705462015)
GHOST_WHITE = Color(_value=4177068031)
GOLD = Color(_value=4292280575)
GOLDENROD = Color(_value=3668254975)
GRAY = Color(_value=2155905279)
GREEN = Color(_value=8388863)
GREEN_YELLOW = Color(_value=2919182335)
HONEYDEW = Color(_value=4043305215)
HOT_PINK = Color(_value=4285117695)
INDIAN_RED = Color(_value=3445382399)
INDIGO = Color(_value=1258324735)
IVORY = Color(_value=4294963455)
KHAKI = Color(_value=4041641215)
LAVENDER = Color(_value=3873897215)
LAVENDER_BLUSH = Color(_value=4293981695)
LAWN_GREEN = Color(_value=2096890111)
LEMON_CHIFFON = Color(_value=4294626815)
LIGHT_BLUE = Color(_value=2916673279)
LIGHT_CORAL = Color(_value=4034953471)
LIGHT_CYAN = Color(_value=3774873599)
LIGHT_GOLDENROD_YELLOW = Color(_value=4210742015)
LIGHT_GRAY = Color(_value=3553874943)
LIGHT_GREEN = Color(_value=2431553791)
LIGHT_PINK = Color(_value=4290167295)
LIGHT_SALMON = Color(_value=4288707327)
LIGHT_SEA_GREEN = Color(_value=548580095)
LIGHT_SKY_BLUE = Color(_value=2278488831)
LIGHT_SLATE_GRAY = Color(_value=2005441023)
LIGHT_STEEL_BLUE = Color(_value=2965692159)
LIGHT_YELLOW = Color(_value=4294959359)
LIME = Color(_value=16711935)
LIME_GREEN = Color(_value=852308735)
LINEN = Color(_value=4210091775)
MAGENTA = Color(_value=4278255615)
MAROON = Color(_value=2147483903)
MEDIUM_AQUAMARINE = Color(_value=1724754687)
MEDIUM_BLUE = Color(_value=52735)
MEDIUM_ORCHID = Color(_value=3126187007)
MEDIUM_PURPLE = Color(_value=2473647103)
MEDIUM_SEA_GREEN = Color(_value=1018393087)
MEDIUM_SLATE_BLUE = Color(_value=2070474495)
MEDIUM_SPRING_GREEN = Color(_value=16423679)
MEDIUM_TURQUOISE = Color(_value=1221709055)
MEDIUM_VIOLET_RED = Color(_value=3340076543)
MIDNIGHT_BLUE = Color(_value=421097727)
MINT_CREAM = Color(_value=4127193855)
MISTY_ROSE = Color(_value=4293190143)
MOCCASIN = Color(_value=4293178879)
NAVAJO_WHITE = Color(_value=4292783615)
NAVY = Color(_value=33023)
OLD_LACE = Color(_value=4260751103)
OLIVE = Color(_value=2155872511)
OLIVE_DRAB = Color(_value=1804477439)
ORANGE = Color(_value=4289003775)
ORANGE_RED = Color(_value=4282712319)
ORCHID = Color(_value=3664828159)
PALE_GOLDENROD = Color(_value=4008225535)
PALE_GREEN = Color(_value=2566625535)
PALE_TURQUOISE = Color(_value=2951671551)
PALE_VIOLET_RED = Color(_value=3681588223)
PAPAYA_WHIP = Color(_value=4293907967)
PEACH_PUFF = Color(_value=4292524543)
PERU = Color(_value=3448061951)
PINK = Color(_value=4290825215)
PLUM = Color(_value=3718307327)
POWDER_BLUE = Color(_value=2967529215)
PURPLE = Color(_value=2147516671)
RED = Color(_value=4278190335)
ROSY_BROWN = Color(_value=3163525119)
ROYAL_BLUE = Color(_value=1097458175)
SADDLE_BROWN = Color(_value=2336560127)
SALMON = Color(_value=4202722047)
SANDY_BROWN = Color(_value=4104413439)
SEA_GREEN = Color(_value=780883967)
SEA_SHELL = Color(_value=4294307583)
SIENNA = Color(_value=2689740287)
SILVER = Color(_value=3233857791)
SKY_BLUE = Color(_value=2278484991)
SLATE_BLUE = Color(_value=1784335871)
SLATE_GRAY = Color(_value=1887473919)
SNOW = Color(_value=4294638335)
SPRING_GREEN = Color(_value=16744447)
STEEL_BLUE = Color(_value=1182971135)
TAN = Color(_value=3535047935)
TEAL = Color(_value=8421631)
THISTLE = Color(_value=3636451583)
TOMATO = Color(_value=4284696575)
TRANSPARENT = Color(_value=4294967040)
TURQUOISE = Color(_value=1088475391)
VIOLET = Color(_value=4001558271)
WHEAT = Color(_value=4125012991)
WHITE = Color(_value=4294967295)
WHITE_SMOKE = Color(_value=4126537215)
YELLOW = Color(_value=4294902015)
YELLOW_GREEN = Color(_value=2597139199)

bot_api.constants module

Constants for the Tank Royale Bot API.

BOUNDING_CIRCLE_RADIUS = 18

Radius of the bounding circle of the bot. A bot gets hit by a bullet when the bullet gets inside this bounding circle.

SCAN_RADIUS = 1200

Radius of the radar’s scan beam. Bots within this radius are detectable by the radar.

MAX_TURN_RATE = 10

Maximum possible driving turn rate in degrees per turn. The speed of the bot affects the turn rate. Formula: MaxTurnRate - 0.75 x abs(speed)

MAX_GUN_TURN_RATE = 20

Maximum gun turn rate in degrees per turn.

MAX_RADAR_TURN_RATE = 45

Maximum radar turn rate in degrees per turn.

MAX_SPEED = 8

Maximum absolute speed in units per turn.

MIN_FIREPOWER = 0.1

Minimum firepower for the bot’s gun. The gun cannot fire with power less than this.

MAX_FIREPOWER = 3

Maximum firepower for the bot’s gun. The gun cannot fire with power greater than this.

MIN_BULLET_SPEED = 11

Minimum bullet speed in units per turn. Derived using the formula: 20 - 3 x MAX_FIREPOWER.

MAX_BULLET_SPEED = 19.7

Maximum bullet speed in units per turn. Derived using the formula: 20 - 3 x MIN_FIREPOWER.

ACCELERATION = 1

Acceleration in units per turn. Incremental increase in speed when moving forward.

DECELERATION = -2

Deceleration in units per turn. Incremental decrease in speed when moving backward. The bot brakes faster than it accelerates forward.

INACTIVITY_ZAP = 0.1

The amount of damage a bot receives per turn when the game’s inactivity time limit is exceeded. A bot that has not fired or been hit by a bullet for max_inactivity_turns consecutive turns will lose this much energy every turn until it acts again.

RAM_DAMAGE = 0.6

The amount of damage dealt to each bot involved in a collision when two bots ram into each other, which is 0.6 energy points per collision.

STARTING_GUN_HEAT = 3.0

The gun heat at the start of a round, which is 3.0. The gun cannot fire until its heat drops to zero, cooling at the rate defined by the game setup’s gun cooling rate.

MAX_NUMBER_OF_TEAM_MESSAGES_PER_TURN = 10

Maximum number of team messages that can be sent per turn.

TEAM_MESSAGE_MAX_SIZE = 32768

Maximum size of a team message in bytes (32 KB).

bot_api.default_event_priority module

class DefaultEventPriority[source]

Bases: object

Default event priorities values. The higher value, the higher event priority. So the WonRoundEvent has the highest priority (150), and DeathEvent has the lowest priority (10).

WON_ROUND = 150

Event priority for the WonRoundEvent

SKIPPED_TURN = 140

Event priority for the SkippedTurnEvent

TICK = 130

Event priority for the TickEvent

CUSTOM = 120

Event priority for the CustomEvent

TEAM_MESSAGE = 110

Event priority for the TeamMessageEvent

BOT_DEATH = 100

Event priority for the BotDeathEvent

BULLET_HIT_WALL = 90

Event priority for the BulletHitWallEvent

BULLET_HIT_BULLET = 80

Event priority for the BulletHitBulletEvent

BULLET_HIT_BOT = 70

Event priority for the BulletHitBotEvent

BULLET_FIRED = 60

Event priority for the BulletFiredEvent

HIT_BY_BULLET = 50

Event priority for the HitByBulletEvent

HIT_WALL = 40

Event priority for the HitWallEvent

HIT_BOT = 30

Event priority for the HitBotEvent

SCANNED_BOT = 20

Event priority for the ScannedBotEvent

DEATH = 10

Event priority for the DeathEvent

bot_api.droid_abc module

class DroidABC[source]

Bases: ABC

An abstract base class representing a specialized droid bot for team-based operations.

A droid bot starts with 120 energy points, 20 more than a standard robot, but it lacks a scanner. Due to this limitation, droids rely entirely on their teammates to perform scanning tasks and share critical information, such as the coordinates of target enemies.

Teams composed of droids and at least one non-droid team member gain a strategic advantage over similarly sized teams without droids, thanks to the increased energy pool.

bot_api.game_setup module

class GameSetup(game_type: str, arena_width: int, arena_height: int, number_of_rounds: int, gun_cooling_rate: float, max_inactivity_turns: int, turn_timeout: int, ready_timeout: int)[source]

Bases: object

Game setup retrieved when game is started.

game_type: str

Game type, e.g. “melee”.

arena_width: int

Width of the arena measured in units.

arena_height: int

Height of the arena measured in units.

number_of_rounds: int

Number of rounds in a battle.

gun_cooling_rate: float

Gun cooling rate. The gun needs to cool down to a gun heat of zero before the gun is able to fire.

max_inactivity_turns: int

Maximum number of inactive turns allowed, where a bot does not take any action before it is zapped by the game.

turn_timeout: int

The turn timeout in microseconds (µs) (where 1 microsecond equals 1/1,000,000 of a second).

ready_timeout: int

The ready timeout in microseconds (µs) (where 1 microsecond equals 1/1,000,000 of a second).

bot_api.game_type module

class GameType[source]

Bases: object

Predefined game types. These game types are described here: https://robocode-dev.github.io/tank-royale/articles/game_types.html

CLASSIC = 'classic'

Classic (standard) battle with a minimum of 2 bots battling each other on an arena size of 800 x 600 units.

MELEE = 'melee'

Melee battle with a minimum of 10 bots battling each other on an arena of 1000 x 1000 units.

ONE_VS_ONE = '1v1'

One versus one (1-vs-1) battle between exactly two bots alone on an arena of 1000 x 1000 units.

bot_api.initial_position module

class InitialPosition(x: float | None, y: float | None, direction: float | None)[source]

Bases: object

Represents the initial position of a bot during debugging, with optional specific coordinates (x, y) and a shared direction for the body, gun, and radar. If not specified, the values are assigned randomly.

Note

The initial position is only applied when debugging and if enabled on the server-side. Otherwise, it will be ignored.

x: float | None

Optional x-coordinate for the starting position. If None, it will be randomly assigned.

y: float | None

Optional y-coordinate for the starting position. If None, it will be randomly assigned.

direction: float | None

Optional shared direction for the body, gun, and radar. If None, it will be randomly assigned.

static from_string(initial_position: str) → InitialPosition | None[source]

Creates an InitialPosition instance from a string.

Parameters:

  • initial_position (str) – A string containing coordinates and direction,

  • whitespace. (separated by commas and/or)

Returns:

An instance of the class if parsing is successful. None: If the input string is invalid or empty.

Return type:

InitialPosition

bot_api.team_message module

Team message type registry for typed team message serialization/deserialization.

This module provides a registry mechanism for team message types, allowing bots to send and receive typed objects (like RobotColors, Point) instead of raw dictionaries. This matches the behavior of Java and C# Bot APIs.

Usage:

# Using decorator
@team_message_type
@dataclass
class RobotColors:
    body_color: Color
    turret_color: Color

# Using function
register_team_message_type(Point)

# The type is automatically serialized/deserialized when using
# broadcast_team_message() and on_team_message()
team_message_type(cls: Type[Any]) → Type[Any][source]

Decorator to register a class as a team message type.

The class name is used as the message type identifier for serialization.

Parameters:

cls – The class to register.

Returns:

The same class, unmodified.

Example:

@team_message_type
@dataclass
class RobotColors:
    body_color: Color
    turret_color: Color
register_team_message_type(cls: Type[Any]) → None[source]

Register a class as a team message type.

The class name is used as the message type identifier for serialization.

Parameters:

cls – The class to register.

Example

register_team_message_type(Point)

get_team_message_type(name: str) → Type[Any] | None[source]

Look up a registered team message type by name.

Parameters:

name – The class name to look up.

Returns:

The registered class, or None if not found.

serialize_team_message(obj: Any) → str[source]

Serialize a team message object to JSON string.

Handles Color objects by converting them to hex strings. Converts snake_case field names to camelCase for JSON.

Parameters:

obj – The object to serialize.

Returns:

JSON string representation.

deserialize_team_message(json_str: str, message_type: str) → Any[source]

Deserialize a JSON string to a team message object.

Uses the message_type to look up the registered class and instantiate it. Handles Color fields by converting hex strings to Color objects.

Parameters:

  • json_str – The JSON string to deserialize.

  • message_type – The class name to deserialize into.

Returns:

The deserialized object, or a dictionary if the type is not registered.

Module contents

class BaseBotABC[source]

Bases: ABC

Interface containing the core API for a bot.

TEAM_MESSAGE_MAX_SIZE: int = 32768

Maximum size of a team message, which is 32 KB.

MAX_NUMBER_OF_TEAM_MESSAGES_PER_TURN: int = 10

The maximum number of team messages that can be sent per turn, which is 10 messages.

abstractmethod start() → None[source]

The method used to start running the bot. You should call this method from the main function or a similar entry point.

This method blocks until the bot disconnects from the server.

Example:

if __name__ == "__main__":
    # create my_bot
    ...
    my_bot.start()
abstractmethod go() → None[source]

Commits the current commands (actions), which finalizes the current turn for the bot.

This method must be called once per turn to send the bot actions to the server and must be called before the turn timeout occurs. A turn timer is started when the GameStartedEvent and TickEvent occurs. If the go() method is called too late, a turn timeout will occur and the SkippedTurnEvent will occur, which means that the bot has skipped all actions for the last turn. In this case, the server will continue executing the last actions received. This could be fatal for the bot due to loss of control over the bot. So make sure that go() is called before the turn ends.

The commands executed when go() is called are set by calling the various setter methods prior to calling the go() method: turn_rate, gun_turn_rate, radar_turn_rate, target_speed, and set_fire().

See also

turn_timeout

abstract property my_id: int

The bot’s unique identifier.

abstract property variant: str

The game variant, which is “Tank Royale”.

Returns:

The game variant of Robocode.

Return type:

str

abstract property version: str

Game version, e.g. “1.0.0”.

Returns:

The game version.

Return type:

str

abstract property game_type: str

Game type, e.g. “melee” or “1v1”.

First available when the game has started.

Returns:

The game type.

Return type:

str

abstract property arena_width: int

Width of the arena measured in units.

First available when the game has started.

Returns:

The arena width measured in units

Return type:

int

abstract property arena_height: int

Height of the arena measured in units.

First available when the game has started.

Returns:

The arena height measured in units

Return type:

int

abstract property number_of_rounds: int

The number of rounds in a battle.

First available when the game has started.

Returns:

The number of rounds in a battle.

Return type:

int

abstract property gun_cooling_rate: float

Gun cooling rate.

The gun needs to cool down to a gun heat of zero before the gun can fire. The gun cooling rate determines how fast the gun cools down. That is, the gun cooling rate is subtracted from the gun heat each turn until the gun heat reaches zero.

First available when the game has started.

Returns:

The gun cooling rate.

Return type:

float

abstract property max_inactivity_turns: int

The maximum number of inactive turns allowed.

The bot will become zapped by the game for being inactive. Inactive means that the bot has taken no action in several turns in a row.

First available when the game has started.

Returns:

The maximum number of allowed inactive turns.

Return type:

int

abstract property turn_timeout: int

The turn timeout in microseconds.

The turn timeout is important as the bot needs to take action by calling go() before the turn timeout occurs. As soon as the TickEvent() is triggered, i.e. when onTick() is called, you need to call go() to take action before the turn timeout occurs. Otherwise, your bot will skip a turn and receive a onSkippedTurn for each turn where go() is called too late.

First available when the game has started.

Returns:

The turn timeout in microseconds.

Return type:

int

abstract property time_left: int

The number of microseconds left of this turn before the bot will skip the turn.

Make sure to call go() before the time runs out.

Returns:

The amount of time left in microseconds.

Return type:

int

abstract property round_number: int

Current round number.

Returns:

The current round number.

Return type:

int

abstract property turn_number: int

Current turn number.

Returns:

The current turn number.

Return type:

int

abstract property enemy_count: int

Number of enemies left in the round.

Returns:

The number of enemies left in the round.

Return type:

int

abstract property energy: float

Current energy level.

When the energy level is positive, the bot is alive and active. When the energy level is 0, the bot is still alive but disabled. If the bot becomes disabled it will not be able to move or take any action. If negative, the bot has been defeated.

Returns:

The current energy level.

Return type:

float

abstract property disabled: bool

Specifies if the bot is disabled, i.e., when the energy is zero.

When the bot is disabled, it is not able to take any action like movement, turning, and firing.

Returns:

True if the bot is disabled; False otherwise.

Return type:

bool

abstract property x: float

Current X coordinate of the center of the bot.

Returns:

The current X coordinate of the bot.

Return type:

float

abstract property y: float

Current Y coordinate of the center of the bot.

Returns:

The current Y coordinate of the bot.

Return type:

float

abstract property direction: float

Current driving direction of the bot in degrees.

Returns:

The current driving direction of the bot.

Return type:

float

abstract property gun_direction: float

Current direction of the gun in degrees.

Returns:

The current gun direction of the bot.

Return type:

float

abstract property radar_direction: float

Current direction of the radar in degrees.

Returns:

The current radar direction of the bot.

Return type:

float

abstract property speed: float

The current speed measured in units per turn.

If the speed is positive, the bot moves forward. If negative, the bot moves backward. Zero speed means that the bot is not moving from its current position.

Returns:

The current speed.

Return type:

float

abstract property gun_heat: float

Current gun heat.

When the gun is fired it gets heated and will not be able to fire before it has been cooled down. The gun is cooled down when the gun heat is zero. When the gun has fired the gun heat is set to 1 + (firepower / 5) and will be cooled down by the gun cooling rate.

Returns:

The current gun heat.

Return type:

float

abstract property bullet_states: Sequence[BulletState | None] | None

Current bullet states.

Keeps track of all the bullets fired by the bot, which are still active on the arena.

Returns:

The current bullet states.

Return type:

list[BulletState]

abstract property events: Sequence[BotEvent | None] | None

Returns an ordered list containing all events currently in the bot’s event queue.

You might, for example, call this while processing another event.

Returns:

An ordered list containing all events currently in the bot’s event queue.

Return type:

list[BotEvent]

abstractmethod clear_events() → None[source]

Clears out any pending events in the bot’s event queue immediately.

abstract property turn_rate: float

Returns the turn rate of the bot in degrees per turn.

Returns:

The turn rate of the bot.

Return type:

float

abstract property max_turn_rate: float

Returns the maximum turn rate of the bot in degrees per turn.

Returns:

The maximum turn rate of the bot.

Return type:

float

abstract property gun_turn_rate: float

Returns the gun turn rate in degrees per turn.

Returns:

The turn rate of the gun.

Return type:

float

abstract property max_gun_turn_rate: float

Returns the maximum gun turn rate in degrees per turn.

Returns:

The maximum turn rate of the gun.

Return type:

float

abstract property radar_turn_rate: float

Returns the radar turn rate in degrees per turn.

Returns:

The turn rate of the radar.

Return type:

float

abstract property max_radar_turn_rate: float

Returns the maximum radar turn rate in degrees per turn.

Returns:

The maximum turn rate of the radar.

Return type:

float

abstract property target_speed: float

Returns the target speed in units per turn.

Returns:

The target speed.

Return type:

float

abstract property max_speed: float

Returns the maximum speed in units per turn.

Returns:

The maximum speed.

Return type:

float

abstractmethod set_fire(firepower: float) → bool[source]

Sets the gun to fire in the direction that the gun is pointing with the specified firepower.

Firepower is the amount of energy your bot will spend on firing the gun. This means that the bot will lose power on firing the gun, where the energy loss is equal to the firepower. You cannot spend more energy than is available from your bot.

The bullet power must be greater than the minimum firepower and gun heat must be zero before the gun can fire.

If the bullet hits an opponent bot, you will gain energy from the bullet hit. When hitting another bot, your bot will be rewarded and retrieve an energy boost of 3x the firepower.

The gun will only fire when the firepower is at or above the minimum firepower. If the firepower is greater than the maximum firepower, the power will be truncated to the maximum firepower.

Whenever the gun is fired, the gun becomes heated and needs to cool down before it can fire again. The gun heat must be zero before the gun can fire again. The gun heat generated by firing the gun is calculated as 1 + (firepower / 5). Hence, the more firepower used, the longer it takes to cool down the gun. The gun cooling rate can be retrieved using the get_gun_cooling_rate() function.

The amount of energy used for firing the gun is subtracted from the bot’s total energy. The amount of damage dealt by a bullet hitting another bot is 4x firepower. If the firepower is greater than 1, it will deal an additional 2 x (firepower - 1) damage.

Note that the gun will automatically keep firing each turn as soon as the gun heat reaches zero. It is possible to disable the gun firing by setting the firepower to zero.

The firepower is truncated between 0 and the maximum firepower if the provided value exceeds this range.

If this property is set multiple times, the last value set before calling go() is used.

Parameters:

firepower (float) – The new firepower.

Returns:

True if the cannon can fire (i.e., if there is no gun heat), False otherwise.

Return type:

bool

See also

  • on_bullet_fired()

  • get_firepower()

  • get_gun_heat()

  • get_gun_cooling_rate()

abstract property firepower: float

Returns the firepower.

Returns:

The firepower.

Return type:

float

abstractmethod set_rescan() → None[source]

Sets the bot to rescan with the radar.

This method is useful if the radar has not turned, and hence will not automatically scan bots. The last radar direction and sweep angle will be used for scanning for bots.

abstractmethod set_fire_assist(enable: bool) → None[source]

Enables or disables fire assistance explicitly. Fire assistance is useful for bots with limited aiming capabilities as it helps the bot by firing directly at a scanned bot when the gun is fired, which is a very simple aiming strategy.

When fire assistance is enabled, the gun will fire towards the center of the scanned bot when all these conditions are met:

  1. The gun is fired (via set_fire or fire()).

  2. The radar is scanning a bot when firing the gun (e.g., in the on_scanned_bot() event, after calling set_rescan() or rescan()).

  3. The gun and radar are pointing in the exact same direction. You can disable radar and gun movement alignment using set_adjust_radar_for_gun_turn(False) to ensure the gun and radar stay aligned while avoiding radar turning independently of the gun.

The fire assistance feature is provided for backwards compatibility with the original Robocode, where bots that were not considered AdvancedRobot had fire assistance enabled by default, as their gun and radar could not move independently of each other. In contrast, AdvancedRobot allows the body, gun, and radar to move independently.

Parameters:

enable (bool) – Enables fire assistance when set to True, and disables it otherwise.

abstractmethod set_interruptible(interruptible: bool) → None[source]

Sets whether the bot’s event handlers are interruptible.

When set to True, event handlers can be interrupted by higher-priority events. When set to False, handlers run to completion before other events are processed.

Parameters:

interruptible (bool) – If True, event handlers are interruptible; otherwise, they are not.

abstract property adjust_gun_for_body_turn: bool

Returns whether the gun adjusts for the bot’s body turn.

Returns:

True if the gun adjusts for body turn; False otherwise.

Return type:

bool

abstract property adjust_radar_for_body_turn: bool

Returns whether the radar adjusts for the bot’s body turn.

Returns:

True if the radar adjusts for body turn; False otherwise.

Return type:

bool

abstract property adjust_radar_for_gun_turn: bool

Returns whether the radar adjusts for the gun’s turn.

Returns:

True if the radar adjusts for gun turn; False otherwise.

Return type:

bool

abstractmethod is_teammate(bot_id: int) → bool[source]

Checks if the specified bot ID is a teammate.

Parameters:

bot_id (int) – The bot ID to check.

Returns:

True if the bot is a teammate; False otherwise.

Return type:

bool

abstract property teammate_ids: set[int]

The IDs of all teammates.

Returns:

A set of IDs of all teammates if the bot is participating in a team, or an empty set if the bot is not in a team.

Return type:

Set[int]

See also

is_teammate: Checks if a bot is a teammate. send_team_message: Sends a message to the team.

abstractmethod broadcast_team_message(message: Any) → None[source]

Broadcasts a message to all teammates.

When the message is sent, it is serialized into a JSON representation. This means that all public fields, and only public fields, are serialized into a JSON representation as a data transfer object (DTO).

The maximum team message size limit is defined by TEAM_MESSAGE_MAX_SIZE, which is set to 32,768 bytes. This size is calculated after serializing the message into a JSON representation.

The maximum number of messages that can be broadcast per turn is limited to MAX_NUMBER_OF_TEAM_MESSAGES_PER_TURN, which is set to 10.

Parameters:

message – The message to broadcast.

Raises:

ValueError – If the size of the message exceeds the size limit.

See also

send_team_message: Method to send a message to teammates. get_teammate_ids: Method to retrieve IDs of all teammates.

abstractmethod send_team_message(teammate_id: int, message: Any) → None[source]

Sends a message to a specific teammate.

When the message is sent, it is serialized into a JSON representation, meaning that all public fields, and only public fields, are being serialized into a JSON representation as a DTO (data transfer object).

The maximum team message size limit is defined by TEAM_MESSAGE_MAX_SIZE, which is set to TEAM_MESSAGE_MAX_SIZE bytes. This size is the size of the message when it is serialized into a JSON representation.

The maximum number of messages that can be sent/broadcast per turn is limited to MAX_NUMBER_OF_TEAM_MESSAGES_PER_TURN.

Parameters:

  • teammate_id – The id of the teammate to send the message to.

  • message – The message to send.

Raises:

ValueError – If the size of the message exceeds the size limit.

abstract property stopped: bool

Checks if the movement has been stopped.

Returns:

True if the movement has been stopped by set_stop(), False otherwise.

Return type:

bool

See also

set_resume: Resumes the movement. set_stop(): Stops the movement. set_stop(flag: bool): Stops the movement, with a flag to specify additional behavior.

abstract property body_color: Color | None

Returns the color of the body.

Returns:

The color of the body, or None if no color has been set yet.

In that case, the default color will be used.

Return type:

Color

abstract property turret_color: Color | None

Returns the color of the gun turret.

Returns:

The color of the turret or None if no color has been set yet, meaning that the default color will be used.

abstract property radar_color: Color | None

Returns the color of the radar.

Returns:

The color of the radar. If no color has been set yet, returns None, which indicates that the default radar color will be used.

Return type:

Color

abstract property bullet_color: Color | None

Returns the color of the fired bullets.

Returns:

The color of the bullets, or None if no color has been set yet, meaning that the default color will be used.

Return type:

Color

abstract property scan_color: Color | None

Returns the color of the scan arc.

Returns:

The color of the scan arc, or None if no color has been set, meaning the default color will be used.

Return type:

Color

abstract property tracks_color: Color | None

Returns the color of the tank tracks.

Returns:

The color of the tank tracks, or None if no color has been set yet, meaning that the default color will be used.

Return type:

Color

abstract property gun_color: Color | None

Returns the color of the gun.

Returns:

The color of the gun, or None if no color has been set yet. If None, the default color will be used.

Return type:

Color

abstract property debugging_enabled: bool

Indicates whether graphical debugging is enabled. If enabled, the graphics property can be used for debug painting.

Returns:

True if graphical debugging is enabled, False otherwise.

Return type:

bool

abstract property graphics: GraphicsABC

Gets a graphics object for debug painting.

Example

g = self.graphics g.set_fill_color(Color.from_rgb(0, 0, 255)) g.fill_rectangle(50, 50, 100, 100) # A blue filled rect

Returns:

A graphics canvas to use for painting graphical objects, making debugging easier.

static on_connected(connected_event: ConnectedEvent) → None[source]

The event handler triggered when connected to the server.

Parameters:

connected_event – The event details from the game.

static on_disconnected(disconnected_event: DisconnectedEvent) → None[source]

The event handler triggered when disconnected from the server.

Parameters:

disconnected_event – The event details from the game.

static on_connection_error(connection_error_event: ConnectionErrorEvent) → None[source]

The event handler triggered when a connection error occurs.

Parameters:

connection_error_event – The event details from the game.

on_game_started(game_started_event: GameStartedEvent) → None[source]

The event handler triggered when a game has started.

Parameters:

game_started_event – The event details from the game.

on_game_ended(game_ended_event: GameEndedEvent) → None[source]

The event handler triggered when a game has ended.

Parameters:

game_ended_event – The event details from the game.

on_round_started(round_started_event: RoundStartedEvent) → None[source]

The event handler triggered when a new round has started.

Parameters:

round_started_event – The event details from the game.

on_round_ended(round_ended_event: RoundEndedEvent) → None[source]

The event handler triggered when a round has ended.

Parameters:

round_ended_event – The event details from the game.

on_tick(tick_event: TickEvent) → None[source]

The event handler triggered when a game tick event occurs, i.e., when a new turn in a round has started.

Parameters:

tick_event – The event details from the game.

on_bot_death(bot_death_event: BotDeathEvent) → None[source]

The event handler triggered when another bot has died.

Parameters:

bot_death_event – The event details from the game.

on_death(death_event: DeathEvent) → None[source]

The event handler triggered when this bot has died.

Parameters:

death_event – The event details from the game.

on_hit_bot(bot_hit_bot_event: HitBotEvent) → None[source]

The event handler triggered when the bot has collided with another bot.

Parameters:

bot_hit_bot_event – The event details from the game.

on_hit_wall(bot_hit_wall_event: HitWallEvent) → None[source]

The event handler triggered when the bot has hit a wall.

Parameters:

bot_hit_wall_event – The event details from the game.

on_bullet_fired(bullet_fired_event: BulletFiredEvent) → None[source]

The event handler triggered when the bot has fired a bullet.

Parameters:

bullet_fired_event – The event details from the game.

on_hit_by_bullet(hit_by_bullet_event: HitByBulletEvent) → None[source]

The event handler triggered when the bot has been hit by a bullet.

Parameters:

hit_by_bullet_event – The event details from the game.

on_bullet_hit(bullet_hit_bot_event: BulletHitBotEvent) → None[source]

The event handler triggered when the bot has hit another bot with a bullet.

Parameters:

bullet_hit_bot_event – The event details from the game.

on_bullet_hit_bullet(bullet_hit_bullet_event: BulletHitBulletEvent) → None[source]

The event handler triggered when a bullet fired from the bot has collided with another bullet.

Parameters:

bullet_hit_bullet_event – The event details from the game.

on_bullet_hit_wall(bullet_hit_wall_event: BulletHitWallEvent) → None[source]

The event handler triggered when a bullet has hit a wall.

Parameters:

bullet_hit_wall_event – The event details from the game.

on_scanned_bot(scanned_bot_event: ScannedBotEvent) → None[source]

The event handler triggered when the bot has skipped a turn. This event occurs if the bot did not take any action in a specific turn. That is, go() was not called before the turn timeout occurred for the turn. If the bot does not take action for multiple turns in a row, it will receive a SkippedTurnEvent for each turn where it did not take action. When the bot is skipping a turn, the server did not receive the message from the bot, and the server will use the newest received instructions for target speed, turn rates, firing, etc.

Parameters:

scanned_bot_event – The event details from the game.

on_skipped_turn(skipped_turn_event: SkippedTurnEvent) → None[source]

Handles the event triggered when the bot skips a turn.

A turn is skipped if the bot does not send any instructions to the server (via the go() method) before the turn timeout occurs. When this happens, the server continues using the last received set of actions, such as movement, turning rates, or firing commands.

Reasons for skipped turns may include:

  • Excessive processing or delays in the bot’s logic, leading to a timeout.

  • Failure to invoke the go() method in the current turn.

  • Misaligned or unintended logic in the bot’s turn-handling code.

This method can be overridden to define custom behavior for handling skipped turns, such as logging the event, debugging performance issues, or modifying the bot’s logic to avoid future skips.

Parameters:

skipped_turn_event – An event containing details about the skipped turn.

on_won_round(won_round_event: WonRoundEvent) → None[source]

The event handler triggered when the bot has won a round.

Parameters:

won_round_event – The event details from the game.

on_custom_event(custom_event: CustomEvent) → None[source]

The event handler triggered when some condition has been met. Use the name of the condition when you need to differentiate between different types of conditions received with this event handler.

Parameters:

custom_event – The event details from the game.

on_team_message(team_message_event: TeamMessageEvent) → None[source]

The event handler triggered when the bot has received a message from a teammate.

Parameters:

team_message_event – The event details from the game.

abstractmethod calc_max_turn_rate(speed: float) → float[source]

Calculates the maximum turn rate for a specific speed.

Parameters:

speed (float) – The speed.

Returns:

The maximum turn rate determined by the given speed.

Return type:

float

abstractmethod calc_bullet_speed(firepower: float) → float[source]

Calculates the bullet speed given a firepower.

Parameters:

firepower (float) – The firepower.

Returns:

The bullet speed determined by the given firepower.

Return type:

float

abstractmethod calc_gun_heat(firepower: float) → float[source]

Calculates gun heat after having fired the gun.

Parameters:

firepower (float) – The firepower used when firing the gun.

Returns:

The gun heat produced when firing the gun with the given firepower.

Return type:

float

abstractmethod get_event_priority(event_class: type) → int[source]

Returns the event priority for a specific event class.

Example

scanned_bot_event_priority = get_priority(ScannedBotEvent)

Parameters:

event_class – The event class to get the event priority for.

Returns:

The event priority for a specific event class.

Return type:

int

See also

DefaultEventPriority set_event_priority

abstractmethod set_event_priority(event_class: type, priority: int) → None[source]

Changes the event priority for an event class. The event priority determines which event types (classes) must be fired and handled before others. Events with higher priorities will be handled before events with lower priorities.

Note

You should normally not need to change the event priority.

Parameters:

  • event_class (Type[BotEvent]) – The event class to change the priority for.

  • priority (int) – The new priority, typically a positive number from 1 to 150. The higher the value, the higher the priority.

See also

DefaultEventPriority, get_event_priority.

calc_bearing(direction: float) → float[source]

Calculates the bearing (delta angle) between the input direction and the bot’s direction.

Example

bearing = calc_bearing(direction) = normalize_relative_degrees(direction - self.direction)

Parameters:

direction (float) – The input direction to calculate the bearing from.

Returns:

A normalized bearing (delta angle) in the range [-180, 180).

Return type:

float

See also

direction, normalize_relative_angle.

calc_gun_bearing(direction: float) → float[source]

Calculates the bearing (delta angle) between the input direction and the gun’s direction.

Example

bearing = calc_gun_bearing(direction) =

normalize_relative_degrees(direction - self.gun_direction)

Parameters:

direction (float) – The input direction to calculate the bearing from.

Returns:

A normalized bearing (delta angle) in the range [-180, 180).

Return type:

float

See also

gun_direction, normalize_relative_angle.

calc_radar_bearing(direction: float) → float[source]

Calculates the bearing (delta angle) between the input direction and the radar’s direction.

Example

bearing = calc_radar_bearing(direction) =

normalize_relative_degrees(direction - self.radar_direction)

Parameters:

direction (float) – The input direction to calculate the bearing from.

Returns:

A normalized bearing (delta angle) in the range [-180, 180).

Return type:

float

See also

radar_direction, normalize_relative_angle.

direction_to(x: float, y: float) → float[source]

Calculates the direction (angle) from the bot’s coordinates to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

The direction to the point (x, y) in the range [0, 360).

Return type:

float

bearing_to(x: float, y: float) → float[source]

Calculates the bearing (delta angle) between the bot’s current direction and the direction to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

A bearing to the point (x, y) in the range [-180, 180).

Return type:

float

gun_bearing_to(x: float, y: float) → float[source]

Calculates the bearing (delta angle) between the gun’s current direction and the direction to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

A bearing to the point (x, y) in the range [-180, 180).

Return type:

float

radar_bearing_to(x: float, y: float) → float[source]

Calculates the bearing (delta angle) between the radar’s current direction and the direction to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

A bearing to the point (x, y) in the range [-180, 180).

Return type:

float

distance_to(x: float, y: float) → float[source]

Calculates the distance from the bot’s coordinates to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

The distance to the point (x, y).

Return type:

float

normalize_absolute_angle(angle: float) → float[source]

Normalizes an angle to an absolute angle in the range [0, 360).

Parameters:

angle (float) – The angle to normalize.

Returns:

The normalized absolute angle.

Return type:

float

normalize_relative_angle(angle: float) → float[source]

Normalizes the given angle to the range [-180, 180] degrees.

Parameters:

angle (float) – The angle to normalize.

Returns:

The normalized angle in degrees.

Return type:

float

calc_delta_angle(target_angle: float, source_angle: float) → float[source]

Calculates the difference between two angles, i.e., the number of degrees from a source angle to a target angle.

Parameters:

  • target_angle (float) – The target angle.

  • source_angle (float) – The source angle.

Returns:

The delta angle in the range [-180, 180].

Return type:

float

class Bot(bot_info: None | BotInfo = None, server_url: None | str = None, server_secret: None | str = None)[source]

Bases: BaseBot, BotABC

Base class for a bot in Robocode Tank Royale.

This class provides the basic structure and methods that all bots must implement. It inherits from BaseBot and BotABC, which define the core functionality and abstract methods that must be overridden by any specific bot implementation.

run() → None[source]

Runs the bot program.

Example

def run(self) -> None:
while self.running:

self.forward(100) self.turn_gun_left(360) self.back(100) self.turn_gun_right(360)

Note

When running a loop that could potentially run forever, the best practice is to check if the bot is still running to stop and exit the loop. This gives the game a chance to stop the thread running the loop. If the thread is not stopped correctly, the bot may behave strangely in new rounds.

See also

running

on_event(event: Condition) → None[source]

Handle events that occur during the bot’s execution.

property turn_rate: float

Get the turn rate of the bot.

property gun_turn_rate: float

Returns the gun turn rate in degrees per turn.

Returns:

The gun turn rate.

property radar_turn_rate: float

Returns the radar turn rate in degrees per turn.

Returns:

The radar turn rate.

property target_speed: float

Returns the target speed in units per turn.

Returns:

The target speed.

property running: bool

Check if this bot is running.

Returns:

True when the bot is running, False otherwise.

set_forward(distance: float) → None[source]

Set the bot to move forward until it has traveled a specific distance from its current position.

The speed is limited by max_speed. While moving forward, ACCELERATION determines the acceleration (+1 unit per turn), and DECELERATION determines braking (-2 units per turn).

This method is executed when go() is called, making it possible to call other setter methods and run them in parallel in the same turn. If this method is called multiple times, the last call before go() is executed counts.

This method cancels the effect of prior calls to target_speed, as set_forward and set_back call target_speed each turn until distance_remaining reaches 0.

Parameters:

distance – Distance to move forward. If negative, the bot moves backward. If positive or negative infinity, the bot moves infinitely in that direction.

forward(distance: float) → None[source]

Move the bot forward until it has traveled a specific distance from its current position.

The speed is limited by max_speed. While moving forward, ACCELERATION determines the acceleration (+1 unit per turn), and DECELERATION determines braking (-2 units per turn).

This call executes immediately by calling go() internally and blocks until completed, which can take one to several turns. New commands take place after this method completes. To run multiple commands in parallel, use setter methods instead of this blocking method.

This method cancels the effect of prior calls to target_speed, set_forward, and set_back.

Parameters:

distance – Distance to move forward. If negative, the bot moves backward. If positive or negative infinity, the bot moves infinitely in that direction.

set_back(distance: float) → None[source]

Set the bot to move backward until it has traveled a specific distance from its current position.

The speed is limited by max_speed. While moving forward, ACCELERATION determines the acceleration (+1 unit per turn), and DECELERATION determines braking (-2 units per turn).

This method is executed when go() is called, making it possible to call other setter methods and run them in parallel in the same turn. If this method is called multiple times, the last call before go() is executed counts.

This method cancels the effect of prior calls to target_speed, as set_forward and set_back call target_speed each turn until distance_remaining reaches 0.

Parameters:

distance – Distance to move backward. If negative, the bot moves forward. If positive or negative infinity, the bot moves infinitely in that direction.

back(distance: float) → None[source]

Move the bot backward until it has traveled a specific distance from its current position.

The speed is limited by max_speed. While moving forward, ACCELERATION determines the acceleration (+1 unit per turn), and DECELERATION determines braking (-2 units per turn).

This call executes immediately by calling go() internally and blocks until completed, which can take one to several turns. New commands take place after this method completes. To run multiple commands in parallel, use setter methods instead of this blocking method.

This method cancels the effect of prior calls to target_speed, set_forward, and set_back.

Parameters:

distance – Distance to move backward. If negative, the bot moves forward. If positive or negative infinity, the bot moves infinitely in that direction.

property distance_remaining: float

Return the remaining distance before the current movement is completed.

When the remaining distance is positive, the bot is moving forward. When negative, the bot is moving backward. Positive/negative infinity means infinite movement in that direction.

set_turn_left(degrees: float) → None[source]

Set the bot to turn left (following the increasing degrees of the unit circle).

The bot turns until turn_remaining is 0. The amount of degrees to turn each turn is limited by max_turn_rate.

This method is executed when go() is called, making it possible to call other setter methods and run them in parallel in the same turn. If this method is called multiple times, the last call before go() is executed counts.

This method cancels the effect of prior calls to set_turn_right.

Parameters:

degrees – Degrees to turn left. If negative, the bot turns right. If positive or negative infinity, the bot turns infinitely in that direction.

turn_left(degrees: float) → None[source]

Turn the bot left (following the increasing degrees of the unit circle).

The bot turns until turn_remaining is 0. The amount of degrees to turn each turn is limited by max_turn_rate.

This call executes immediately by calling go() internally and blocks until completed, which can take one to several turns. New commands take place after this method completes. To run multiple commands in parallel, use setter methods instead of this blocking method.

This method cancels the effect of prior calls to set_turn_left and set_turn_right.

Parameters:

degrees – Degrees to turn left. If negative, the bot turns right. If positive or negative infinity, the bot turns infinitely in that direction.

set_turn_right(degrees: float) → None[source]

Set the bot to turn right (following the decreasing degrees of the unit circle).

The bot turns until turn_remaining is 0. The amount of degrees to turn each turn is limited by max_turn_rate.

This method is executed when go() is called, making it possible to call other setter methods and run them in parallel in the same turn. If this method is called multiple times, the last call before go() is executed counts.

This method cancels the effect of prior calls to set_turn_left.

Parameters:

degrees – Degrees to turn right. If negative, the bot turns left. If positive or negative infinity, the bot turns infinitely in that direction.

turn_right(degrees: float) → None[source]

Turn the bot right (following the increasing degrees of the unit circle).

The bot turns until turn_remaining is 0. The amount of degrees to turn each turn is limited by max_turn_rate.

This call executes immediately by calling go() internally and blocks until completed, which can take one to several turns. New commands take place after this method completes. To run multiple commands in parallel, use setter methods instead of this blocking method.

This method cancels the effect of prior calls to set_turn_left and set_turn_right.

Parameters:

degrees – Degrees to turn right. If negative, the bot turns left. If positive or negative infinity, the bot turns infinitely in that direction.

property turn_remaining: float

Return the remaining degrees before the current turn is completed.

Positive means turning left along the unit circle; negative means turning right. Positive or negative infinity means infinite turning in that direction.

set_turn_gun_left(degrees: float) → None[source]

Set the gun to turn left (following the increasing degrees of the unit circle).

The gun turns until gun_turn_remaining is 0. The amount of degrees to turn each turn is limited by max_gun_turn_rate.

This method is executed when go() is called, making it possible to call other setter methods and run them in parallel in the same turn. If this method is called multiple times, the last call before go() is executed counts.

This method cancels the effect of prior calls to set_turn_gun_right.

Parameters:

degrees – Degrees to turn left. If negative, the gun turns right. If positive or negative infinity, the gun turns infinitely in that direction.

turn_gun_left(degrees: float) → None[source]

Turn the gun left (following the increasing degrees of the unit circle).

The gun turns until gun_turn_remaining is 0. The amount of degrees to turn each turn is limited by max_gun_turn_rate.

This call executes immediately by calling go() internally and blocks until completed, which can take one to several turns. New commands take place after this method completes. To run multiple commands in parallel, use setter methods instead of this blocking method.

This method cancels the effect of prior calls to set_turn_gun_left and set_turn_gun_right.

Parameters:

degrees – Degrees to turn left. If negative, the gun turns right. If positive or negative infinity, the gun turns infinitely in that direction.

set_turn_gun_right(degrees: float) → None[source]

Set the gun to turn right (following the decreasing degrees of the unit circle).

The gun turns until gun_turn_remaining is 0. The amount of degrees to turn each turn is limited by max_gun_turn_rate.

This method is executed when go() is called, making it possible to call other setter methods and run them in parallel in the same turn. If this method is called multiple times, the last call before go() is executed counts.

This method cancels the effect of prior calls to set_turn_gun_left.

Parameters:

degrees – Degrees to turn right. If negative, the gun turns left. If positive or negative infinity, the gun turns infinitely in that direction.

turn_gun_right(degrees: float) → None[source]

Turn the gun right (following the decreasing degrees of the unit circle).

The gun turns until gun_turn_remaining is 0. The amount of degrees to turn each turn is limited by max_gun_turn_rate.

This call executes immediately by calling go() internally and blocks until completed, which can take one to several turns. New commands take place after this method completes. To run multiple commands in parallel, use setter methods instead of this blocking method.

This method cancels the effect of prior calls to set_turn_gun_left and set_turn_gun_right.

Parameters:

degrees – Degrees to turn right. If negative, the gun turns left. If positive or negative infinity, the gun turns infinitely in that direction.

property gun_turn_remaining: float

Return the remaining degrees before the current gun turn is completed.

Positive means turning left along the unit circle; negative means turning right. Positive or negative infinity means infinite turning in that direction.

set_turn_radar_left(degrees: float) → None[source]

Set the radar to turn left (following the increasing degrees of the unit circle).

The radar turns until radar_turn_remaining is 0. The amount of degrees to turn each turn is limited by max_radar_turn_rate.

This method is executed when go() is called, making it possible to call other setter methods and run them in parallel in the same turn. If this method is called multiple times, the last call before go() is executed counts.

This method cancels the effect of prior calls to set_turn_radar_right.

Parameters:

degrees – Degrees to turn left. If negative, the radar turns right. If positive or negative infinity, the radar turns infinitely in that direction.

turn_radar_left(degrees: float) → None[source]

Turn the radar left (following the increasing degrees of the unit circle).

The radar turns until radar_turn_remaining is 0. The amount of degrees to turn each turn is limited by max_radar_turn_rate.

This call executes immediately by calling go() internally and blocks until completed, which can take one to several turns. New commands take place after this method completes. To run multiple commands in parallel, use setter methods instead of this blocking method.

This method cancels the effect of prior calls to set_turn_radar_left and set_turn_radar_right.

Parameters:

degrees – Degrees to turn left. If negative, the radar turns right. If positive or negative infinity, the radar turns infinitely in that direction.

set_turn_radar_right(degrees: float) → None[source]

Set the radar to turn right (following the decreasing degrees of the unit circle).

The radar turns until radar_turn_remaining is 0. The amount of degrees to turn each turn is limited by max_radar_turn_rate.

This method is executed when go() is called, making it possible to call other setter methods and run them in parallel in the same turn. If this method is called multiple times, the last call before go() is executed counts.

This method cancels the effect of prior calls to set_turn_radar_left.

Parameters:

degrees – Degrees to turn right. If negative, the radar turns left. If positive or negative infinity, the radar turns infinitely in that direction.

turn_radar_right(degrees: float) → None[source]

Turn the radar right (following the increasing degrees of the unit circle).

The radar turns until radar_turn_remaining is 0. The amount of degrees to turn each turn is limited by max_radar_turn_rate.

This call executes immediately by calling go() internally and blocks until completed, which can take one to several turns. New commands take place after this method completes. To run multiple commands in parallel, use setter methods instead of this blocking method.

This method cancels the effect of prior calls to set_turn_radar_left and set_turn_radar_right.

Parameters:

degrees – Degrees to turn right. If negative, the radar turns left. If positive or negative infinity, the radar turns infinitely in that direction.

property radar_turn_remaining: float

Return the remaining degrees before the current radar turn is completed.

Positive means turning left along the unit circle; negative means turning right. Positive or negative infinity means infinite turning in that direction.

fire(firepower: float) → None[source]

Fire the gun in the direction the gun is pointing.

Firing spends energy from the bot. The energy loss equals firepower, and hitting another bot rewards energy equal to 3x firepower. The gun can fire only when firepower is at least MIN_FIREPOWER. If firepower exceeds MAX_FIREPOWER, it is truncated to MAX_FIREPOWER.

The gun heats when firing and must cool down before it can fire again. Gun heat generated by firing is 1 + (firepower / 5). The gun cooling rate is read from gun_cooling_rate.

Damage dealt is 4x firepower, and if firepower > 1, it adds 2 * (firepower - 1).

This call executes immediately by calling go() internally and blocks until completed, which can take one to several turns. New commands take place after this method completes. To run multiple commands in parallel, use setter methods instead of this blocking method.

This method cancels the effect of prior calls to set_fire.

Parameters:

firepower – Energy to spend on firing. Must be at least MIN_FIREPOWER.

MAX_NUMBER_OF_TEAM_MESSAGES_PER_TURN: int = 10

The maximum number of team messages that can be sent per turn, which is 10 messages.

TEAM_MESSAGE_MAX_SIZE: int = 32768

Maximum size of a team message, which is 32 KB.

add_custom_event(condition: Condition) → bool

Adds a custom event based on a condition. When the condition is met, the on_custom_event() handler is triggered with a CustomEvent containing the condition.

Parameters:

condition – The condition that must be met to trigger the custom event.

Returns:

True if the condition was added; False if it already exists.

property adjust_gun_for_body_turn: bool

Returns whether the gun adjusts for the bot’s body turn.

property adjust_radar_for_body_turn: bool

Returns whether the radar adjusts for the bot’s body turn.

property adjust_radar_for_gun_turn: bool

Returns whether the radar adjusts for the gun’s turn.

property arena_height: int

Height of the arena measured in units.

First available when the game has started.

Returns:

The arena height measured in units.

property arena_width: int

Width of the arena measured in units.

First available when the game has started.

Returns:

The arena width measured in units.

bearing_to(x: float, y: float) → float

Calculates the bearing (delta angle) between the bot’s current direction and the direction to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

A bearing to the point (x, y) in the range [-180, 180).

Return type:

float

property body_color: Color | None

Returns the color of the body.

Returns:

The body color or None if not set.

broadcast_team_message(message: Any) → None

Broadcasts a message to all teammates.

Parameters:

message – The message to broadcast.

property bullet_color: Color | None

Returns the color of the bullets.

Returns:

The bullet color or None if not set.

property bullet_states: Sequence[BulletState | None] | None

Current bullet states. Keeps track of all the bullets fired by the bot, which are still active on the arena.

Returns:

The current bullet states.

calc_bearing(direction: float) → float

Calculates the bearing (delta angle) between the input direction and the bot’s direction.

Example

bearing = calc_bearing(direction) = normalize_relative_degrees(direction - self.direction)

Parameters:

direction (float) – The input direction to calculate the bearing from.

Returns:

A normalized bearing (delta angle) in the range [-180, 180).

Return type:

float

See also

direction, normalize_relative_angle.

calc_bullet_speed(firepower: float) → float

Calculates the bullet speed for a given firepower.

Parameters:

firepower – The firepower.

Returns:

The bullet speed.

calc_delta_angle(target_angle: float, source_angle: float) → float

Calculates the difference between two angles, i.e., the number of degrees from a source angle to a target angle.

Parameters:

  • target_angle (float) – The target angle.

  • source_angle (float) – The source angle.

Returns:

The delta angle in the range [-180, 180].

Return type:

float

calc_gun_bearing(direction: float) → float

Calculates the bearing (delta angle) between the input direction and the gun’s direction.

Example

bearing = calc_gun_bearing(direction) =

normalize_relative_degrees(direction - self.gun_direction)

Parameters:

direction (float) – The input direction to calculate the bearing from.

Returns:

A normalized bearing (delta angle) in the range [-180, 180).

Return type:

float

See also

gun_direction, normalize_relative_angle.

calc_gun_heat(firepower: float) → float

Calculates the gun heat generated by firing with a given firepower.

Parameters:

firepower – The firepower.

Returns:

The gun heat generated.

calc_max_turn_rate(speed: float) → float

Calculates the maximum turn rate for a given speed.

Parameters:

speed – The speed.

Returns:

The maximum turn rate at the given speed.

calc_radar_bearing(direction: float) → float

Calculates the bearing (delta angle) between the input direction and the radar’s direction.

Example

bearing = calc_radar_bearing(direction) =

normalize_relative_degrees(direction - self.radar_direction)

Parameters:

direction (float) – The input direction to calculate the bearing from.

Returns:

A normalized bearing (delta angle) in the range [-180, 180).

Return type:

float

See also

radar_direction, normalize_relative_angle.

clear_events() → None

Clears out any pending events in the bot’s event queue immediately.

See also

events

property debugging_enabled: bool

Checks if debugging is enabled for this bot.

Returns:

True if debugging is enabled; False otherwise.

property direction: float

Current driving direction of the bot in degrees.

Returns:

The current driving direction of the bot.

direction_to(x: float, y: float) → float

Calculates the direction (angle) from the bot’s coordinates to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

The direction to the point (x, y) in the range [0, 360).

Return type:

float

property disabled: bool

Specifies if the bot is disabled, i.e., when the energy is zero. When the bot is disabled, it is not able to take any action like movement, turning, and firing.

Returns:

True if the bot is disabled; False otherwise.

distance_to(x: float, y: float) → float

Calculates the distance from the bot’s coordinates to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

The distance to the point (x, y).

Return type:

float

property enemy_count: int

Number of enemies left in the round.

Returns:

The number of enemies left in the round.

property energy: float

Current energy level. When the energy level is positive, the bot is alive and active. When the energy level is 0, the bot is still alive but disabled. If the bot becomes disabled it will not be able to move or take any action. If negative, the bot has been defeated.

Returns:

The current energy level.

property events: Sequence[BotEvent | None] | None

Returns an ordered list containing all events currently in the bot’s event queue. You might, for example, call this while processing another event.

Returns:

An ordered list containing all events currently in the bot’s event queue.

See also

clear_events

property firepower: float

Returns the firepower set for firing the gun.

Returns:

The firepower.

property game_type: str

Game type, e.g. “melee” or “1v1”.

First available when the game has started.

Returns:

The game type.

get_event_priority(event_class: type) → int

Returns the priority of an event class.

Parameters:

event_class – The event class.

Returns:

The priority of the event class.

go() → None

Commits the current commands (actions), which finalizes the current turn for the bot.

This method must be called once per turn to send the bot actions to the server and must be called before the turn timeout occurs. A turn timer is started when the GameStartedEvent and TickEvent occurs. If the go() method is called too late, a turn timeout will occur and the SkippedTurnEvent will occur, which means that the bot has skipped all actions for the last turn. In this case, the server will continue executing the last actions received. This could be fatal for the bot due to loss of control over the bot. So make sure that go() is called before the turn ends.

The commands executed when go() is called are set by calling the various setter methods prior to calling the go() method: turn_rate, gun_turn_rate, radar_turn_rate, target_speed, and set_fire().

See also

turn_timeout

property graphics: GraphicsABC

Returns the graphics context for drawing debug graphics.

Returns:

The graphics context.

gun_bearing_to(x: float, y: float) → float

Calculates the bearing (delta angle) between the gun’s current direction and the direction to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

A bearing to the point (x, y) in the range [-180, 180).

Return type:

float

property gun_color: Color | None

Returns the color of the gun.

Returns:

The gun color or None if not set.

property gun_cooling_rate: float

Gun cooling rate. The gun needs to cool down to a gun heat of zero before the gun can fire. The gun cooling rate determines how fast the gun cools down. That is, the gun cooling rate is subtracted from the gun heat each turn until the gun heat reaches zero.

First available when the game has started.

Returns:

The gun cooling rate.

See also

gun_heat

property gun_direction: float

Current direction of the gun in degrees.

Returns:

The current gun direction of the bot.

property gun_heat: float

Current gun heat. When the gun is fired it gets heated and will not be able to fire before it has been cooled down. The gun is cooled down when the gun heat is zero.

When the gun has fired the gun heat is set to 1 + (firepower / 5) and will be cooled down by the gun cooling rate.

Returns:

The current gun heat.

See also

gun_cooling_rate

is_teammate(bot_id: int) → bool

Checks if the specified bot ID is a teammate.

Parameters:

bot_id – The bot ID to check.

Returns:

True if the bot is a teammate; False otherwise.

property max_gun_turn_rate: float

Returns the maximum gun turn rate in degrees per turn.

Returns:

The maximum gun turn rate.

property max_inactivity_turns: int

The maximum number of inactive turns allowed the bot will become zapped by the game for being inactive. Inactive means that the bot has taken no action in several turns in a row.

First available when the game has started.

Returns:

The maximum number of allowed inactive turns.

property max_radar_turn_rate: float

Returns the maximum radar turn rate in degrees per turn.

Returns:

The maximum radar turn rate.

property max_speed: float

Returns the maximum speed in units per turn.

Returns:

The maximum speed.

property max_turn_rate: float

Returns the maximum turn rate of the bot in degrees per turn.

Returns:

The maximum turn rate of the bot.

property my_id: int

Unique id of this bot, which is available when the game has started.

Returns:

The unique id of this bot.

normalize_absolute_angle(angle: float) → float

Normalizes an angle to an absolute angle in the range [0, 360).

Parameters:

angle (float) – The angle to normalize.

Returns:

The normalized absolute angle.

Return type:

float

normalize_relative_angle(angle: float) → float

Normalizes the given angle to the range [-180, 180] degrees.

Parameters:

angle (float) – The angle to normalize.

Returns:

The normalized angle in degrees.

Return type:

float

property number_of_rounds: int

The number of rounds in a battle.

First available when the game has started.

Returns:

The number of rounds in a battle.

on_bot_death(bot_death_event: BotDeathEvent) → None

The event handler triggered when another bot has died.

Parameters:

bot_death_event – The event details from the game.

on_bullet_fired(bullet_fired_event: BulletFiredEvent) → None

The event handler triggered when the bot has fired a bullet.

Parameters:

bullet_fired_event – The event details from the game.

on_bullet_hit(bullet_hit_bot_event: BulletHitBotEvent) → None

The event handler triggered when the bot has hit another bot with a bullet.

Parameters:

bullet_hit_bot_event – The event details from the game.

on_bullet_hit_bullet(bullet_hit_bullet_event: BulletHitBulletEvent) → None

The event handler triggered when a bullet fired from the bot has collided with another bullet.

Parameters:

bullet_hit_bullet_event – The event details from the game.

on_bullet_hit_wall(bullet_hit_wall_event: BulletHitWallEvent) → None

The event handler triggered when a bullet has hit a wall.

Parameters:

bullet_hit_wall_event – The event details from the game.

static on_connected(connected_event: ConnectedEvent) → None

The event handler triggered when connected to the server.

Parameters:

connected_event – The event details from the game.

static on_connection_error(connection_error_event: ConnectionErrorEvent) → None

The event handler triggered when a connection error occurs.

Parameters:

connection_error_event – The event details from the game.

on_custom_event(custom_event: CustomEvent) → None

The event handler triggered when some condition has been met. Use the name of the condition when you need to differentiate between different types of conditions received with this event handler.

Parameters:

custom_event – The event details from the game.

on_death(death_event: DeathEvent) → None

The event handler triggered when this bot has died.

Parameters:

death_event – The event details from the game.

static on_disconnected(disconnected_event: DisconnectedEvent) → None

The event handler triggered when disconnected from the server.

Parameters:

disconnected_event – The event details from the game.

on_game_ended(game_ended_event: GameEndedEvent) → None

The event handler triggered when a game has ended.

Parameters:

game_ended_event – The event details from the game.

on_game_started(game_started_event: GameStartedEvent) → None

The event handler triggered when a game has started.

Parameters:

game_started_event – The event details from the game.

on_hit_bot(bot_hit_bot_event: HitBotEvent) → None

The event handler triggered when the bot has collided with another bot.

Parameters:

bot_hit_bot_event – The event details from the game.

on_hit_by_bullet(hit_by_bullet_event: HitByBulletEvent) → None

The event handler triggered when the bot has been hit by a bullet.

Parameters:

hit_by_bullet_event – The event details from the game.

on_hit_wall(bot_hit_wall_event: HitWallEvent) → None

The event handler triggered when the bot has hit a wall.

Parameters:

bot_hit_wall_event – The event details from the game.

on_round_ended(round_ended_event: RoundEndedEvent) → None

The event handler triggered when a round has ended.

Parameters:

round_ended_event – The event details from the game.

on_round_started(round_started_event: RoundStartedEvent) → None

The event handler triggered when a new round has started.

Parameters:

round_started_event – The event details from the game.

on_scanned_bot(scanned_bot_event: ScannedBotEvent) → None

The event handler triggered when the bot has skipped a turn. This event occurs if the bot did not take any action in a specific turn. That is, go() was not called before the turn timeout occurred for the turn. If the bot does not take action for multiple turns in a row, it will receive a SkippedTurnEvent for each turn where it did not take action. When the bot is skipping a turn, the server did not receive the message from the bot, and the server will use the newest received instructions for target speed, turn rates, firing, etc.

Parameters:

scanned_bot_event – The event details from the game.

on_skipped_turn(skipped_turn_event: SkippedTurnEvent) → None

Handles the event triggered when the bot skips a turn.

A turn is skipped if the bot does not send any instructions to the server (via the go() method) before the turn timeout occurs. When this happens, the server continues using the last received set of actions, such as movement, turning rates, or firing commands.

Reasons for skipped turns may include:

  • Excessive processing or delays in the bot’s logic, leading to a timeout.

  • Failure to invoke the go() method in the current turn.

  • Misaligned or unintended logic in the bot’s turn-handling code.

This method can be overridden to define custom behavior for handling skipped turns, such as logging the event, debugging performance issues, or modifying the bot’s logic to avoid future skips.

Parameters:

skipped_turn_event – An event containing details about the skipped turn.

on_team_message(team_message_event: TeamMessageEvent) → None

The event handler triggered when the bot has received a message from a teammate.

Parameters:

team_message_event – The event details from the game.

on_tick(tick_event: TickEvent) → None

The event handler triggered when a game tick event occurs, i.e., when a new turn in a round has started.

Parameters:

tick_event – The event details from the game.

on_won_round(won_round_event: WonRoundEvent) → None

The event handler triggered when the bot has won a round.

Parameters:

won_round_event – The event details from the game.

radar_bearing_to(x: float, y: float) → float

Calculates the bearing (delta angle) between the radar’s current direction and the direction to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

A bearing to the point (x, y) in the range [-180, 180).

Return type:

float

property radar_color: Color | None

Returns the color of the radar.

Returns:

The radar color or None if not set.

property radar_direction: float

Current direction of the radar in degrees.

Returns:

The current radar direction of the bot.

remove_custom_event(condition: Condition) → bool

Removes a custom event that was previously added with add_custom_event().

Parameters:

condition – The condition to remove.

Returns:

True if the condition was removed; False if it was not found.

property round_number: int

Current round number.

Returns:

The current round number.

property scan_color: Color | None

Returns the color of the scan arc.

Returns:

The scan color or None if not set.

send_team_message(teammate_id: int, message: Any) → None

Sends a message to a specific teammate.

Parameters:

  • teammate_id – The ID of the teammate to send the message to.

  • message – The message to send.

set_event_priority(event_class: type, priority: int) → None

Sets the priority of an event class.

Parameters:

  • event_class – The event class.

  • priority – The new priority.

set_fire(firepower: float) → bool

Sets the gun to fire in the direction the gun is pointing with the specified firepower.

Parameters:

firepower – The firepower to use for firing.

Returns:

True if the gun will fire; False otherwise.

set_fire_assist(enable: bool) → None

Enables or disables fire assistance.

Parameters:

enable – True to enable fire assist; False to disable.

set_interruptible(interruptible: bool) → None

Sets whether the bot’s event handlers are interruptible.

When set to True, the bot’s event handlers can be interrupted by higher-priority events. When set to False, event handlers will run to completion before other events are processed.

Parameters:

interruptible (bool) – If True, event handlers are interruptible; otherwise, they are not.

set_rescan() → None

Sets the radar to rescan with the radar.

set_resume() → None

Sets the bot to resume the movement prior to calling set_stop() or stop().

set_stop(overwrite: bool = False) → None

Sets the bot to stop all movement including turning the gun and radar. The remaining movement is saved for a call to set_resume() or resume().

Parameters:

overwrite – True to override a previously saved movement from stop() or set_stop().

property speed: float

The current speed measured in units per turn. If the speed is positive, the bot moves forward. If negative, the bot moves backward. Zero speed means that the bot is not moving from its current position.

Returns:

The current speed.

start() → None

The method used to start running the bot. You should call this method from the main method or similar.

Example

if __name__ == “__main__”:

# create my_bot … my_bot.start()

stop(overwrite: bool = False) → None[source]

Stop all movement including turning the gun and radar.

Remaining movement is saved for a call to set_resume or resume. This call executes immediately by calling go() internally and blocks until completed, which can take one to several turns. New commands take place after this method completes.

Parameters:

overwrite – True to override a previously saved movement from stop or set_stop. If False, this method is identical to set_stop.

property stopped: bool

Checks if the bot is currently stopped.

Returns:

True if the bot is stopped; False otherwise.

property teammate_ids: set[int]

Returns the IDs of all teammates.

Returns:

A set of teammate IDs.

property time_left: int

The number of microseconds left of this turn before the bot will skip the turn. Make sure to call go() before the time runs out.

Returns:

The amount of time left in microseconds.

See also

turn_timeout, go

property tracks_color: Color | None

Returns the color of the tracks.

Returns:

The tracks color or None if not set.

property turn_number: int

Current turn number.

Returns:

The current turn number.

property turn_timeout: int

The turn timeout is important as the bot needs to take action by calling go() before the turn timeout occurs. As soon as the TickEvent is triggered, i.e. when on_tick() is called, you need to call go() to take action before the turn timeout occurs. Otherwise, your bot will skip a turn and receive a on_skipped_turn() for each turn where go() is called too late.

First available when the game has started.

Returns:

The turn timeout in microseconds (1 / 1,000,000 second).

See also

time_left, go

property turret_color: Color | None

Returns the color of the turret.

Returns:

The turret color or None if not set.

property variant: str

The game variant, which is “Tank Royale”.

Returns:

The game variant of Robocode.

property version: str

Game version, e.g. “1.0.0”.

Returns:

The game version.

property x: float

Current X coordinate of the center of the bot.

Returns:

The current X coordinate of the bot.

property y: float

Current Y coordinate of the center of the bot.

Returns:

The current Y coordinate of the bot.

resume() → None[source]

Resume the movement prior to calling set_stop or stop.

This call executes immediately by calling go() internally and blocks until completed, which can take one to several turns. New commands take place after this method completes.

rescan() → None[source]

Scan again with the radar.

This is useful when the radar is not turning and cannot automatically scan bots, e.g. after stop has been called. The last radar direction and sweep angle are used for rescanning.

wait_for(condition: Callable[[], bool]) → None[source]

Block until a condition is met (condition returns True).

Parameters:

condition – Callable that returns True when the condition is met.

class BotABC[source]

Bases: BaseBotABC

Interface for a bot that extends the core API with convenient methods for movement, turning, and firing the gun.

run() → None[source]

The run() method is used for running a program for the bot like:

Example

def run(self):
while self.is_running():

self.forward(100) self.turn_gun_left(360) self.back(100) self.turn_gun_right(360)

Notes

  • Note that the program runs in a loop in this example (as long as the bot is running), meaning that it will start moving forward as soon as turn_gun_right has executed.

  • When running a loop that could potentially run forever, the best practice is to check if the bot is still running to stop and exit the loop. This gives the game a chance of stopping the thread running the loop in the code behind. If the thread is not stopped correctly, the bot may behave strangely in new rounds.

References

  • running

abstract property running: bool

Checks if this bot is running.

Returns:

True when the bot is running, False otherwise.

Return type:

bool

abstractmethod set_forward(distance: float) → None[source]

Sets the bot to move forward until it has traveled a specific distance from its current position or reached an obstacle.

The movement speed is limited by set_max_speed.

Acceleration/Deceleration:
  • The bot’s acceleration and deceleration are controlled by constants:

    • Constants.ACCELERATION: Adds 1 unit to the speed per turn while accelerating.

    • Constants.DECELERATION: Subtracts 2 units from speed per turn while decelerating.

Behavior:

  • The method is executed when go() is called, allowing you to combine other methods (e.g., turning, firing) to occur in parallel in a single turn.

  • For multiple calls to this method, the most recent call before go() is executed.

  • Cancels the effect of prior calls to set_target_speed, as this method adjusts the target speed for each turn until distance_remaining is 0.

Parameters:

distance (float) – Distance to move forward. - If negative, the bot will move backward. - If float(‘inf’), the bot will move forward infinitely. - If float(‘-inf’), the bot will move backward infinitely.

References

  • forward, set_back, back, distance_remaining, set_target_speed

abstractmethod forward(distance: float) → None[source]

Moves the bot forward until it has traveled a specific distance or reached an obstacle.

The movement speed is limited by set_max_speed.

Acceleration/Deceleration:
  • The bot’s acceleration and deceleration are controlled by constants:

    • Constants.ACCELERATION: Adds 1 unit to the speed per turn while accelerating.

    • Constants.DECELERATION: Subtracts 2 units from speed per turn while decelerating.

Behavior:

  • This method executes immediately by internally calling go() and blocks execution until the movement is complete. Subsequent commands will execute only after this. Use setter methods if parallel execution is needed.

  • Cancels the effect of previous calls to set_target_speed, set_forward, and set_back.

Parameters:

distance (float) – Distance to move forward. - If negative, the bot will move backward. - If float(‘inf’), the bot will move forward infinitely. - If float(‘-inf’), the bot will move backward infinitely.

References

  • set_forward, set_back, back, distance_remaining, set_target_speed

abstractmethod set_back(distance: float) → None[source]

Sets the bot to move backward until it has traveled a specific distance from its current position or reached an obstacle.

The movement speed is limited by set_max_speed.

Acceleration/Deceleration:
  • The bot’s acceleration and deceleration are controlled by constants:

    • Constants.ACCELERATION: Adds 1 unit to the speed per turn while accelerating.

    • Constants.DECELERATION: Subtracts 2 units from speed per turn while decelerating.

Behavior:

  • The method is executed when go() is called, allowing you to combine other methods (e.g., turning, firing) to occur in parallel in a single turn.

  • For multiple calls to this method, the most recent call before go() is executed.

  • Cancels the effect of prior calls to set_target_speed, as this method adjusts the target speed for each turn until distance_remaining is 0.

Parameters:

distance (float) – Distance to move backward. - If negative, the bot will move forward. - If float(‘inf’), the bot will move backward infinitely. - If float(‘-inf’), the bot will move forward infinitely.

References

  • back, set_forward, forward, distance_remaining, set_target_speed

abstractmethod back(distance: float) → None[source]

Moves the bot backward until it has traveled a specific distance from its current position, or it is moving into an obstacle. The speed is limited by setMaxSpeed.

When the bot is moving forward, the Constants.ACCELERATION determines the acceleration of the bot that adds 1 additional unit to the speed per turn while accelerating. However, the bot is faster at braking. The Constants.DECELERATION determines the deceleration of the bot that subtracts 2 units from the speed per turn.

This call is executed immediately by calling go in the code behind. This method will block until it has been completed, which can take one to several turns. New commands will first take place after this method is completed. If you need to execute multiple commands in parallel, use setter methods instead of this blocking method.

This method will cancel the effect of prior calls to setTargetSpeed, setForward, and setBack methods.

Parameters:

distance (float) – The distance to move backward. If negative, the bot will move forward. If float(‘inf’), the bot will move backward infinitely. If float(‘-inf’), the bot will move forward infinitely.

See also

setForward: Method to set the bot to move forward. setBack: Method to set the bot to move backward. forward: Method to immediately move the bot forward. getDistanceRemaining: Method to get the remaining travel distance. setTargetSpeed: Method to set the target speed of the bot.

property distance_remaining: float

Returns the distance remaining until the bot has finished moving after calling set_forward, set_back, forward, or back. When the distance remaining reaches 0, the bot has finished its current movement.

When the distance remaining is positive, the bot is moving forward. When the distance remaining is negative, the bot is moving backward.

Returns:

The remaining distance to move before the current movement is completed.

  • If float(‘inf’), the bot will move forward infinitely.

  • If float(‘-inf’), the bot will move backward infinitely.

Return type:

float

See also

set_forward, set_back, forward, back

set_turn_left(degrees: float) → None[source]

Set the bot to turn to the left (following the increasing degrees of the unit circle) until it has turned the specified amount of degrees. This completes when turn_remaining returns 0. The amount of degrees to turn each turn is limited by set_max_turn_rate().

This method will first be executed when go() is called, making it possible to call other set methods after execution. This allows the bot to move, turn the body, radar, gun, and fire the gun in parallel during a single turn when go() is called. Note that executing multiple methods in parallel is only possible by using setter methods prior to calling go().

If this method is called multiple times, only the last call before go() is executed is honored.

This method cancels the effect of prior calls to set_turn_right().

Parameters:

degrees (float) – The amount of degrees to turn left. If negative, the bot will turn right. If float(‘inf’), the bot will turn left infinitely. If float(‘-inf’), the bot will turn right infinitely.

See:

  • unit circle

  • set_turn_right

  • turn_right

  • turn_left

  • turn_remaining

  • set_turn_rate

turn_left(degrees: float) → None[source]

Turn the bot to the left (following the increasing degrees of the unit circle) until it has turned the specified amount of degrees. That is, when turn_remaining is 0. The amount of degrees to turn each turn is limited by set_max_turn_rate().

This call is executed immediately by invoking go() in the code behind. This method will block until it has been completed, which can take one to several turns. New commands will first take place after this method is completed.

If you need to execute multiple commands in parallel, use setter methods instead of this blocking method.

This method will cancel the effect of prior calls to set_turn_left() and set_turn_right().

Parameters:

degrees (float) – The amount of degrees to turn left. - If negative, the bot will turn right. - If float(‘inf’), the bot will turn left infinitely. - If float(‘-inf’), the bot will turn right infinitely.

See also

  • Unit circle

  • set_turn_left()

  • set_turn_right()

  • turn_right()

  • turn_remaining

  • set_turn_rate()

set_turn_right(degrees: float) → None[source]

Set the bot to turn to the right (following the decreasing degrees of the unit circle) until it turned the specified amount of degrees. That is, when turn_remaining returns 0. The amount of degrees to turn each turn is limited by set_max_turn_rate().

This method will first be executed when go() is called, making it possible to call other set methods after execution. This makes it possible to set the bot to move, turn the body, radar, gun, and fire the gun in parallel in a single turn when calling go(). But notice that this is only possible to execute multiple methods in parallel by using setter methods only prior to calling go().

If this method is called multiple times, the last call before go() is executed counts.

This method will cancel the effect of prior calls to set_turn_left().

Parameters:

degrees (float) – The amount of degrees to turn right. If negative, the bot will turn left. If float(‘inf’), the bot will turn right infinitely. If float(‘-inf’), the bot will turn left infinitely.

See also

set_turn_left turn_right turn_left turn_remaining set_turn_rate

turn_right(degrees: float) → None[source]

Turn the bot to the right (following the increasing degrees of the unit circle) until it turned the specified amount of degrees. That is, when turn_remaining returns 0. The amount of degrees to turn each turn is limited by set_max_turn_rate().

This call is executed immediately, and it will block until it has been completed, which can take one to several turns. New commands will first take place after this method is completed. If you need to execute multiple commands in parallel, use setter methods instead of this blocking method.

This method will cancel the effect of prior calls to set_turn_left() and set_turn_right().

Parameters:

degrees (float) – The amount of degrees to turn right. If negative, the bot will turn left. If float(‘inf’), the bot will turn right infinitely. If float(‘-inf’), the bot will turn left infinitely.

See also

Unit circle set_turn_left set_turn_right turn_left turn_remaining set_turn_rate

property turn_remaining: float

Returns the remaining turn in degrees until the bot has finished turning after having called set_turn_left(), set_turn_right(), turn_left(), or turn_right(). When the turn remaining has reached 0, the bot has finished turning.

When the turn remaining is positive, the bot is turning to the left (along the unit circle). When the turn remaining is negative, the bot is turning to the right.

Returns:

The remaining degrees to turn before its current turning is completed. If float(‘inf’), the bot will turn left infinitely. If float(‘-inf’), the bot will turn right infinitely.

Return type:

float

See also

set_turn_left set_turn_right turn_left turn_right

set_turn_gun_left(degrees: float) → None[source]

Set the gun to turn to the left (following the increasing degrees of the unit circle) until it turned the specified amount of degrees. That is, when gun_turn_remaining returns 0. The amount of degrees to turn each turn is limited by set_max_gun_turn_rate().

This method will first be executed when go() is called, making it possible to call other set methods after execution. This makes it possible to set the bot to move, turn the body, radar, gun, and fire the gun in parallel in a single turn when calling go(). But notice that this is only possible to execute multiple methods in parallel by using setter methods only prior to calling go().

If this method is called multiple times, the last call before go() is executed counts.

This method will cancel the effect of prior calls to set_turn_gun_right().

Parameters:

degrees (float) – The amount of degrees to turn left. If negative, the gun will turn right. If float(‘inf’), the gun will turn left infinitely. If float(‘-inf’), the gun will turn right infinitely.

See also

Unit circle set_turn_gun_right turn_gun_right turn_gun_left gun_turn_remaining set_gun_turn_rate

turn_gun_left(degrees: float) → None[source]

Rotates the gun to the left (increasing degrees of the unit circle) until it has turned the specified number of degrees.

This method is executed immediately and will block until the action is completed, which might take several turns. During this time, new commands will not take effect. To execute multiple commands in parallel, use the corresponding “set” methods instead of this blocking method.

The turn rate per tick is limited by set_max_gun_turn_rate.

If called, this method cancels any prior calls to set_turn_gun_left or set_turn_gun_right.

Parameters:

degrees (float) – The number of degrees to turn the gun left. - If negative, the gun will turn right. - If float(‘inf’), the gun will turn left indefinitely. - If float(‘-inf’), the gun will turn right indefinitely.

set_turn_gun_right(degrees: float) → None[source]

Schedules the gun to turn to the right (decreasing degrees of the unit circle) until it has turned the specified number of degrees.

This method will execute when go() is called, allowing you to chain multiple commands such as moving, turning, and firing together for simultaneous execution in a single turn.

The turn rate per tick is limited by set_max_gun_turn_rate.

If this method is called multiple times before go(), only the last call will be executed. It also cancels any prior calls to set_turn_gun_left.

Parameters:

degrees (float) – The number of degrees to turn the gun right. - If negative, the gun will turn left. - If float(‘inf’), the gun will turn right indefinitely. - If float(‘-inf’), the gun will turn left indefinitely.

turn_gun_right(degrees: float) → None[source]

Rotates the gun to the right (decreasing degrees of the unit circle) until it has turned the specified number of degrees.

This method is executed immediately and will block until the action is completed, which might take several turns. During this time, new commands will not take effect. To execute multiple commands in parallel, use the corresponding “set” methods instead of this blocking method.

The turn rate per tick is limited by set_max_gun_turn_rate.

If called, this method cancels any prior calls to set_turn_gun_left or set_turn_gun_right.

Parameters:

degrees (float) – The number of degrees to turn the gun right. - If negative, the gun will turn left. - If float(‘inf’), the gun will turn right indefinitely. - If float(‘-inf’), the gun will turn left indefinitely.

property gun_turn_remaining: float

Gets the remaining turn angle in degrees for the gun to finish its current turning action.

Positive values indicate the gun is turning left (increasing degrees of the unit circle), while negative values indicate it is turning right (decreasing degrees of the unit circle).

Returns:

The remaining degrees for the gun to complete the turn.

  • If float(‘inf’), the gun is turning left indefinitely.

  • If float(‘-inf’), the gun is turning right indefinitely.

Return type:

float

set_turn_radar_left(degrees: float) → None[source]

Schedules the radar to turn to the left (increasing degrees of the unit circle) until it has turned the specified number of degrees.

This method will execute when go() is called, allowing you to chain multiple commands such as moving, turning, and scanning together for simultaneous execution in a single turn.

The turn rate per tick is limited by set_max_radar_turn_rate.

If this method is called multiple times before go(), only the last call will be executed. It also cancels any prior calls to set_turn_radar_right.

Parameters:

degrees (float) – The number of degrees to turn the radar left. - If negative, the radar will turn right. - If float(‘inf’), the radar will turn left indefinitely. - If float(‘-inf’), the radar will turn right indefinitely.

turn_radar_left(degrees: float | int) → None[source]

Turn the radar to the left (following the increasing degrees of the unit circle) until it has turned the specified amount of degrees. This method will block until completed.

Parameters:

degrees (Union[float, int]) – The amount of degrees to turn left. If negative, the radar will turn right. If positive infinity, the radar will turn left infinitely. If negative infinity, the radar will turn right infinitely.

Notes

  • The amount of degrees to turn per turn is limited by the maximum radar turn rate.

  • New commands will only be processed after this call completes.

  • This will cancel any prior calls to set_turn_radar_left() or set_turn_radar_right().

set_turn_radar_right(degrees: float | int) → None[source]

Set the radar to turn right (following the decreasing degrees of the unit circle) until it has turned the specified amount of degrees. This method does not block but will execute when go() is called.

Parameters:

degrees (Union[float, int]) – The amount of degrees to turn right. If negative, the radar will turn left. If positive infinity, the radar will turn right infinitely. If negative infinity, the radar will turn left infinitely.

Notes

  • The amount of degrees turned per turn is limited by the maximum radar turn rate.

  • The last call to this method before go() is executed will override any previous ones.

  • This cancels prior calls to set_turn_radar_left() and itself.

turn_radar_right(degrees: float | int) → None[source]

Turn the radar to the right (following the increasing degrees of the unit circle) until it has turned the specified amount of degrees. This method will block until completed.

Parameters:

degrees (Union[float, int]) – The amount of degrees to turn right. If negative, the radar will turn left. If positive infinity, the radar will turn right infinitely. If negative infinity, the radar will turn left infinitely.

Notes

  • The amount of degrees to turn per turn is limited by the maximum radar turn rate.

  • New commands will only be processed after this call completes.

  • This will cancel any prior calls to set_turn_radar_left() or set_turn_radar_right().

property radar_turn_remaining: float

Get the remaining turn in degrees until the radar has finished its current turn.

Returns:

The remaining degrees to turn the radar. Positive values indicate the radar is turning left (along the unit circle), and negative values indicate it is turning right. If positive infinity, the radar will turn left infinitely. If negative infinity, the radar will turn right infinitely.

Return type:

float

Notes

  • This applies to the current turn initiated by methods like set_turn_radar_left(), set_turn_radar_right(), turn_radar_left(), or turn_radar_right().

fire(firepower: float) → None[source]

Fires the gun in the direction the gun is pointing.

Note

  • Firing the gun spends energy. The energy loss is equal to the firepower used.

  • If the bullet hits an opponent bot, the bot gains energy from the bullet hit. Specifically, the bot is rewarded with an energy boost of 3 times the firepower.

Rules:

  • The gun will only fire if the firepower is at or above the minimum (Constants.MIN_FIREPOWER).

  • If the firepower exceeds the maximum (Constants.MAX_FIREPOWER), it is truncated to the maximum allowed value.

Gun Heat:

  • The gun heats up whenever it is fired and must cool down to zero heat before it can fire again.

  • The heat generated is calculated as 1 + (firepower / 5), meaning higher firepower increases cooling time.

  • The gun’s cooling rate can be retrieved via get_gun_cooling_rate().

Energy Usage and Damage:

  • The energy used for firing is subtracted from the bot’s total energy.

  • Damage dealt by the bullet is 4 * firepower. Additionally, if firepower exceeds 1, extra damage is calculated as 2 * (firepower - 1).

Execution:

  • This method is executed immediately and blocks until completion, taking one or several turns.

  • New commands will only take effect after the completion of this method.

  • For executing multiple commands in parallel, it is recommended to use setter methods instead of this blocking method.

Side Effects:

  • Cancels prior calls to set_fire.

Parameters:

firepower (float) – The amount of energy spent on firing the gun. - Must be greater than Constants.MIN_FIREPOWER. - Cannot exceed the energy available to the bot.

See also

  • on_bullet_fired()

  • set_fire()

  • get_gun_heat()

  • get_gun_cooling_rate()

abstractmethod stop(overwrite: bool = False) → None[source]

Immediately stops all motion, including the robot’s movement, gun rotation, and radar movement. Any remaining movement is preserved for future execution via set_resume or resume.

This is a blocking call and will only return after the stop operation is completed. New commands will take effect after this method finishes. To perform multiple commands concurrently, use the non-blocking setter methods.

Parameters:

overwrite (bool) – If True, overwrites previously saved movement data from a prior call to stop_with_overwrite or set_stop. If False, behaves equivalently to stop_with_overwrite(False).

abstractmethod resume() → None[source]

Resume the movement prior to calling the set_stop or stop method. This method has no effect if it has already been called.

This call is executed immediately and blocks until completed. New commands will take effect only after this method is completed. To execute multiple commands in parallel, use non-blocking setter methods.

abstractmethod rescan() → None[source]

Scan again with the radar. This method is useful if the radar has not been turning and is unable to scan bots automatically.

The last radar direction and sweep angle will be used for rescanning for bots.

abstractmethod wait_for(condition: Callable[[], bool]) → None[source]

Blocks until a condition is met, i.e., when Condition.test() returns True.

Parameters:

condition – The condition to be met before this method stops waiting.

MAX_NUMBER_OF_TEAM_MESSAGES_PER_TURN: int = 10

The maximum number of team messages that can be sent per turn, which is 10 messages.

TEAM_MESSAGE_MAX_SIZE: int = 32768

Maximum size of a team message, which is 32 KB.

abstract property adjust_gun_for_body_turn: bool

Returns whether the gun adjusts for the bot’s body turn.

Returns:

True if the gun adjusts for body turn; False otherwise.

Return type:

bool

abstract property adjust_radar_for_body_turn: bool

Returns whether the radar adjusts for the bot’s body turn.

Returns:

True if the radar adjusts for body turn; False otherwise.

Return type:

bool

abstract property adjust_radar_for_gun_turn: bool

Returns whether the radar adjusts for the gun’s turn.

Returns:

True if the radar adjusts for gun turn; False otherwise.

Return type:

bool

abstract property arena_height: int

Height of the arena measured in units.

First available when the game has started.

Returns:

The arena height measured in units

Return type:

int

abstract property arena_width: int

Width of the arena measured in units.

First available when the game has started.

Returns:

The arena width measured in units

Return type:

int

bearing_to(x: float, y: float) → float

Calculates the bearing (delta angle) between the bot’s current direction and the direction to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

A bearing to the point (x, y) in the range [-180, 180).

Return type:

float

abstract property body_color: Color | None

Returns the color of the body.

Returns:

The color of the body, or None if no color has been set yet.

In that case, the default color will be used.

Return type:

Color

abstractmethod broadcast_team_message(message: Any) → None

Broadcasts a message to all teammates.

When the message is sent, it is serialized into a JSON representation. This means that all public fields, and only public fields, are serialized into a JSON representation as a data transfer object (DTO).

The maximum team message size limit is defined by TEAM_MESSAGE_MAX_SIZE, which is set to 32,768 bytes. This size is calculated after serializing the message into a JSON representation.

The maximum number of messages that can be broadcast per turn is limited to MAX_NUMBER_OF_TEAM_MESSAGES_PER_TURN, which is set to 10.

Parameters:

message – The message to broadcast.

Raises:

ValueError – If the size of the message exceeds the size limit.

See also

send_team_message: Method to send a message to teammates. get_teammate_ids: Method to retrieve IDs of all teammates.

abstract property bullet_color: Color | None

Returns the color of the fired bullets.

Returns:

The color of the bullets, or None if no color has been set yet, meaning that the default color will be used.

Return type:

Color

abstract property bullet_states: Sequence[BulletState | None] | None

Current bullet states.

Keeps track of all the bullets fired by the bot, which are still active on the arena.

Returns:

The current bullet states.

Return type:

list[BulletState]

calc_bearing(direction: float) → float

Calculates the bearing (delta angle) between the input direction and the bot’s direction.

Example

bearing = calc_bearing(direction) = normalize_relative_degrees(direction - self.direction)

Parameters:

direction (float) – The input direction to calculate the bearing from.

Returns:

A normalized bearing (delta angle) in the range [-180, 180).

Return type:

float

See also

direction, normalize_relative_angle.

abstractmethod calc_bullet_speed(firepower: float) → float

Calculates the bullet speed given a firepower.

Parameters:

firepower (float) – The firepower.

Returns:

The bullet speed determined by the given firepower.

Return type:

float

calc_delta_angle(target_angle: float, source_angle: float) → float

Calculates the difference between two angles, i.e., the number of degrees from a source angle to a target angle.

Parameters:

  • target_angle (float) – The target angle.

  • source_angle (float) – The source angle.

Returns:

The delta angle in the range [-180, 180].

Return type:

float

calc_gun_bearing(direction: float) → float

Calculates the bearing (delta angle) between the input direction and the gun’s direction.

Example

bearing = calc_gun_bearing(direction) =

normalize_relative_degrees(direction - self.gun_direction)

Parameters:

direction (float) – The input direction to calculate the bearing from.

Returns:

A normalized bearing (delta angle) in the range [-180, 180).

Return type:

float

See also

gun_direction, normalize_relative_angle.

abstractmethod calc_gun_heat(firepower: float) → float

Calculates gun heat after having fired the gun.

Parameters:

firepower (float) – The firepower used when firing the gun.

Returns:

The gun heat produced when firing the gun with the given firepower.

Return type:

float

abstractmethod calc_max_turn_rate(speed: float) → float

Calculates the maximum turn rate for a specific speed.

Parameters:

speed (float) – The speed.

Returns:

The maximum turn rate determined by the given speed.

Return type:

float

calc_radar_bearing(direction: float) → float

Calculates the bearing (delta angle) between the input direction and the radar’s direction.

Example

bearing = calc_radar_bearing(direction) =

normalize_relative_degrees(direction - self.radar_direction)

Parameters:

direction (float) – The input direction to calculate the bearing from.

Returns:

A normalized bearing (delta angle) in the range [-180, 180).

Return type:

float

See also

radar_direction, normalize_relative_angle.

abstractmethod clear_events() → None

Clears out any pending events in the bot’s event queue immediately.

abstract property debugging_enabled: bool

Indicates whether graphical debugging is enabled. If enabled, the graphics property can be used for debug painting.

Returns:

True if graphical debugging is enabled, False otherwise.

Return type:

bool

abstract property direction: float

Current driving direction of the bot in degrees.

Returns:

The current driving direction of the bot.

Return type:

float

direction_to(x: float, y: float) → float

Calculates the direction (angle) from the bot’s coordinates to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

The direction to the point (x, y) in the range [0, 360).

Return type:

float

abstract property disabled: bool

Specifies if the bot is disabled, i.e., when the energy is zero.

When the bot is disabled, it is not able to take any action like movement, turning, and firing.

Returns:

True if the bot is disabled; False otherwise.

Return type:

bool

distance_to(x: float, y: float) → float

Calculates the distance from the bot’s coordinates to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

The distance to the point (x, y).

Return type:

float

abstract property enemy_count: int

Number of enemies left in the round.

Returns:

The number of enemies left in the round.

Return type:

int

abstract property energy: float

Current energy level.

When the energy level is positive, the bot is alive and active. When the energy level is 0, the bot is still alive but disabled. If the bot becomes disabled it will not be able to move or take any action. If negative, the bot has been defeated.

Returns:

The current energy level.

Return type:

float

abstract property events: Sequence[BotEvent | None] | None

Returns an ordered list containing all events currently in the bot’s event queue.

You might, for example, call this while processing another event.

Returns:

An ordered list containing all events currently in the bot’s event queue.

Return type:

list[BotEvent]

abstract property firepower: float

Returns the firepower.

Returns:

The firepower.

Return type:

float

abstract property game_type: str

Game type, e.g. “melee” or “1v1”.

First available when the game has started.

Returns:

The game type.

Return type:

str

abstractmethod get_event_priority(event_class: type) → int

Returns the event priority for a specific event class.

Example

scanned_bot_event_priority = get_priority(ScannedBotEvent)

Parameters:

event_class – The event class to get the event priority for.

Returns:

The event priority for a specific event class.

Return type:

int

See also

DefaultEventPriority set_event_priority

abstractmethod go() → None

Commits the current commands (actions), which finalizes the current turn for the bot.

This method must be called once per turn to send the bot actions to the server and must be called before the turn timeout occurs. A turn timer is started when the GameStartedEvent and TickEvent occurs. If the go() method is called too late, a turn timeout will occur and the SkippedTurnEvent will occur, which means that the bot has skipped all actions for the last turn. In this case, the server will continue executing the last actions received. This could be fatal for the bot due to loss of control over the bot. So make sure that go() is called before the turn ends.

The commands executed when go() is called are set by calling the various setter methods prior to calling the go() method: turn_rate, gun_turn_rate, radar_turn_rate, target_speed, and set_fire().

See also

turn_timeout

abstract property graphics: GraphicsABC

Gets a graphics object for debug painting.

Example

g = self.graphics g.set_fill_color(Color.from_rgb(0, 0, 255)) g.fill_rectangle(50, 50, 100, 100) # A blue filled rect

Returns:

A graphics canvas to use for painting graphical objects, making debugging easier.

gun_bearing_to(x: float, y: float) → float

Calculates the bearing (delta angle) between the gun’s current direction and the direction to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

A bearing to the point (x, y) in the range [-180, 180).

Return type:

float

abstract property gun_color: Color | None

Returns the color of the gun.

Returns:

The color of the gun, or None if no color has been set yet. If None, the default color will be used.

Return type:

Color

abstract property gun_cooling_rate: float

Gun cooling rate.

The gun needs to cool down to a gun heat of zero before the gun can fire. The gun cooling rate determines how fast the gun cools down. That is, the gun cooling rate is subtracted from the gun heat each turn until the gun heat reaches zero.

First available when the game has started.

Returns:

The gun cooling rate.

Return type:

float

abstract property gun_direction: float

Current direction of the gun in degrees.

Returns:

The current gun direction of the bot.

Return type:

float

abstract property gun_heat: float

Current gun heat.

When the gun is fired it gets heated and will not be able to fire before it has been cooled down. The gun is cooled down when the gun heat is zero. When the gun has fired the gun heat is set to 1 + (firepower / 5) and will be cooled down by the gun cooling rate.

Returns:

The current gun heat.

Return type:

float

abstract property gun_turn_rate: float

Returns the gun turn rate in degrees per turn.

Returns:

The turn rate of the gun.

Return type:

float

abstractmethod is_teammate(bot_id: int) → bool

Checks if the specified bot ID is a teammate.

Parameters:

bot_id (int) – The bot ID to check.

Returns:

True if the bot is a teammate; False otherwise.

Return type:

bool

abstract property max_gun_turn_rate: float

Returns the maximum gun turn rate in degrees per turn.

Returns:

The maximum turn rate of the gun.

Return type:

float

abstract property max_inactivity_turns: int

The maximum number of inactive turns allowed.

The bot will become zapped by the game for being inactive. Inactive means that the bot has taken no action in several turns in a row.

First available when the game has started.

Returns:

The maximum number of allowed inactive turns.

Return type:

int

abstract property max_radar_turn_rate: float

Returns the maximum radar turn rate in degrees per turn.

Returns:

The maximum turn rate of the radar.

Return type:

float

abstract property max_speed: float

Returns the maximum speed in units per turn.

Returns:

The maximum speed.

Return type:

float

abstract property max_turn_rate: float

Returns the maximum turn rate of the bot in degrees per turn.

Returns:

The maximum turn rate of the bot.

Return type:

float

abstract property my_id: int

The bot’s unique identifier.

normalize_absolute_angle(angle: float) → float

Normalizes an angle to an absolute angle in the range [0, 360).

Parameters:

angle (float) – The angle to normalize.

Returns:

The normalized absolute angle.

Return type:

float

normalize_relative_angle(angle: float) → float

Normalizes the given angle to the range [-180, 180] degrees.

Parameters:

angle (float) – The angle to normalize.

Returns:

The normalized angle in degrees.

Return type:

float

abstract property number_of_rounds: int

The number of rounds in a battle.

First available when the game has started.

Returns:

The number of rounds in a battle.

Return type:

int

on_bot_death(bot_death_event: BotDeathEvent) → None

The event handler triggered when another bot has died.

Parameters:

bot_death_event – The event details from the game.

on_bullet_fired(bullet_fired_event: BulletFiredEvent) → None

The event handler triggered when the bot has fired a bullet.

Parameters:

bullet_fired_event – The event details from the game.

on_bullet_hit(bullet_hit_bot_event: BulletHitBotEvent) → None

The event handler triggered when the bot has hit another bot with a bullet.

Parameters:

bullet_hit_bot_event – The event details from the game.

on_bullet_hit_bullet(bullet_hit_bullet_event: BulletHitBulletEvent) → None

The event handler triggered when a bullet fired from the bot has collided with another bullet.

Parameters:

bullet_hit_bullet_event – The event details from the game.

on_bullet_hit_wall(bullet_hit_wall_event: BulletHitWallEvent) → None

The event handler triggered when a bullet has hit a wall.

Parameters:

bullet_hit_wall_event – The event details from the game.

static on_connected(connected_event: ConnectedEvent) → None

The event handler triggered when connected to the server.

Parameters:

connected_event – The event details from the game.

static on_connection_error(connection_error_event: ConnectionErrorEvent) → None

The event handler triggered when a connection error occurs.

Parameters:

connection_error_event – The event details from the game.

on_custom_event(custom_event: CustomEvent) → None

The event handler triggered when some condition has been met. Use the name of the condition when you need to differentiate between different types of conditions received with this event handler.

Parameters:

custom_event – The event details from the game.

on_death(death_event: DeathEvent) → None

The event handler triggered when this bot has died.

Parameters:

death_event – The event details from the game.

static on_disconnected(disconnected_event: DisconnectedEvent) → None

The event handler triggered when disconnected from the server.

Parameters:

disconnected_event – The event details from the game.

on_game_ended(game_ended_event: GameEndedEvent) → None

The event handler triggered when a game has ended.

Parameters:

game_ended_event – The event details from the game.

on_game_started(game_started_event: GameStartedEvent) → None

The event handler triggered when a game has started.

Parameters:

game_started_event – The event details from the game.

on_hit_bot(bot_hit_bot_event: HitBotEvent) → None

The event handler triggered when the bot has collided with another bot.

Parameters:

bot_hit_bot_event – The event details from the game.

on_hit_by_bullet(hit_by_bullet_event: HitByBulletEvent) → None

The event handler triggered when the bot has been hit by a bullet.

Parameters:

hit_by_bullet_event – The event details from the game.

on_hit_wall(bot_hit_wall_event: HitWallEvent) → None

The event handler triggered when the bot has hit a wall.

Parameters:

bot_hit_wall_event – The event details from the game.

on_round_ended(round_ended_event: RoundEndedEvent) → None

The event handler triggered when a round has ended.

Parameters:

round_ended_event – The event details from the game.

on_round_started(round_started_event: RoundStartedEvent) → None

The event handler triggered when a new round has started.

Parameters:

round_started_event – The event details from the game.

on_scanned_bot(scanned_bot_event: ScannedBotEvent) → None

The event handler triggered when the bot has skipped a turn. This event occurs if the bot did not take any action in a specific turn. That is, go() was not called before the turn timeout occurred for the turn. If the bot does not take action for multiple turns in a row, it will receive a SkippedTurnEvent for each turn where it did not take action. When the bot is skipping a turn, the server did not receive the message from the bot, and the server will use the newest received instructions for target speed, turn rates, firing, etc.

Parameters:

scanned_bot_event – The event details from the game.

on_skipped_turn(skipped_turn_event: SkippedTurnEvent) → None

Handles the event triggered when the bot skips a turn.

A turn is skipped if the bot does not send any instructions to the server (via the go() method) before the turn timeout occurs. When this happens, the server continues using the last received set of actions, such as movement, turning rates, or firing commands.

Reasons for skipped turns may include:

  • Excessive processing or delays in the bot’s logic, leading to a timeout.

  • Failure to invoke the go() method in the current turn.

  • Misaligned or unintended logic in the bot’s turn-handling code.

This method can be overridden to define custom behavior for handling skipped turns, such as logging the event, debugging performance issues, or modifying the bot’s logic to avoid future skips.

Parameters:

skipped_turn_event – An event containing details about the skipped turn.

on_team_message(team_message_event: TeamMessageEvent) → None

The event handler triggered when the bot has received a message from a teammate.

Parameters:

team_message_event – The event details from the game.

on_tick(tick_event: TickEvent) → None

The event handler triggered when a game tick event occurs, i.e., when a new turn in a round has started.

Parameters:

tick_event – The event details from the game.

on_won_round(won_round_event: WonRoundEvent) → None

The event handler triggered when the bot has won a round.

Parameters:

won_round_event – The event details from the game.

radar_bearing_to(x: float, y: float) → float

Calculates the bearing (delta angle) between the radar’s current direction and the direction to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

A bearing to the point (x, y) in the range [-180, 180).

Return type:

float

abstract property radar_color: Color | None

Returns the color of the radar.

Returns:

The color of the radar. If no color has been set yet, returns None, which indicates that the default radar color will be used.

Return type:

Color

abstract property radar_direction: float

Current direction of the radar in degrees.

Returns:

The current radar direction of the bot.

Return type:

float

abstract property radar_turn_rate: float

Returns the radar turn rate in degrees per turn.

Returns:

The turn rate of the radar.

Return type:

float

abstract property round_number: int

Current round number.

Returns:

The current round number.

Return type:

int

abstract property scan_color: Color | None

Returns the color of the scan arc.

Returns:

The color of the scan arc, or None if no color has been set, meaning the default color will be used.

Return type:

Color

abstractmethod send_team_message(teammate_id: int, message: Any) → None

Sends a message to a specific teammate.

When the message is sent, it is serialized into a JSON representation, meaning that all public fields, and only public fields, are being serialized into a JSON representation as a DTO (data transfer object).

The maximum team message size limit is defined by TEAM_MESSAGE_MAX_SIZE, which is set to TEAM_MESSAGE_MAX_SIZE bytes. This size is the size of the message when it is serialized into a JSON representation.

The maximum number of messages that can be sent/broadcast per turn is limited to MAX_NUMBER_OF_TEAM_MESSAGES_PER_TURN.

Parameters:

  • teammate_id – The id of the teammate to send the message to.

  • message – The message to send.

Raises:

ValueError – If the size of the message exceeds the size limit.

abstractmethod set_event_priority(event_class: type, priority: int) → None

Changes the event priority for an event class. The event priority determines which event types (classes) must be fired and handled before others. Events with higher priorities will be handled before events with lower priorities.

Note

You should normally not need to change the event priority.

Parameters:

  • event_class (Type[BotEvent]) – The event class to change the priority for.

  • priority (int) – The new priority, typically a positive number from 1 to 150. The higher the value, the higher the priority.

See also

DefaultEventPriority, get_event_priority.

abstractmethod set_fire(firepower: float) → bool

Sets the gun to fire in the direction that the gun is pointing with the specified firepower.

Firepower is the amount of energy your bot will spend on firing the gun. This means that the bot will lose power on firing the gun, where the energy loss is equal to the firepower. You cannot spend more energy than is available from your bot.

The bullet power must be greater than the minimum firepower and gun heat must be zero before the gun can fire.

If the bullet hits an opponent bot, you will gain energy from the bullet hit. When hitting another bot, your bot will be rewarded and retrieve an energy boost of 3x the firepower.

The gun will only fire when the firepower is at or above the minimum firepower. If the firepower is greater than the maximum firepower, the power will be truncated to the maximum firepower.

Whenever the gun is fired, the gun becomes heated and needs to cool down before it can fire again. The gun heat must be zero before the gun can fire again. The gun heat generated by firing the gun is calculated as 1 + (firepower / 5). Hence, the more firepower used, the longer it takes to cool down the gun. The gun cooling rate can be retrieved using the get_gun_cooling_rate() function.

The amount of energy used for firing the gun is subtracted from the bot’s total energy. The amount of damage dealt by a bullet hitting another bot is 4x firepower. If the firepower is greater than 1, it will deal an additional 2 x (firepower - 1) damage.

Note that the gun will automatically keep firing each turn as soon as the gun heat reaches zero. It is possible to disable the gun firing by setting the firepower to zero.

The firepower is truncated between 0 and the maximum firepower if the provided value exceeds this range.

If this property is set multiple times, the last value set before calling go() is used.

Parameters:

firepower (float) – The new firepower.

Returns:

True if the cannon can fire (i.e., if there is no gun heat), False otherwise.

Return type:

bool

See also

  • on_bullet_fired()

  • get_firepower()

  • get_gun_heat()

  • get_gun_cooling_rate()

abstractmethod set_fire_assist(enable: bool) → None

Enables or disables fire assistance explicitly. Fire assistance is useful for bots with limited aiming capabilities as it helps the bot by firing directly at a scanned bot when the gun is fired, which is a very simple aiming strategy.

When fire assistance is enabled, the gun will fire towards the center of the scanned bot when all these conditions are met:

  1. The gun is fired (via set_fire or fire()).

  2. The radar is scanning a bot when firing the gun (e.g., in the on_scanned_bot() event, after calling set_rescan() or rescan()).

  3. The gun and radar are pointing in the exact same direction. You can disable radar and gun movement alignment using set_adjust_radar_for_gun_turn(False) to ensure the gun and radar stay aligned while avoiding radar turning independently of the gun.

The fire assistance feature is provided for backwards compatibility with the original Robocode, where bots that were not considered AdvancedRobot had fire assistance enabled by default, as their gun and radar could not move independently of each other. In contrast, AdvancedRobot allows the body, gun, and radar to move independently.

Parameters:

enable (bool) – Enables fire assistance when set to True, and disables it otherwise.

abstractmethod set_interruptible(interruptible: bool) → None

Sets whether the bot’s event handlers are interruptible.

When set to True, event handlers can be interrupted by higher-priority events. When set to False, handlers run to completion before other events are processed.

Parameters:

interruptible (bool) – If True, event handlers are interruptible; otherwise, they are not.

abstractmethod set_rescan() → None

Sets the bot to rescan with the radar.

This method is useful if the radar has not turned, and hence will not automatically scan bots. The last radar direction and sweep angle will be used for scanning for bots.

abstract property speed: float

The current speed measured in units per turn.

If the speed is positive, the bot moves forward. If negative, the bot moves backward. Zero speed means that the bot is not moving from its current position.

Returns:

The current speed.

Return type:

float

abstractmethod start() → None

The method used to start running the bot. You should call this method from the main function or a similar entry point.

This method blocks until the bot disconnects from the server.

Example:

if __name__ == "__main__":
    # create my_bot
    ...
    my_bot.start()
abstract property stopped: bool

Checks if the movement has been stopped.

Returns:

True if the movement has been stopped by set_stop(), False otherwise.

Return type:

bool

See also

set_resume: Resumes the movement. set_stop(): Stops the movement. set_stop(flag: bool): Stops the movement, with a flag to specify additional behavior.

abstract property target_speed: float

Returns the target speed in units per turn.

Returns:

The target speed.

Return type:

float

abstract property teammate_ids: set[int]

The IDs of all teammates.

Returns:

A set of IDs of all teammates if the bot is participating in a team, or an empty set if the bot is not in a team.

Return type:

Set[int]

See also

is_teammate: Checks if a bot is a teammate. send_team_message: Sends a message to the team.

abstract property time_left: int

The number of microseconds left of this turn before the bot will skip the turn.

Make sure to call go() before the time runs out.

Returns:

The amount of time left in microseconds.

Return type:

int

abstract property tracks_color: Color | None

Returns the color of the tank tracks.

Returns:

The color of the tank tracks, or None if no color has been set yet, meaning that the default color will be used.

Return type:

Color

abstract property turn_number: int

Current turn number.

Returns:

The current turn number.

Return type:

int

abstract property turn_rate: float

Returns the turn rate of the bot in degrees per turn.

Returns:

The turn rate of the bot.

Return type:

float

abstract property turn_timeout: int

The turn timeout in microseconds.

The turn timeout is important as the bot needs to take action by calling go() before the turn timeout occurs. As soon as the TickEvent() is triggered, i.e. when onTick() is called, you need to call go() to take action before the turn timeout occurs. Otherwise, your bot will skip a turn and receive a onSkippedTurn for each turn where go() is called too late.

First available when the game has started.

Returns:

The turn timeout in microseconds.

Return type:

int

abstract property turret_color: Color | None

Returns the color of the gun turret.

Returns:

The color of the turret or None if no color has been set yet, meaning that the default color will be used.

abstract property variant: str

The game variant, which is “Tank Royale”.

Returns:

The game variant of Robocode.

Return type:

str

abstract property version: str

Game version, e.g. “1.0.0”.

Returns:

The game version.

Return type:

str

abstract property x: float

Current X coordinate of the center of the bot.

Returns:

The current X coordinate of the bot.

Return type:

float

abstract property y: float

Current Y coordinate of the center of the bot.

Returns:

The current Y coordinate of the bot.

Return type:

float

exception BotException(message, cause=None)[source]

Bases: Exception

Represents errors that occur with bot execution.

__init__(message, cause=None)[source]

Initializes a new instance of the BotException class.

Parameters:

  • message – The error message that describes the error.

  • cause – The exception that is the cause of this exception. Defaults to None.

add_note()

Exception.add_note(note) – add a note to the exception

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class BotInfo(name: str | None = None, version: str | None = None, authors: List[str] | None = None, description: str | None = None, homepage: str | None = None, country_codes: List[str] | None = None, game_types: Set[str] | None = None, platform: str | None = None, programming_lang: str | None = None, initial_position: InitialPosition | None = None)[source]

Bases: object

BotInfo class contains the properties of a bot. Implements validation and supports a builder pattern.

MAX_NAME_LENGTH = 30

Maximum number of characters accepted for the name.

MAX_VERSION_LENGTH = 20

Maximum number of characters accepted for the version.

MAX_AUTHOR_LENGTH = 50

Maximum number of characters accepted for an author name.

MAX_DESCRIPTION_LENGTH = 250

Maximum number of characters accepted for the description.

MAX_HOMEPAGE_LENGTH = 150

Maximum number of characters accepted for the link to the homepage.

MAX_GAME_TYPE_LENGTH = 20

Maximum number of characters accepted for a game type.

MAX_PLATFORM_LENGTH = 30

Maximum number of characters accepted for the platform name.

MAX_PROGRAMMING_LANG_LENGTH = 30

Maximum number of characters accepted for the programming language name.

MAX_NUMBER_OF_AUTHORS = 20

Maximum number of authors allowed.

MAX_NUMBER_OF_COUNTRY_CODES = 20

Maximum number of country codes allowed.

MAX_NUMBER_OF_GAME_TYPES = 10

Maximum number of game types allowed.

__init__(name: str | None = None, version: str | None = None, authors: List[str] | None = None, description: str | None = None, homepage: str | None = None, country_codes: List[str] | None = None, game_types: Set[str] | None = None, platform: str | None = None, programming_lang: str | None = None, initial_position: InitialPosition | None = None)[source]

Initializes a new instance of the BotInfo class.

Note

The recommended method for creating a BotInfo instance is to use the IBuilder interface provided with the BotInfo.builder() static method.

Variables:

  • name (str) – The name of the bot (optional).

  • version (str) – The version of the bot (optional).

  • authors (list) – The author(s) of the bot (optional).

  • description (str) – A short description of the bot (optional).

  • homepage (str) – A link to a homepage for the bot (optional).

  • country_codes (list) – The country code(s) for the bot (optional).

  • game_types (set) – The game types that this bot can handle (optional).

  • platform (str) – The platform used for running the bot (optional).

  • programming_lang (str) – The programming language used for developing the bot (optional).

  • initial_position (InitialPosition) – The initial position with starting coordinate and angle (optional).

classmethod from_json(json_data: str) → BotInfo[source]
classmethod from_file(file_path: str) → BotInfo[source]

Reads the bot info from a JSON file.

Parameters:

file_path (str) – The path to the JSON file containing bot info.

Returns:

An instance of BotInfo populated with data from the file.

Return type:

BotInfo

class Builder[source]

Bases: object

Builder interface for creating builder objects for constructing BotInfo instances. Supports method chaining.

game_types: set[str]
set_name(name: str) → Builder[source]

Sets the bot name. (required)

Note

The maximum length of the name is defined by MAX_NAME_LENGTH characters.

Example

“Rampage”

Parameters:

name (str) – The name of the bot.

Returns:

The IBuilder instance, allowing for method chaining.

Return type:

IBuilder

set_version(version: str) → Builder[source]

Sets the bot version. (required)

Note

The maximum length of the version is 20 characters.

Example

“1.0”

Parameters:

version (str) – The version of the bot.

Returns:

Self, for method chaining.

set_authors(authors: List[str]) → Builder[source]

Sets the names(s) of the author(s) of the bot. (required)

Note

  • The maximum length of an author name is 50 characters.

  • Maximum number of names is 5.

  • Providing None will remove all authors.

Example

[“John Doe”]

Parameters:

authors (list) – A list containing the names(s) of the author(s).

Returns:

Self, for method chaining.

add_author(author: str) → Builder[source]

Adds an author of the bot. (required)

See also

set_authors()

Parameters:

author (str) – The name of an author to add.

Returns:

Self, for method chaining.

set_description(description: str) → Builder[source]

Sets a short description of the bot. (optional)

Note

  • The maximum length of the description is 250 characters.

  • Line-breaks (line-feed or newline) are supported, but expect up to 3 lines to be displayed on UI.

Example

“The rampage bot will try to ram bots that are very close.n”

“Sneaks around corners and shoots at bots that come too near.”

Parameters:

description (str) – A short description of the bot.

Returns:

Self, for method chaining.

set_homepage(homepage: str) → Builder[source]

Sets a link to the homepage for the bot. (optional)

Note

The maximum length of a link is 150 characters.

Example

“https://fictive-homepage.net/Rampage”

Parameters:

homepage (str) – A link to a homepage for the bot.

Returns:

Self, for method chaining.

set_country_codes(country_codes: List[str]) → Builder[source]

Sets the country codes for the bot. (optional)

Notes

  • Each country code uses a 2-character alpha-2 format from the ISO 3166 standard.

  • Maximum number of country codes is 5.

  • Providing None removes all country codes.

  • If no valid country code is specified, the default locale country code is used.

Example

[“dk”]

Parameters:

country_codes (list) – A list of country codes.

Returns:

Self, for method chaining.

add_country_code(country_code: str) → Builder[source]

Adds a country code for the bot. (optional)

See also

set_country_codes()

Parameters:

country_code (str) – The country code to add.

Returns:

Self, for method chaining.

set_game_types(game_types: Set[str]) → Builder[source]

Sets the game types that this bot is capable of participating in. (required)

Notes

  • Standard game types can be found at the referenced documentation or API spec.

  • More types may be added in the future.

  • Use the predefined strings from the GameType class when possible.

  • Maximum game type length is 20 characters.

  • Maximum number of game types is 10.

  • Providing None removes all game types.

Example

{“classic”, “melee”, “future-type”}

Parameters:

game_types (set) – A set of game types that the bot is capable of participating in.

Returns:

Self, for method chaining.

add_game_type(game_type: str) → Builder[source]

Adds a game type that this bot is capable of participating in. (required)

See also

set_game_types()

Example

“classic”

Parameters:

game_type (str) – A game type that the bot can participate in.

Returns:

Self, for method chaining.

set_platform(platform: str) → Builder[source]

Sets the name of the platform that this bot is built for. (optional)

Note

  • The maximum length of the platform name is 30 characters.

  • If None or a blank string is provided, the default string (Java Runtime Environment) is used.

Example

“Java Runtime Environment (JRE) [version]”

Parameters:

platform (str) – The name of the platform for this bot.

Returns:

Self, for method chaining.

set_programming_lang(language: str) → Builder[source]

Sets the name of the programming language used for developing this bot. (optional)

Note

The maximum length of the programming language’s name is 30 characters.

Example

Python 3.12

Parameters:

language (str) – The name of the programming language.

Returns:

Self, for method chaining.

set_initial_position(initial_position: str) → Builder[source]

Sets the initial position of the bot. (optional)

Note

Initial positions must be enabled or allowed by the game (server) to take effect.

Parameters:

initial_position – The initial position of the bot.

Returns:

Self, for method chaining.

build() → BotInfo[source]

Builds and returns the BotInfo instance based on the data set added to this builder so far.

This method is typically the final step in the builder’s workflow to extract the result of the building process.

Returns:

The resulting BotInfo instance.

Return type:

BotInfo

class BotResults(rank: int, survival: float, last_survivor_bonus: float, bullet_damage: float, bullet_kill_bonus: float, ram_damage: float, ram_kill_bonus: float, total_score: float, first_places: int, second_places: int, third_places: int)[source]

Bases: object

Represents individual bot results.

rank: int

Rank/placement of the bot, where 1 means 1st place, 4 means 4th place etc.

survival: float

Accumulated survival score. Every bot still alive scores 50 points every time another bot is defeated.

last_survivor_bonus: float

Last survivor score. The last bot alive scores 10 points or each bot that has been defeated.

bullet_damage: float

Bullet damage score. A bot scores 1 point for each point of damage they do to other bots.

bullet_kill_bonus: float

Bullet kill-bonus. When a bot kills another bot, it scores an additional 20% points of the total damage it did to that bot.

ram_damage: float

Ram damage score. Bots score 2 points for each point of damage inflicted by ramming an enemy bot. Ramming is the act deliberately driving forward (not backward) and hitting another bot.

ram_kill_bonus: float

Ram kill-bonus. When a bot kills another bot due to ramming, it scores an additional 30% of the total ramming damage it did to that bot.

total_score: float

Total score is the sum of all scores and determines the ranking.

first_places: int

Number of 1st places for the bot.

second_places: int

Number of 2nd places for the bot.

third_places: int

Number of 3rd places for the bot.

class BotState(droid: bool, energy: float, x: float, y: float, direction: float, gun_direction: float, radar_direction: float, radar_sweep: float, speed: float, turn_rate: float, gun_turn_rate: float, radar_turn_rate: float, gun_heat: float, enemy_count: int, body_color: bot_api.graphics.color.Color | None, turret_color: bot_api.graphics.color.Color | None, radar_color: bot_api.graphics.color.Color | None, bullet_color: bot_api.graphics.color.Color | None, scan_color: bot_api.graphics.color.Color | None, tracks_color: bot_api.graphics.color.Color | None, gun_color: bot_api.graphics.color.Color | None, debugging_enabled: bool)[source]

Bases: object

class Color(_value: int)

Bases: object

Represents an RGBA (red, green, blue, alpha) color used in the Tank Royale game.

This graphics Color implementation contains: - Internal 32-bit RGBA value - Factory methods from_rgb(), from_rgba(r,g,b,a), and from_rgba_value(rgba) - Read-only channel properties: red, green, blue, alpha (mapped to R,G,B,A) - to_rgba() for round-trip, to_hex_color() for hex string - Equality/hash based on RGBA value - Many predefined common colors

Note: For compatibility with existing Python code, to_color_schema() is preserved and uses lowercase hex values as before.

ALICE_BLUE = Color(_value=4042850303)
ANTIQUE_WHITE = Color(_value=4209760255)
AQUA = Color(_value=16777215)
AQUAMARINE = Color(_value=2147472639)
AZURE = Color(_value=4043309055)
BEIGE = Color(_value=4126530815)
BISQUE = Color(_value=4293182719)
BLACK = Color(_value=255)
BLANCHED_ALMOND = Color(_value=4293643775)
BLUE = Color(_value=65535)
BLUE_VIOLET = Color(_value=2318131967)
BROWN = Color(_value=2771004159)
BURLY_WOOD = Color(_value=3736635391)
CADET_BLUE = Color(_value=1604231423)
CHARTREUSE = Color(_value=2147418367)
CHOCOLATE = Color(_value=3530104575)
CORAL = Color(_value=4286533887)
CORNFLOWER_BLUE = Color(_value=1687547391)
CORNSILK = Color(_value=4294499583)
CRIMSON = Color(_value=3692313855)
CYAN = Color(_value=16777215)
DARK_BLUE = Color(_value=35839)
DARK_CYAN = Color(_value=9145343)
DARK_GOLDENROD = Color(_value=3095792639)
DARK_GRAY = Color(_value=2846468607)
DARK_GREEN = Color(_value=6553855)
DARK_KHAKI = Color(_value=3182914559)
DARK_MAGENTA = Color(_value=2332068863)
DARK_OLIVE_GREEN = Color(_value=1433087999)
DARK_ORANGE = Color(_value=4287365375)
DARK_ORCHID = Color(_value=2570243327)
DARK_RED = Color(_value=2332033279)
DARK_SALMON = Color(_value=3918953215)
DARK_SEA_GREEN = Color(_value=2411498495)
DARK_SLATE_BLUE = Color(_value=1211993087)
DARK_SLATE_GRAY = Color(_value=793726975)
DARK_TURQUOISE = Color(_value=13554175)
DARK_VIOLET = Color(_value=2483082239)
DEEP_PINK = Color(_value=4279538687)
DEEP_SKY_BLUE = Color(_value=12582911)
DIM_GRAY = Color(_value=1768516095)
DODGER_BLUE = Color(_value=512819199)
FIREBRICK = Color(_value=2988581631)
FLORAL_WHITE = Color(_value=4294635775)
FOREST_GREEN = Color(_value=579543807)
FUCHSIA = Color(_value=4278255615)
GAINSBORO = Color(_value=3705462015)
GHOST_WHITE = Color(_value=4177068031)
GOLD = Color(_value=4292280575)
GOLDENROD = Color(_value=3668254975)
GRAY = Color(_value=2155905279)
GREEN = Color(_value=8388863)
GREEN_YELLOW = Color(_value=2919182335)
HONEYDEW = Color(_value=4043305215)
HOT_PINK = Color(_value=4285117695)
INDIAN_RED = Color(_value=3445382399)
INDIGO = Color(_value=1258324735)
IVORY = Color(_value=4294963455)
KHAKI = Color(_value=4041641215)
LAVENDER = Color(_value=3873897215)
LAVENDER_BLUSH = Color(_value=4293981695)
LAWN_GREEN = Color(_value=2096890111)
LEMON_CHIFFON = Color(_value=4294626815)
LIGHT_BLUE = Color(_value=2916673279)
LIGHT_CORAL = Color(_value=4034953471)
LIGHT_CYAN = Color(_value=3774873599)
LIGHT_GOLDENROD_YELLOW = Color(_value=4210742015)
LIGHT_GRAY = Color(_value=3553874943)
LIGHT_GREEN = Color(_value=2431553791)
LIGHT_PINK = Color(_value=4290167295)
LIGHT_SALMON = Color(_value=4288707327)
LIGHT_SEA_GREEN = Color(_value=548580095)
LIGHT_SKY_BLUE = Color(_value=2278488831)
LIGHT_SLATE_GRAY = Color(_value=2005441023)
LIGHT_STEEL_BLUE = Color(_value=2965692159)
LIGHT_YELLOW = Color(_value=4294959359)
LIME = Color(_value=16711935)
LIME_GREEN = Color(_value=852308735)
LINEN = Color(_value=4210091775)
MAGENTA = Color(_value=4278255615)
MAROON = Color(_value=2147483903)
MEDIUM_AQUAMARINE = Color(_value=1724754687)
MEDIUM_BLUE = Color(_value=52735)
MEDIUM_ORCHID = Color(_value=3126187007)
MEDIUM_PURPLE = Color(_value=2473647103)
MEDIUM_SEA_GREEN = Color(_value=1018393087)
MEDIUM_SLATE_BLUE = Color(_value=2070474495)
MEDIUM_SPRING_GREEN = Color(_value=16423679)
MEDIUM_TURQUOISE = Color(_value=1221709055)
MEDIUM_VIOLET_RED = Color(_value=3340076543)
MIDNIGHT_BLUE = Color(_value=421097727)
MINT_CREAM = Color(_value=4127193855)
MISTY_ROSE = Color(_value=4293190143)
MOCCASIN = Color(_value=4293178879)
NAVAJO_WHITE = Color(_value=4292783615)
NAVY = Color(_value=33023)
OLD_LACE = Color(_value=4260751103)
OLIVE = Color(_value=2155872511)
OLIVE_DRAB = Color(_value=1804477439)
ORANGE = Color(_value=4289003775)
ORANGE_RED = Color(_value=4282712319)
ORCHID = Color(_value=3664828159)
PALE_GOLDENROD = Color(_value=4008225535)
PALE_GREEN = Color(_value=2566625535)
PALE_TURQUOISE = Color(_value=2951671551)
PALE_VIOLET_RED = Color(_value=3681588223)
PAPAYA_WHIP = Color(_value=4293907967)
PEACH_PUFF = Color(_value=4292524543)
PERU = Color(_value=3448061951)
PINK = Color(_value=4290825215)
PLUM = Color(_value=3718307327)
POWDER_BLUE = Color(_value=2967529215)
PURPLE = Color(_value=2147516671)
RED = Color(_value=4278190335)
ROSY_BROWN = Color(_value=3163525119)
ROYAL_BLUE = Color(_value=1097458175)
SADDLE_BROWN = Color(_value=2336560127)
SALMON = Color(_value=4202722047)
SANDY_BROWN = Color(_value=4104413439)
SEA_GREEN = Color(_value=780883967)
SEA_SHELL = Color(_value=4294307583)
SIENNA = Color(_value=2689740287)
SILVER = Color(_value=3233857791)
SKY_BLUE = Color(_value=2278484991)
SLATE_BLUE = Color(_value=1784335871)
SLATE_GRAY = Color(_value=1887473919)
SNOW = Color(_value=4294638335)
SPRING_GREEN = Color(_value=16744447)
STEEL_BLUE = Color(_value=1182971135)
TAN = Color(_value=3535047935)
TEAL = Color(_value=8421631)
THISTLE = Color(_value=3636451583)
TOMATO = Color(_value=4284696575)
TRANSPARENT = Color(_value=4294967040)
TURQUOISE = Color(_value=1088475391)
VIOLET = Color(_value=4001558271)
WHEAT = Color(_value=4125012991)
WHITE = Color(_value=4294967295)
WHITE_SMOKE = Color(_value=4126537215)
YELLOW = Color(_value=4294902015)
YELLOW_GREEN = Color(_value=2597139199)
property a: int
property alpha: int

Gets the alpha component value of this color.

Returns:

The alpha component value between 0 and 255.

property b: int
property blue: int

Gets the blue component value of this color.

Returns:

The blue component value between 0 and 255.

classmethod from_color_with_alpha(base_color: Color, a: int) → Color

Creates a color from the specified base color with a new alpha value.

Parameters:

  • base_color – The Color from which to derive the RGB values.

  • a – The alpha component value (0-255).

Returns:

A new Color with the RGB values from the base color and the specified alpha value.

classmethod from_hex(hex_triplet: str) → Color

Creates a color from a hex triplet (RGB, RRGGBB, or RRGGBBAA without hash).

A hex triplet is either three, six, or eight hexadecimal digits that represent an RGB or RGBA color. An example of a hex triplet is “09C” or “0099CC”, which both represent the same color.

Parameters:

hex_triplet – A string containing hex digits like “09C”, “0099CC”, or “0099CCFF”.

Returns:

A new Color.

Raises:

ValueError – If the string is not valid hex digits (3, 6, or 8 characters).

classmethod from_hex_color(hex_color: str | None) → Color | None

Creates a color from a hex color string (#RGB, #RRGGBB, or #RRGGBBAA).

This method works the same as from_hex() except that it requires a hash sign before the hex value. An example of a numeric RGB value is “#09C” or “#0099CC”, which both represent the same color.

Parameters:

hex_color – A string containing a hex color like “#09C”, “#0099CC”, or “#0099CCFF”.

Returns:

A new Color; None if the input is None.

Raises:

ValueError – If the string is not in valid numeric RGB format.

classmethod from_rgb(r: int, g: int, b: int) → Color

Creates a color from the specified red, green, and blue values with alpha 255 (fully opaque).

Parameters:

  • r – The red component value (0-255).

  • g – The green component value (0-255).

  • b – The blue component value (0-255).

Returns:

A new Color initialized with the specified RGB values and an alpha value of 255.

classmethod from_rgba(r: int, g: int, b: int, a: int) → Color

Creates a color from the specified red, green, blue, and alpha values.

Parameters:

  • r – The red component value (0-255).

  • g – The green component value (0-255).

  • b – The blue component value (0-255).

  • a – The alpha component value (0-255).

Returns:

A new Color initialized with the specified RGBA values.

classmethod from_rgba_value(rgba: int) → Color

Creates a color from a 32-bit RGBA value.

Parameters:

rgba – A 32-bit value specifying the RGBA components.

Returns:

A new Color initialized with the specified RGBA value.

property g: int
property green: int

Gets the green component value of this color.

Returns:

The green component value between 0 and 255.

property r: int
property red: int

Gets the red component value of this color.

Returns:

The red component value between 0 and 255.

to_color_schema() → Color

Converts this color to the schema Color representation used by the API.

Note

The returned hex string uses lowercase letters for compatibility with the Python schema representation.

Returns:

A Color schema object with the hex value set.

to_hex_color() → str

Converts the color to its hexadecimal representation.

Returns:

  • If alpha is 255 (fully opaque), returns “#RRGGBB”.

  • If alpha is not 255, returns “#RRGGBBAA”.

Return type:

A string representing the color in hexadecimal format

to_rgba() → int

Converts this Color to a 32-bit RGBA value.

Returns:

A 32-bit integer containing the RGBA representation of this color.

droid: bool

Flag specifying if the bot is a droid.

energy: float

Energy level. Typically starts at 100.

x: float

X coordinate.

y: float

Y coordinate.

direction: float

Driving direction in degrees.

gun_direction: float

Gun direction in degrees.

radar_direction: float

Radar direction in degrees.

radar_sweep: float

Radar sweep angle in degrees.

speed: float

Speed measured in units per turn.

turn_rate: float

Turn rate of the body in degrees per turn.

gun_turn_rate: float

Turn rate of the gun in degrees per turn.

radar_turn_rate: float

Turn rate of the radar in degrees per turn.

gun_heat: float

Gun heat.

enemy_count: int

Number of enemies left.

body_color: Color | None

Body color.

turret_color: Color | None

Gun turret color.

radar_color: Color | None

Radar color.

bullet_color: Color | None

Bullet color.

scan_color: Color | None

Scan arc color.

tracks_color: Color | None

Tracks color.

gun_color: Color | None

Gun color.

debugging_enabled: bool

Flag indicating if graphical debugging is enabled.

class BulletState(bullet_id: int, owner_id: int, power: float, x: float, y: float, direction: float, color: Color)[source]

Bases: object

Represents the state of a bullet that has been fired by a bot.

Variables:

  • bullet_id (int) – Unique identifier for the bullet.

  • owner_id (int) – Identifier of the bot that fired the bullet.

  • power (float) – Firepower level of the bullet, which also determines its speed.

  • x (float) – The X-coordinate of the bullet’s position.

  • y (float) – The Y-coordinate of the bullet’s position.

  • direction (float) – The direction of the bullet in degrees, where 0 points to the right.

  • color (Color) – The visual color of the bullet.

class Color(_value: int)

Bases: object

Represents an RGBA (red, green, blue, alpha) color used in the Tank Royale game.

This graphics Color implementation contains: - Internal 32-bit RGBA value - Factory methods from_rgb(), from_rgba(r,g,b,a), and from_rgba_value(rgba) - Read-only channel properties: red, green, blue, alpha (mapped to R,G,B,A) - to_rgba() for round-trip, to_hex_color() for hex string - Equality/hash based on RGBA value - Many predefined common colors

Note: For compatibility with existing Python code, to_color_schema() is preserved and uses lowercase hex values as before.

ALICE_BLUE = Color(_value=4042850303)
ANTIQUE_WHITE = Color(_value=4209760255)
AQUA = Color(_value=16777215)
AQUAMARINE = Color(_value=2147472639)
AZURE = Color(_value=4043309055)
BEIGE = Color(_value=4126530815)
BISQUE = Color(_value=4293182719)
BLACK = Color(_value=255)
BLANCHED_ALMOND = Color(_value=4293643775)
BLUE = Color(_value=65535)
BLUE_VIOLET = Color(_value=2318131967)
BROWN = Color(_value=2771004159)
BURLY_WOOD = Color(_value=3736635391)
CADET_BLUE = Color(_value=1604231423)
CHARTREUSE = Color(_value=2147418367)
CHOCOLATE = Color(_value=3530104575)
CORAL = Color(_value=4286533887)
CORNFLOWER_BLUE = Color(_value=1687547391)
CORNSILK = Color(_value=4294499583)
CRIMSON = Color(_value=3692313855)
CYAN = Color(_value=16777215)
DARK_BLUE = Color(_value=35839)
DARK_CYAN = Color(_value=9145343)
DARK_GOLDENROD = Color(_value=3095792639)
DARK_GRAY = Color(_value=2846468607)
DARK_GREEN = Color(_value=6553855)
DARK_KHAKI = Color(_value=3182914559)
DARK_MAGENTA = Color(_value=2332068863)
DARK_OLIVE_GREEN = Color(_value=1433087999)
DARK_ORANGE = Color(_value=4287365375)
DARK_ORCHID = Color(_value=2570243327)
DARK_RED = Color(_value=2332033279)
DARK_SALMON = Color(_value=3918953215)
DARK_SEA_GREEN = Color(_value=2411498495)
DARK_SLATE_BLUE = Color(_value=1211993087)
DARK_SLATE_GRAY = Color(_value=793726975)
DARK_TURQUOISE = Color(_value=13554175)
DARK_VIOLET = Color(_value=2483082239)
DEEP_PINK = Color(_value=4279538687)
DEEP_SKY_BLUE = Color(_value=12582911)
DIM_GRAY = Color(_value=1768516095)
DODGER_BLUE = Color(_value=512819199)
FIREBRICK = Color(_value=2988581631)
FLORAL_WHITE = Color(_value=4294635775)
FOREST_GREEN = Color(_value=579543807)
FUCHSIA = Color(_value=4278255615)
GAINSBORO = Color(_value=3705462015)
GHOST_WHITE = Color(_value=4177068031)
GOLD = Color(_value=4292280575)
GOLDENROD = Color(_value=3668254975)
GRAY = Color(_value=2155905279)
GREEN = Color(_value=8388863)
GREEN_YELLOW = Color(_value=2919182335)
HONEYDEW = Color(_value=4043305215)
HOT_PINK = Color(_value=4285117695)
INDIAN_RED = Color(_value=3445382399)
INDIGO = Color(_value=1258324735)
IVORY = Color(_value=4294963455)
KHAKI = Color(_value=4041641215)
LAVENDER = Color(_value=3873897215)
LAVENDER_BLUSH = Color(_value=4293981695)
LAWN_GREEN = Color(_value=2096890111)
LEMON_CHIFFON = Color(_value=4294626815)
LIGHT_BLUE = Color(_value=2916673279)
LIGHT_CORAL = Color(_value=4034953471)
LIGHT_CYAN = Color(_value=3774873599)
LIGHT_GOLDENROD_YELLOW = Color(_value=4210742015)
LIGHT_GRAY = Color(_value=3553874943)
LIGHT_GREEN = Color(_value=2431553791)
LIGHT_PINK = Color(_value=4290167295)
LIGHT_SALMON = Color(_value=4288707327)
LIGHT_SEA_GREEN = Color(_value=548580095)
LIGHT_SKY_BLUE = Color(_value=2278488831)
LIGHT_SLATE_GRAY = Color(_value=2005441023)
LIGHT_STEEL_BLUE = Color(_value=2965692159)
LIGHT_YELLOW = Color(_value=4294959359)
LIME = Color(_value=16711935)
LIME_GREEN = Color(_value=852308735)
LINEN = Color(_value=4210091775)
MAGENTA = Color(_value=4278255615)
MAROON = Color(_value=2147483903)
MEDIUM_AQUAMARINE = Color(_value=1724754687)
MEDIUM_BLUE = Color(_value=52735)
MEDIUM_ORCHID = Color(_value=3126187007)
MEDIUM_PURPLE = Color(_value=2473647103)
MEDIUM_SEA_GREEN = Color(_value=1018393087)
MEDIUM_SLATE_BLUE = Color(_value=2070474495)
MEDIUM_SPRING_GREEN = Color(_value=16423679)
MEDIUM_TURQUOISE = Color(_value=1221709055)
MEDIUM_VIOLET_RED = Color(_value=3340076543)
MIDNIGHT_BLUE = Color(_value=421097727)
MINT_CREAM = Color(_value=4127193855)
MISTY_ROSE = Color(_value=4293190143)
MOCCASIN = Color(_value=4293178879)
NAVAJO_WHITE = Color(_value=4292783615)
NAVY = Color(_value=33023)
OLD_LACE = Color(_value=4260751103)
OLIVE = Color(_value=2155872511)
OLIVE_DRAB = Color(_value=1804477439)
ORANGE = Color(_value=4289003775)
ORANGE_RED = Color(_value=4282712319)
ORCHID = Color(_value=3664828159)
PALE_GOLDENROD = Color(_value=4008225535)
PALE_GREEN = Color(_value=2566625535)
PALE_TURQUOISE = Color(_value=2951671551)
PALE_VIOLET_RED = Color(_value=3681588223)
PAPAYA_WHIP = Color(_value=4293907967)
PEACH_PUFF = Color(_value=4292524543)
PERU = Color(_value=3448061951)
PINK = Color(_value=4290825215)
PLUM = Color(_value=3718307327)
POWDER_BLUE = Color(_value=2967529215)
PURPLE = Color(_value=2147516671)
RED = Color(_value=4278190335)
ROSY_BROWN = Color(_value=3163525119)
ROYAL_BLUE = Color(_value=1097458175)
SADDLE_BROWN = Color(_value=2336560127)
SALMON = Color(_value=4202722047)
SANDY_BROWN = Color(_value=4104413439)
SEA_GREEN = Color(_value=780883967)
SEA_SHELL = Color(_value=4294307583)
SIENNA = Color(_value=2689740287)
SILVER = Color(_value=3233857791)
SKY_BLUE = Color(_value=2278484991)
SLATE_BLUE = Color(_value=1784335871)
SLATE_GRAY = Color(_value=1887473919)
SNOW = Color(_value=4294638335)
SPRING_GREEN = Color(_value=16744447)
STEEL_BLUE = Color(_value=1182971135)
TAN = Color(_value=3535047935)
TEAL = Color(_value=8421631)
THISTLE = Color(_value=3636451583)
TOMATO = Color(_value=4284696575)
TRANSPARENT = Color(_value=4294967040)
TURQUOISE = Color(_value=1088475391)
VIOLET = Color(_value=4001558271)
WHEAT = Color(_value=4125012991)
WHITE = Color(_value=4294967295)
WHITE_SMOKE = Color(_value=4126537215)
YELLOW = Color(_value=4294902015)
YELLOW_GREEN = Color(_value=2597139199)
property a: int
property alpha: int

Gets the alpha component value of this color.

Returns:

The alpha component value between 0 and 255.

property b: int
property blue: int

Gets the blue component value of this color.

Returns:

The blue component value between 0 and 255.

classmethod from_color_with_alpha(base_color: Color, a: int) → Color

Creates a color from the specified base color with a new alpha value.

Parameters:

  • base_color – The Color from which to derive the RGB values.

  • a – The alpha component value (0-255).

Returns:

A new Color with the RGB values from the base color and the specified alpha value.

classmethod from_hex(hex_triplet: str) → Color

Creates a color from a hex triplet (RGB, RRGGBB, or RRGGBBAA without hash).

A hex triplet is either three, six, or eight hexadecimal digits that represent an RGB or RGBA color. An example of a hex triplet is “09C” or “0099CC”, which both represent the same color.

Parameters:

hex_triplet – A string containing hex digits like “09C”, “0099CC”, or “0099CCFF”.

Returns:

A new Color.

Raises:

ValueError – If the string is not valid hex digits (3, 6, or 8 characters).

classmethod from_hex_color(hex_color: str | None) → Color | None

Creates a color from a hex color string (#RGB, #RRGGBB, or #RRGGBBAA).

This method works the same as from_hex() except that it requires a hash sign before the hex value. An example of a numeric RGB value is “#09C” or “#0099CC”, which both represent the same color.

Parameters:

hex_color – A string containing a hex color like “#09C”, “#0099CC”, or “#0099CCFF”.

Returns:

A new Color; None if the input is None.

Raises:

ValueError – If the string is not in valid numeric RGB format.

classmethod from_rgb(r: int, g: int, b: int) → Color

Creates a color from the specified red, green, and blue values with alpha 255 (fully opaque).

Parameters:

  • r – The red component value (0-255).

  • g – The green component value (0-255).

  • b – The blue component value (0-255).

Returns:

A new Color initialized with the specified RGB values and an alpha value of 255.

classmethod from_rgba(r: int, g: int, b: int, a: int) → Color

Creates a color from the specified red, green, blue, and alpha values.

Parameters:

  • r – The red component value (0-255).

  • g – The green component value (0-255).

  • b – The blue component value (0-255).

  • a – The alpha component value (0-255).

Returns:

A new Color initialized with the specified RGBA values.

classmethod from_rgba_value(rgba: int) → Color

Creates a color from a 32-bit RGBA value.

Parameters:

rgba – A 32-bit value specifying the RGBA components.

Returns:

A new Color initialized with the specified RGBA value.

property g: int
property green: int

Gets the green component value of this color.

Returns:

The green component value between 0 and 255.

property r: int
property red: int

Gets the red component value of this color.

Returns:

The red component value between 0 and 255.

to_color_schema() → Color

Converts this color to the schema Color representation used by the API.

Note

The returned hex string uses lowercase letters for compatibility with the Python schema representation.

Returns:

A Color schema object with the hex value set.

to_hex_color() → str

Converts the color to its hexadecimal representation.

Returns:

  • If alpha is 255 (fully opaque), returns “#RRGGBB”.

  • If alpha is not 255, returns “#RRGGBBAA”.

Return type:

A string representing the color in hexadecimal format

to_rgba() → int

Converts this Color to a 32-bit RGBA value.

Returns:

A 32-bit integer containing the RGBA representation of this color.

bullet_id: int
owner_id: int
power: float
x: float
y: float
direction: float
color: Color
property speed: float

Calculates and returns the speed of the bullet in units per turn. The speed decreases with higher firepower levels.

Formula:

speed = 20 - 3 * power

Returns:

The calculated speed of the bullet in units per turn.

Return type:

float

class Color(_value: int)[source]

Bases: object

Represents an RGBA (red, green, blue, alpha) color used in the Tank Royale game.

This graphics Color implementation contains: - Internal 32-bit RGBA value - Factory methods from_rgb(), from_rgba(r,g,b,a), and from_rgba_value(rgba) - Read-only channel properties: red, green, blue, alpha (mapped to R,G,B,A) - to_rgba() for round-trip, to_hex_color() for hex string - Equality/hash based on RGBA value - Many predefined common colors

Note: For compatibility with existing Python code, to_color_schema() is preserved and uses lowercase hex values as before.

classmethod from_rgba_value(rgba: int) → Color[source]

Creates a color from a 32-bit RGBA value.

Parameters:

rgba – A 32-bit value specifying the RGBA components.

Returns:

A new Color initialized with the specified RGBA value.

classmethod from_rgba(r: int, g: int, b: int, a: int) → Color[source]

Creates a color from the specified red, green, blue, and alpha values.

Parameters:

  • r – The red component value (0-255).

  • g – The green component value (0-255).

  • b – The blue component value (0-255).

  • a – The alpha component value (0-255).

Returns:

A new Color initialized with the specified RGBA values.

classmethod from_rgb(r: int, g: int, b: int) → Color[source]

Creates a color from the specified red, green, and blue values with alpha 255 (fully opaque).

Parameters:

  • r – The red component value (0-255).

  • g – The green component value (0-255).

  • b – The blue component value (0-255).

Returns:

A new Color initialized with the specified RGB values and an alpha value of 255.

classmethod from_color_with_alpha(base_color: Color, a: int) → Color[source]

Creates a color from the specified base color with a new alpha value.

Parameters:

  • base_color – The Color from which to derive the RGB values.

  • a – The alpha component value (0-255).

Returns:

A new Color with the RGB values from the base color and the specified alpha value.

classmethod from_hex_color(hex_color: str | None) → Color | None[source]

Creates a color from a hex color string (#RGB, #RRGGBB, or #RRGGBBAA).

This method works the same as from_hex() except that it requires a hash sign before the hex value. An example of a numeric RGB value is “#09C” or “#0099CC”, which both represent the same color.

Parameters:

hex_color – A string containing a hex color like “#09C”, “#0099CC”, or “#0099CCFF”.

Returns:

A new Color; None if the input is None.

Raises:

ValueError – If the string is not in valid numeric RGB format.

classmethod from_hex(hex_triplet: str) → Color[source]

Creates a color from a hex triplet (RGB, RRGGBB, or RRGGBBAA without hash).

A hex triplet is either three, six, or eight hexadecimal digits that represent an RGB or RGBA color. An example of a hex triplet is “09C” or “0099CC”, which both represent the same color.

Parameters:

hex_triplet – A string containing hex digits like “09C”, “0099CC”, or “0099CCFF”.

Returns:

A new Color.

Raises:

ValueError – If the string is not valid hex digits (3, 6, or 8 characters).

property red: int

Gets the red component value of this color.

Returns:

The red component value between 0 and 255.

property green: int

Gets the green component value of this color.

Returns:

The green component value between 0 and 255.

property blue: int

Gets the blue component value of this color.

Returns:

The blue component value between 0 and 255.

property alpha: int

Gets the alpha component value of this color.

Returns:

The alpha component value between 0 and 255.

property r: int
property g: int
property b: int
property a: int
to_rgba() → int[source]

Converts this Color to a 32-bit RGBA value.

Returns:

A 32-bit integer containing the RGBA representation of this color.

to_hex_color() → str[source]

Converts the color to its hexadecimal representation.

Returns:

  • If alpha is 255 (fully opaque), returns “#RRGGBB”.

  • If alpha is not 255, returns “#RRGGBBAA”.

Return type:

A string representing the color in hexadecimal format

to_color_schema() → Color[source]

Converts this color to the schema Color representation used by the API.

Note

The returned hex string uses lowercase letters for compatibility with the Python schema representation.

Returns:

A Color schema object with the hex value set.

ALICE_BLUE = Color(_value=4042850303)
ANTIQUE_WHITE = Color(_value=4209760255)
AQUA = Color(_value=16777215)
AQUAMARINE = Color(_value=2147472639)
AZURE = Color(_value=4043309055)
BEIGE = Color(_value=4126530815)
BISQUE = Color(_value=4293182719)
BLACK = Color(_value=255)
BLANCHED_ALMOND = Color(_value=4293643775)
BLUE = Color(_value=65535)
BLUE_VIOLET = Color(_value=2318131967)
BROWN = Color(_value=2771004159)
BURLY_WOOD = Color(_value=3736635391)
CADET_BLUE = Color(_value=1604231423)
CHARTREUSE = Color(_value=2147418367)
CHOCOLATE = Color(_value=3530104575)
CORAL = Color(_value=4286533887)
CORNFLOWER_BLUE = Color(_value=1687547391)
CORNSILK = Color(_value=4294499583)
CRIMSON = Color(_value=3692313855)
CYAN = Color(_value=16777215)
DARK_BLUE = Color(_value=35839)
DARK_CYAN = Color(_value=9145343)
DARK_GOLDENROD = Color(_value=3095792639)
DARK_GRAY = Color(_value=2846468607)
DARK_GREEN = Color(_value=6553855)
DARK_KHAKI = Color(_value=3182914559)
DARK_MAGENTA = Color(_value=2332068863)
DARK_OLIVE_GREEN = Color(_value=1433087999)
DARK_ORANGE = Color(_value=4287365375)
DARK_ORCHID = Color(_value=2570243327)
DARK_RED = Color(_value=2332033279)
DARK_SALMON = Color(_value=3918953215)
DARK_SEA_GREEN = Color(_value=2411498495)
DARK_SLATE_BLUE = Color(_value=1211993087)
DARK_SLATE_GRAY = Color(_value=793726975)
DARK_TURQUOISE = Color(_value=13554175)
DARK_VIOLET = Color(_value=2483082239)
DEEP_PINK = Color(_value=4279538687)
DEEP_SKY_BLUE = Color(_value=12582911)
DIM_GRAY = Color(_value=1768516095)
DODGER_BLUE = Color(_value=512819199)
FIREBRICK = Color(_value=2988581631)
FLORAL_WHITE = Color(_value=4294635775)
FOREST_GREEN = Color(_value=579543807)
FUCHSIA = Color(_value=4278255615)
GAINSBORO = Color(_value=3705462015)
GHOST_WHITE = Color(_value=4177068031)
GOLD = Color(_value=4292280575)
GOLDENROD = Color(_value=3668254975)
GRAY = Color(_value=2155905279)
GREEN = Color(_value=8388863)
GREEN_YELLOW = Color(_value=2919182335)
HONEYDEW = Color(_value=4043305215)
HOT_PINK = Color(_value=4285117695)
INDIAN_RED = Color(_value=3445382399)
INDIGO = Color(_value=1258324735)
IVORY = Color(_value=4294963455)
KHAKI = Color(_value=4041641215)
LAVENDER = Color(_value=3873897215)
LAVENDER_BLUSH = Color(_value=4293981695)
LAWN_GREEN = Color(_value=2096890111)
LEMON_CHIFFON = Color(_value=4294626815)
LIGHT_BLUE = Color(_value=2916673279)
LIGHT_CORAL = Color(_value=4034953471)
LIGHT_CYAN = Color(_value=3774873599)
LIGHT_GOLDENROD_YELLOW = Color(_value=4210742015)
LIGHT_GRAY = Color(_value=3553874943)
LIGHT_GREEN = Color(_value=2431553791)
LIGHT_PINK = Color(_value=4290167295)
LIGHT_SALMON = Color(_value=4288707327)
LIGHT_SEA_GREEN = Color(_value=548580095)
LIGHT_SKY_BLUE = Color(_value=2278488831)
LIGHT_SLATE_GRAY = Color(_value=2005441023)
LIGHT_STEEL_BLUE = Color(_value=2965692159)
LIGHT_YELLOW = Color(_value=4294959359)
LIME = Color(_value=16711935)
LIME_GREEN = Color(_value=852308735)
LINEN = Color(_value=4210091775)
MAGENTA = Color(_value=4278255615)
MAROON = Color(_value=2147483903)
MEDIUM_AQUAMARINE = Color(_value=1724754687)
MEDIUM_BLUE = Color(_value=52735)
MEDIUM_ORCHID = Color(_value=3126187007)
MEDIUM_PURPLE = Color(_value=2473647103)
MEDIUM_SEA_GREEN = Color(_value=1018393087)
MEDIUM_SLATE_BLUE = Color(_value=2070474495)
MEDIUM_SPRING_GREEN = Color(_value=16423679)
MEDIUM_TURQUOISE = Color(_value=1221709055)
MEDIUM_VIOLET_RED = Color(_value=3340076543)
MIDNIGHT_BLUE = Color(_value=421097727)
MINT_CREAM = Color(_value=4127193855)
MISTY_ROSE = Color(_value=4293190143)
MOCCASIN = Color(_value=4293178879)
NAVAJO_WHITE = Color(_value=4292783615)
NAVY = Color(_value=33023)
OLD_LACE = Color(_value=4260751103)
OLIVE = Color(_value=2155872511)
OLIVE_DRAB = Color(_value=1804477439)
ORANGE = Color(_value=4289003775)
ORANGE_RED = Color(_value=4282712319)
ORCHID = Color(_value=3664828159)
PALE_GOLDENROD = Color(_value=4008225535)
PALE_GREEN = Color(_value=2566625535)
PALE_TURQUOISE = Color(_value=2951671551)
PALE_VIOLET_RED = Color(_value=3681588223)
PAPAYA_WHIP = Color(_value=4293907967)
PEACH_PUFF = Color(_value=4292524543)
PERU = Color(_value=3448061951)
PINK = Color(_value=4290825215)
PLUM = Color(_value=3718307327)
POWDER_BLUE = Color(_value=2967529215)
PURPLE = Color(_value=2147516671)
RED = Color(_value=4278190335)
ROSY_BROWN = Color(_value=3163525119)
ROYAL_BLUE = Color(_value=1097458175)
SADDLE_BROWN = Color(_value=2336560127)
SALMON = Color(_value=4202722047)
SANDY_BROWN = Color(_value=4104413439)
SEA_GREEN = Color(_value=780883967)
SEA_SHELL = Color(_value=4294307583)
SIENNA = Color(_value=2689740287)
SILVER = Color(_value=3233857791)
SKY_BLUE = Color(_value=2278484991)
SLATE_BLUE = Color(_value=1784335871)
SLATE_GRAY = Color(_value=1887473919)
SNOW = Color(_value=4294638335)
SPRING_GREEN = Color(_value=16744447)
STEEL_BLUE = Color(_value=1182971135)
TAN = Color(_value=3535047935)
TEAL = Color(_value=8421631)
THISTLE = Color(_value=3636451583)
TOMATO = Color(_value=4284696575)
TRANSPARENT = Color(_value=4294967040)
TURQUOISE = Color(_value=1088475391)
VIOLET = Color(_value=4001558271)
WHEAT = Color(_value=4125012991)
WHITE = Color(_value=4294967295)
WHITE_SMOKE = Color(_value=4126537215)
YELLOW = Color(_value=4294902015)
YELLOW_GREEN = Color(_value=2597139199)
class DefaultEventPriority[source]

Bases: object

Default event priorities values. The higher value, the higher event priority. So the WonRoundEvent has the highest priority (150), and DeathEvent has the lowest priority (10).

WON_ROUND = 150

Event priority for the WonRoundEvent

SKIPPED_TURN = 140

Event priority for the SkippedTurnEvent

TICK = 130

Event priority for the TickEvent

CUSTOM = 120

Event priority for the CustomEvent

TEAM_MESSAGE = 110

Event priority for the TeamMessageEvent

BOT_DEATH = 100

Event priority for the BotDeathEvent

BULLET_HIT_WALL = 90

Event priority for the BulletHitWallEvent

BULLET_HIT_BULLET = 80

Event priority for the BulletHitBulletEvent

BULLET_HIT_BOT = 70

Event priority for the BulletHitBotEvent

BULLET_FIRED = 60

Event priority for the BulletFiredEvent

HIT_BY_BULLET = 50

Event priority for the HitByBulletEvent

HIT_WALL = 40

Event priority for the HitWallEvent

HIT_BOT = 30

Event priority for the HitBotEvent

SCANNED_BOT = 20

Event priority for the ScannedBotEvent

DEATH = 10

Event priority for the DeathEvent

class DroidABC[source]

Bases: ABC

An abstract base class representing a specialized droid bot for team-based operations.

A droid bot starts with 120 energy points, 20 more than a standard robot, but it lacks a scanner. Due to this limitation, droids rely entirely on their teammates to perform scanning tasks and share critical information, such as the coordinates of target enemies.

Teams composed of droids and at least one non-droid team member gain a strategic advantage over similarly sized teams without droids, thanks to the increased energy pool.

class GameSetup(game_type: str, arena_width: int, arena_height: int, number_of_rounds: int, gun_cooling_rate: float, max_inactivity_turns: int, turn_timeout: int, ready_timeout: int)[source]

Bases: object

Game setup retrieved when game is started.

game_type: str

Game type, e.g. “melee”.

arena_width: int

Width of the arena measured in units.

arena_height: int

Height of the arena measured in units.

number_of_rounds: int

Number of rounds in a battle.

gun_cooling_rate: float

Gun cooling rate. The gun needs to cool down to a gun heat of zero before the gun is able to fire.

max_inactivity_turns: int

Maximum number of inactive turns allowed, where a bot does not take any action before it is zapped by the game.

turn_timeout: int

The turn timeout in microseconds (µs) (where 1 microsecond equals 1/1,000,000 of a second).

ready_timeout: int

The ready timeout in microseconds (µs) (where 1 microsecond equals 1/1,000,000 of a second).

class GameType[source]

Bases: object

Predefined game types. These game types are described here: https://robocode-dev.github.io/tank-royale/articles/game_types.html

CLASSIC = 'classic'

Classic (standard) battle with a minimum of 2 bots battling each other on an arena size of 800 x 600 units.

MELEE = 'melee'

Melee battle with a minimum of 10 bots battling each other on an arena of 1000 x 1000 units.

ONE_VS_ONE = '1v1'

One versus one (1-vs-1) battle between exactly two bots alone on an arena of 1000 x 1000 units.

class InitialPosition(x: float | None, y: float | None, direction: float | None)[source]

Bases: object

Represents the initial position of a bot during debugging, with optional specific coordinates (x, y) and a shared direction for the body, gun, and radar. If not specified, the values are assigned randomly.

Note

The initial position is only applied when debugging and if enabled on the server-side. Otherwise, it will be ignored.

x: float | None

Optional x-coordinate for the starting position. If None, it will be randomly assigned.

y: float | None

Optional y-coordinate for the starting position. If None, it will be randomly assigned.

direction: float | None

Optional shared direction for the body, gun, and radar. If None, it will be randomly assigned.

static from_string(initial_position: str) → InitialPosition | None[source]

Creates an InitialPosition instance from a string.

Parameters:

  • initial_position (str) – A string containing coordinates and direction,

  • whitespace. (separated by commas and/or)

Returns:

An instance of the class if parsing is successful. None: If the input string is invalid or empty.

Return type:

InitialPosition

class BaseBot(bot_info: BotInfo | None = None, server_url: str | None = None, server_secret: str | None = None)[source]

Bases: BaseBotABC

BaseBot is a base class for creating Robocode Tank Royale bots.

Configuration and defaults:

  • By default, the constructor attempts to load a bot config JSON named <ClassName>.json located next to your bot class. If not found or incomplete, environment variables are used instead.

  • SERVER_URL can be set to the WebSocket URL of the server. If not set, ws://localhost:7654 is used.

  • SERVER_SECRET is optional. Set it only if the server requires a secret for connecting bots. If the server enforces secrets and none is provided, the server will disconnect the bot.

  • When no config file is used, these BotInfo environment variables must be provided: BOT_NAME, BOT_VERSION, BOT_AUTHORS. Optional vars include: BOT_DESCRIPTION, BOT_HOMEPAGE, BOT_COUNTRY_CODES, BOT_GAME_TYPES, BOT_PLATFORM, BOT_PROG_LANG, BOT_INITIAL_POS.

You can also pass bot_info, server_url, and server_secret explicitly via the constructor.

start() → None[source]

The method used to start running the bot. You should call this method from the main method or similar.

Example

if __name__ == “__main__”:

# create my_bot … my_bot.start()

go() → None[source]

Commits the current commands (actions), which finalizes the current turn for the bot.

This method must be called once per turn to send the bot actions to the server and must be called before the turn timeout occurs. A turn timer is started when the GameStartedEvent and TickEvent occurs. If the go() method is called too late, a turn timeout will occur and the SkippedTurnEvent will occur, which means that the bot has skipped all actions for the last turn. In this case, the server will continue executing the last actions received. This could be fatal for the bot due to loss of control over the bot. So make sure that go() is called before the turn ends.

The commands executed when go() is called are set by calling the various setter methods prior to calling the go() method: turn_rate, gun_turn_rate, radar_turn_rate, target_speed, and set_fire().

See also

turn_timeout

property my_id: int

Unique id of this bot, which is available when the game has started.

Returns:

The unique id of this bot.

property variant: str

The game variant, which is “Tank Royale”.

Returns:

The game variant of Robocode.

property version: str

Game version, e.g. “1.0.0”.

Returns:

The game version.

property game_type: str

Game type, e.g. “melee” or “1v1”.

First available when the game has started.

Returns:

The game type.

property arena_width: int

Width of the arena measured in units.

First available when the game has started.

Returns:

The arena width measured in units.

property arena_height: int

Height of the arena measured in units.

First available when the game has started.

Returns:

The arena height measured in units.

property number_of_rounds: int

The number of rounds in a battle.

First available when the game has started.

Returns:

The number of rounds in a battle.

property gun_cooling_rate: float

Gun cooling rate. The gun needs to cool down to a gun heat of zero before the gun can fire. The gun cooling rate determines how fast the gun cools down. That is, the gun cooling rate is subtracted from the gun heat each turn until the gun heat reaches zero.

First available when the game has started.

Returns:

The gun cooling rate.

See also

gun_heat

property max_inactivity_turns: int

The maximum number of inactive turns allowed the bot will become zapped by the game for being inactive. Inactive means that the bot has taken no action in several turns in a row.

First available when the game has started.

Returns:

The maximum number of allowed inactive turns.

property turn_timeout: int

The turn timeout is important as the bot needs to take action by calling go() before the turn timeout occurs. As soon as the TickEvent is triggered, i.e. when on_tick() is called, you need to call go() to take action before the turn timeout occurs. Otherwise, your bot will skip a turn and receive a on_skipped_turn() for each turn where go() is called too late.

First available when the game has started.

Returns:

The turn timeout in microseconds (1 / 1,000,000 second).

See also

time_left, go

property time_left: int

The number of microseconds left of this turn before the bot will skip the turn. Make sure to call go() before the time runs out.

Returns:

The amount of time left in microseconds.

See also

turn_timeout, go

property round_number: int

Current round number.

Returns:

The current round number.

property turn_number: int

Current turn number.

Returns:

The current turn number.

property enemy_count: int

Number of enemies left in the round.

Returns:

The number of enemies left in the round.

property energy: float

Current energy level. When the energy level is positive, the bot is alive and active. When the energy level is 0, the bot is still alive but disabled. If the bot becomes disabled it will not be able to move or take any action. If negative, the bot has been defeated.

Returns:

The current energy level.

property disabled: bool

Specifies if the bot is disabled, i.e., when the energy is zero. When the bot is disabled, it is not able to take any action like movement, turning, and firing.

Returns:

True if the bot is disabled; False otherwise.

property x: float

Current X coordinate of the center of the bot.

Returns:

The current X coordinate of the bot.

property y: float

Current Y coordinate of the center of the bot.

Returns:

The current Y coordinate of the bot.

property direction: float

Current driving direction of the bot in degrees.

Returns:

The current driving direction of the bot.

property gun_direction: float

Current direction of the gun in degrees.

Returns:

The current gun direction of the bot.

property radar_direction: float

Current direction of the radar in degrees.

Returns:

The current radar direction of the bot.

property speed: float

The current speed measured in units per turn. If the speed is positive, the bot moves forward. If negative, the bot moves backward. Zero speed means that the bot is not moving from its current position.

Returns:

The current speed.

property gun_heat: float

Current gun heat. When the gun is fired it gets heated and will not be able to fire before it has been cooled down. The gun is cooled down when the gun heat is zero.

When the gun has fired the gun heat is set to 1 + (firepower / 5) and will be cooled down by the gun cooling rate.

Returns:

The current gun heat.

See also

gun_cooling_rate

property bullet_states: Sequence[BulletState | None] | None

Current bullet states. Keeps track of all the bullets fired by the bot, which are still active on the arena.

Returns:

The current bullet states.

property events: Sequence[BotEvent | None] | None

Returns an ordered list containing all events currently in the bot’s event queue. You might, for example, call this while processing another event.

Returns:

An ordered list containing all events currently in the bot’s event queue.

See also

clear_events

clear_events() → None[source]

Clears out any pending events in the bot’s event queue immediately.

See also

events

property turn_rate: float

Returns the turn rate of the bot in degrees per turn.

Returns:

The turn rate of the bot.

property max_turn_rate: float

Returns the maximum turn rate of the bot in degrees per turn.

Returns:

The maximum turn rate of the bot.

property gun_turn_rate: float

Returns the gun turn rate in degrees per turn.

Returns:

The gun turn rate.

property max_gun_turn_rate: float

Returns the maximum gun turn rate in degrees per turn.

Returns:

The maximum gun turn rate.

property radar_turn_rate: float

Returns the radar turn rate in degrees per turn.

Returns:

The radar turn rate.

property max_radar_turn_rate: float

Returns the maximum radar turn rate in degrees per turn.

Returns:

The maximum radar turn rate.

property target_speed: float

Returns the target speed in units per turn.

Returns:

The target speed.

property max_speed: float

Returns the maximum speed in units per turn.

Returns:

The maximum speed.

set_fire(firepower: float) → bool[source]

Sets the gun to fire in the direction the gun is pointing with the specified firepower.

Parameters:

firepower – The firepower to use for firing.

Returns:

True if the gun will fire; False otherwise.

property firepower: float

Returns the firepower set for firing the gun.

Returns:

The firepower.

set_rescan() → None[source]

Sets the radar to rescan with the radar.

set_fire_assist(enable: bool) → None[source]

Enables or disables fire assistance.

Parameters:

enable – True to enable fire assist; False to disable.

set_interruptible(interruptible: bool) → None[source]

Sets whether the bot’s event handlers are interruptible.

When set to True, the bot’s event handlers can be interrupted by higher-priority events. When set to False, event handlers will run to completion before other events are processed.

Parameters:

interruptible (bool) – If True, event handlers are interruptible; otherwise, they are not.

property adjust_gun_for_body_turn: bool

Returns whether the gun adjusts for the bot’s body turn.

property adjust_radar_for_body_turn: bool

Returns whether the radar adjusts for the bot’s body turn.

property adjust_radar_for_gun_turn: bool

Returns whether the radar adjusts for the gun’s turn.

add_custom_event(condition: Condition) → bool[source]

Adds a custom event based on a condition. When the condition is met, the on_custom_event() handler is triggered with a CustomEvent containing the condition.

Parameters:

condition – The condition that must be met to trigger the custom event.

Returns:

True if the condition was added; False if it already exists.

remove_custom_event(condition: Condition) → bool[source]

Removes a custom event that was previously added with add_custom_event().

Parameters:

condition – The condition to remove.

Returns:

True if the condition was removed; False if it was not found.

set_stop(overwrite: bool = False) → None[source]

Sets the bot to stop all movement including turning the gun and radar. The remaining movement is saved for a call to set_resume() or resume().

Parameters:

overwrite – True to override a previously saved movement from stop() or set_stop().

set_resume() → None[source]

Sets the bot to resume the movement prior to calling set_stop() or stop().

property teammate_ids: set[int]

Returns the IDs of all teammates.

Returns:

A set of teammate IDs.

is_teammate(bot_id: int) → bool[source]

Checks if the specified bot ID is a teammate.

Parameters:

bot_id – The bot ID to check.

Returns:

True if the bot is a teammate; False otherwise.

broadcast_team_message(message: Any) → None[source]

Broadcasts a message to all teammates.

Parameters:

message – The message to broadcast.

send_team_message(teammate_id: int, message: Any) → None[source]

Sends a message to a specific teammate.

Parameters:

  • teammate_id – The ID of the teammate to send the message to.

  • message – The message to send.

property stopped: bool

Checks if the bot is currently stopped.

Returns:

True if the bot is stopped; False otherwise.

property body_color: Color | None

Returns the color of the body.

Returns:

The body color or None if not set.

MAX_NUMBER_OF_TEAM_MESSAGES_PER_TURN: int = 10

The maximum number of team messages that can be sent per turn, which is 10 messages.

TEAM_MESSAGE_MAX_SIZE: int = 32768

Maximum size of a team message, which is 32 KB.

bearing_to(x: float, y: float) → float

Calculates the bearing (delta angle) between the bot’s current direction and the direction to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

A bearing to the point (x, y) in the range [-180, 180).

Return type:

float

calc_bearing(direction: float) → float

Calculates the bearing (delta angle) between the input direction and the bot’s direction.

Example

bearing = calc_bearing(direction) = normalize_relative_degrees(direction - self.direction)

Parameters:

direction (float) – The input direction to calculate the bearing from.

Returns:

A normalized bearing (delta angle) in the range [-180, 180).

Return type:

float

See also

direction, normalize_relative_angle.

calc_delta_angle(target_angle: float, source_angle: float) → float

Calculates the difference between two angles, i.e., the number of degrees from a source angle to a target angle.

Parameters:

  • target_angle (float) – The target angle.

  • source_angle (float) – The source angle.

Returns:

The delta angle in the range [-180, 180].

Return type:

float

calc_gun_bearing(direction: float) → float

Calculates the bearing (delta angle) between the input direction and the gun’s direction.

Example

bearing = calc_gun_bearing(direction) =

normalize_relative_degrees(direction - self.gun_direction)

Parameters:

direction (float) – The input direction to calculate the bearing from.

Returns:

A normalized bearing (delta angle) in the range [-180, 180).

Return type:

float

See also

gun_direction, normalize_relative_angle.

calc_radar_bearing(direction: float) → float

Calculates the bearing (delta angle) between the input direction and the radar’s direction.

Example

bearing = calc_radar_bearing(direction) =

normalize_relative_degrees(direction - self.radar_direction)

Parameters:

direction (float) – The input direction to calculate the bearing from.

Returns:

A normalized bearing (delta angle) in the range [-180, 180).

Return type:

float

See also

radar_direction, normalize_relative_angle.

direction_to(x: float, y: float) → float

Calculates the direction (angle) from the bot’s coordinates to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

The direction to the point (x, y) in the range [0, 360).

Return type:

float

distance_to(x: float, y: float) → float

Calculates the distance from the bot’s coordinates to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

The distance to the point (x, y).

Return type:

float

gun_bearing_to(x: float, y: float) → float

Calculates the bearing (delta angle) between the gun’s current direction and the direction to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

A bearing to the point (x, y) in the range [-180, 180).

Return type:

float

normalize_absolute_angle(angle: float) → float

Normalizes an angle to an absolute angle in the range [0, 360).

Parameters:

angle (float) – The angle to normalize.

Returns:

The normalized absolute angle.

Return type:

float

normalize_relative_angle(angle: float) → float

Normalizes the given angle to the range [-180, 180] degrees.

Parameters:

angle (float) – The angle to normalize.

Returns:

The normalized angle in degrees.

Return type:

float

on_bot_death(bot_death_event: BotDeathEvent) → None

The event handler triggered when another bot has died.

Parameters:

bot_death_event – The event details from the game.

on_bullet_fired(bullet_fired_event: BulletFiredEvent) → None

The event handler triggered when the bot has fired a bullet.

Parameters:

bullet_fired_event – The event details from the game.

on_bullet_hit(bullet_hit_bot_event: BulletHitBotEvent) → None

The event handler triggered when the bot has hit another bot with a bullet.

Parameters:

bullet_hit_bot_event – The event details from the game.

on_bullet_hit_bullet(bullet_hit_bullet_event: BulletHitBulletEvent) → None

The event handler triggered when a bullet fired from the bot has collided with another bullet.

Parameters:

bullet_hit_bullet_event – The event details from the game.

on_bullet_hit_wall(bullet_hit_wall_event: BulletHitWallEvent) → None

The event handler triggered when a bullet has hit a wall.

Parameters:

bullet_hit_wall_event – The event details from the game.

static on_connected(connected_event: ConnectedEvent) → None

The event handler triggered when connected to the server.

Parameters:

connected_event – The event details from the game.

static on_connection_error(connection_error_event: ConnectionErrorEvent) → None

The event handler triggered when a connection error occurs.

Parameters:

connection_error_event – The event details from the game.

on_custom_event(custom_event: CustomEvent) → None

The event handler triggered when some condition has been met. Use the name of the condition when you need to differentiate between different types of conditions received with this event handler.

Parameters:

custom_event – The event details from the game.

on_death(death_event: DeathEvent) → None

The event handler triggered when this bot has died.

Parameters:

death_event – The event details from the game.

static on_disconnected(disconnected_event: DisconnectedEvent) → None

The event handler triggered when disconnected from the server.

Parameters:

disconnected_event – The event details from the game.

on_game_ended(game_ended_event: GameEndedEvent) → None

The event handler triggered when a game has ended.

Parameters:

game_ended_event – The event details from the game.

on_game_started(game_started_event: GameStartedEvent) → None

The event handler triggered when a game has started.

Parameters:

game_started_event – The event details from the game.

on_hit_bot(bot_hit_bot_event: HitBotEvent) → None

The event handler triggered when the bot has collided with another bot.

Parameters:

bot_hit_bot_event – The event details from the game.

on_hit_by_bullet(hit_by_bullet_event: HitByBulletEvent) → None

The event handler triggered when the bot has been hit by a bullet.

Parameters:

hit_by_bullet_event – The event details from the game.

on_hit_wall(bot_hit_wall_event: HitWallEvent) → None

The event handler triggered when the bot has hit a wall.

Parameters:

bot_hit_wall_event – The event details from the game.

on_round_ended(round_ended_event: RoundEndedEvent) → None

The event handler triggered when a round has ended.

Parameters:

round_ended_event – The event details from the game.

on_round_started(round_started_event: RoundStartedEvent) → None

The event handler triggered when a new round has started.

Parameters:

round_started_event – The event details from the game.

on_scanned_bot(scanned_bot_event: ScannedBotEvent) → None

The event handler triggered when the bot has skipped a turn. This event occurs if the bot did not take any action in a specific turn. That is, go() was not called before the turn timeout occurred for the turn. If the bot does not take action for multiple turns in a row, it will receive a SkippedTurnEvent for each turn where it did not take action. When the bot is skipping a turn, the server did not receive the message from the bot, and the server will use the newest received instructions for target speed, turn rates, firing, etc.

Parameters:

scanned_bot_event – The event details from the game.

on_skipped_turn(skipped_turn_event: SkippedTurnEvent) → None

Handles the event triggered when the bot skips a turn.

A turn is skipped if the bot does not send any instructions to the server (via the go() method) before the turn timeout occurs. When this happens, the server continues using the last received set of actions, such as movement, turning rates, or firing commands.

Reasons for skipped turns may include:

  • Excessive processing or delays in the bot’s logic, leading to a timeout.

  • Failure to invoke the go() method in the current turn.

  • Misaligned or unintended logic in the bot’s turn-handling code.

This method can be overridden to define custom behavior for handling skipped turns, such as logging the event, debugging performance issues, or modifying the bot’s logic to avoid future skips.

Parameters:

skipped_turn_event – An event containing details about the skipped turn.

on_team_message(team_message_event: TeamMessageEvent) → None

The event handler triggered when the bot has received a message from a teammate.

Parameters:

team_message_event – The event details from the game.

on_tick(tick_event: TickEvent) → None

The event handler triggered when a game tick event occurs, i.e., when a new turn in a round has started.

Parameters:

tick_event – The event details from the game.

on_won_round(won_round_event: WonRoundEvent) → None

The event handler triggered when the bot has won a round.

Parameters:

won_round_event – The event details from the game.

radar_bearing_to(x: float, y: float) → float

Calculates the bearing (delta angle) between the radar’s current direction and the direction to a point (x, y).

Parameters:

  • x (float) – The x-coordinate of the point.

  • y (float) – The y-coordinate of the point.

Returns:

A bearing to the point (x, y) in the range [-180, 180).

Return type:

float

property turret_color: Color | None

Returns the color of the turret.

Returns:

The turret color or None if not set.

property radar_color: Color | None

Returns the color of the radar.

Returns:

The radar color or None if not set.

property bullet_color: Color | None

Returns the color of the bullets.

Returns:

The bullet color or None if not set.

property scan_color: Color | None

Returns the color of the scan arc.

Returns:

The scan color or None if not set.

property tracks_color: Color | None

Returns the color of the tracks.

Returns:

The tracks color or None if not set.

property gun_color: Color | None

Returns the color of the gun.

Returns:

The gun color or None if not set.

property debugging_enabled: bool

Checks if debugging is enabled for this bot.

Returns:

True if debugging is enabled; False otherwise.

property graphics: GraphicsABC

Returns the graphics context for drawing debug graphics.

Returns:

The graphics context.

calc_max_turn_rate(speed: float) → float[source]

Calculates the maximum turn rate for a given speed.

Parameters:

speed – The speed.

Returns:

The maximum turn rate at the given speed.

calc_bullet_speed(firepower: float) → float[source]

Calculates the bullet speed for a given firepower.

Parameters:

firepower – The firepower.

Returns:

The bullet speed.

calc_gun_heat(firepower: float) → float[source]

Calculates the gun heat generated by firing with a given firepower.

Parameters:

firepower – The firepower.

Returns:

The gun heat generated.

get_event_priority(event_class: type) → int[source]

Returns the priority of an event class.

Parameters:

event_class – The event class.

Returns:

The priority of the event class.

set_event_priority(event_class: type, priority: int) → None[source]

Sets the priority of an event class.

Parameters:

  • event_class – The event class.

  • priority – The new priority.

team_message_type(cls: Type[Any]) → Type[Any][source]

Decorator to register a class as a team message type.

The class name is used as the message type identifier for serialization.

Parameters:

cls – The class to register.

Returns:

The same class, unmodified.

Example:

@team_message_type
@dataclass
class RobotColors:
    body_color: Color
    turret_color: Color
register_team_message_type(cls: Type[Any]) → None[source]

Register a class as a team message type.

The class name is used as the message type identifier for serialization.

Parameters:

cls – The class to register.

Example

register_team_message_type(Point)