empire-core 0.7.3__py3-none-any.whl

empire_core/utils/helpers.py

@@ -0,0 +1,252 @@
+"""
+Helper functions for common game operations.
+"""
+
+from typing import Dict, List, Optional
+
+from empire_core.state.models import Castle, Player
+from empire_core.state.world_models import Movement
+from empire_core.utils.enums import MovementType
+
+
+class CastleHelper:
+    """Helper for castle operations."""
+
+    @staticmethod
+    def has_sufficient_resources(castle: Castle, wood: int = 0, stone: int = 0, food: int = 0) -> bool:
+        """Check if castle has sufficient resources."""
+        return castle.resources.wood >= wood and castle.resources.stone >= stone and castle.resources.food >= food
+
+    @staticmethod
+    def get_resource_overflow(castle: Castle) -> Dict[str, int]:
+        """Get resources exceeding capacity."""
+        overflow = {}
+
+        if castle.resources.wood > castle.resources.wood_cap:
+            overflow["wood"] = castle.resources.wood - castle.resources.wood_cap
+
+        if castle.resources.stone > castle.resources.stone_cap:
+            overflow["stone"] = castle.resources.stone - castle.resources.stone_cap
+
+        if castle.resources.food > castle.resources.food_cap:
+            overflow["food"] = castle.resources.food - castle.resources.food_cap
+
+        return overflow
+
+    @staticmethod
+    def can_upgrade_building(
+        castle: Castle,
+        building_id: int,
+        cost_wood: int = 0,
+        cost_stone: int = 0,
+        cost_food: int = 0,
+    ) -> bool:
+        """Check if building can be upgraded."""
+        return CastleHelper.has_sufficient_resources(castle, cost_wood, cost_stone, cost_food)
+
+
+class MovementHelper:
+    """Helper for movement operations."""
+
+    @staticmethod
+    def get_incoming_attacks(movements: Dict[int, Movement]) -> List[Movement]:
+        """Get all incoming attacks."""
+        return [m for m in movements.values() if m.is_incoming and m.is_attack]
+
+    @staticmethod
+    def get_outgoing_attacks(movements: Dict[int, Movement]) -> List[Movement]:
+        """Get all outgoing attacks."""
+        return [m for m in movements.values() if m.is_outgoing and m.is_attack]
+
+    @staticmethod
+    def get_returning_movements(movements: Dict[int, Movement]) -> List[Movement]:
+        """Get all returning movements."""
+        return [m for m in movements.values() if m.is_returning]
+
+    @staticmethod
+    def get_movements_to_area(movements: Dict[int, Movement], area_id: int) -> List[Movement]:
+        """Get all movements to specific area."""
+        return [m for m in movements.values() if m.target_area_id == area_id]
+
+    @staticmethod
+    def get_movements_from_area(movements: Dict[int, Movement], area_id: int) -> List[Movement]:
+        """Get all movements from specific area."""
+        return [m for m in movements.values() if m.source_area_id == area_id]
+
+    @staticmethod
+    def get_movements_by_type(movements: Dict[int, Movement], movement_type: MovementType) -> List[Movement]:
+        """Get all movements of a specific type."""
+        return [m for m in movements.values() if m.T == movement_type]
+
+    @staticmethod
+    def estimate_arrival_time(movement: Movement) -> float:
+        """
+        Estimate arrival timestamp (Unix time).
+
+        Returns:
+            Unix timestamp of estimated arrival
+        """
+        return movement.last_updated + movement.time_remaining
+
+    @staticmethod
+    def get_soonest_arrival(movements: Dict[int, Movement]) -> Optional[Movement]:
+        """Get the movement arriving soonest."""
+        if not movements:
+            return None
+        return min(movements.values(), key=lambda m: m.time_remaining)
+
+    @staticmethod
+    def get_soonest_incoming_attack(
+        movements: Dict[int, Movement],
+    ) -> Optional[Movement]:
+        """Get the soonest incoming attack."""
+        attacks = MovementHelper.get_incoming_attacks(movements)
+        if not attacks:
+            return None
+        return min(attacks, key=lambda m: m.time_remaining)
+
+    @staticmethod
+    def sort_by_arrival(movements: List[Movement], ascending: bool = True) -> List[Movement]:
+        """Sort movements by arrival time."""
+        return sorted(movements, key=lambda m: m.time_remaining, reverse=not ascending)
+
+    @staticmethod
+    def get_movements_arriving_within(movements: Dict[int, Movement], seconds: int) -> List[Movement]:
+        """Get all movements arriving within specified seconds."""
+        return [m for m in movements.values() if m.time_remaining <= seconds]
+
+    @staticmethod
+    def get_total_units_in_movements(movements: List[Movement]) -> Dict[int, int]:
+        """Get total units across all movements."""
+        totals: Dict[int, int] = {}
+        for m in movements:
+            for unit_id, count in m.units.items():
+                totals[unit_id] = totals.get(unit_id, 0) + count
+        return totals
+
+    @staticmethod
+    def get_total_resources_in_movements(movements: List[Movement]) -> Dict[str, int]:
+        """Get total resources across all movements (transports/returns)."""
+        totals = {"wood": 0, "stone": 0, "food": 0}
+        for m in movements:
+            totals["wood"] += m.resources.wood
+            totals["stone"] += m.resources.stone
+            totals["food"] += m.resources.food
+        return totals
+
+    @staticmethod
+    def format_movement(movement: Movement) -> str:
+        """Format a movement for display."""
+        direction = "→" if movement.is_outgoing else "←" if movement.is_incoming else "↺"
+        if movement.is_returning:
+            direction = "↩"
+
+        return (
+            f"[{movement.MID}] {movement.movement_type_name} {direction} "
+            f"{movement.source_area_id} → {movement.target_area_id} "
+            f"({movement.format_time_remaining()}, {movement.unit_count} units)"
+        )
+
+    @staticmethod
+    def format_movements_table(movements: List[Movement]) -> str:
+        """Format a list of movements as a table."""
+        if not movements:
+            return "No movements."
+
+        lines = [f"{'ID':<10} {'Type':<12} {'From':<10} {'To':<10} {'Units':<8} {'Time':<12}"]
+        lines.append("-" * 65)
+
+        for m in sorted(movements, key=lambda x: x.time_remaining):
+            lines.append(
+                f"{m.MID:<10} {m.movement_type_name:<12} "
+                f"{m.source_area_id:<10} {m.target_area_id:<10} "
+                f"{m.unit_count:<8} {m.format_time_remaining():<12}"
+            )
+
+        return "\n".join(lines)
+
+    @staticmethod
+    def is_attack_imminent(movements: Dict[int, Movement], threshold_seconds: int = 60) -> bool:
+        """Check if any attack is arriving within threshold."""
+        attacks = MovementHelper.get_incoming_attacks(movements)
+        return any(a.time_remaining <= threshold_seconds for a in attacks)
+
+    @staticmethod
+    def count_movements_by_type(movements: Dict[int, Movement]) -> Dict[str, int]:
+        """Count movements grouped by type."""
+        counts: Dict[str, int] = {}
+        for m in movements.values():
+            type_name = m.movement_type_name
+            counts[type_name] = counts.get(type_name, 0) + 1
+        return counts
+
+
+class ResourceHelper:
+    """Helper for resource management."""
+
+    @staticmethod
+    def calculate_production_until_full(castle: Castle) -> Dict[str, float]:
+        """Calculate hours until resources are full."""
+        result = {}
+
+        if castle.resources.wood_rate > 0:
+            space = castle.resources.wood_cap - castle.resources.wood
+            if space > 0:
+                result["wood"] = space / castle.resources.wood_rate
+
+        if castle.resources.stone_rate > 0:
+            space = castle.resources.stone_cap - castle.resources.stone
+            if space > 0:
+                result["stone"] = space / castle.resources.stone_rate
+
+        if castle.resources.food_rate > 0:
+            space = castle.resources.food_cap - castle.resources.food
+            if space > 0:
+                result["food"] = space / castle.resources.food_rate
+
+        return result
+
+    @staticmethod
+    def get_optimal_transport_amount(source: Castle, target_capacity: int, resource_type: str = "wood") -> int:
+        """Calculate optimal amount to transport."""
+        if resource_type == "wood":
+            available = source.resources.wood
+            safe = source.resources.wood_safe
+        elif resource_type == "stone":
+            available = source.resources.stone
+            safe = source.resources.stone_safe
+        elif resource_type == "food":
+            available = source.resources.food
+            safe = source.resources.food_safe
+        else:
+            return 0
+
+        # Transport excess over safe storage, up to capacity
+        excess = max(0, available - safe)
+        return min(int(excess), target_capacity)
+
+
+class PlayerHelper:
+    """Helper for player operations."""
+
+    @staticmethod
+    def get_total_resources(player: Player) -> Dict[str, int]:
+        """Get total resources across all castles."""
+        totals = {"wood": 0, "stone": 0, "food": 0}
+
+        for castle in player.castles.values():
+            totals["wood"] += castle.resources.wood
+            totals["stone"] += castle.resources.stone
+            totals["food"] += castle.resources.food
+
+        return totals
+
+    @staticmethod
+    def get_total_population(player: Player) -> int:
+        """Get total population across all castles."""
+        return sum(c.population for c in player.castles.values())
+
+    @staticmethod
+    def get_total_buildings(player: Player) -> int:
+        """Get total buildings across all castles."""
+        return sum(len(c.buildings) for c in player.castles.values())

