empire-core 0.7.3__py3-none-any.whl

empire_core/protocol/models/defense.py

@@ -0,0 +1,300 @@
+"""
+Defense protocol models.
+
+Commands:
+- dfc: Get defense configuration
+- dfk: Change keep defense
+- dfw: Change wall defense
+- dfm: Change moat defense
+"""
+
+from __future__ import annotations
+
+from pydantic import ConfigDict, Field
+
+from .base import BaseRequest, BaseResponse, UnitCount
+
+# =============================================================================
+# DFC - Get Defense Configuration
+# =============================================================================
+
+
+class GetDefenseRequest(BaseRequest):
+    """
+    Get defense configuration for a castle.
+
+    Command: dfc
+    Payload: {"CID": castle_id}
+    """
+
+    command = "dfc"
+
+    castle_id: int = Field(alias="CID")
+
+
+class DefenseConfiguration(BaseResponse):
+    """Defense configuration for a location (keep, wall, moat)."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    units: list[UnitCount] = Field(alias="U", default_factory=list)
+    tools: list[UnitCount] = Field(alias="T", default_factory=list)
+
+
+class GetDefenseResponse(BaseResponse):
+    """
+    Response containing defense configuration.
+
+    Command: dfc
+    """
+
+    command = "dfc"
+
+    keep: DefenseConfiguration | None = Field(alias="K", default=None)
+    wall: DefenseConfiguration | None = Field(alias="W", default=None)
+    moat: DefenseConfiguration | None = Field(alias="M", default=None)
+    courtyard: DefenseConfiguration | None = Field(alias="C", default=None)
+
+
+# =============================================================================
+# DFK - Change Keep Defense
+# =============================================================================
+
+
+class ChangeKeepDefenseRequest(BaseRequest):
+    """
+    Change keep defense configuration.
+
+    Command: dfk
+    Payload: {
+        "CID": castle_id,
+        "U": [{"UID": unit_id, "C": count}, ...],
+        "T": [{"TID": tool_id, "C": count}, ...]
+    }
+    """
+
+    command = "dfk"
+
+    castle_id: int = Field(alias="CID")
+    units: list[UnitCount] = Field(alias="U", default_factory=list)
+    tools: list[UnitCount] = Field(alias="T", default_factory=list)
+
+
+class ChangeKeepDefenseResponse(BaseResponse):
+    """
+    Response to changing keep defense.
+
+    Command: dfk
+    """
+
+    command = "dfk"
+
+    success: bool = Field(default=True)
+    error_code: int = Field(alias="E", default=0)
+
+
+# =============================================================================
+# DFW - Change Wall Defense
+# =============================================================================
+
+
+class ChangeWallDefenseRequest(BaseRequest):
+    """
+    Change wall defense configuration.
+
+    Command: dfw
+    Payload: {
+        "CID": castle_id,
+        "U": [{"UID": unit_id, "C": count}, ...],
+        "T": [{"TID": tool_id, "C": count}, ...]
+    }
+    """
+
+    command = "dfw"
+
+    castle_id: int = Field(alias="CID")
+    units: list[UnitCount] = Field(alias="U", default_factory=list)
+    tools: list[UnitCount] = Field(alias="T", default_factory=list)
+
+
+class ChangeWallDefenseResponse(BaseResponse):
+    """
+    Response to changing wall defense.
+
+    Command: dfw
+    """
+
+    command = "dfw"
+
+    success: bool = Field(default=True)
+    error_code: int = Field(alias="E", default=0)
+
+
+# =============================================================================
+# DFM - Change Moat Defense
+# =============================================================================
+
+
+class ChangeMoatDefenseRequest(BaseRequest):
+    """
+    Change moat defense configuration.
+
+    Command: dfm
+    Payload: {
+        "CID": castle_id,
+        "U": [{"UID": unit_id, "C": count}, ...],
+        "T": [{"TID": tool_id, "C": count}, ...]
+    }
+    """
+
+    command = "dfm"
+
+    castle_id: int = Field(alias="CID")
+    units: list[UnitCount] = Field(alias="U", default_factory=list)
+    tools: list[UnitCount] = Field(alias="T", default_factory=list)
+
+
+class ChangeMoatDefenseResponse(BaseResponse):
+    """
+    Response to changing moat defense.
+
+    Command: dfm
+    """
+
+    command = "dfm"
+
+    success: bool = Field(default=True)
+    error_code: int = Field(alias="E", default=0)
+
+
+# =============================================================================
+# SDI - Support Defense Info (Alliance Member Castle Defense)
+# =============================================================================
+
+
+class GetSupportDefenseRequest(BaseRequest):
+    """
+    Get defense info for an alliance member's castle.
+
+    Command: sdi
+    Payload: {"TX": target_x, "TY": target_y, "SX": source_x, "SY": source_y}
+
+    Note: Can only query castles of players in the same alliance.
+    TX/TY = Target castle coordinates (the one being attacked)
+    SX/SY = Source castle coordinates (your castle sending support)
+    """
+
+    command = "sdi"
+
+    target_x: int = Field(alias="TX")
+    target_y: int = Field(alias="TY")
+    source_x: int = Field(alias="SX")
+    source_y: int = Field(alias="SY")
+
+
+class GetSupportDefenseResponse(BaseResponse):
+    """
+    Response containing defense information for an alliance member's castle.
+
+    Command: sdi
+
+    The response contains:
+    - SCID: Castle ID queried
+    - S: List of 6 defense positions, each containing [[unit_id, count], ...] pairs
+    - B: Commander/Lord info
+    - gui: Unit inventory
+    - gli: Lords info
+    - UYL: Total yard limit (max troops in courtyard)
+    - AUYL: Available yard limit
+    - UWL: Wall limit
+
+    To get total defenders, sum all unit counts across all positions in S.
+    """
+
+    command = "sdi"
+
+    castle_id: int = Field(alias="SCID", default=0)
+
+    # S contains 6 arrays (defense positions), each with [unit_id, count] pairs
+    # e.g. [[[487, 5174], [488, 20]], [[487, 347]], ...]
+    defense_positions: list = Field(alias="S", default_factory=list)
+
+    # Commander/Lord info (optional, not always present)
+    commander_info: dict | None = Field(alias="B", default=None)
+
+    # Unit inventory info
+    unit_inventory: dict | None = Field(alias="gui", default=None)
+
+    # Lords info
+    lords_info: dict | None = Field(alias="gli", default=None)
+
+    # Capacity limits
+    yard_limit: int = Field(alias="UYL", default=0)  # Total yard/courtyard limit
+    available_yard_limit: int = Field(alias="AUYL", default=0)  # Available yard space
+    wall_limit: int = Field(alias="UWL", default=0)  # Wall limit
+
+    def get_total_defenders(self) -> int:
+        """
+        Calculate total number of defending troops.
+
+        Returns:
+            Total count of all units across all defense positions.
+        """
+        total = 0
+        for position in self.defense_positions:
+            if isinstance(position, list):
+                for unit_pair in position:
+                    if isinstance(unit_pair, list) and len(unit_pair) >= 2:
+                        # unit_pair is [unit_id, count]
+                        total += unit_pair[1]
+        return total
+
+    def get_max_defense(self) -> int:
+        """
+        Get the maximum defense capacity for this castle.
+
+        UYL (yard_limit) represents the total capacity including
+        courtyard limit plus room for alliance support.
+
+        Returns:
+            Maximum number of troops that can defend this castle.
+        """
+        return self.yard_limit
+
+    def get_units_by_position(self) -> list[dict[int, int]]:
+        """
+        Get unit counts grouped by defense position.
+
+        Returns:
+            List of 6 dicts, each mapping unit_id -> count for that position.
+        """
+        result = []
+        for position in self.defense_positions:
+            units: dict[int, int] = {}
+            if isinstance(position, list):
+                for unit_pair in position:
+                    if isinstance(unit_pair, list) and len(unit_pair) >= 2:
+                        unit_id, count = unit_pair[0], unit_pair[1]
+                        units[unit_id] = units.get(unit_id, 0) + count
+            result.append(units)
+        return result
+
+
+__all__ = [
+    # DFC - Get Defense
+    "GetDefenseRequest",
+    "GetDefenseResponse",
+    "DefenseConfiguration",
+    # DFK - Keep Defense
+    "ChangeKeepDefenseRequest",
+    "ChangeKeepDefenseResponse",
+    # DFW - Wall Defense
+    "ChangeWallDefenseRequest",
+    "ChangeWallDefenseResponse",
+    # DFM - Moat Defense
+    "ChangeMoatDefenseRequest",
+    "ChangeMoatDefenseResponse",
+    # SDI - Support Defense Info
+    "GetSupportDefenseRequest",
+    "GetSupportDefenseResponse",
+]

empire_core/protocol/models/map.py

@@ -0,0 +1,269 @@
+"""
+Map protocol models.
+
+Commands:
+- gaa: Get map area/chunk
+- gam: Get active movements
+- fnm: Find NPC on map
+- adi: Get area/target detailed info
+"""
+
+from __future__ import annotations
+
+from pydantic import ConfigDict, Field
+
+from .base import BaseRequest, BaseResponse, PlayerInfo, Position
+
+# =============================================================================
+# GAA - Get Map Area
+# =============================================================================
+
+
+class GetMapAreaRequest(BaseRequest):
+    """
+    Get a chunk of the map.
+
+    Command: gaa
+    Payload: {"X": x, "Y": y, "W": width, "H": height, "KID": kingdom_id}
+
+    Returns information about all objects in the specified area.
+    """
+
+    command = "gaa"
+
+    x: int = Field(alias="X")
+    y: int = Field(alias="Y")
+    width: int = Field(alias="W", default=10)
+    height: int = Field(alias="H", default=10)
+    kingdom_id: int = Field(alias="KID", default=0)
+
+
+class MapObject(BaseResponse):
+    """An object on the map (castle, NPC, resource, etc.)."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    x: int = Field(alias="X")
+    y: int = Field(alias="Y")
+    object_type: int = Field(alias="OT")  # Type of object
+    object_id: int = Field(alias="OID", default=0)
+    owner_id: int | None = Field(alias="PID", default=None)
+    owner_name: str | None = Field(alias="PN", default=None)
+    alliance_id: int | None = Field(alias="AID", default=None)
+    alliance_name: str | None = Field(alias="AN", default=None)
+    level: int = Field(alias="L", default=0)
+    name: str | None = Field(alias="N", default=None)
+
+    @property
+    def position(self) -> Position:
+        """Get object position."""
+        return Position(X=self.x, Y=self.y)
+
+
+class GetMapAreaResponse(BaseResponse):
+    """
+    Response containing map area data.
+
+    Command: gaa
+    """
+
+    command = "gaa"
+
+    objects: list[MapObject] = Field(alias="O", default_factory=list)
+
+
+# =============================================================================
+# GAM - Get Active Movements
+# =============================================================================
+
+
+class GetMovementsRequest(BaseRequest):
+    """
+    Get all active troop movements.
+
+    Command: gam
+    Payload: {} (empty) or {"CID": castle_id}
+    """
+
+    command = "gam"
+
+    castle_id: int | None = Field(alias="CID", default=None)
+
+
+class Movement(BaseResponse):
+    """An active troop movement."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    movement_id: int = Field(alias="MID")
+    movement_type: int = Field(alias="MT")  # 1=attack, 2=support, 3=spy, 4=trade, etc.
+
+    # Source
+    source_x: int = Field(alias="SX")
+    source_y: int = Field(alias="SY")
+    source_castle_id: int = Field(alias="SCID", default=0)
+    source_player_id: int = Field(alias="SPID", default=0)
+
+    # Target
+    target_x: int = Field(alias="TX")
+    target_y: int = Field(alias="TY")
+    target_castle_id: int | None = Field(alias="TCID", default=None)
+    target_player_id: int | None = Field(alias="TPID", default=None)
+
+    # Timing
+    start_time: int = Field(alias="ST")  # Unix timestamp
+    arrival_time: int = Field(alias="AT")  # Unix timestamp
+    return_time: int | None = Field(alias="RT", default=None)
+
+    # Status
+    is_returning: bool = Field(alias="IR", default=False)
+
+    @property
+    def source_position(self) -> Position:
+        """Get source position."""
+        return Position(X=self.source_x, Y=self.source_y)
+
+    @property
+    def target_position(self) -> Position:
+        """Get target position."""
+        return Position(X=self.target_x, Y=self.target_y)
+
+
+class GetMovementsResponse(BaseResponse):
+    """
+    Response containing active movements.
+
+    Command: gam
+    """
+
+    command = "gam"
+
+    movements: list[Movement] = Field(alias="M", default_factory=list)
+
+
+# =============================================================================
+# FNM - Find NPC
+# =============================================================================
+
+
+class FindNPCRequest(BaseRequest):
+    """
+    Find NPC targets on the map.
+
+    Command: fnm
+    Payload: {"NT": npc_type, "L": level, "KID": kingdom_id}
+
+    NPC types vary by game version.
+    """
+
+    command = "fnm"
+
+    npc_type: int = Field(alias="NT")
+    level: int | None = Field(alias="L", default=None)
+    kingdom_id: int = Field(alias="KID", default=0)
+
+
+class NPCLocation(BaseResponse):
+    """An NPC location on the map."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    x: int = Field(alias="X")
+    y: int = Field(alias="Y")
+    npc_type: int = Field(alias="NT")
+    level: int = Field(alias="L")
+    npc_id: int = Field(alias="NID", default=0)
+
+    @property
+    def position(self) -> Position:
+        """Get NPC position."""
+        return Position(X=self.x, Y=self.y)
+
+
+class FindNPCResponse(BaseResponse):
+    """
+    Response containing NPC locations.
+
+    Command: fnm
+    """
+
+    command = "fnm"
+
+    npcs: list[NPCLocation] = Field(alias="N", default_factory=list)
+
+
+# =============================================================================
+# ADI - Get Area/Target Detailed Info
+# =============================================================================
+
+
+class GetTargetInfoRequest(BaseRequest):
+    """
+    Get detailed info about a specific map location/target.
+
+    Command: adi
+    Payload: {"X": x, "Y": y, "KID": kingdom_id}
+    """
+
+    command = "adi"
+
+    x: int = Field(alias="X")
+    y: int = Field(alias="Y")
+    kingdom_id: int = Field(alias="KID", default=0)
+
+
+class TargetInfo(BaseResponse):
+    """Detailed information about a target location."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    x: int = Field(alias="X")
+    y: int = Field(alias="Y")
+    object_type: int = Field(alias="OT")
+    object_id: int = Field(alias="OID", default=0)
+
+    # Owner info (if owned)
+    owner: PlayerInfo | None = Field(alias="O", default=None)
+
+    # Castle-specific
+    castle_name: str | None = Field(alias="CN", default=None)
+    castle_level: int | None = Field(alias="CL", default=None)
+
+    # NPC-specific
+    npc_type: int | None = Field(alias="NT", default=None)
+    npc_level: int | None = Field(alias="NL", default=None)
+
+    # Resources (for resource nodes)
+    resources: int | None = Field(alias="R", default=None)
+
+
+class GetTargetInfoResponse(BaseResponse):
+    """
+    Response containing target information.
+
+    Command: adi
+    """
+
+    command = "adi"
+
+    target: TargetInfo | None = Field(alias="T", default=None)
+
+
+__all__ = [
+    # GAA - Map Area
+    "GetMapAreaRequest",
+    "GetMapAreaResponse",
+    "MapObject",
+    # GAM - Movements
+    "GetMovementsRequest",
+    "GetMovementsResponse",
+    "Movement",
+    # FNM - Find NPC
+    "FindNPCRequest",
+    "FindNPCResponse",
+    "NPCLocation",
+    # ADI - Target Info
+    "GetTargetInfoRequest",
+    "GetTargetInfoResponse",
+    "TargetInfo",
+]

empire_core/protocol/packet.py

@@ -0,0 +1,104 @@
+import json
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Union
+
+
+@dataclass
+class Packet:
+    """
+    Base representation of a SmartFoxServer packet.
+    Can be either XML (Handshake) or XT (Extended/JSON).
+    """
+
+    raw_data: str
+    is_xml: bool
+
+    command_id: Optional[str] = None
+    request_id: int = -1
+    error_code: int = 0  # New field for XT status/error code
+    payload: Union[Dict[str, Any], ET.Element, None] = None
+
+    @staticmethod
+    def build_xt(zone: str, command: str, payload: Dict[str, Any], request_id: int = 1) -> str:
+        """
+        Build an XT (Extended) packet string.
+
+        Args:
+            zone: Game zone (e.g., "EmpireEx_21")
+            command: Command ID (e.g., "att", "tra", "bui")
+            payload: Dictionary payload to JSON encode
+            request_id: Request ID (default 1)
+
+        Returns:
+            Formatted XT packet string
+        """
+        return f"%xt%{zone}%{command}%{request_id}%{json.dumps(payload)}%"
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> "Packet":
+        decoded = data.decode("utf-8").rstrip("\x00")
+        if not decoded:
+            raise ValueError("Empty packet")
+
+        if decoded.startswith("<"):
+            return cls._parse_xml(decoded)
+        elif decoded.startswith("%xt%"):
+            return cls._parse_xt(decoded)
+
+        # Unknown or junk, return raw wrapper
+        return cls(raw_data=decoded, is_xml=False)
+
+    @classmethod
+    def _parse_xml(cls, data: str) -> "Packet":
+        try:
+            root = ET.fromstring(data)
+            # Structure: <msg t='sys'><body action='verChk' ...>
+            body = root.find("body")
+            cmd = body.get("action") if body is not None else None
+
+            # Fallback: Use root tag if no action (e.g. <cross-domain-policy>)
+            if cmd is None:
+                cmd = root.tag
+
+            return cls(raw_data=data, is_xml=True, command_id=cmd, payload=root)
+        except ET.ParseError:
+            return cls(raw_data=data, is_xml=True)
+
+    @classmethod
+    def _parse_xt(cls, data: str) -> "Packet":
+        # Format: %xt%{Command}%{RequestId}%{Status}%{Payload}%
+        parts = data.split("%")
+        if len(parts) < 5:
+            return cls(raw_data=data, is_xml=False)
+
+        cmd = parts[2]
+        req_id = int(parts[3]) if parts[3].isdigit() else -1
+
+        error_code = 0
+        if parts[4].isdigit() or (parts[4].startswith("-") and parts[4][1:].isdigit()):
+            error_code = int(parts[4])
+
+        raw_payload = parts[5] if len(parts) > 5 else ""
+
+        # Optimization: Only parse JSON if it looks like JSON
+        payload_data = {}
+        if raw_payload.startswith("{") or raw_payload.startswith("["):
+            try:
+                payload_data = json.loads(raw_payload)
+            except json.JSONDecodeError:
+                payload_data = {"raw": raw_payload}
+        else:
+            payload_data = {"raw": raw_payload}
+
+        return cls(
+            raw_data=data,
+            is_xml=False,
+            command_id=cmd,
+            request_id=req_id,
+            error_code=error_code,
+            payload=payload_data,
+        )
+
+    def to_bytes(self) -> bytes:
+        return (self.raw_data + "\x00").encode("utf-8")

empire_core/services/__init__.py

@@ -0,0 +1,31 @@
+"""
+Service layer for EmpireCore.
+
+Services provide high-level APIs for different game domains (alliance, castle, etc.)
+and are auto-registered with the EmpireClient.
+
+Usage:
+    @register_service("alliance")
+    class AllianceService(BaseService):
+        def send_chat(self, message: str):
+            request = AllianceChatMessageRequest.create(message)
+            self.send(request)
+
+    # Client auto-discovers services:
+    client = EmpireClient(...)
+    client.alliance.send_chat("Hello!")
+"""
+
+# Import services to trigger registration
+from .alliance import AllianceService
+from .base import BaseService, get_registered_services, register_service
+from .castle import CastleService
+
+__all__ = [
+    "BaseService",
+    "register_service",
+    "get_registered_services",
+    # Services
+    "AllianceService",
+    "CastleService",
+]