foothold-sitac 0.1.0__tar.gz

foothold_sitac-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.1
+Name: foothold-sitac
+Version: 0.1.0
+Summary: Web application displaying tactical maps for DCS World Foothold missions
+License: MIT
+Author: Michel NAUD
+Author-email: michel.naud26400@gmail.com
+Requires-Python: >=3.12,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Games/Entertainment :: Simulation
+Requires-Dist: fastapi (>=0.121.1,<0.122.0)
+Requires-Dist: jinja2 (>=3.1.6,<4.0.0)
+Requires-Dist: lupa (>=2.6,<3.0)
+Requires-Dist: pydantic (>=2.12.4,<3.0.0)
+Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
+Requires-Dist: uvicorn (>=0.38.0,<0.39.0)
+Description-Content-Type: text/markdown
+
+# Foothold Sitac
+
+POC about a web sitac for Foothold missions
+
+## Features
+
+See [docs/features.md](docs/features.md) for a complete list of features including:
+- Interactive tactical map with zone and player tracking
+- Distance measurement tool (ruler)
+- Player rankings and statistics
+- Campaign progress tracking
+- REST API for programmatic access
+
+## Installation
+
+### Prerequisites
+
+- Git
+- Python 3.12+
+- Poetry
+
+### Clone the project
+
+```shell
+git clone git@github.com:VEAF/foothold-sitac.git
+cd foothold-sitac
+```
+
+### Windows (recommended)
+
+1. Run `install.cmd` (copies config and installs dependencies)
+2. Edit `config/config.yml` if needed (mandatory: set `dcs.saved_games` path)
+3. Run `run.cmd` to start the web server
+
+### Linux/Mac
+
+1. Copy `config/config.yml.dist` to `config/config.yml`
+2. Edit `config/config.yml` (mandatory: set `dcs.saved_games` path)
+3. Install dependencies:
+```shell
+poetry install --only main
+```
+4. Start web service:
+```shell
+poetry run python run.py
+```
+
+## Update
+
+### Windows
+
+Run `update.cmd`
+
+### Linux/Mac
+
+```shell
+git pull origin main
+poetry install --only main
+```
+
+## Run tests
+
+```shell
+poetry run pytest
+```
+
+## Access to web service
+
+Default configuration: [localhost](http://localhost:8080)
+

foothold_sitac-0.1.0/README.md

@@ -0,0 +1,69 @@
+# Foothold Sitac
+
+POC about a web sitac for Foothold missions
+
+## Features
+
+See [docs/features.md](docs/features.md) for a complete list of features including:
+- Interactive tactical map with zone and player tracking
+- Distance measurement tool (ruler)
+- Player rankings and statistics
+- Campaign progress tracking
+- REST API for programmatic access
+
+## Installation
+
+### Prerequisites
+
+- Git
+- Python 3.12+
+- Poetry
+
+### Clone the project
+
+```shell
+git clone git@github.com:VEAF/foothold-sitac.git
+cd foothold-sitac
+```
+
+### Windows (recommended)
+
+1. Run `install.cmd` (copies config and installs dependencies)
+2. Edit `config/config.yml` if needed (mandatory: set `dcs.saved_games` path)
+3. Run `run.cmd` to start the web server
+
+### Linux/Mac
+
+1. Copy `config/config.yml.dist` to `config/config.yml`
+2. Edit `config/config.yml` (mandatory: set `dcs.saved_games` path)
+3. Install dependencies:
+```shell
+poetry install --only main
+```
+4. Start web service:
+```shell
+poetry run python run.py
+```
+
+## Update
+
+### Windows
+
+Run `update.cmd`
+
+### Linux/Mac
+
+```shell
+git pull origin main
+poetry install --only main
+```
+
+## Run tests
+
+```shell
+poetry run pytest
+```
+
+## Access to web service
+
+Default configuration: [localhost](http://localhost:8080)

foothold_sitac-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[tool.poetry]
+name = "foothold-sitac"
+version = "0.1.0"
+description = "Web application displaying tactical maps for DCS World Foothold missions"
+authors = ["Michel NAUD <michel.naud26400@gmail.com>"]
+readme = "README.md"
+license = "MIT"
+packages = [{include = "foothold_sitac", from = "src"}]
+include = [
+    "src/foothold_sitac/static/**/*",
+    "src/foothold_sitac/templates/**/*",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: FastAPI",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Games/Entertainment :: Simulation",
+]
+
+[tool.poetry.dependencies]
+python = "^3.12"
+fastapi = "^0.121.1"
+uvicorn = "^0.38.0"
+jinja2 = "^3.1.6"
+pydantic = "^2.12.4"
+lupa = "^2.6"
+pyyaml = "^6.0.3"
+
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^9.0.1"
+httpx = "^0.28.1"
+ruff = "^0.8"
+mypy = "^1.14"
+types-pyyaml = "^6.0.12.20250915"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+pythonpath = [".", "src"]
+
+[tool.ruff]
+line-length = 120

foothold_sitac-0.1.0/src/foothold_sitac/config.py

@@ -0,0 +1,67 @@
+import os
+from typing import Annotated, Any
+from functools import cache
+import yaml
+from pydantic import BaseModel, Field
+
+
+class WebConfig(BaseModel):
+    host: str = "0.0.0.0"
+    port: int = 8080
+    title: str = "Foothold Sitac Server"
+    reload: bool = False
+    refresh_interval: int = 60
+
+
+class DcsConfig(BaseModel):
+    saved_games: str = "var"  # "DCS Saved Games Path"
+
+
+class TileLayerConfig(BaseModel):
+    name: str
+    url: str
+
+
+class MapConfig(BaseModel):
+    url_tiles: str = "https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}"
+    alternative_tiles: Annotated[list[TileLayerConfig], Field(default_factory=list)]
+
+    min_zoom: int = 8
+    max_zoom: int = 11
+
+
+class AppConfig(BaseModel):
+    web: Annotated[WebConfig, Field(default_factory=WebConfig)]
+    dcs: Annotated[DcsConfig, Field(default_factory=DcsConfig)]
+    map: Annotated[MapConfig, Field(default_factory=MapConfig)]
+
+
+def _expand_env_vars(value: Any) -> Any:
+    """Recursively expand environment vars like "${VAR}" or "$VAR"."""
+    if isinstance(value, str):
+        return os.path.expandvars(value)
+    if isinstance(value, dict):
+        return {k: _expand_env_vars(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_expand_env_vars(v) for v in value]
+    return value
+
+
+def load_config_str(raw_config: dict[Any, Any]) -> AppConfig:
+    expanded = _expand_env_vars(raw_config)
+    return AppConfig.model_validate(expanded)
+
+
+def load_config(path: str) -> AppConfig:
+    with open(path, "r") as f:
+        raw_config = yaml.safe_load(f)
+
+    return load_config_str(raw_config)
+
+
+@cache
+def get_config() -> AppConfig:
+    config_path = "config/config.yml"
+    if not os.path.exists(config_path):
+        return AppConfig(web=WebConfig(), dcs=DcsConfig(), map=MapConfig(alternative_tiles=[]))
+    return load_config(config_path)

foothold_sitac-0.1.0/src/foothold_sitac/dependencies.py

@@ -0,0 +1,38 @@
+from fastapi import HTTPException, status
+from foothold_sitac.foothold import (
+    Sitac,
+    detect_foothold_mission_path,
+    get_server_path_by_name,
+    load_sitac,
+)
+
+
+def get_sitac_or_none(server: str) -> Sitac | None:
+    """Load sitac for a server, return None if not available"""
+    server_path = get_server_path_by_name(server)
+
+    if not server_path.is_dir():
+        return None
+
+    mission_path = detect_foothold_mission_path(server)
+
+    if not mission_path:
+        return None
+
+    return load_sitac(mission_path)
+
+
+def get_active_sitac(server: str) -> Sitac:
+    """Dependency injection of sitac by server name"""
+
+    server_path = get_server_path_by_name(server)
+
+    if not server_path.is_dir():
+        raise HTTPException(status.HTTP_404_NOT_FOUND, f"server {server} not found")
+
+    mission_path = detect_foothold_mission_path(server)
+
+    if not mission_path:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, f"mission not found for server {server}")
+
+    return load_sitac(mission_path)

foothold_sitac-0.1.0/src/foothold_sitac/foothold.py

@@ -0,0 +1,254 @@
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from lupa import LuaRuntime  # type: ignore[import-untyped]
+from pydantic import BaseModel, Field, field_validator
+
+from foothold_sitac.config import get_config
+
+
+class ConfigError(Exception): ...
+
+
+class Position(BaseModel):
+    latitude: float
+    longitude: float
+    altitude: int | None = None  # not used anymore
+
+
+class Zone(BaseModel):
+    upgrades_used: int = Field(alias="upgradesUsed")
+    side: int
+    active: bool
+    destroyed: dict[int, str] | list[str] | dict[Any, Any]
+    extra_upgrade: dict[Any, Any] = Field(alias="extraUpgrade")
+    remaining_units: dict[int, dict[int, str]] | dict[Any, Any] = Field(alias="remainingUnits")
+    first_capture_by_red: bool = Field(alias="firstCaptureByRed")
+    level: int
+    wasBlue: bool
+    triggers: dict[str, int]
+    position: Position = Field(alias="lat_long")
+    hidden: bool = False
+    flavor_text: str | None = Field(alias="flavorText", default=None)
+
+    @property
+    def side_color(self) -> str:
+        if not self.active:
+            return "darkgray"
+        if self.side == 1:
+            return "red"
+        elif self.side == 2:
+            return "blue"
+        return "lightgray"
+
+    @property
+    def side_str(self) -> str:
+        if not self.active:
+            return "disabled"
+        if self.side == 1:
+            return "red"
+        elif self.side == 2:
+            return "blue"
+        return "neutral"
+
+    @property
+    def total_units(self) -> int:
+        return sum([len(group_units) for group_units in self.remaining_units.values()])
+
+
+class Mission(BaseModel):
+    is_escort_mission: bool = Field(alias="isEscortMission")
+    description: str
+    title: str
+    is_running: bool = Field(alias="isRunning")
+
+
+class Connection(BaseModel):
+    from_zone: str = Field(alias="from")
+    to_zone: str = Field(alias="to")
+
+
+class Player(BaseModel):
+    coalition: str
+    unit_type: str = Field(alias="unitType")
+    player_name: str = Field(alias="playerName")
+    latitude: float
+    longitude: float
+    altitude: float | None = None
+
+    @property
+    def side_color(self) -> str:
+        if self.coalition == "red":
+            return "red"
+        elif self.coalition == "blue":
+            return "blue"
+        return "gray"
+
+
+class EjectedPilot(BaseModel):
+    player_name: str = Field(alias="playerName")
+    latitude: float
+    longitude: float
+    altitude: float = 0
+    lost_credits: float = Field(alias="lostCredits", default=0)
+
+
+class PlayerStats(BaseModel):
+    air: int = Field(alias="Air", default=0)
+    SAM: int = Field(alias="SAM", default=0)
+    points: float = Field(alias="Points", default=0)
+    deaths: int = Field(alias="Deaths", default=0)
+    zone_capture: int = Field(alias="Zone capture", default=0)
+    zone_upgrade: int = Field(alias="Zone upgrade", default=0)
+    CAS_mission: int = Field(alias="CAS mission", default=0)
+    points_spent: int = Field(alias="Points spent", default=0)
+    infantry: int = Field(alias="Infantry", default=0)
+    ground_units: int = Field(alias="Ground Units", default=0)
+    helo: int = Field(alias="Helo", default=0)
+
+
+class Sitac(BaseModel):
+    updated_at: datetime
+    zones: dict[str, Zone]
+    player_stats: dict[str, PlayerStats] = Field(alias="playerStats")
+    missions: list[Mission] = Field(default_factory=list)
+    connections: list[Connection] = Field(default_factory=list)
+    players: list[Player] = Field(default_factory=list)
+    ejected_pilots: list[EjectedPilot] = Field(alias="ejectedPilots", default_factory=list)
+
+    @field_validator("missions", "connections", "players", "ejected_pilots", mode="before")
+    @classmethod
+    def convert_lua_table_to_list(cls, v: Any) -> list[Any]:
+        """Convert Lua table (dict with numeric keys) to list."""
+        if v is None:
+            return []
+        if isinstance(v, dict):
+            return list(v.values())
+        return list(v) if not isinstance(v, list) else v
+
+    @property
+    def campaign_progress(self) -> float:
+        """Return the campaign progress percentage (0-100).
+
+        Progress is calculated as:
+        (visible_zones - red_zones) / visible_zones * 100
+
+        Hidden zones (hidden=True) and inactive zones (active=False) are
+        excluded.
+        """
+        visible_zones = [z for z in self.zones.values() if not z.hidden and z.active]
+        if not visible_zones:
+            return 0.0
+        red_zones = sum(1 for z in visible_zones if z.side == 1)
+        return (len(visible_zones) - red_zones) / len(visible_zones) * 100
+
+
+def lua_to_dict(lua_table: Any) -> dict[Any, Any] | None:
+    if lua_table is None:
+        return None
+    result: dict[Any, Any] = {}
+    for k, v in lua_table.items():
+        if hasattr(v, "items"):
+            v = lua_to_dict(v)
+        result[k] = v
+    return result
+
+
+def load_sitac(file: Path) -> Sitac:
+    lua = LuaRuntime(unpack_returned_tuples=True)
+
+    with open(file.absolute(), "r", encoding="utf-8") as f:
+        lua_code = f.read()
+
+    lua.execute(lua_code)
+
+    zone_persistance = lua.globals().zonePersistance
+    zone_persistance_dict = lua_to_dict(zone_persistance)
+
+    # Merge zonesDetails into zones (new format support)
+    # In new format, flavorText is stored in zonesDetails instead of directly in zones
+    zones_details = zone_persistance_dict.get("zonesDetails", {})  # type: ignore[union-attr]
+    if zones_details and "zones" in zone_persistance_dict:  # type: ignore[operator]
+        for zone_name, details in zones_details.items():
+            if zone_name in zone_persistance_dict["zones"]:  # type: ignore[index]
+                zone_persistance_dict["zones"][zone_name].update(details)  # type: ignore[index]
+
+    return Sitac(
+        **zone_persistance_dict,  # type: ignore[arg-type]
+        updated_at=datetime.fromtimestamp(file.stat().st_mtime),
+    )
+
+
+def detect_foothold_mission_path(server_name: str) -> Path | None:
+    file_status = get_foothold_server_status_path(server_name)
+
+    if not file_status.is_file():
+        return None
+
+    with open(file_status) as f:
+        mission_file_path = Path(f.readline().strip())
+
+    print(mission_file_path)
+    return mission_file_path
+
+
+def get_server_path_by_name(server_name: str) -> Path:
+    return Path(get_config().dcs.saved_games) / server_name
+
+
+def get_foothold_server_saves_path(server_name: str) -> Path:
+    return get_server_path_by_name(server_name) / "Missions" / "Saves"
+
+
+def get_foothold_server_status_path(server_name: str) -> Path:
+    return get_foothold_server_saves_path(server_name) / "foothold.status"
+
+
+def is_foothold_path(server_name: str) -> bool:
+    """Check if server_name (directory in DCS Saved Games) is a Foothold server path"""
+
+    path = get_foothold_server_status_path(server_name)
+
+    return path.is_file()
+
+
+def list_servers() -> list[str]:
+    base_path = Path(get_config().dcs.saved_games)
+
+    if not base_path.is_dir():
+        raise ConfigError(f"config:dcs.saved_games '{get_config().dcs.saved_games}' is not a valid dir")
+
+    return sorted(
+        [file.name for file in base_path.iterdir() if not file.name.startswith(".") and is_foothold_path(file.name)]
+    )
+
+
+def get_sitac_range(sitac: Sitac) -> tuple[Position, Position]:
+    if not sitac.zones:
+        raise ValueError("sitac without zones")
+    first_zone = sitac.zones[next(iter(sitac.zones))]
+
+    min_lat, max_lat = first_zone.position.latitude, first_zone.position.latitude
+    min_long, max_long = first_zone.position.longitude, first_zone.position.longitude
+
+    for zone in sitac.zones.values():
+        min_lat, max_lat = (
+            min(min_lat, zone.position.latitude),
+            max(max_lat, zone.position.latitude),
+        )
+        min_long, max_long = (
+            min(min_long, zone.position.longitude),
+            max(max_long, zone.position.longitude),
+        )
+
+    return Position(latitude=min_lat, longitude=min_long), Position(latitude=max_lat, longitude=max_long)
+
+
+def get_sitac_center(sitac: Sitac) -> Position:
+    min_pos, max_pos = get_sitac_range(sitac)
+
+    return Position(
+        latitude=(max_pos.latitude + min_pos.latitude) / 2,
+        longitude=(max_pos.longitude + min_pos.longitude) / 2,
+    )

foothold_sitac-0.1.0/src/foothold_sitac/foothold_api_router.py

@@ -0,0 +1,106 @@
+from datetime import datetime
+from typing import Annotated, Any
+from fastapi import APIRouter, Depends
+from foothold_sitac.dependencies import get_active_sitac
+from foothold_sitac.foothold import Sitac, list_servers
+from foothold_sitac.schemas import MapConnection, MapData, MapEjectedPilot, MapPlayer, MapZone, Server
+
+router = APIRouter()
+
+
+@router.get("", response_model=list[Server], description="List foothold servers")
+async def foothold_list_servers() -> Any:
+    return [Server.model_validate({"name": server}) for server in list_servers()]
+
+
+@router.get("/{server}/sitac", response_model=Sitac)
+async def foothold_get_sitac(sitac: Annotated[Sitac, Depends(get_active_sitac)]) -> Any:
+    return sitac
+
+
+@router.get("/{server}/map.json", response_model=MapData)
+async def foothold_get_map_data(
+    sitac: Annotated[Sitac, Depends(get_active_sitac)],
+) -> Any:
+    zones = [
+        MapZone.model_validate(
+            {
+                "name": zone_name,
+                "lat": zone.position.latitude,
+                "lon": zone.position.longitude,
+                "side": zone.side_str,
+                "color": zone.side_color,
+                "units": zone.total_units,
+                "level": zone.level,
+                "flavor_text": zone.flavor_text,
+            }
+        )
+        for zone_name, zone in sitac.zones.items()
+        if zone.position and not zone.hidden
+    ]
+
+    # Build connections with resolved coordinates
+    connections = []
+    for conn in sitac.connections:
+        from_zone = sitac.zones.get(conn.from_zone)
+        to_zone = sitac.zones.get(conn.to_zone)
+        # Only include connection if both zones exist, have positions, and are not hidden
+        if (
+            from_zone
+            and to_zone
+            and from_zone.position
+            and to_zone.position
+            and not from_zone.hidden
+            and not to_zone.hidden
+        ):
+            connections.append(
+                MapConnection(
+                    from_zone=conn.from_zone,
+                    to_zone=conn.to_zone,
+                    from_lat=from_zone.position.latitude,
+                    from_lon=from_zone.position.longitude,
+                    to_lat=to_zone.position.latitude,
+                    to_lon=to_zone.position.longitude,
+                    color=from_zone.side_color,
+                )
+            )
+
+    age_seconds = (datetime.now() - sitac.updated_at).total_seconds()
+
+    # Build players list
+    players = [
+        MapPlayer(
+            player_name=player.player_name,
+            lat=player.latitude,
+            lon=player.longitude,
+            coalition=player.coalition,
+            unit_type=player.unit_type,
+            color=player.side_color,
+        )
+        for player in sitac.players
+    ]
+
+    # Build ejected pilots list (exclude "Unknown" pilots)
+    ejected_pilots = [
+        MapEjectedPilot(
+            player_name=pilot.player_name,
+            lat=pilot.latitude,
+            lon=pilot.longitude,
+            altitude=pilot.altitude,
+            lost_credits=pilot.lost_credits,
+        )
+        for pilot in sitac.ejected_pilots
+        # if pilot.player_name != "Unknown" # don't hide Unknown pilots, real pilots have this name
+    ]
+
+    return MapData(
+        updated_at=sitac.updated_at,
+        age_seconds=age_seconds,
+        zones=zones,
+        connections=connections,
+        players=players,
+        ejected_pilots=ejected_pilots,
+        progress=sitac.campaign_progress,
+        missions_count=len(sitac.missions),
+        ejected_pilots_count=len(ejected_pilots),
+    )