bot_api.internal package

Submodules

bot_api.internal.base_bot_internals module

class BaseBotInternals(base_bot: BaseBotABC, bot_info: BotInfo | None, server_url: str | None, server_secret: str | None)

Bases: object

property my_id: int

property teammate_ids: Set[int]

property game_setup: GameSetup

property initial_position: InitialPosition | None

get_bot_intent() → BotIntent

property tick_event: TickEvent | None

property current_tick_or_throw: TickEvent

get_current_tick_or_throw() → TickEvent

set_tick_event(tick_event: TickEvent) → None

property current_tick_or_null: TickEvent | None

get_current_tick_or_null() → TickEvent | None

property tick_start_nano_time: int

get_tick_start_nano_time() → int

set_tick_start_nano_time(tick_start_nano_time: int) → None

get_time_left() → int

property event_handling_disabled_turn: int

enable_event_handling(enable: bool) → None

is_event_handling_disabled() → bool

get_events() → Sequence[BotEvent]

clear_events() → None

add_events_from_tick(event: TickEvent) → None

add_event(event: BotEvent) → None

set_interruptible(interruptible: bool) → None

dispatch_events(turn_number: int) → None

set_running(is_running: bool) → None

is_running() → bool

start_thread(bot: BotABC) → None

Start bot thread (matches Java’s startThread)

stop_thread() → None

Stop bot thread (matches Java’s stopThread)

start() → None

Start bot and block until game ends (matches Java’s start)

execute(captured_turn_number: int) → None

Execute bot intent and wait for next turn.

Parameters:

captured_turn_number – The turn number captured by go() at the time events were dispatched, or -1 if no tick was available.

set_fire(firepower: float) → bool

Set fire with given firepower. Matches Java’s setFire() semantics exactly.

get_gun_heat() → float

get_speed() → float

property turn_rate: float

property gun_turn_rate: float

property radar_turn_rate: float

property target_speed: float | None

get_max_speed() → float

set_max_speed(max_speed: float) → None

get_max_turn_rate() → float

set_max_turn_rate(max_turn_rate: float) → None

get_max_gun_turn_rate() → float

set_max_gun_turn_rate(max_gun_turn_rate: float) → None

get_max_radar_turn_rate() → float

set_max_radar_turn_rate(max_radar_turn_rate: float) → None

get_new_target_speed(speed: float, distance: float) → float

get_distance_traveled_until_stop(speed: float) → float

property conditions: Set[Condition]

add_condition(condition: Condition) → bool

remove_condition(condition: Condition) → bool

set_stop(overwrite: bool) → None

set_resume() → None

is_teammate(bot_id: int) → bool

broadcast_team_message(message: Any) → None

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

property body_color: Color | None

property turret_color: Color | None

property radar_color: Color | None

property bullet_color: Color | None

property scan_color: Color | None

property tracks_color: Color | None

property gun_color: Color | None

get_graphics() → GraphicsABC

get_bullet_states() → Sequence[BulletState | None]

property server_handshake: ServerHandshake

property variant: str

property version: str

bot_api.internal.bot_event_handlers module

Class used for bot event handlers on the public API.

These handlers may or may not be triggered by the bot event queue, and might not be handled immediately by the bot logic.

class BotEventHandlers(base_bot: BaseBotABC)

Bases: object

Class used for bot event handlers on the public API.

These handlers may or may not be triggered by the bot event queue, and might not be handled immediately by the bot logic.

__init__(base_bot: BaseBotABC)

Initialize a new BotEventHandlers instance.

Parameters:

base_bot – The base bot that will handle the events.

fire_event(event: BotEvent) → None

Fire an event to its registered handler.

Parameters:

event – The event to fire.

Raises:

IllegalStateException – If there is no handler for the event type.

class GameAbortedEvent

Bases: EventABC

Virtual event class representing a game aborted event.

bot_api.internal.bot_handshake_factory module

class BotHandshakeFactory

Bases: object

static create(session_id: str, bot_info: BotInfo, is_droid: bool, secret: str | None) → BotHandshake

