sonartk 0.1__py3-none-any.whl

sonartk/__init__.py

@@ -0,0 +1,34 @@
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
+__all__ = [
+    "Window",
+    "MapGridGameBuilder",
+    "BuiltMapGridGame",
+    "MapSoundNavigationController",
+]
+
+if TYPE_CHECKING:
+    from sonartk.orchestration.game_builder import (
+        BuiltMapGridGame,
+        MapGridGameBuilder,
+    )
+    from sonartk.orchestration.map_sound_navigation import (
+        MapSoundNavigationController,
+    )
+    from sonartk.ui.window import Window
+
+
+def __getattr__(name: str) -> Any:
+    if name == "Window":
+        from sonartk.ui.window import Window
+
+        return Window
+    if name in {
+        "MapGridGameBuilder",
+        "BuiltMapGridGame",
+        "MapSoundNavigationController",
+    }:
+        orchestration = import_module("sonartk.orchestration")
+        return getattr(orchestration, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

sonartk/map_builder/__init__.py

@@ -0,0 +1,14 @@
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
+__all__ = ["Map2d", "MapTile", "load_2d_map"]
+
+if TYPE_CHECKING:
+    from sonartk.map_builder.map_2d import Map2d, MapTile, load_2d_map
+
+
+def __getattr__(name: str) -> Any:
+    if name in __all__:
+        module = import_module("sonartk.map_builder.map_2d")
+        return getattr(module, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

sonartk/map_builder/map_2d/__init__.py

@@ -0,0 +1,25 @@
+from sonartk.map_builder.map_2d.map_loader import load_2d_map
+from sonartk.map_builder.map_2d.map_2d import Map2d
+from sonartk.map_builder.map_2d.map_queries import (
+    Map2dQueries,
+    MapQueryResult,
+    PathfindingResult,
+    PathfindingState,
+)
+from sonartk.map_builder.map_2d.map_tile import MapTile
+from sonartk.map_builder.map_2d.direction_tools import (
+    direction_offset,
+    step_coordinates,
+)
+
+__all__ = [
+    "Map2d",
+    "Map2dQueries",
+    "MapQueryResult",
+    "PathfindingResult",
+    "PathfindingState",
+    "MapTile",
+    "direction_offset",
+    "step_coordinates",
+    "load_2d_map",
+]

sonartk/map_builder/map_2d/direction_tools.py

@@ -0,0 +1,29 @@
+from sonartk.util import Coordinates, Direction
+
+
+def direction_offset(direction: Direction) -> tuple[int, int]:
+    """Return the coordinate delta for a Direction value."""
+    direction_to_offset: dict[Direction, tuple[int, int]] = {
+        Direction.UP: (0, 1),
+        Direction.DIAGONAL_UPPER_RIGHT: (1, 1),
+        Direction.RIGHT: (1, 0),
+        Direction.DIAGONAL_LOWER_RIGHT: (1, -1),
+        Direction.DOWN: (0, -1),
+        Direction.DIAGONAL_LOWER_LEFT: (-1, -1),
+        Direction.LEFT: (-1, 0),
+        Direction.DIAGONAL_UPPER_LEFT: (-1, 1),
+    }
+    return direction_to_offset[direction]
+
+
+def step_coordinates(
+    origin: Coordinates,
+    direction: Direction,
+    distance: int = 1,
+) -> Coordinates:
+    """Translate origin by direction and integer distance."""
+    if distance < 0:
+        raise ValueError("distance must be greater than or equal to 0")
+
+    dx, dy = direction_offset(direction)
+    return (origin[0] + (dx * distance), origin[1] + (dy * distance))

sonartk/map_builder/map_2d/map_2d.py

@@ -0,0 +1,257 @@
+from types import MappingProxyType
+from typing import Literal, Mapping, Optional
+
+from sonartk.map_builder.map_2d.map_object.character import Character
+from sonartk.map_builder.map_2d.map_tile import MapTile
+from sonartk.map_builder.map_2d.map_object import MapObject
+from sonartk.map_builder.map_2d.map_queries import Map2dQueries
+from sonartk.util import Coordinates
+
+CharacterCollisionPolicy = Literal["error", "replace"]
+ObjectCollisionPolicy = Literal["error", "replace"]
+
+
+class Map2d:
+    def __init__(
+        self,
+        name: str,
+        character: Character,
+        *,
+        character_collision_policy: CharacterCollisionPolicy = "error",
+        object_collision_policy: ObjectCollisionPolicy = "error",
+    ) -> None:
+        self.name: str = name
+        self.character: Character = character
+        self.tile_map: list[MapTile] = []
+        self.height: int = 0
+        self.width: int = 0
+        self.character_collision_policy = character_collision_policy
+        self.object_collision_policy = object_collision_policy
+        self._character_index: dict[Coordinates, Character] = {}
+        self._object_index: dict[Coordinates, MapObject] = {}
+        self._character_index_view: Mapping[Coordinates, Character] = (
+            MappingProxyType(self._character_index)
+        )
+        self._object_index_view: Mapping[Coordinates, MapObject] = (
+            MappingProxyType(self._object_index)
+        )
+        self.queries: Map2dQueries = Map2dQueries(self)
+        self.register_character(character)
+
+    @property
+    def character_index(self) -> Mapping[Coordinates, Character]:
+        """Read-only coordinate index for registered characters."""
+        return self._character_index_view
+
+    @property
+    def object_index(self) -> Mapping[Coordinates, MapObject]:
+        """Read-only coordinate index for registered map objects."""
+        return self._object_index_view
+
+    def add_row(self, row: list[MapTile]) -> None:
+        """Insert a map row and update map dimensions.
+
+        New rows are prepended so ``y=0`` points at the most recently inserted
+        row, matching the current map coordinate convention.
+        """
+        if self.tile_map and self.width != len(row):
+            raise IndexError(
+                f"The width of the new row must match the width of the map.  Row Width: {len(row)} - Map Width: {self.width}"
+            )
+        if not self.tile_map:
+            self.width = len(row)
+
+        self.height += 1
+        self.tile_map[:0] = row
+
+    def get_tile(self, coordinates: Coordinates) -> MapTile:
+        """Return the tile at coordinates, raising on out-of-range access."""
+        x, y = coordinates
+        if x >= self.width or x < 0:
+            raise IndexError(
+                f"x value is out of bounds. x cannot be less than0 or greater than map width.  x: {x} - map width: {self.width}"
+            )
+        if y >= self.height or y < 0:
+            raise IndexError(
+                f"y value is out of bounds. y cannot be less than 0 or greater than map height.  y: {y} - map height: {self.height}"
+            )
+
+        return self.tile_map[y * self.width + x]
+
+    def set_tile(self, coordinates: Coordinates, tile: MapTile) -> None:
+        """Replace the tile at coordinates, raising on out-of-range access."""
+        x, y = coordinates
+        if x >= self.width or x < 0:
+            raise IndexError(
+                f"x value is out of bounds. x cannot be less than0 or greater than map width.  x: {x} - map width: {self.width}"
+            )
+        if y >= self.height or y < 0:
+            raise IndexError(
+                f"y value is out of bounds. y cannot be less than 0 or greater than map height.  y: {y} - map height: {self.height}"
+            )
+
+        self.tile_map[y * self.width + x] = tile
+
+    def set_tiles(self, updates: Mapping[Coordinates, MapTile]) -> None:
+        """Apply multiple tile replacements as a single convenience operation."""
+        for coordinates, tile in updates.items():
+            self.set_tile(coordinates, tile)
+
+    def register_character(self, character: Character) -> Optional[Character]:
+        """Register a character and return any displaced occupant at that coordinate."""
+        self._validate_coordinate_for_registration(character.coordinates)
+        displaced = self._ensure_character_slot_available(
+            character.coordinates, character
+        )
+        self._character_index[character.coordinates] = character
+        return displaced
+
+    def move_character(
+        self, character: Character, new_coordinates: Coordinates
+    ) -> Optional[Character]:
+        """Move a character and return any displaced occupant at destination."""
+        self._validate_coordinate_for_registration(new_coordinates)
+        current_coordinates = character.coordinates
+        if self._character_index.get(current_coordinates) is not character:
+            raise LookupError(
+                f"The character {character.name} is not registered at coordinates {current_coordinates}."
+            )
+
+        displaced = self._ensure_character_slot_available(
+            new_coordinates, character
+        )
+
+        del self._character_index[current_coordinates]
+        character.coordinates = new_coordinates
+        self._character_index[new_coordinates] = character
+        return displaced
+
+    def remove_character(self, character: Character) -> None:
+        """Remove a registered character from the coordinate index."""
+        current_coordinates = character.coordinates
+        if self._character_index.get(current_coordinates) is not character:
+            raise LookupError(
+                f"The character {character.name} is not registered at coordinates {current_coordinates}."
+            )
+
+        del self._character_index[current_coordinates]
+
+    def register_map_object(
+        self, map_object: MapObject
+    ) -> Optional[MapObject]:
+        """Register a map object and return any displaced occupant at that coordinate."""
+        self._validate_coordinate_for_registration(map_object.coordinates)
+        displaced = self._ensure_object_slot_available(
+            map_object.coordinates, map_object
+        )
+        self._object_index[map_object.coordinates] = map_object
+        return displaced
+
+    def move_map_object(
+        self, map_object: MapObject, new_coordinates: Coordinates
+    ) -> Optional[MapObject]:
+        """Move a map object and return any displaced occupant at destination."""
+        self._validate_coordinate_for_registration(new_coordinates)
+        current_coordinates = map_object.coordinates
+        if self._object_index.get(current_coordinates) is not map_object:
+            raise LookupError(
+                f"The map object {map_object.name} is not registered at coordinates {current_coordinates}."
+            )
+
+        displaced = self._ensure_object_slot_available(
+            new_coordinates, map_object
+        )
+
+        del self._object_index[current_coordinates]
+        map_object.coordinates = new_coordinates
+        self._object_index[new_coordinates] = map_object
+        return displaced
+
+    def remove_map_object(self, map_object: MapObject) -> None:
+        """Remove a registered map object from the coordinate index."""
+        current_coordinates = map_object.coordinates
+        if self._object_index.get(current_coordinates) is not map_object:
+            raise LookupError(
+                f"The map object {map_object.name} is not registered at coordinates {current_coordinates}."
+            )
+
+        del self._object_index[current_coordinates]
+
+    def find_map_object_coordinates(
+        self, map_object: MapObject
+    ) -> Optional[Coordinates]:
+        """Return coordinates for a registered map object by identity."""
+        for coordinates, registered_object in self._object_index.items():
+            if registered_object is map_object:
+                return coordinates
+
+        return None
+
+    def is_map_object_registered(self, map_object: MapObject) -> bool:
+        """Return whether a map object is currently registered by identity."""
+        return self.find_map_object_coordinates(map_object) is not None
+
+    def get_map_object_at(
+        self, coordinates: Coordinates
+    ) -> Optional[MapObject]:
+        """Return the registered map object at coordinates, if present."""
+        return self._object_index.get(coordinates)
+
+    def remove_map_object_at(
+        self, coordinates: Coordinates
+    ) -> Optional[MapObject]:
+        """Remove and return the map object at coordinates, if present."""
+        removed = self._object_index.get(coordinates)
+        if removed is None:
+            return None
+
+        del self._object_index[coordinates]
+        return removed
+
+    def _ensure_character_slot_available(
+        self, coordinates: Coordinates, character: Character
+    ) -> Optional[Character]:
+        existing = self._character_index.get(coordinates)
+        if existing is None or existing is character:
+            return None
+
+        if self.character_collision_policy == "replace":
+            del self._character_index[coordinates]
+            return existing
+
+        raise ValueError(
+            f"Character coordinate collision at {coordinates} for '{character.name}'."
+        )
+
+    def _validate_coordinate_for_registration(
+        self, coordinates: Coordinates
+    ) -> None:
+        """Validate coordinates when map dimensions are known.
+
+        Map entities are constructed before rows are loaded in many flows, so
+        bounds checks are deferred until width/height are available.
+        """
+        if self.width == 0 or self.height == 0:
+            return
+
+        x, y = coordinates
+        if x < 0 or y < 0 or x >= self.width or y >= self.height:
+            raise ValueError(
+                "Coordinates out of map bounds: "
+                f"{coordinates} for map size ({self.width}, {self.height})."
+            )
+
+    def _ensure_object_slot_available(
+        self, coordinates: Coordinates, map_object: MapObject
+    ) -> Optional[MapObject]:
+        existing = self._object_index.get(coordinates)
+        if existing is None or existing is map_object:
+            return None
+
+        if self.object_collision_policy == "replace":
+            del self._object_index[coordinates]
+            return existing
+
+        raise ValueError(
+            f"Map object coordinate collision at {coordinates} for '{map_object.name}'."
+        )

sonartk/map_builder/map_2d/map_loader.py

@@ -0,0 +1,33 @@
+from typing import Callable, TypeVar
+
+from sonartk.map_builder.map_2d.map_2d import Map2d
+from sonartk.map_builder.map_2d.map_object.character import Character
+from sonartk.map_builder.map_2d.map_tile import MapTile
+from sonartk.map_builder.map_2d.parser.map_parser import MapParser
+from sonartk.map_builder.map_2d.parser.stop_parsing_exception import (
+    StopParsingException,
+)
+
+T = TypeVar("T")
+
+
+def load_2d_map(
+    map_name: str,
+    file_name: str,
+    parser: MapParser[T],
+    mapper: Callable[[T], MapTile],
+    character: Character,
+) -> Map2d:
+    """Load a 2D map file with a parser and convert each parsed entry to a MapTile."""
+    map2d: Map2d = Map2d(map_name, character)
+    with parser:
+        parser.open(file_name)
+        while True:
+            try:
+                row: list[T] = parser.read()
+                mapped_row: list[MapTile] = [mapper(tile) for tile in row]
+                map2d.add_row(mapped_row)
+            except StopParsingException:
+                break
+
+    return map2d

sonartk/map_builder/map_2d/map_object/__init__.py

@@ -0,0 +1,4 @@
+from sonartk.map_builder.map_2d.map_object.map_object import MapObject
+from sonartk.map_builder.map_2d.map_object.character import Character
+
+__all__ = ["MapObject", "Character"]

sonartk/map_builder/map_2d/map_object/character.py

@@ -0,0 +1,15 @@
+from sonartk.map_builder.map_2d.map_object import MapObject
+from sonartk.util import Coordinates, Direction
+
+
+class Character(MapObject):
+    def __init__(
+        self,
+        name: str,
+        coordinates: Coordinates,
+        directional_orientation: Direction,
+        radius: int = 5,
+    ) -> None:
+        super().__init__(name, coordinates)
+        self.directional_orientation: Direction = directional_orientation
+        self.radius: int = radius

sonartk/map_builder/map_2d/map_object/map_object.py

@@ -0,0 +1,11 @@
+from sonartk.util import Coordinates
+
+
+class MapObject:
+    def __init__(self, name: str, coordinates: Coordinates) -> None:
+        self.name: str = name
+        self.coordinates: Coordinates = coordinates
+
+    def interact(self) -> None:
+        """Interact."""
+        pass