empire-core 0.7.3__py3-none-any.whl

empire_core/services/alliance.py

@@ -0,0 +1,222 @@
+"""
+Alliance service for EmpireCore.
+
+Provides high-level APIs for:
+- Alliance chat (send messages, get history)
+- Alliance help (help members, help all, request help)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Callable
+
+from empire_core.protocol.models import (
+    AllianceChatLogRequest,
+    AllianceChatLogResponse,
+    AllianceChatMessageRequest,
+    AllianceChatMessageResponse,
+    AskHelpRequest,
+    ChatLogEntry,
+    HelpAllRequest,
+    HelpAllResponse,
+    HelpMemberRequest,
+)
+
+from .base import BaseService, register_service
+
+if TYPE_CHECKING:
+    pass
+
+
+@register_service("alliance")
+class AllianceService(BaseService):
+    """
+    Service for alliance operations.
+
+    Accessible via client.alliance after auto-registration.
+
+    Usage:
+        client = EmpireClient(...)
+        client.login()
+
+        # Send chat message
+        client.alliance.send_chat("Hello alliance!")
+
+        # Help all members
+        client.alliance.help_all()
+
+        # Subscribe to incoming messages
+        def on_message(response: AllianceChatMessageResponse):
+            print(f"{response.player_name}: {response.decoded_text}")
+
+        client.alliance.on_chat_message(on_message)
+    """
+
+    def __init__(self, client) -> None:
+        super().__init__(client)
+        self._chat_callbacks: list[Callable[[AllianceChatMessageResponse], None]] = []
+
+        # Register internal handler for chat messages
+        self.on_response("acm", self._handle_chat_message)
+
+    # =========================================================================
+    # Chat Operations
+    # =========================================================================
+
+    def send_chat(self, message: str) -> None:
+        """
+        Send a message to alliance chat.
+
+        Args:
+            message: The message text to send (will be auto-encoded)
+
+        Example:
+            client.alliance.send_chat("Hello alliance!")
+            client.alliance.send_chat("Special chars work: 100% safe!")
+        """
+        request = AllianceChatMessageRequest.create(message)
+        self.send(request)
+
+    def get_chat_log(self, timeout: float = 5.0) -> list[ChatLogEntry]:
+        """
+        Get alliance chat history.
+
+        Args:
+            timeout: Timeout in seconds to wait for response
+
+        Returns:
+            List of ChatLogEntry objects
+
+        Example:
+            history = client.alliance.get_chat_log()
+            for entry in history:
+                print(f"{entry.player_name}: {entry.decoded_text}")
+        """
+        request = AllianceChatLogRequest()
+        response = self.send(request, wait=True, timeout=timeout)
+
+        if isinstance(response, AllianceChatLogResponse):
+            return response.chat_log
+
+        return []
+
+    def on_chat_message(self, callback: Callable[[AllianceChatMessageResponse], None]) -> None:
+        """
+        Register a callback for incoming alliance chat messages.
+
+        The callback will be called whenever a chat message is received,
+        including messages from other players and confirmations of your own.
+
+        Args:
+            callback: Function that receives AllianceChatMessageResponse
+
+        Example:
+            def on_message(msg: AllianceChatMessageResponse):
+                print(f"[{msg.player_name}] {msg.decoded_text}")
+
+            client.alliance.on_chat_message(on_message)
+        """
+        self._chat_callbacks.append(callback)
+
+    def _handle_chat_message(self, response) -> None:
+        """Internal handler for chat message responses."""
+        if isinstance(response, AllianceChatMessageResponse):
+            for callback in self._chat_callbacks:
+                try:
+                    callback(response)
+                except Exception:
+                    pass  # Silently ignore callback errors
+
+    # =========================================================================
+    # Help Operations
+    # =========================================================================
+
+    def help_all(self) -> HelpAllResponse | None:
+        """
+        Help all alliance members who need help.
+
+        Sends a single request that helps all pending help requests
+        (heal, repair, recruit).
+
+        Returns:
+            HelpAllResponse with helped_count, or None on failure
+
+        Example:
+            response = client.alliance.help_all()
+            if response:
+                print(f"Helped {response.helped_count} members")
+        """
+        request = HelpAllRequest()
+        response = self.send(request, wait=True, timeout=5.0)
+
+        if isinstance(response, HelpAllResponse):
+            return response
+
+        return None
+
+    def help_member_heal(self, player_id: int, castle_id: int) -> None:
+        """
+        Help heal a specific member's wounded soldiers.
+
+        Args:
+            player_id: The player's ID
+            castle_id: The castle ID with wounded soldiers
+        """
+        request = HelpMemberRequest.heal(player_id, castle_id)
+        self.send(request)
+
+    def help_member_repair(self, player_id: int, castle_id: int) -> None:
+        """
+        Help repair a specific member's building.
+
+        Args:
+            player_id: The player's ID
+            castle_id: The castle ID with damaged building
+        """
+        request = HelpMemberRequest.repair(player_id, castle_id)
+        self.send(request)
+
+    def help_member_recruit(self, player_id: int, castle_id: int) -> None:
+        """
+        Help a specific member with soldier recruitment.
+
+        Args:
+            player_id: The player's ID
+            castle_id: The castle ID recruiting soldiers
+        """
+        request = HelpMemberRequest.recruit(player_id, castle_id)
+        self.send(request)
+
+    def request_heal_help(self, castle_id: int) -> None:
+        """
+        Request heal help from alliance for a castle.
+
+        Args:
+            castle_id: The castle ID with wounded soldiers
+        """
+        request = AskHelpRequest.heal(castle_id)
+        self.send(request)
+
+    def request_repair_help(self, castle_id: int, building_id: int) -> None:
+        """
+        Request repair help from alliance for a building.
+
+        Args:
+            castle_id: The castle ID
+            building_id: The building ID that needs repair
+        """
+        request = AskHelpRequest.repair(castle_id, building_id)
+        self.send(request)
+
+    def request_recruit_help(self, castle_id: int) -> None:
+        """
+        Request recruit help from alliance for a castle.
+
+        Args:
+            castle_id: The castle ID recruiting soldiers
+        """
+        request = AskHelpRequest.recruit(castle_id)
+        self.send(request)
+
+
+__all__ = ["AllianceService"]

empire_core/services/base.py

@@ -0,0 +1,107 @@
+"""
+Base service class and registration decorator.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Callable, Type, TypeVar
+
+from empire_core.protocol.models import BaseRequest, BaseResponse, parse_response
+
+if TYPE_CHECKING:
+    from empire_core.client.client import EmpireClient
+
+# Registry of service classes
+_service_registry: dict[str, Type["BaseService"]] = {}
+
+T = TypeVar("T", bound="BaseService")
+
+
+def register_service(name: str) -> Callable[[Type[T]], Type[T]]:
+    """
+    Decorator to register a service class.
+
+    Usage:
+        @register_service("alliance")
+        class AllianceService(BaseService):
+            ...
+
+    The service will be accessible as client.alliance
+    """
+
+    def decorator(cls: Type[T]) -> Type[T]:
+        _service_registry[name] = cls
+        cls._service_name = name
+        return cls
+
+    return decorator
+
+
+def get_registered_services() -> dict[str, Type["BaseService"]]:
+    """Get all registered service classes."""
+    return _service_registry.copy()
+
+
+class BaseService:
+    """
+    Base class for all services.
+
+    Services provide high-level APIs for game domains and use
+    protocol models for type-safe request/response handling.
+    """
+
+    _service_name: str = ""
+
+    def __init__(self, client: "EmpireClient") -> None:
+        self.client = client
+
+    @property
+    def zone(self) -> str:
+        """Get the game zone from client config."""
+        return self.client.config.default_zone
+
+    def send(self, request: BaseRequest, wait: bool = False, timeout: float = 5.0) -> BaseResponse | None:
+        """
+        Send a request to the server.
+
+        Args:
+            request: The request model to send
+            wait: Whether to wait for a response
+            timeout: Timeout in seconds when waiting
+
+        Returns:
+            The parsed response if wait=True, otherwise None
+        """
+        packet = request.to_packet(zone=self.zone)
+        self.client.connection.send(packet)
+
+        if wait:
+            command = request.get_command()
+            try:
+                response_packet = self.client.connection.wait_for(command, timeout=timeout)
+                if response_packet and isinstance(response_packet.payload, dict):
+                    return parse_response(command, response_packet.payload)
+            except Exception:
+                return None
+
+        return None
+
+    def on_response(self, command: str, handler: Callable[[BaseResponse], None]) -> None:
+        """
+        Register a handler for a specific response type.
+
+        Handlers are registered with the client for efficient routing.
+        Only commands with registered handlers will be parsed.
+
+        Args:
+            command: The command code to handle (e.g., "acm")
+            handler: Callback function that receives the parsed response
+        """
+        self.client._register_handler(command, handler)
+
+
+__all__ = [
+    "BaseService",
+    "register_service",
+    "get_registered_services",
+]