static is_debugger_attached() → bool

Detects if a debugger is attached to the process. @return true if a debugger is attached, false otherwise

bot_api.internal.bot_internals module

class BotInternals(bot: Bot, base_bot_internals: BaseBotInternals)

Bases: StopResumeListenerABC

on_next_turn(e: TickEvent) → None

Handle the next turn event.

on_hit_wall()

on_hit_bot(e: HitBotEvent) → None

property turn_rate: float

property gun_turn_rate: float

property radar_turn_rate: float

property target_speed: float | None

set_forward(distance: float) → None

forward(distance: float) → None

set_turn_left(degrees: float) → None

turn_left(degrees: float) → None

set_turn_gun_left(degrees: float) → None

turn_gun_left(degrees: float) → None

set_turn_radar_left(degrees: float) → None

turn_radar_left(degrees: float) → None

fire(firepower: float) → None

rescan() → None

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

stop(overwrite: bool) → None

resume() → None

on_stop() → None

on_resume()

bot_api.internal.env_vars module

class EnvVars

Bases: object

Utility class for reading environment variables.

ServerUrl = 'SERVER_URL'

Name of environment variable for server URL.

ServerSecret = 'SERVER_SECRET'

Name of environment variable for server secret.

BotName = 'BOT_NAME'

Name of environment variable for bot name.

BotVersion = 'BOT_VERSION'

Name of environment variable for bot version.

BotAuthors = 'BOT_AUTHORS'

Name of environment variable for bot author(s).

BotDescription = 'BOT_DESCRIPTION'

Name of environment variable for bot description.

BotHomepage = 'BOT_HOMEPAGE'

Name of environment variable for bot homepage URL.

BotCountryCodes = 'BOT_COUNTRY_CODES'

Name of environment variable for bot country code(s).

BotGameTypes = 'BOT_GAME_TYPES'

Name of environment variable for bot game type(s).

BotPlatform = 'BOT_PLATFORM'

Name of environment variable for bot platform.

BotProgrammingLang = 'BOT_PROG_LANG'

Name of environment variable for bot programming language.

BotInitialPosition = 'BOT_INITIAL_POS'

Name of environment variable for bot initial position.

TeamId = 'TEAM_ID'

Name of environment variable for bot team id.

TeamName = 'TEAM_NAME'

Name of environment variable for bot team name.

TeamVersion = 'TEAM_VERSION'

Name of environment variable for bot team version.

BotBooted = 'BOT_BOOTED'

Name of environment variable that set if the bot is being booted.

MissingEnvValue = 'Missing environment variable: '

static get_bot_info() → BotInfo

Gets the bot info from environment variables.

Returns:

An object containing the bot’s information.

Return type:

BotInfo

static get_server_url() → str | None

Gets the server URL from environment variables.

Returns:

The server URL, or None if not set.

Return type:

Optional[str]

static get_server_secret() → str | None

Gets the server secret from environment variables.

Returns:

The server secret, or None if not set.

Return type:

Optional[str]

static get_bot_name() → str | None

Gets the bot name from environment variables.

Returns:

The bot name, or None if not set.

Return type:

Optional[str]

static get_bot_version() → str | None

Gets the bot version from environment variables.

Returns:

The bot version, or None if not set.

Return type:

Optional[str]

static get_bot_authors() → List[str]

Gets the bot author(s) from environment variables.

Returns:

A list of author names, or an empty list if not set.

Return type:

List[str]

static get_bot_description() → str | None

Gets the bot description from environment variables.

Returns:

The bot description, or None if not set.

Return type:

Optional[str]

static get_bot_homepage() → str | None

Gets the bot homepage URL from environment variables.

Returns:

The bot homepage URL, or None if not set.

Return type:

Optional[str]

static get_bot_country_codes() → List[str]

Gets the bot country code(s) from environment variables.

Returns:

A list of country codes, or an empty list if not set.

Return type:

List[str]

static get_bot_game_types() → Set[str]