empire_core/utils/response_awaiter.py

@@ -0,0 +1,153 @@
+"""
+Response awaiter for waiting on server responses to commands.
+"""
+
+import asyncio
+import logging
+import time
+from typing import Any, Dict
+
+from empire_core.exceptions import TimeoutError
+
+logger = logging.getLogger(__name__)
+
+
+class ResponseAwaiter:
+    """
+    Manages waiting for server responses to commands.
+
+    Usage:
+        awaiter = ResponseAwaiter()
+
+        # Start waiting for a response
+        response_future = awaiter.create_waiter('att')
+
+        # Send command
+        await connection.send(packet)
+
+        # Wait for response
+        response = await awaiter.wait_for('att', timeout=5.0)
+    """
+
+    def __init__(self):
+        self.pending: Dict[str, asyncio.Future] = {}
+        self.sequence = 0
+
+    def create_waiter(self, command_id: str) -> str:
+        """
+        Create a waiter for a specific command response.
+
+        Args:
+            command_id: Command to wait for (e.g., 'att', 'tra', 'bui')
+
+        Returns:
+            str: Unique waiter ID
+        """
+        self.sequence += 1
+        waiter_id = f"{command_id}_{self.sequence}_{time.time()}"
+
+        future: asyncio.Future = asyncio.Future()
+        self.pending[waiter_id] = future
+
+        logger.debug(f"Created waiter: {waiter_id}")
+        return waiter_id
+
+    def set_response(self, command_id: str, response: Any) -> bool:
+        """
+        Set response for waiting command.
+
+        Args:
+            command_id: Command ID that responded
+            response: Response data
+
+        Returns:
+            bool: True if waiter was found and notified
+        """
+        # Find matching waiter (most recent for this command)
+        matching_waiters = [wid for wid in self.pending.keys() if wid.startswith(f"{command_id}_")]
+
+        if not matching_waiters:
+            logger.debug(f"No waiter found for response: {command_id}")
+            return False
+
+        # Get most recent waiter
+        waiter_id = matching_waiters[-1]
+        future = self.pending.pop(waiter_id)
+
+        if not future.done():
+            future.set_result(response)
+            logger.debug(f"Set response for waiter: {waiter_id}")
+            return True
+
+        return False
+
+    async def wait_for(self, command_id: str, timeout: float = 5.0) -> Any:
+        """
+        Wait for response to a specific command.
+
+        Args:
+            command_id: Command to wait for
+            timeout: Max seconds to wait
+
+        Returns:
+            Response data
+
+        Raises:
+            TimeoutError: If timeout exceeded
+        """
+        # Find waiter
+        matching_waiters = [wid for wid in self.pending.keys() if wid.startswith(f"{command_id}_")]
+
+        if not matching_waiters:
+            raise ValueError(f"No waiter created for command: {command_id}")
+
+        waiter_id = matching_waiters[-1]
+        future = self.pending[waiter_id]
+
+        try:
+            response = await asyncio.wait_for(future, timeout)
+            logger.debug(f"Received response for: {waiter_id}")
+            return response
+        except asyncio.TimeoutError:
+            # Clean up
+            self.pending.pop(waiter_id, None)
+            logger.warning(f"Timeout waiting for response: {command_id}")
+            raise TimeoutError(f"No response received for command: {command_id} (timeout: {timeout}s)")
+
+    def cancel_all(self):
+        """Cancel all pending waiters."""
+        for waiter_id, future in self.pending.items():
+            if not future.done():
+                future.cancel()
+                logger.debug(f"Cancelled waiter: {waiter_id}")
+
+        self.pending.clear()
+
+    def cancel_command(self, command_id: str) -> int:
+        """
+        Cancel all waiters for a specific command.
+
+        Args:
+            command_id: Command to cancel waiters for
+
+        Returns:
+            int: Number of waiters cancelled
+        """
+        matching = [wid for wid in self.pending.keys() if wid.startswith(f"{command_id}_")]
+
+        count = 0
+        for waiter_id in matching:
+            future = self.pending.pop(waiter_id)
+            if not future.done():
+                future.cancel()
+                count += 1
+
+        if count > 0:
+            logger.debug(f"Cancelled {count} waiters for: {command_id}")
+
+        return count
+
+    @property
+    def pending_count(self) -> int:
+        """Get number of pending waiters."""
+        return len(self.pending)