empire_core/services/castle.py

@@ -0,0 +1,221 @@
+"""
+Castle service for EmpireCore.
+
+Provides high-level APIs for:
+- Castle management (list, select, rename, relocate)
+- Resource information
+- Production rates
+"""
+
+from __future__ import annotations
+
+from empire_core.protocol.models import (
+    CastleInfo,
+    DetailedCastleInfo,
+    GetCastlesRequest,
+    GetCastlesResponse,
+    GetDetailedCastleRequest,
+    GetDetailedCastleResponse,
+    GetProductionRequest,
+    GetProductionResponse,
+    GetResourcesRequest,
+    GetResourcesResponse,
+    ProductionRates,
+    RenameCastleRequest,
+    RenameCastleResponse,
+    ResourceAmount,
+    SelectCastleRequest,
+    SelectCastleResponse,
+)
+
+from .base import BaseService, register_service
+
+
+@register_service("castle")
+class CastleService(BaseService):
+    """
+    Service for castle operations.
+
+    Accessible via client.castle after auto-registration.
+
+    Usage:
+        client = EmpireClient(...)
+        client.login()
+
+        # Get all castles
+        castles = client.castle.get_all()
+        for c in castles:
+            print(f"{c.castle_name} at ({c.x}, {c.y})")
+
+        # Select a castle
+        client.castle.select(castle_id=12345)
+
+        # Get resources
+        resources = client.castle.get_resources(castle_id=12345)
+    """
+
+    # =========================================================================
+    # Castle List Operations
+    # =========================================================================
+
+    def get_all(self, timeout: float = 5.0) -> list[CastleInfo]:
+        """
+        Get list of all player's castles.
+
+        Args:
+            timeout: Timeout in seconds to wait for response
+
+        Returns:
+            List of CastleInfo objects
+
+        Example:
+            castles = client.castle.get_all()
+            for c in castles:
+                print(f"{c.castle_name} (ID: {c.castle_id}) at ({c.x}, {c.y})")
+        """
+        request = GetCastlesRequest()
+        response = self.send(request, wait=True, timeout=timeout)
+
+        if isinstance(response, GetCastlesResponse):
+            return response.castles
+
+        return []
+
+    def get_details(self, castle_id: int, timeout: float = 5.0) -> DetailedCastleInfo | None:
+        """
+        Get detailed information about a specific castle.
+
+        Args:
+            castle_id: The castle ID
+            timeout: Timeout in seconds
+
+        Returns:
+            DetailedCastleInfo with buildings, resources, etc., or None
+
+        Example:
+            details = client.castle.get_details(12345)
+            if details:
+                print(f"Buildings: {len(details.buildings)}")
+                print(f"Population: {details.population}/{details.max_population}")
+        """
+        request = GetDetailedCastleRequest(CID=castle_id)
+        response = self.send(request, wait=True, timeout=timeout)
+
+        if isinstance(response, GetDetailedCastleResponse):
+            return response.castle
+
+        return None
+
+    # =========================================================================
+    # Castle Selection
+    # =========================================================================
+
+    def select(self, castle_id: int, timeout: float = 5.0) -> bool:
+        """
+        Select/jump to a castle (makes it the active castle).
+
+        Args:
+            castle_id: The castle ID to select
+            timeout: Timeout in seconds
+
+        Returns:
+            True if successful, False otherwise
+
+        Example:
+            if client.castle.select(12345):
+                print("Castle selected!")
+        """
+        request = SelectCastleRequest(CID=castle_id)
+        response = self.send(request, wait=True, timeout=timeout)
+
+        if isinstance(response, SelectCastleResponse):
+            return response.error_code == 0
+
+        return False
+
+    # =========================================================================
+    # Castle Modification
+    # =========================================================================
+
+    def rename(self, castle_id: int, new_name: str, timeout: float = 5.0) -> bool:
+        """
+        Rename a castle.
+
+        Args:
+            castle_id: The castle ID
+            new_name: The new castle name
+            timeout: Timeout in seconds
+
+        Returns:
+            True if successful, False otherwise
+
+        Example:
+            if client.castle.rename(12345, "My Fortress"):
+                print("Castle renamed!")
+        """
+        request = RenameCastleRequest(CID=castle_id, CN=new_name)
+        response = self.send(request, wait=True, timeout=timeout)
+
+        if isinstance(response, RenameCastleResponse):
+            return response.error_code == 0
+
+        return False
+
+    # =========================================================================
+    # Resource Operations
+    # =========================================================================
+
+    def get_resources(self, castle_id: int, timeout: float = 5.0) -> ResourceAmount | None:
+        """
+        Get current resources for a castle.
+
+        Args:
+            castle_id: The castle ID
+            timeout: Timeout in seconds
+
+        Returns:
+            ResourceAmount with wood, stone, food, coins, or None
+
+        Example:
+            resources = client.castle.get_resources(12345)
+            if resources:
+                print(f"Wood: {resources.wood}")
+                print(f"Stone: {resources.stone}")
+        """
+        request = GetResourcesRequest(CID=castle_id)
+        response = self.send(request, wait=True, timeout=timeout)
+
+        if isinstance(response, GetResourcesResponse):
+            return response.resources
+
+        return None
+
+    def get_production(
+        self, castle_id: int, timeout: float = 5.0
+    ) -> tuple[ProductionRates | None, ProductionRates | None]:
+        """
+        Get production and consumption rates for a castle.
+
+        Args:
+            castle_id: The castle ID
+            timeout: Timeout in seconds
+
+        Returns:
+            Tuple of (production_rates, consumption_rates), either may be None
+
+        Example:
+            production, consumption = client.castle.get_production(12345)
+            if production:
+                print(f"Wood/hr: {production.wood}")
+                print(f"Food/hr: {production.food}")
+        """
+        request = GetProductionRequest(CID=castle_id)
+        response = self.send(request, wait=True, timeout=timeout)
+
+        if isinstance(response, GetProductionResponse):
+            return response.production, response.consumption
+
+        return None, None
+
+
+__all__ = ["CastleService"]