> ## Documentation Index > Fetch the complete documentation index at: https://docs.battlecode.cam/llms.txt > Use this file to discover all available pages before exploring further. # 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. ```python theme={"dark"} class Player: def run(self, c: Controller): # c is the Controller for this unit pos = c.get_position() ``` ## Info methods ### Unit info Return the team of the entity with the given id, or this unit if omitted. Return the position of the entity with the given id, or this unit if omitted. Return this unit's entity id. Return this unit's current action cooldown. Actions require cooldown == 0. Return this unit's current move cooldown. Movement requires cooldown == 0. Return the current HP of the entity with the given id, or this unit if omitted. Return the max HP of the entity with the given id, or this unit if omitted. Return the EntityType of the entity with the given id, or this unit if omitted. Return the facing direction of a conveyor, splitter, armoured conveyor, or turret. Raises `GameError` if the entity has no direction. Return the vision radius squared of the given unit, or this unit if omitted. ### Turret info Return the amount of ammo this turret currently holds. Return the resource type loaded as ammo, or None if empty. Return the closest targetable occupied tile on the gunner's forward line, or None if none exists. Empty tiles are skipped. Markers are targetable but do not block farther legal targets. Walls block the line but are not targetable. Builder bots and non-marker buildings are both targetable and blocking, so if either appears first it is returned and nothing beyond it is legal. Only valid on gunners. Return this turret's raw geometric attack pattern as `list[Position]`. This ignores ammo, cooldown, occupancy, blockers, and any other legality checks. For gunners, this is the full forward ray up to range, including tiles behind walls. For sentinels, this is the full +/-1 band around the forward line within vision radius squared 32. For breaches, this is the forward 180-degree cone within distance squared 24. For launchers, this is every in-bounds tile with `0 < distance^2 <= 26`. Raises `GameError` if this unit is not a turret. Return the same raw geometric attack pattern for a hypothetical turret at position. This can be called from any controller and does not check whether a turret exists there, whether it could legally be built there, or whether the tile is occupied. If position is out of bounds, returns `[]`. In Python, turret\_type must be one of `EntityType.GUNNER`, `EntityType.SENTINEL`, `EntityType.BREACH`, or `EntityType.LAUNCHER`; any other `EntityType` raises `ValueError`. direction is ignored for launchers. ### Building info Return the output target position of a bridge. Raises `GameError` if not a bridge. Return the resource stored in a conveyor/splitter/armoured conveyor/bridge/foundry, or None if empty. Raises `GameError` if the entity has no storage. Return the id of the resource stack stored in a conveyor/splitter/armoured conveyor/bridge/foundry, or None if empty. Raises `GameError` if the entity has no storage. ### Tile queries Return the environment type (empty, wall, ore) of the tile at pos. Return the id of the building on the tile at pos, or None if empty. Return the id of the builder bot on the tile at pos, or None if empty. Return True if the tile has no building and is not a wall. Return True if a builder bot belonging to this team could stand on the tile. A tile is passable when it contains a walkable building (conveyor, splitter, armoured conveyor, bridge, or road) or an allied core, and no builder bot is already present. Return True if pos is within this unit's vision radius. ### Nearby queries Return all in-bounds tile positions within dist\_sq of this unit (defaults to vision radius). dist\_sq must not exceed the vision radius. Return ids of all entities on tiles within dist\_sq (defaults to vision radius). Return ids of all buildings within dist\_sq (defaults to vision radius). Return ids of all units within dist\_sq (defaults to vision radius). ### Map and game state Return the width of the map in tiles. Return the height of the map in tiles. Return the current round number (starts at 1). Return (titanium, axionite) in this team's global resource pool. Return this team's current cost scale as a percentage (100.0 = base cost). Return the number of living units currently on your team, including the core. 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: ```python theme={"dark"} 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 this builder bot one step in direction. Raises `GameError` if not legal. 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 or raises `GameError` if not legal. If a `can_build_*` method would create a living unit, it also accounts for the global unit cap. If a tile already contains a builder bot, only walkable buildings (conveyors and roads) may be built on that tile. ### Directional buildings These take `(position: Position, direction: Direction)` — the direction the building faces: ```python theme={"dark"} c.build_conveyor(pos, direction) c.can_build_conveyor(pos, direction) c.build_splitter(pos, direction) c.can_build_splitter(pos, direction) c.build_armoured_conveyor(pos, direction) c.can_build_armoured_conveyor(pos, direction) c.build_gunner(pos, direction) c.can_build_gunner(pos, direction) c.build_sentinel(pos, direction) c.can_build_sentinel(pos, direction) c.build_breach(pos, direction) c.can_build_breach(pos, direction) ``` ### Bridge Takes `(position: Position, target: Position)` — the bridge's output target tile (within distance² 9): ```python theme={"dark"} c.build_bridge(pos, target) c.can_build_bridge(pos, target) ``` ### Non-directional buildings Take only `(position: Position)`: ```python theme={"dark"} c.build_harvester(pos) c.can_build_harvester(pos) c.build_road(pos) c.can_build_road(pos) c.build_barrier(pos) c.can_build_barrier(pos) c.build_foundry(pos) c.can_build_foundry(pos) c.build_launcher(pos) c.can_build_launcher(pos) ``` ### Generic build A single pair of methods that dispatches to the correct type-specific builder. Use these when the entity type is determined at runtime. Return True if `entity_type` can be built at `position`. For directional buildings and turrets (conveyor, splitter, armoured\_conveyor, gunner, sentinel, breach), `extra` must be a `Direction`. For bridges, `extra` must be the target `Position`. For all other types (harvester, road, barrier, launcher, foundry), `extra` is unused. Build `entity_type` at `position`. Returns the new entity's id. The `extra` parameter follows the same rules as `can_build()`. Raises `GameError` if not legal. ## Healing & destruction Heal all friendly entities on a tile within this builder bot's action radius by 4 HP. If both a friendly builder bot and a friendly building share the tile, both are healed. Costs 1 titanium and one action cooldown. Raises `GameError` if not legal. Return True if this builder bot can heal the tile at position this round. Position must be within the builder bot's action radius. Requires action cooldown == 0, enough titanium, and at least one damaged friendly entity on the tile. Destroy the allied building at building\_pos. Does **not** cost action cooldown. Return True if this builder bot can destroy the allied building. Destroy this unit. Builder bots no longer deal damage on self-destruct. **Terminates this unit's execution immediately** — no code after `self_destruct()` will run. Forfeit the game immediately. Destroys this team's core, ending the game as a loss. **Terminates this unit's execution immediately** — no code after `resign()` will run. The optional `message` (max 500 characters) is saved to the replay and displayed in match results. ## Markers Place a marker with the given u32 value. Does not cost action cooldown. Max one per round. Return True if this unit can place a marker at position this round. Return the u32 value stored in the friendly marker. ## Combat Fire this turret at target, or perform the builder bot's own-tile attack. Builder bots spend 2 titanium to deal 2 damage to the building on their current tile. Gunners use first-obstruction line of sight: empty tiles and markers do not block, markers are targetable, walls block but are not targetable, and builder bots plus non-marker buildings are both targetable and blocking. If a turret attacks a tile containing both a building and a builder bot, only the builder bot is hit. Use `launch()` for launchers. Return True if this turret can fire at target this round, or if this builder bot can use its own-tile attack on target. Gunners use the same first-obstruction line of sight as `fire()`: empty tiles and markers do not block, markers are targetable, walls block but are not targetable, and builder bots plus non-marker buildings are both targetable and blocking. Return whether a hypothetical turret at position would have a legal shot at target on the current map. This treats position as the turret's tile and uses current map occupancy and walls, but ignores ammo, cooldown, whether a real turret is present, and whether one could legally be built there. If either position or target is out of bounds, returns False. For sentinels and breaches, this is only a geometric range/shape check. For launchers, this is only the raw throw-range check `0 < distance^2 <= 26`; it does not check pickup adjacency, whether a builder bot exists, or whether the destination is bot-passable. direction is ignored for launchers. Return whether `rotate(direction)` would be legal this round. This returns False if the current unit is not a gunner, if direction is `Direction.CENTRE`, if direction is the gunner's current facing direction, if the gunner cannot act this turn, or if the team cannot afford the global 10 Ti rotate cost. Unlike `rotate()`, this does not raise on non-gunners. Rotate this gunner to face `direction`. Costs 10 titanium from the global resource pool and applies a 1-turn cooldown. Raises `GameError` if not legal. Only valid on gunners. Pick up the builder bot at bot\_pos and throw it to target. Return True if this launcher can pick up and throw the bot. ## Core Convert `amount` refined axionite from this team's global resource pool into titanium at a rate of 1 Ax to 4 Ti. Converted axionite is removed from the Ax collected stat and added to the Ti collected stat. Raises `GameError` if not legal. Only valid on cores. Spawn a builder bot on one of the 9 core tiles. Costs one action cooldown and requires room under the global unit cap. Returns the new entity's id. Return True if the core can spawn a builder at position this round, including the unit-cap check. ## Debug indicators Draw a debug line between two positions with RGB colour. Saved to the replay. Draw a debug dot at a position with RGB colour. Saved to the replay.