Gets the list of game type(s) supported by the bot from environment variables.

Returns:

A set of game types, or an empty set if not set.

Return type:

Set[str]

static get_bot_platform() → str | None

Gets the platform used for running the game from environment variables.

Returns:

The platform, or None if not set.

Return type:

Optional[str]

static get_bot_programming_lang() → str | None

Gets the programming language used for running the game from environment variables.

Returns:

The programming language, or None if not set.

Return type:

Optional[str]

static get_bot_initial_position() → InitialPosition | None

Gets the initial starting position for the bot used for debugging from environment variables.

Returns:

The initial position of the bot.

Return type:

InitialPosition

static get_team_id() → int | None

Gets the bot team ID if provided from environment variables.

Returns:

The team ID, or None if not set.

Return type:

Optional[int]

static get_team_name() → str | None

Gets the bot team name if provided from environment variables.

Returns:

The team name, or None if not set.

Return type:

Optional[str]

static get_team_version() → str | None

Gets the bot team version if provided from environment variables.

Returns:

The team version, or None if not set.

Return type:

Optional[str]

static is_bot_booted() → bool

Checks if the bot is being booted.

Returns:

True if the bot is being booted, False otherwise.

Return type:

bool

bot_api.internal.event_handler module

class EventHandler

Bases: Generic[T]

Generic event handler for handling and dispatching events of type T.

Events can be published to all subscribed listeners, which will be invoked in order of their priority. Subscribers with higher priority are invoked before lower priority ones. This handler provides thread-safety through synchronization and exception handling during event publication.

Type Parameters:

T: The type of event that this handler processes. Must implement the EventABC interface.

__init__()

Initialize a new EventHandler instance.

subscribe(subscriber: Callable[[T], None], priority: int = 1) → None

Subscribe a new event handler with a given priority.

Parameters:

• subscriber – The subscriber callback that will handle the events

• priority – The priority of the subscriber; higher values indicate higher priority (0-100)

Raises:

• ValueError – If priority is outside valid range or subscriber is already registered

• TypeError – If subscriber is None

unsubscribe(subscriber: Callable[[T], None]) → bool

Unsubscribe a subscriber from this event handler.

Parameters:

subscriber – The subscriber to be removed from subscriptions

Returns:

True if the subscriber was found and removed, False otherwise

Return type:

bool

clear() → None

Removes all subscribers from this event handler.

publish(event_data: T) → None

Publishes an event, invoking all subscribed listeners in order of their priority.

Parameters:

event_data – The event data to be published to the subscribers

Raises:

TypeError – If event_data does not implement the EventABC interface

get_subscriber_count() → int

Returns the number of subscribers currently registered.

Returns:

The count of subscribers

Return type:

int

class EntryWithPriority(subscriber: Callable[[T], None], priority: int)

Bases: object

Private class to store a subscriber together with its priority.

__init__(subscriber: Callable[[T], None], priority: int)

Constructs a new entry with the specified subscriber and priority.

Parameters:

• subscriber – The subscriber callback function

• priority – The priority of the subscriber

bot_api.internal.event_interruption module

class EventInterruption

Bases: object

Manages event interruption settings for bot events.

This class is responsible for tracking which bot event types are marked as interruptible. Events marked as interruptible can interrupt the normal execution flow of bot events.

__init__()

Initializes the EventInterruption class.

This is a private constructor to prevent instantiation of this class.

static set_interruptible(event_class: Type[EventABC], interruptible: bool) → None

Sets whether a specific event class should be interruptible or not.

Parameters:

• event_class – The class of the event to configure.

• interruptible – True if the event should be interruptible; False otherwise.

static is_interruptible(event_class: Type[EventABC]) → bool

Checks if a specific event class is marked as interruptible.

Parameters:

event_class – The class of the event to check.

Returns:

True if the event is interruptible; False otherwise.

Return type:

bool

bot_api.internal.event_priorities module

class EventPriorities

Bases: object

Manages priorities for bot events in the game.