empire_core/utils/troops.py

@@ -0,0 +1,93 @@
+"""
+Troop metadata fetcher - gets valid troop IDs from GGE CDN.
+
+Units with slotTypes are equipment, not troops.
+This filters to get only actual combat units.
+"""
+
+import logging
+from typing import Optional, Set
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+# Cached troop IDs
+_troop_ids: Optional[Set[int]] = None
+
+
+def get_items_version() -> str:
+    """Fetch the current items version from GGE CDN."""
+    url = "https://empire-html5.goodgamestudios.com/default/items/ItemsVersion.properties"
+    response = requests.get(url, timeout=10)
+    response.raise_for_status()
+    return response.text.split("=")[-1].strip()
+
+
+def fetch_items_data(version: str) -> dict:
+    """Fetch items data for a specific version."""
+    url = f"https://empire-html5.goodgamestudios.com/default/items/items_v{version}.json"
+    response = requests.get(url, timeout=30)
+    response.raise_for_status()
+    return response.json()
+
+
+def get_troop_ids(force_refresh: bool = False) -> Set[int]:
+    """
+    Get the set of valid troop unit IDs.
+
+    Troops are units without slotTypes (equipment has slotTypes).
+
+    Args:
+        force_refresh: Force re-fetch from CDN
+
+    Returns:
+        Set of wodID values for valid troops
+    """
+    global _troop_ids
+
+    if _troop_ids is not None and not force_refresh:
+        return _troop_ids
+
+    try:
+        version = get_items_version()
+        items_data = fetch_items_data(version)
+
+        units = items_data.get("units", [])
+        # Filter units without slotTypes (those are actual troops)
+        troop_ids = set()
+        for unit in units:
+            if not unit.get("slotTypes"):
+                wod_id = unit.get("wodID")
+                if wod_id:
+                    troop_ids.add(wod_id)
+
+        _troop_ids = troop_ids
+        logger.info(f"Loaded {len(troop_ids)} troop IDs from GGE CDN (v{version})")
+        return troop_ids
+
+    except Exception as e:
+        logger.error(f"Failed to fetch troop metadata: {e}")
+        # Return empty set on failure - will count all units
+        return set()
+
+
+def count_troops(units: dict[int, int], troop_ids: Optional[Set[int]] = None) -> int:
+    """
+    Count only actual troops in a unit dict, excluding equipment.
+
+    Args:
+        units: Dict of {unit_id: count}
+        troop_ids: Optional set of valid troop IDs (fetched if not provided)
+
+    Returns:
+        Total count of actual troops
+    """
+    if troop_ids is None:
+        troop_ids = get_troop_ids()
+
+    # If we couldn't get troop IDs, count everything
+    if not troop_ids:
+        return sum(units.values())
+
+    return sum(count for uid, count in units.items() if uid in troop_ids)

