Controller

Complete reference for all Controller methods available to your bot.

The Controller object is passed to your Player.run() method each round. It provides all queries and actions for interacting with the game.

class Player:
    def run(self, c: Controller):
        # c is the Controller for this unit
        pos = c.get_position()

Info methods

Unit info

get_team(id: int | None = None) · Team

Return the team of the entity with the given id, or this unit if omitted.

get_position(id: int | None = None) · Position

Return the position of the entity with the given id, or this unit if omitted.

get_id() · int

Return this unit’s entity id.

get_action_cooldown() · int

Return this unit’s current action cooldown. Actions require cooldown == 0.

get_move_cooldown() · int

Return this unit’s current move cooldown. Movement requires cooldown == 0.

get_hp(id: int | None = None) · int

Return the current HP of the entity with the given id, or this unit if omitted.

get_max_hp(id: int | None = None) · int

Return the max HP of the entity with the given id, or this unit if omitted.

get_entity_type(id: int | None = None) · EntityType

Return the EntityType of the entity with the given id, or this unit if omitted.

get_direction(id: int | None = None) · Direction

Return the facing direction of a conveyor, splitter, armoured conveyor, or turret. Raises GameError if the entity has no direction.

get_vision_radius_sq(id: int | None = None) · int

Return the vision radius squared of the given unit, or this unit if omitted.

Turret info

get_ammo_amount() · int

Return the amount of ammo this turret currently holds.

get_ammo_type() · ResourceType | None

Return the resource type loaded as ammo, or None if empty.

get_gunner_target() · Position | None

Return the position of the closest non-empty tile in the gunner’s facing direction, or None if nothing is in range. Only valid on gunners.

Building info

get_bridge_target(id: int) · Position

Return the output target position of a bridge. Raises GameError if not a bridge.

get_stored_resource(id: int | None = None) · ResourceType | None

Return the resource stored in a conveyor/splitter/armoured conveyor/bridge/foundry, or None if empty. Raises GameError if the entity has no storage.

Tile queries

get_tile_env(pos: Position) · Environment

Return the environment type (empty, wall, ore) of the tile at pos.

get_tile_building_id(pos: Position) · int | None

Return the id of the building on the tile at pos, or None if empty.

get_tile_builder_bot_id(pos: Position) · int | None

Return the id of the builder bot on the tile at pos, or None if empty.

is_tile_empty(pos: Position) · bool

Return True if the tile has no building and is not a wall.

is_tile_passable(pos: Position) · bool

Return True if a builder bot belonging to this team could stand on the tile (conveyor, road, or allied core, and no other builder bot).

is_in_vision(pos: Position) · bool

Return True if pos is within this unit’s vision radius.

Nearby queries

get_nearby_tiles(dist_sq: int | None = None) · list[Position]

Return all in-bounds tile positions within dist_sq of this unit (defaults to vision radius). dist_sq must not exceed the vision radius.

get_nearby_entities(dist_sq: int | None = None) · list[int]

Return ids of all entities on tiles within dist_sq (defaults to vision radius).

get_nearby_buildings(dist_sq: int | None = None) · list[int]

Return ids of all buildings within dist_sq (defaults to vision radius).

get_nearby_units(dist_sq: int | None = None) · list[int]

Return ids of all units within dist_sq (defaults to vision radius).

Map and game state

get_map_width() · int

Return the width of the map in tiles.

get_map_height() · int

Return the height of the map in tiles.

get_current_round() · int

Return the current round number (starts at 1).

get_global_resources() · tuple[int, int]

Return (titanium, axionite) in this team’s global resource pool.

get_scale_percent() · float

Return this team’s current cost scale as a percentage (100.0 = base cost).

get_cpu_time_elapsed() · int

Return the CPU time elapsed this round in microseconds.

Cost getters

Every buildable entity has a cost getter that returns the current scaled (titanium, axionite) cost:

c.get_conveyor_cost()           # -> (int, int)
c.get_splitter_cost()
c.get_bridge_cost()
c.get_armoured_conveyor_cost()
c.get_harvester_cost()
c.get_road_cost()
c.get_barrier_cost()
c.get_gunner_cost()
c.get_sentinel_cost()
c.get_breach_cost()
c.get_launcher_cost()
c.get_foundry_cost()
c.get_builder_bot_cost()

Movement

move(direction: Direction) · None

Move this builder bot one step in direction. Raises GameError if not legal.

can_move(direction: Direction) · bool

Return True if this builder bot can move in direction this round.

Building

Every buildable entity has can_build_* and build_* methods. All require action cooldown == 0 and sufficient resources. The can_build_* variants return bool; build_* returns the new entity’s int id and raises GameError if not legal.

Directional buildings

These take (position: Position, direction: Direction) — the direction the building faces. They return the new building’s entity id.

c.build_conveyor(pos, direction)          # -> int     c.can_build_conveyor(pos, direction)
c.build_splitter(pos, direction)          # -> int     c.can_build_splitter(pos, direction)
c.build_armoured_conveyor(pos, direction) # -> int     c.can_build_armoured_conveyor(pos, direction)
c.build_gunner(pos, direction)            # -> int     c.can_build_gunner(pos, direction)
c.build_sentinel(pos, direction)          # -> int     c.can_build_sentinel(pos, direction)
c.build_breach(pos, direction)            # -> int     c.can_build_breach(pos, direction)

Bridge

Takes (position: Position, target: Position) — the bridge’s output target tile (within distance² 9). Returns the new bridge’s entity id.

c.build_bridge(pos, target)               # -> int     c.can_build_bridge(pos, target)

Non-directional buildings

Take only (position: Position). They return the new building’s entity id.

c.build_harvester(pos)                    # -> int     c.can_build_harvester(pos)
c.build_road(pos)                         # -> int     c.can_build_road(pos)
c.build_barrier(pos)                      # -> int     c.can_build_barrier(pos)
c.build_foundry(pos)                      # -> int     c.can_build_foundry(pos)
c.build_launcher(pos)                     # -> int     c.can_build_launcher(pos)

Healing & destruction

heal(position: Position) · None

Heal all friendly entities on the tile by 10 HP. Costs one action cooldown.

can_heal(position: Position) · bool

Return True if this builder bot can heal the tile this round.

destroy(building_pos: Position) · None

Destroy the allied building at building_pos. Does not cost action cooldown.

can_destroy(building_pos: Position) · bool

Return True if this builder bot can destroy the allied building.

self_destruct() · None

Destroy this unit. Builder bots deal 20 damage to their tile. Terminates the bot’s turn immediately (the bot will not execute any further code this round).

resign() · None

Forfeit the game immediately. Destroys this team’s core, ending the game as a loss. Terminates the bot’s turn immediately.

Markers

place_marker(position: Position, value: int) · None

Place a marker with the given u32 value. Does not cost action cooldown. Max one per round.

can_place_marker(position: Position) · bool

Return True if this unit can place a marker at position this round.

get_marker_value(id: int) · int

Return the u32 value stored in the friendly marker.

Combat

fire(target: Position) · None

Fire this turret at target. Use launch() for launchers.

can_fire(target: Position) · bool

Return True if this turret can fire at target this round.

launch(bot_pos: Position, target: Position) · None

Pick up the builder bot at bot_pos and throw it to target.

can_launch(bot_pos: Position, target: Position) · bool

Return True if this launcher can pick up and throw the bot.

Core

spawn_builder(position: Position) · int

Spawn a builder bot on one of the 9 core tiles. Costs one action cooldown. Returns the new builder bot’s entity id.

can_spawn(position: Position) · bool

Return True if the core can spawn a builder at position this round.

Debug indicators

draw_indicator_line(pos_a: Position, pos_b: Position, r: int, g: int, b: int) · None

Draw a debug line between two positions with RGB colour. Saved to the replay.

draw_indicator_dot(pos: Position, r: int, g: int, b: int) · None

Draw a debug dot at a position with RGB colour. Saved to the replay.