This class maintains a registry of event priorities that determine the order in which events are processed by the bot API.

__init__()

Private constructor to prevent instantiation.

static initialize_event_priorities() → dict[Type[BotEvent], int]

Initializes the default event priorities map.

Returns:

A map containing default priority values for all supported event types.

Return type:

dict

EVENT_PRIORITIES = {<class 'bot_api.events.bot_death_event.BotDeathEvent'>: 100, <class 'bot_api.events.bullet_fired_event.BulletFiredEvent'>: 60, <class 'bot_api.events.bullet_hit_bot_event.BulletHitBotEvent'>: 70, <class 'bot_api.events.bullet_hit_bullet_event.BulletHitBulletEvent'>: 80, <class 'bot_api.events.bullet_hit_wall_event.BulletHitWallEvent'>: 90, <class 'bot_api.events.custom_event.CustomEvent'>: 120, <class 'bot_api.events.death_event.DeathEvent'>: 10, <class 'bot_api.events.hit_bot_event.HitBotEvent'>: 30, <class 'bot_api.events.hit_by_bullet_event.HitByBulletEvent'>: 50, <class 'bot_api.events.hit_wall_event.HitWallEvent'>: 40, <class 'bot_api.events.scanned_bot_event.ScannedBotEvent'>: 20, <class 'bot_api.events.skipped_turn_event.SkippedTurnEvent'>: 140, <class 'bot_api.events.team_message_event.TeamMessageEvent'>: 110, <class 'bot_api.events.tick_event.TickEvent'>: 130, <class 'bot_api.events.won_round_event.WonRoundEvent'>: 150}

static set_priority(event_class: Type[BotEvent] | None, priority: int) → None

Sets the priority for a specific event class.

Parameters:

• event_class (type) – The event class to set priority for.

• priority (int) – The priority value to assign.

Raises:

ValueError – If event_class is None.

static get_priority(event_class: Type[BotEvent] | None) → int

Gets the priority for a specific event class.

Parameters:

event_class (type) – The event class to get priority for.

Returns:

The priority value for the specified event class.

Return type:

int

Raises:

• ValueError – If event_class is None.

• Exception – If no priority is defined for the event class.

bot_api.internal.event_queue module

class EventQueue(base_bot_internals: BaseBotInternals, bot_event_handlers: BotEventHandlers)

Bases: object

Queue containing bot events that are being prioritized and dispatched to event handlers.

The event queue makes sure that the events are being processed in the right order based on event priority and age of the events. Old events that are no longer relevant will be removed from the queue.

MAX_QUEUE_SIZE = 256

MAX_EVENT_AGE = 2

clear() → None

Clears all events in the queue and custom event conditions.

get_events(turn_number: int) → list[BotEvent]

Returns a list containing all events in the queue.

Parameters:

turn_number – Current turn number used for removing old events.

Returns:

List of all events in the queue.

clear_events()

Removes all events in the queue.

set_current_event_interruptible(interruptible: bool) → None

Sets if the current event can be interrupted by new events with higher priority.

Parameters:

interruptible – True if the current event can be interrupted; false otherwise.

is_current_event_interruptible() → bool

Checks if the current event can be interrupted by new events with higher priority.

Returns:

True if the current event can be interrupted; false otherwise.

add_events_from_tick(event: TickEvent) → None

Adds standard events from a tick event, and custom events from conditions.

Parameters:

event – The tick event containing the standard events to add.

dispatch_events(turn_number: int) → None

Dispatches events in prioritized order to event handlers.

Parameters:

turn_number – Current turn number used for removing old events.

remove_old_events(turn_number: int) → None

sort_events() → None

peek_next_event()

remove_next_event()

static get_priority(bot_event: BotEvent) → int

dispatch(bot_event: BotEvent, turn_number: int)

static is_not_old_or_is_critical_event(bot_event: BotEvent, turn_number: int) → bool

static is_old_and_non_critical_event(bot_event: BotEvent, turn_number: int) → bool

add_event(bot_event: BotEvent)

add_custom_events()