empire_core-0.7.3.dist-info/METADATA

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: empire-core
+Version: 0.7.3
+Summary: Fully typed Python API for Goodgame Empire
+Project-URL: Repository, https://github.com/eschnitzler/EmpireCore
+Author-email: E Joseph <east1499@gmail.com>
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: aiosqlite>=0.19.0
+Requires-Dist: pydantic>=2.5
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: sqlmodel>=0.0.14
+Requires-Dist: tabulate>=0.9.0
+Requires-Dist: tqdm>=4.66.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: websocket-client>=1.9.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: python-semantic-release>=9.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: sqlalchemy[mypy]; extra == 'dev'
+Requires-Dist: types-requests; extra == 'dev'
+Requires-Dist: types-tabulate; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+">
+  <img src="https://img.shields.io/badge/pydantic-v2-purple.svg" alt="Pydantic v2">
+  <img src="https://img.shields.io/badge/tool-uv-orange.svg" alt="UV">
+  <img src="https://img.shields.io/badge/status-WIP-red.svg" alt="Work in Progress">
+</p>
+
+<h1 align="center">EmpireCore</h1>
+
+<p align="center">
+  <strong>Fully typed Python library for Goodgame Empire</strong>
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> •
+  <a href="#installation">Installation</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#services">Services</a> •
+  <a href="#contributing">Contributing</a>
+</p>
+
+---
+
+> **Warning: Work in Progress**
+> 
+> This library is under active development. APIs may change, and some features are incomplete or untested.
+
+---
+
+## Features
+
+| Category | Description |
+|----------|-------------|
+| **Connection** | WebSocket with background threads, auto-reconnect, keepalive |
+| **Protocol Models** | Pydantic models for all GGE commands with type-safe request/response handling |
+| **Services** | High-level APIs for alliance, castle, and more - auto-attached to client |
+| **State Tracking** | Player, castles, resources, movements |
+
+## Installation
+
+```bash
+# Using uv (recommended)
+uv add empire-core
+
+# Or with pip
+pip install empire-core
+```
+
+For development:
+
+```bash
+git clone https://github.com/eschnitzler/EmpireCore.git
+cd EmpireCore
+uv sync
+```
+
+## Quick Start
+
+```python
+from empire_core import EmpireClient
+
+client = EmpireClient(username="your_user", password="your_pass")
+client.login()
+
+# Services are auto-attached to the client
+client.alliance.send_chat("Hello alliance!")
+client.alliance.help_all()
+
+castles = client.castle.get_all()
+for c in castles:
+    print(f"{c.castle_name} at ({c.x}, {c.y})")
+
+client.close()
+```
+
+## Services
+
+Services provide high-level APIs and are automatically attached to the client.
+
+### AllianceService (`client.alliance`)
+
+```python
+# Send chat message
+client.alliance.send_chat("Hello!")
+
+# Get chat history
+history = client.alliance.get_chat_log()
+for entry in history:
+    print(f"{entry.player_name}: {entry.decoded_text}")
+
+# Help all members
+response = client.alliance.help_all()
+print(f"Helped {response.helped_count} members")
+
+# Subscribe to incoming messages
+def on_message(msg):
+    print(f"[{msg.player_name}] {msg.decoded_text}")
+
+client.alliance.on_chat_message(on_message)
+```
+
+### CastleService (`client.castle`)
+
+```python
+# Get all castles
+castles = client.castle.get_all()
+
+# Get detailed info
+details = client.castle.get_details(castle_id=12345)
+print(f"Buildings: {len(details.buildings)}")
+
+# Select a castle
+client.castle.select(castle_id=12345)
+
+# Get resources
+resources = client.castle.get_resources(castle_id=12345)
+print(f"Wood: {resources.wood}, Stone: {resources.stone}")
+```
+
+## Protocol Models
+
+For lower-level access, use protocol models directly:
+
+```python
+from empire_core.protocol.models import (
+    AllianceChatMessageRequest,
+    GetCastlesRequest,
+    parse_response,
+)
+
+# Build a request
+request = AllianceChatMessageRequest.create("Hello 100%!")
+packet = request.to_packet()
+# -> "%xt%EmpireEx_21%acm%1%{"M": "Hello 100&percnt;!"}%"
+
+# Send via client
+client.send(request)
+
+# Or wait for response
+response = client.send(GetCastlesRequest(), wait=True)
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for:
+
+- Adding new protocol commands
+- Creating new services
+- Protocol model conventions
+- Testing guidelines
+
+## Architecture
+
+```
+empire_core/
+├── client/          # EmpireClient - main entry point
+├── protocol/
+│   └── models/      # Pydantic models for GGE commands
+├── services/        # High-level service APIs
+├── state/           # Game state models
+└── network/         # WebSocket connection
+```
+
+---
+
+<p align="center">
+  <sub>For educational purposes only. Use responsibly.</sub>
+</p>