fcode 2.2.0__cp312-cp312-macosx_11_0_arm64.whl

fcode/__init__.py

@@ -0,0 +1,3 @@
+__version__ = "2.2.0"
+
+from fcode._types import *  # noqa: F401,F403

fcode/_types.py

@@ -0,0 +1,655 @@
+"""Common types for the Titan game."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING, NamedTuple
+
+
+class GameError(Exception):
+    """Raised when a player issues an invalid action."""
+
+    __slots__ = ()
+
+
+class Team(Enum):
+    __slots__ = ()
+
+    A = "a"
+    B = "b"
+
+
+class ResourceType(Enum):
+    __slots__ = ()
+
+    TITANIUM = "titanium"
+
+
+class EntityType(Enum):
+    __slots__ = ()
+
+    BUILDER_BOT = "builder_bot"
+    CORE = "core"
+    GUNNER = "gunner"
+    SENTINEL = "sentinel"
+    LAUNCHER = "launcher"
+    CONVEYOR = "conveyor"
+    SPLITTER = "splitter"
+    HARVESTER = "harvester"
+    BARRIER = "barrier"
+
+
+class GameConstants:
+    __slots__ = ()
+
+    MAX_TURNS = 1000
+    STACK_SIZE = 10
+    STARTING_TITANIUM = 500
+    MAX_TEAM_UNITS = 50
+    PASSIVE_TITANIUM_AMOUNT = 10
+    PASSIVE_TITANIUM_INTERVAL = 4
+
+    ACTION_RADIUS_SQ = 2
+    CORE_SPAWNING_RADIUS_SQ = 2
+    CORE_ACTION_RADIUS_SQ = 8
+
+    CORE_VISION_RADIUS_SQ = 36
+    BUILDER_BOT_VISION_RADIUS_SQ = 20
+    GUNNER_VISION_RADIUS_SQ = 13
+    SENTINEL_VISION_RADIUS_SQ = 32
+    LAUNCHER_VISION_RADIUS_SQ = 26
+
+    CONVEYOR_BASE_COST = 3
+    SPLITTER_BASE_COST = 6
+    HARVESTER_BASE_COST = 20
+    BARRIER_BASE_COST = 3
+    GUNNER_BASE_COST = 10
+    SENTINEL_BASE_COST = 30
+    LAUNCHER_BASE_COST = 20
+    BUILDER_BOT_BASE_COST = 30
+    GUNNER_ROTATE_COST = 10
+    GUNNER_ROTATE_COOLDOWN = 1
+
+    CONVEYOR_MAX_HP = 20
+    SPLITTER_MAX_HP = 20
+    HARVESTER_MAX_HP = 30
+    BARRIER_MAX_HP = 30
+
+    STORE_SIZE = 16
+
+    BUILDER_BOT_MAX_HP = 40
+    CORE_MAX_HP = 500
+    GUNNER_MAX_HP = 40
+    SENTINEL_MAX_HP = 30
+    LAUNCHER_MAX_HP = 30
+
+    BUILDER_BOT_SELF_DESTRUCT_DAMAGE = 0
+    BUILDER_BOT_ATTACK_DAMAGE = 2
+    BUILDER_BOT_ATTACK_COST = 2
+    BUILDER_BOT_HEAL_COST = 1
+    HEAL_AMOUNT = 4
+
+    GUNNER_DAMAGE = 10
+    GUNNER_FIRE_COOLDOWN = 1
+    GUNNER_AMMO_COST = 2
+
+    SENTINEL_DAMAGE = 18
+    SENTINEL_FIRE_COOLDOWN = 3
+    SENTINEL_AMMO_COST = 10
+
+    LAUNCHER_FIRE_COOLDOWN = 1
+
+
+class Environment(Enum):
+    __slots__ = ()
+
+    EMPTY = "empty"
+    WALL = "wall"
+    ORE_TITANIUM = "ore_titanium"
+
+
+class Direction(Enum):
+    __slots__ = ()
+
+    NORTH = "north"
+    NORTHEAST = "northeast"
+    EAST = "east"
+    SOUTHEAST = "southeast"
+    SOUTH = "south"
+    SOUTHWEST = "southwest"
+    WEST = "west"
+    NORTHWEST = "northwest"
+    CENTRE = "centre"
+
+    def delta(self) -> tuple[int, int]:
+        """Return the (dx, dy) step for this direction."""
+        return {
+            Direction.NORTH: (0, -1),
+            Direction.NORTHEAST: (1, -1),
+            Direction.EAST: (1, 0),
+            Direction.SOUTHEAST: (1, 1),
+            Direction.SOUTH: (0, 1),
+            Direction.SOUTHWEST: (-1, 1),
+            Direction.WEST: (-1, 0),
+            Direction.NORTHWEST: (-1, -1),
+            Direction.CENTRE: (0, 0),
+        }[self]
+
+    def rotate_left(self) -> Direction:
+        """Return the direction rotated 45 degrees counterclockwise."""
+        return {
+            Direction.NORTH: Direction.NORTHWEST,
+            Direction.NORTHEAST: Direction.NORTH,
+            Direction.EAST: Direction.NORTHEAST,
+            Direction.SOUTHEAST: Direction.EAST,
+            Direction.SOUTH: Direction.SOUTHEAST,
+            Direction.SOUTHWEST: Direction.SOUTH,
+            Direction.WEST: Direction.SOUTHWEST,
+            Direction.NORTHWEST: Direction.WEST,
+            Direction.CENTRE: Direction.CENTRE,
+        }[self]
+
+    def rotate_right(self) -> Direction:
+        """Return the direction rotated 45 degrees clockwise."""
+        return {
+            Direction.NORTH: Direction.NORTHEAST,
+            Direction.NORTHEAST: Direction.EAST,
+            Direction.EAST: Direction.SOUTHEAST,
+            Direction.SOUTHEAST: Direction.SOUTH,
+            Direction.SOUTH: Direction.SOUTHWEST,
+            Direction.SOUTHWEST: Direction.WEST,
+            Direction.WEST: Direction.NORTHWEST,
+            Direction.NORTHWEST: Direction.NORTH,
+            Direction.CENTRE: Direction.CENTRE,
+        }[self]
+
+    def opposite(self) -> Direction:
+        """Return the opposite direction (180 degrees)."""
+        return {
+            Direction.NORTH: Direction.SOUTH,
+            Direction.NORTHEAST: Direction.SOUTHWEST,
+            Direction.EAST: Direction.WEST,
+            Direction.SOUTHEAST: Direction.NORTHWEST,
+            Direction.SOUTH: Direction.NORTH,
+            Direction.SOUTHWEST: Direction.NORTHEAST,
+            Direction.WEST: Direction.EAST,
+            Direction.NORTHWEST: Direction.SOUTHEAST,
+            Direction.CENTRE: Direction.CENTRE,
+        }[self]
+
+
+class Position(NamedTuple):
+    x: int
+    y: int
+
+    def add(self, d: Direction) -> Position:
+        """Return a new position offset by the direction delta."""
+        dx, dy = d.delta()
+        return Position(self.x + dx, self.y + dy)
+
+    def distance_squared(self, other: Position) -> int:
+        """Return squared distance to another position."""
+        dx = self.x - other.x
+        dy = self.y - other.y
+        return dx * dx + dy * dy
+
+    def direction_to(self, other: Position) -> Direction:
+        """Return the closest 45-degree Direction approximation toward other."""
+        dx = other.x - self.x
+        dy = other.y - self.y
+        if dx == 0 and dy == 0:
+            return Direction.CENTRE
+        # atan2 gives angle in radians; map to one of 8 compass directions.
+        import math
+
+        # Use y-up convention for direction mapping: north is decreasing y.
+        angle = math.atan2(-dy, dx)  # radians, x-east / y-north convention
+        # Snap to nearest 45-degree sector (each sector is pi/4 wide).
+        # Sectors: E=0, NE=1, N=2, NW=3, W=4, SW=5, S=6, SE=7
+        sector = int((angle + 2 * math.pi + math.pi / 8) / (math.pi / 4)) % 8
+        return [
+            Direction.EAST,
+            Direction.NORTHEAST,
+            Direction.NORTH,
+            Direction.NORTHWEST,
+            Direction.WEST,
+            Direction.SOUTHWEST,
+            Direction.SOUTH,
+            Direction.SOUTHEAST,
+        ][sector]
+
+
+# The real Controller is injected from Rust at runtime, overwriting this placeholder.
+# Keep the TYPE_CHECKING stub in sync with engine/rust/src/bindings/controller.rs.
+#
+# IMPORTANT: The runtime placeholder must have NO methods. With SHARED_GIL
+# subinterpreters, Python methods on a Controller class pollute the Rust
+# Controller's method resolution, causing bot-defined methods with the same
+# name (e.g. `move`) to be incorrectly bound to Controller instances in other
+# subinterpreters. The full stub is only for type checkers.
+#
+# NOTE: We use `if not TYPE_CHECKING: ... else: ...` (not a top-level class
+# followed by a TYPE_CHECKING override) because mypy treats a top-level
+# redefinition as an error and sticks with the first (empty) class.
+# The else branch must contain the stubs so they come last — PyCharm uses
+# "last definition wins" rather than properly evaluating TYPE_CHECKING.
+if not TYPE_CHECKING:
+
+    class Controller:  # Placeholder — overwritten by Rust class before bot code runs.
+        pass
+else:
+
+    class Controller:
+        # --- Info ---
+
+        def get_team(self, id: int | None = None) -> Team:
+            """Return the team of the entity with the given id, or this unit if omitted."""
+            ...
+
+        def get_position(self, id: int | None = None) -> Position:
+            """Return the position of the entity with the given id, or this unit if omitted."""
+            ...
+
+        def get_id(self) -> int:
+            """Return this unit's entity id."""
+            ...
+
+        def get_action_cooldown(self) -> int:
+            """Return this unit's current action cooldown. Actions require cooldown == 0."""
+            ...
+
+        def get_move_cooldown(self) -> int:
+            """Return this unit's current move cooldown. Movement requires cooldown == 0."""
+            ...
+
+        def get_ammo_amount(self) -> int:
+            """Return the amount of ammo this turret currently holds."""
+            ...
+
+        def get_ammo_type(self) -> ResourceType | None:
+            """Return the resource type loaded as ammo, or None if empty."""
+            ...
+
+        def get_vision_radius_sq(self, id: int | None = None) -> int:
+            """Return the vision radius squared of the given unit, or this unit if omitted."""
+            ...
+
+        def get_hp(self, id: int | None = None) -> int:
+            """Return the current HP of the entity with the given id, or this unit if omitted."""
+            ...
+
+        def get_max_hp(self, id: int | None = None) -> int:
+            """Return the max HP of the entity with the given id, or this unit if omitted."""
+            ...
+
+        def get_entity_type(self, id: int | None = None) -> EntityType:
+            """Return the EntityType of the entity with the given id, or this unit if omitted."""
+            ...
+
+        def get_direction(self, id: int | None = None) -> Direction:
+            """Return the facing direction of a conveyor, splitter, or turret.
+            Raises GameError if the entity has no direction."""
+            ...
+
+        def get_stored_resource(self, id: int | None = None) -> ResourceType | None:
+            """Return the resource stored in a conveyor or splitter.
+            Returns None if empty. Raises GameError if the entity has no storage."""
+            ...
+
+        def get_stored_resource_id(self, id: int | None = None) -> int | None:
+            """Return the id of the resource stored in a conveyor or splitter.
+            Returns None if empty. Raises GameError if the entity has no storage."""
+            ...
+
+        def get_tile_env(self, pos: Position) -> Environment:
+            """Return the environment type (empty, wall, ore) of the tile at pos."""
+            ...
+
+        def get_tile_building_id(self, pos: Position) -> int | None:
+            """Return the id of the building on the tile at pos, or None if there is none."""
+            ...
+
+        def get_tile_builder_bot_id(self, pos: Position) -> int | None:
+            """Return the id of the builder bot on the tile at pos, or None if there is none."""
+            ...
+
+        def is_tile_empty(self, pos: Position) -> bool:
+            """Return True if the tile has no building and is not a wall."""
+            ...
+
+        def is_tile_passable(self, pos: Position) -> bool:
+            """Return True if a builder bot belonging to this team could stand on the tile
+            (i.e. no other builder bot is there, and the tile is not a wall and either has
+            no building on it or has a conveyor, splitter, or the allied core)."""
+            ...
+
+        def is_in_vision(self, pos: Position) -> bool:
+            """Return True if pos is within this unit's vision radius."""
+            ...
+
+        def get_nearby_tiles(self, 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."""
+            ...
+
+        def get_nearby_entities(self, dist_sq: int | None = None) -> list[int]:
+            """Return ids of all entities on tiles within dist_sq (defaults to vision radius)."""
+            ...
+
+        def get_nearby_buildings(self, dist_sq: int | None = None) -> list[int]:
+            """Return ids of all buildings within dist_sq (defaults to vision radius)."""
+            ...
+
+        def get_nearby_units(self, dist_sq: int | None = None) -> list[int]:
+            """Return ids of all units within dist_sq (defaults to vision radius)."""
+            ...
+
+        def get_map_width(self) -> int:
+            """Return the width of the map in tiles."""
+            ...
+
+        def get_map_height(self) -> int:
+            """Return the height of the map in tiles."""
+            ...
+
+        def get_current_round(self) -> int:
+            """Return the current round number (starts at 1)."""
+            ...
+
+        def get_global_resources(self) -> int:
+            """Return this team's titanium balance."""
+            ...
+
+        def get_scale_percent(self) -> float:
+            """Return this team's current cost scale as a percentage (100.0 = base cost; used in the scaling formula)."""
+            ...
+
+        def get_cpu_time_elapsed(self) -> int:
+            """Return the CPU time elapsed this turn in microseconds."""
+            ...
+
+        # --- Cost getters ---
+
+        def get_conveyor_cost(self) -> int:
+            """Return the current scaled cost to build a conveyor."""
+            ...
+
+        def get_splitter_cost(self) -> int:
+            """Return the current scaled cost to build a splitter."""
+            ...
+
+        def get_harvester_cost(self) -> int:
+            """Return the current scaled cost to build a harvester."""
+            ...
+
+        def get_barrier_cost(self) -> int:
+            """Return the current scaled cost to build a barrier."""
+            ...
+
+        def get_gunner_cost(self) -> int:
+            """Return the current scaled cost to build a gunner."""
+            ...
+
+        def get_sentinel_cost(self) -> int:
+            """Return the current scaled cost to build a sentinel."""
+            ...
+
+        def get_launcher_cost(self) -> int:
+            """Return the current scaled cost to build a launcher."""
+            ...
+
+        def get_builder_bot_cost(self) -> int:
+            """Return the current scaled cost to spawn a builder bot."""
+            ...
+
+        def get_unit_count(self) -> int:
+            """Return the number of living units currently on this unit's team, including the core."""
+            ...
+
+        # --- Movement ---
+
+        def move(self, direction: Direction) -> None:
+            """Move this builder bot one step in direction. Raises GameError if the move is not legal."""
+            ...
+
+        def can_move(self, direction: Direction) -> bool:
+            """Return True if this builder bot can move in direction this turn."""
+            ...
+
+        # --- Building ---
+
+        def can_build_conveyor(self, position: Position, direction: Direction) -> bool:
+            """Return True if a conveyor facing direction can be built at position."""
+            ...
+
+        def can_build_splitter(self, position: Position, direction: Direction) -> bool:
+            """Return True if a splitter facing direction can be built at position."""
+            ...
+
+        def can_build_harvester(self, position: Position) -> bool:
+            """Return True if a harvester can be built at position (must be an ore tile)."""
+            ...
+
+        def can_build_barrier(self, position: Position) -> bool:
+            """Return True if a barrier can be built at position."""
+            ...
+
+        def can_build_gunner(self, position: Position, direction: Direction) -> bool:
+            """Return True if a gunner facing direction can be built at position.
+            Respects the global unit cap."""
+            ...
+
+        def can_build_sentinel(self, position: Position, direction: Direction) -> bool:
+            """Return True if a sentinel facing direction can be built at position.
+            Respects the global unit cap."""
+            ...
+
+        def can_build_launcher(self, position: Position) -> bool:
+            """Return True if a launcher can be built at position.
+            Respects the global unit cap."""
+            ...
+
+        def build_conveyor(self, position: Position, direction: Direction) -> int:
+            """Build a conveyor facing direction at position. Raises GameError if not legal."""
+            ...
+
+        def build_splitter(self, position: Position, direction: Direction) -> int:
+            """Build a splitter facing direction at position. Raises GameError if not legal."""
+            ...
+
+        def build_harvester(self, position: Position) -> int:
+            """Build a harvester at position (must be an ore tile). Raises GameError if not legal."""
+            ...
+
+        def build_barrier(self, position: Position) -> int:
+            """Build a barrier at position. Raises GameError if not legal."""
+            ...
+
+        def build_gunner(self, position: Position, direction: Direction) -> int:
+            """Build a gunner facing direction at position. Raises GameError if not legal."""
+            ...
+
+        def build_sentinel(self, position: Position, direction: Direction) -> int:
+            """Build a sentinel facing direction at position. Raises GameError if not legal."""
+            ...
+
+        def build_launcher(self, position: Position) -> int:
+            """Build a launcher at position. Raises GameError if not legal."""
+            ...
+
+        def can_build(
+            self,
+            entity_type: EntityType,
+            position: Position,
+            extra: Direction | Position | None = None,
+        ) -> bool:
+            """Return True if entity_type can be built at position.
+            For entity types that require a direction (conveyor, splitter,
+            gunner, sentinel), extra must be a Direction.
+            For harvester, barrier, launcher, extra is unused."""
+            ...
+
+        def build(
+            self,
+            entity_type: EntityType,
+            position: Position,
+            extra: Direction | Position | None = None,
+        ) -> int:
+            """Build entity_type at position. Raises GameError if not legal.
+            For entity types that require a direction (conveyor, splitter,
+            gunner, sentinel), extra must be a Direction.
+            For harvester, barrier, launcher, extra is unused."""
+            ...
+
+        # --- Healing ---
+
+        def heal(self, position: Position) -> None:
+            """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 are on the tile, both are healed.
+            Costs 1 titanium and one action cooldown. Raises GameError if not legal."""
+            ...
+
+        def can_heal(self, position: Position) -> bool:
+            """Return True if this builder bot can heal the tile at position this turn.
+            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."""
+            ...
+
+        # --- Destruction ---
+
+        def can_destroy(self, building_pos: Position) -> bool:
+            """Return True if this builder bot can destroy the allied building at building_pos."""
+            ...
+
+        def destroy(self, building_pos: Position) -> None:
+            """Destroy the allied building at building_pos. Does not cost action cooldown.
+            Raises GameError if not legal."""
+            ...
+
+        def self_destruct(self) -> None:
+            """Destroy this unit. Builder bots no longer deal explosion damage when they self-destruct."""
+            ...
+
+        def resign(self, message: str | None = None) -> None:
+            """Forfeit the game immediately. Destroys this team's core, ending the game as a loss.
+
+            Args:
+                message: Optional reason for resigning. Displayed in match results.
+            """
+            ...
+
+        # --- Communication Store ---
+
+        def read_store(self, index: int) -> int:
+            """Return the u32 value at index in this team's global communication store.
+            Reads the snapshot from the start of this turn. index must be in 0..STORE_SIZE."""
+            ...
+
+        def write_store(self, index: int, value: int) -> None:
+            """Buffer a write to this team's communication store at index.
+            The write takes effect at the start of next turn and is visible to all units.
+            index must be in 0..STORE_SIZE; value is treated as u32 (0..2^32-1)."""
+            ...
+
+        # --- Turrets ---
+
+        def can_fire(self, target: Position) -> bool:
+            """Return True if this builder bot or turret can fire at target this turn.
+            Builder bots may only target their own tile and only damage the building on it.
+            For gunners, only empty tiles fail to block the firing line. Walls block the line but
+            are not targetable. Builder bots and buildings are both targetable and blocking.
+            Use can_launch() instead for launchers."""
+            ...
+
+        def can_fire_from(
+            self,
+            position: Position,
+            direction: Direction,
+            turret_type: EntityType,
+            target: Position,
+        ) -> bool:
+            """Return True if a hypothetical turret at position facing direction could fire at target.
+            This uses the current map state for occupancy and walls, but ignores ammo and cooldown.
+            For gunners, the target tile must be occupied. Only empty tiles do not block the line;
+            walls, builder bots, and buildings do, with walls remaining untargetable.
+            For launchers this only checks raw throw range, and direction is ignored."""
+            ...
+
+        def fire(self, target: Position) -> None:
+            """Fire this builder bot or turret at target. Builder bots may only target their own tile.
+            For gunners, walls, builder bots, and buildings stop the firing line; walls themselves
+            are not valid targets.
+            Use launch() instead for launchers.
+            Raises GameError if not legal."""
+            ...
+
+        def can_rotate(self, direction: Direction) -> bool:
+            """Return True if this gunner can rotate to a different compass direction this turn.
+            Also checks that your team can afford the global titanium cost."""
+            ...
+
+        def rotate(self, direction: Direction) -> None:
+            """Rotate this gunner to a different compass direction.
+            Costs 10 titanium and sets action cooldown to 1.
+            Raises GameError if not legal."""
+            ...
+
+        def get_gunner_target(self) -> Position | None:
+            """Return the position of the closest targetable tile in the gunner's facing direction,
+            or None if nothing is in range. Empty tiles are skipped. Walls block the line without
+            being targetable. Only valid on gunners."""
+            ...
+
+        def get_attackable_tiles(self) -> list[Position]:
+            """Return all in-bounds tiles in this turret's raw attack pattern.
+            This ignores ammo, cooldown, occupancy, and other target-specific legality checks.
+            For gunners this includes the full firing line within range, even behind walls.
+            Use get_gunner_target(), can_fire(), or can_launch() for actual legal targets.
+            Raises GameError if this unit is not a turret."""
+            ...
+
+        def get_attackable_tiles_from(
+            self,
+            position: Position,
+            direction: Direction,
+            turret_type: EntityType,
+        ) -> list[Position]:
+            """Return all in-bounds tiles in a hypothetical turret's raw attack pattern.
+            This ignores ammo, cooldown, occupancy, and other target-specific legality checks.
+            For gunners this includes the full firing line within range, even behind walls.
+            Launchers ignore direction."""
+            ...
+
+        def can_launch(self, bot_pos: Position, target: Position) -> bool:
+            """Return True if this launcher can pick up the builder bot at bot_pos and throw it to target."""
+            ...
+
+        def launch(self, bot_pos: Position, target: Position) -> None:
+            """Pick up the builder bot at bot_pos and throw it to target.
+            Raises GameError if not legal."""
+            ...
+
+        # --- Core ---
+
+        def spawn_builder(self, position: Position) -> int:
+            """Spawn a builder bot on a tile immediately surrounding the core's footprint at position.
+            Costs one action cooldown. Raises GameError if not legal."""
+            ...
+
+        def can_spawn(self, position: Position) -> bool:
+            """Return True if the core can spawn a builder bot at position this turn.
+            Also requires spare room under the global 50-unit cap."""
+            ...
+
+        # --- Indicators ---
+
+        def draw_indicator_line(
+            self, pos_a: Position, pos_b: Position, r: int, g: int, b: int
+        ) -> None:
+            """Draw a debug line from pos_a to pos_b with RGB colour. Saved to the replay."""
+            ...
+
+        def draw_indicator_dot(self, pos: Position, r: int, g: int, b: int) -> None:
+            """Draw a debug dot at pos with RGB colour. Saved to the replay."""
+            ...