dump_events(turn_number: int)

bot_api.internal.graphics_state module

class GraphicsState

Bases: object

get_svg_output() → str | None

Returns the current graphics state as an SVG string. Returns None if there is nothing to render.

clear() → None

Clears all graphics elements.

add_element(element: Dict[str, Any])

Adds a generic graphics element.

bot_api.internal.intent_validator module

class IntentValidator

Bases: object

static validate_firepower(firepower: float) → float

static validate_turn_rate(turn_rate: float, max_turn_rate: float) → float

static validate_gun_turn_rate(gun_turn_rate: float, max_gun_turn_rate: float) → float

static validate_radar_turn_rate(radar_turn_rate: float, max_radar_turn_rate: float) → float

static validate_target_speed(target_speed: float, max_speed: float) → float

static validate_max_speed(max_speed: float) → float

static validate_max_turn_rate(max_turn_rate: float) → float

static validate_max_gun_turn_rate(max_gun_turn_rate: float) → float

static validate_max_radar_turn_rate(max_radar_turn_rate: float) → float

static get_new_target_speed(speed: float, distance: float, max_speed: float) → float

static get_distance_traveled_until_stop(speed: float, max_speed: float) → float

static validate_teammate_id(teammate_id: int | None, teammate_ids: Set[int]) → None

static validate_team_message(message: Any, current_team_message_count: int) → None

static validate_team_message_size(json_message_str: str) → None

static color_to_schema(color: Color | None) → str | None

bot_api.internal.internal_event_handlers module

Internal event handler support.

class InternalEventHandlers

Bases: object

Class used for instant event handling only used for updating the state of the API internals.

__init__()

Initialize a new InternalEventHandlers instance.

fire_event(event: EventABC) → None

Fire an event to its registered handler.

Parameters:

event – The event to fire.

Note

If there is no registered event handler for the event type, the event is ignored.

class GameAbortedEvent

Bases: EventABC

Virtual event class representing a game aborted event.

class NextTurnEvent

Bases: EventABC

Private virtual event class representing a next turn event.

bot_api.internal.json_util module

to_camel_case(snake_str: str) → str

Converts a snake_case string to camelCase.

to_snake_case(camel_str: str) → str

Converts a camelCase string to snake_case.

class MessageEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: JSONEncoder

default(o: Any) → Any

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return super().default(o)

__init__(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Constructor for JSONEncoder, with sensible defaults.

If skipkeys is false, then it is a TypeError to attempt encoding of keys that are not str, int, float, bool or None. If skipkeys is True, such items are simply skipped.

If ensure_ascii is true, the output is guaranteed to be str objects with all incoming non-ASCII characters escaped. If ensure_ascii is false, the output can contain non-ASCII characters.

If check_circular is true, then lists, dicts, and custom encoded objects will be checked for circular references during encoding to prevent an infinite recursion (which would cause an RecursionError). Otherwise, no such check takes place.

If allow_nan is true, then NaN, Infinity, and -Infinity will be encoded as such. This behavior is not JSON specification compliant, but is consistent with most JavaScript based encoders and decoders. Otherwise, it will be a ValueError to encode such floats.

If sort_keys is true, then the output of dictionaries will be sorted by key; this is useful for regression tests to ensure that JSON serializations can be compared on a day-to-day basis.

If indent is a non-negative integer, then JSON array elements and object members will be pretty-printed with that indent level. An indent level of 0 will only insert newlines. None is the most compact representation.

If specified, separators should be an (item_separator, key_separator) tuple. The default is (’, ‘, ‘: ‘) if indent is None and (‘,’, ‘: ‘) otherwise. To get the most compact JSON representation, you should specify (‘,’, ‘:’) to eliminate whitespace.

If specified, default is a function that gets called for objects that can’t otherwise be serialized. It should return a JSON encodable version of the object or raise a TypeError.

encode(o)

Return a JSON string representation of a Python data structure.

>>> from json.encoder import JSONEncoder
>>> JSONEncoder().encode({"foo": ["bar", "baz"]})
'{"foo": ["bar", "baz"]}'

item_separator = ', '

iterencode(o, _one_shot=False)

Encode the given object and yield each string representation as available.

For example:

for chunk in JSONEncoder().iterencode(bigobject):
    mysocket.write(chunk)

key_separator = ': '

from_json(json_str_or_dict: str | dict[str, Any]) → Message

Deserializes a JSON string into a Message object.

to_json(obj: Message) → str

Serializes a Message object into a JSON string.

bot_api.internal.recording_text_writer module

RecordingTextWriter - Captures stdout/stderr output for sending to server. This matches the functionality of RecordingPrintStream (Java) and RecordingTextWriter (C#/.NET).

class RecordingTextWriter(text_writer: TextIO)

Bases: object

A text writer wrapper that records all written text and forwards it to an underlying writer. Thread-safe for concurrent writes (e.g., from print statements in event handlers).

__init__(text_writer: TextIO)

Initialize the recording text writer.

Parameters:

text_writer – The underlying text writer to forward output to (e.g., sys.stdout)

write(text: str) → int

Write text to both the underlying writer and the recording buffer. Thread-safe.

Parameters:

text – The text to write

Returns:

The number of characters written

flush() → None

Flush both the underlying writer and the recording buffer. Thread-safe.

read_next() → str

Read and clear the recorded output since the last read. Thread-safe.

Returns:

The recorded output as a string

isatty() → bool

Return whether the underlying writer is a TTY.

property encoding: str

Return the encoding of the underlying writer.

property errors

Return the error handling mode of the underlying writer.

bot_api.internal.stop_resume_listener_abs module

class StopResumeListenerABC

Bases: ABC

on_stop()

on_resume()

bot_api.internal.thread_interrupted_exception module

exception ThreadInterruptedException

Bases: BaseException

Exception used for interrupting event handlers.

This exception is thrown to signal that the current event handler has been interrupted deliberately and processing should stop so another event can take place.

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.internal.websocket_handler module

class WebSocketHandler(base_bot_internals: BaseBotInternals, server_url: str, server_secret: str | None, base_bot: BaseBotABC, bot_info: BotInfo, bot_event_handlers: BotEventHandlers, internal_event_handlers: InternalEventHandlers, closed_event: Event, event_queue: EventQueue)

Bases: object

Websocket handler for Robocode Tank Royale Bot API that handles websocket connections and messages from the server.

__init__(base_bot_internals: BaseBotInternals, server_url: str, server_secret: str | None, base_bot: BaseBotABC, bot_info: BotInfo, bot_event_handlers: BotEventHandlers, internal_event_handlers: InternalEventHandlers, closed_event: Event, event_queue: EventQueue)

Initialize the websocket handler.

async connect()

Connect to the WebSocket server.

async disconnect(code: int = 1000, reason: str = '')

Disconnect from the WebSocket server.

async on_close(websocket: ClientConnection, code: int, reason: str) → None

Handle WebSocket close event.

async on_error(websocket: ClientConnection, error: Exception)

Handle WebSocket error.

async receive_messages()

Main loop for receiving messages from the WebSocket server.

async process_message(message: str)

Process the received WebSocket message.

async handle_tick(json_msg: Dict[Any, Any]) → None

Handle a tick event from the server.

async handle_round_started(json_msg: Dict[Any, Any]) → None

Handle a round started event from the server.

async handle_round_ended(json_msg: Dict[Any, Any])

Handle a round ended event from the server.

async handle_game_started(json_msg: Dict[Any, Any]) → None

Handle a game started event from the server.

async handle_game_ended(json_msg: Dict[Any, Any]) → None

Handle a game ended event from the server.

async handle_game_aborted() → None

Handle a game aborted event from the server.

async handle_skipped_turn(json_msg: Dict[Any, Any]) → None

Handle a skipped turn event from the server.

async handle_server_handshake(json_msg: Dict[Any, Any]) → None

Handle a server handshake from the server.

Module contents