Add real server pool, race roster overhaul, and ship energy system

Server browsing & matchmaking: - HL2-style main menu (QUICK PLAY/SERVER SELECT/OPTIONS/PROFILE/QUIT) replaces the old CASUAL/RANKED tiles; RANKED removed end-to-end (menu, matchmaking-api's Mode.ranked queue path, MMR matching) until ranked is real. - New menu/server_select.gd lists real servers from the matchmaking API's GET /servers and connects directly, retiring the old unreachable menu/server_browser.gd. - Real game-server pool: NetworkManager.host_server() self-registers on boot and heartbeats every 8s with live player counts; API computes available/full status from player_count, and a background sweep marks any server offline once its heartbeat goes stale (catches a crashed server that never deregistered). - Server-select rows get a live UDP ping probe (query port = game port + 10000) instead of trusting stale DB numbers; post-connect HUD shows live RTT off ENet's own peer stats. Race roster overhaul: - Swapped Terran/Mechanos/Vorg for the pivoted roster — Apex Dynamics, Inner Sphere Navy, Outer Rim Collective — each with a 3-ship Fighter/Gunner/Tank lineup, art cropped from concept sheets with background removal + orientation fixes per sheet. - Live headcount + roster + "TEAM FULL" lock on the race-select screen, shared between the initial pre-spawn pick and the pause menu's live SELECT TEAM swap. - Bot personalities (bots/bot_personality.gd): aggression/caution/ accuracy/reaction/awareness traits rolled per bot instead of one fixed AI profile. HUD additions: - Player list (roster, teammates white/enemies yellow, bots flagged), kill feed, minimap, and explosion VFX on death. - Health and energy now render as bars (hud/stat_bar.gd) instead of text in the top-left HUD. Ship energy system: - Per-role max energy (Fighter 100 / Gunner 150 / Tank 250), 75 energy per shot, flat regen (100 per 2.5s), fully server-authoritative and piggybacked on the existing per-tick state broadcast alongside health. - New blue "mirrored" bar top-middle of the screen (hud/energy_bar.gd) whose fill drains from both edges toward the center instead of left-to-right. Ship handling tuning: - Turn rate reduced (4.0 -> 1.0 rad/s) so a quick tap no longer over-rotates; holding past 0.15s ramps to double speed (2.0 rad/s) for fast full turns, gated the same way damage already is so replay during reconciliation can't double-count the hold timer. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-15 17:56:33 -04:00
parent c0b5f421c5
commit 7b44b2f2dc
112 changed files with 3349 additions and 872 deletions
@@ -1,11 +1,10 @@
 DATABASE_URL=postgresql+asyncpg://matchmaking:matchmaking@postgres:5432/matchmaking

-# Real-value targets per overview/bots.md (casual min 7v7) and overview/racesclasses.md (ranked 5v5).
-# CASUAL_TEAM_SIZE no longer gates when a casual match forms (bot fill means
-# 1 real player is enough — see queue_manager.py); it only caps how many real
-# players group into one casual match.
+# Real-value target per overview/bots.md (casual min 7v7). CASUAL_TEAM_SIZE
+# no longer gates when a casual match forms (bot fill means 1 real player is
+# enough — see queue_manager.py); it only caps how many real players group
+# into one casual match.
 CASUAL_TEAM_SIZE=7
-RANKED_TEAM_SIZE=5

 # Registered on API startup so local matchmaking has somewhere to assign
 # players to before real game servers self-register via POST /servers/register.
@@ -27,37 +27,59 @@ rebuilding the image. Rebuild (`docker compose up -d --build`) only when

 ## How matchmaking works right now

- `POST /matchmaking/queue/join` `{callsign, mode, mmr?}` — creates the
+- `POST /matchmaking/queue/join` `{callsign, mode}` — creates the
  player row if it doesn't exist yet, returns a `ticket_id`.
 - `GET /matchmaking/queue/status/{ticket_id}` — poll this; once matched it
  returns the assigned server's `server_ip`/`server_port`/`team`.
 - `POST /matchmaking/queue/leave?ticket_id=...` — cancel a queued ticket.

 A background loop (`app/queue_manager.py`) runs every 2s and forms a match
-once enough players are queued for a mode, then splits them into two teams
-and assigns the first available `GameServer` for that mode. Casual and
-ranked differ here: casual has bot fill (`spacewar/bots/bot_manager.gd`
-pads both teams up to `GameConfig.bot_min_team_size` in-game), so 1 queued
-player is enough to form a casual match — `CASUAL_TEAM_SIZE` just caps how
-many real players can group into one match, it no longer gates formation.
-Ranked has no bots, so it still waits for the full `RANKED_TEAM_SIZE × 2`
-real players before forming.
+once enough players are queued for casual, then splits them into two teams
+and assigns the first available `GameServer`. Casual has bot fill
+(`spacewar/bots/bot_manager.gd` pads both teams up to
+`GameConfig.bot_min_team_size` in-game), so 1 queued player is enough to
+form a match — `CASUAL_TEAM_SIZE` just caps how many real players can group
+into one match, it no longer gates formation. Ranked mode has been removed
+entirely (was never implemented past matchmaking-queue scaffolding) — the
+`Mode` enum only has `casual` now.

-There's no real game-server pool yet — one dev server is auto-seeded on API
-startup from `DEV_SEED_SERVER_IP`/`DEV_SEED_SERVER_PORT` (defaults to
-`127.0.0.1:7777`, i.e. a Godot server run on the host via
-`godot4 --headless --path spacewar -- --server`). That IP is handed straight
+Real servers self-register: `spacewar/autoload/network_manager.gd`'s
+`host_server()` calls `POST /servers/register` once on boot and then every
+`HEARTBEAT_INTERVAL` (8s) as a heartbeat, reporting live player count. The
+endpoint upserts on `(ip, port, mode)` — an unrecognized combo creates a
+row, a recognized one just refreshes it — and now also computes `status`
+from `player_count` vs `max_players` (`full` once at capacity) instead of
+always writing `available`. A background loop (`sweep_stale_servers` in
+`app/routers/servers.py`, run every 5s from `main.py`'s lifespan) marks a
+server `offline` once its `last_heartbeat` is older than
+`server_stale_seconds` (20s default) — catches a server that crashed or was
+`kill -9`'d instead of shutting down cleanly, so it doesn't sit in the list
+looking joinable forever.
+
+Three demo `GameServer` rows are still auto-seeded on API startup
+(`_seed_demo_servers` in `main.py`) at `127.0.0.1:7777/7778/7779` with
+`player_count` 40/20/10 out of `max_players` 50, so `menu/server_select.gd`
+has something to list even with no real server running — and since
+registration is a plain upsert, running a real Godot server on one of those
+same `(ip, port)` pairs (`godot4 --headless --path spacewar -- --server`)
+just takes that row over with live data, no special-casing needed. A demo
+row with nothing real backing it goes stale and flips to `offline` within
+`server_stale_seconds` of API startup, same as any other server. `--server-ip=`
+(new `network_manager.gd` cmdline arg) controls what IP a hosted server
+advertises — defaults to loopback for local dev. That IP is handed straight
 to game clients to connect to, so it must be reachable from wherever the
 *client* runs, not the API container — `host.docker.internal` would resolve
 inside the api container but not on the client's machine, which is why this
-isn't a docker-internal address. Real servers should eventually call
-`POST /servers/register` on boot and periodically as a heartbeat — that
-endpoint exists but nothing calls it yet.
+isn't a docker-internal address (same constraint `DEV_SEED_SERVER_IP` has).
+`player_count`/`max_players` from `GET /servers` are just this DB-stored
+value; `menu/server_select.gd` also queries each server directly over UDP
+(`network_manager.gd`'s ping responder) for a live, pre-connect number and
+RTT, overriding the DB value in the UI once that probe answers.

 ## Client integration

 The Godot client is wired up (`spacewar/autoload/matchmaking_client.gd`):
-CASUAL/RANKED on the main menu calls `POST /matchmaking/queue/join`, polls
+QUICK PLAY on the main menu calls `POST /matchmaking/queue/join`, polls
 `GET /matchmaking/queue/status/{ticket_id}` every 1.5s, and once `matched`
 connects `NetworkManager` directly to the returned `server_ip`/`server_port`.
 Point it at a non-default API with `godot4 ... -- --matchmaking-api=http://host:port`.
@@ -81,6 +103,6 @@ support, in this same service.
 - **Auth**: `callsign` is the only player identity, matching the game
  client's current state (no accounts yet). Real identity arrives with the
  GodotSteam auth checklist item in `overview/tech.md`.
- **Ranked MMR-window widening / bot-fill timeouts**: current matching is a
-  simple threshold (enough players queued → form a match). Refine once
-  there's real queue volume to tune against.
+- **Bot-fill timeouts**: current matching is a simple threshold (enough
+  players queued → form a match). Refine once there's real queue volume to
+  tune against.
@@ -6,9 +6,14 @@ class Settings(BaseSettings):

    database_url: str
    casual_team_size: int = 7
-    ranked_team_size: int = 5
    dev_seed_server_ip: str = "127.0.0.1"
    dev_seed_server_port: int = 7777
+    # Real/demo servers are considered offline once their last heartbeat is
+    # older than this. Godot's NetworkManager heartbeats every 8s (see
+    # spacewar/autoload/network_manager.gd's HEARTBEAT_INTERVAL), so this
+    # needs enough slack for one missed beat without flapping a live server
+    # to "offline" and back.
+    server_stale_seconds: int = 20


 settings = Settings()
@@ -9,17 +9,30 @@ from app.database import Base, async_session, engine
 from app.models import GameServer, Mode, ServerStatus
 from app.queue_manager import queue_manager
 from app.routers import matchmaking, ranks, servers, stats
+from app.routers.servers import sweep_stale_servers


-async def _seed_dev_server() -> None:
+# Three fake rows so server_select.gd has a realistic-looking list before a
+# real server pool exists (see README's "Not set up yet"). Only the first
+# port matches DEV_SEED_SERVER_IP/PORT, so it's the only one of the three
+# that's actually reachable by running a real Godot server locally — the
+# other two are display-only until real servers self-register on those
+# ports. player_count here is just the DB fallback; a live server overrides
+# it via the UDP query responder the client probes directly (see
+# spacewar/autoload/network_manager.gd).
+_DEMO_PLAYER_COUNTS = [40, 20, 10]
+
+
+async def _seed_demo_servers() -> None:
    async with async_session() as db:
-        for mode in (Mode.casual, Mode.ranked):
+        for i, player_count in enumerate(_DEMO_PLAYER_COUNTS):
+            port = settings.dev_seed_server_port + i
            existing = (
                await db.execute(
                    select(GameServer).where(
                        GameServer.ip == settings.dev_seed_server_ip,
-                        GameServer.port == settings.dev_seed_server_port,
-                        GameServer.mode == mode,
+                        GameServer.port == port,
+                        GameServer.mode == Mode.casual,
                    )
                )
            ).scalars().first()
@@ -27,22 +40,33 @@ async def _seed_dev_server() -> None:
                db.add(
                    GameServer(
                        ip=settings.dev_seed_server_ip,
-                        port=settings.dev_seed_server_port,
-                        mode=mode,
+                        port=port,
+                        mode=Mode.casual,
                        status=ServerStatus.available,
+                        player_count=player_count,
+                        max_players=50,
                    )
                )
        await db.commit()


+async def _run_stale_sweep_loop() -> None:
+    while True:
+        await asyncio.sleep(5)
+        async with async_session() as db:
+            await sweep_stale_servers(db)
+
+
@asynccontextmanager
 async def lifespan(app: FastAPI):
    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.create_all)
-    await _seed_dev_server()
+    await _seed_demo_servers()
    matching_task = asyncio.create_task(queue_manager.run_matching_loop())
+    sweep_task = asyncio.create_task(_run_stale_sweep_loop())
    yield
    matching_task.cancel()
+    sweep_task.cancel()


 app = FastAPI(title="Spacewar Matchmaking API", lifespan=lifespan)
@@ -11,7 +11,6 @@ from app.database import Base

 class Mode(str, enum.Enum):
    casual = "casual"
-    ranked = "ranked"


 class ServerStatus(str, enum.Enum):
@@ -43,6 +42,13 @@ class GameServer(Base):
    mode: Mapped[Mode] = mapped_column(SAEnum(Mode))
    status: Mapped[ServerStatus] = mapped_column(SAEnum(ServerStatus), default=ServerStatus.available)
    last_heartbeat: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
+    # DB-stored fallback shown immediately in the server list; a live server
+    # is queried directly for its real-time count (see
+    # spacewar/autoload/network_manager.gd's UDP query responder and
+    # menu/server_select.gd's ping probe), which overrides this in the UI
+    # once that probe answers.
+    player_count: Mapped[int] = mapped_column(Integer, default=0)
+    max_players: Mapped[int] = mapped_column(Integer, default=50)


 class Match(Base):
@@ -55,14 +55,7 @@ class QueueManager:

    def _waiting(self, mode: Mode) -> list[Ticket]:
        tickets = [t for t in self._tickets.values() if t.mode == mode and t.status == "queued"]
-        if mode == Mode.ranked:
-            # Simple MMR-sorted grouping. No widening-window-by-wait-time yet
-            # (real ranked matchmaking will want that) — nearest-neighbor by
-            # mmr is a reasonable placeholder until ranked queue volume
-            # exists to tune against.
-            tickets.sort(key=lambda t: t.mmr)
-        else:
-            tickets.sort(key=lambda t: t.queued_at)
+        tickets.sort(key=lambda t: t.queued_at)
        return tickets

    async def _try_form_match(self, mode: Mode, required: int, cap: int, db: AsyncSession) -> None:
@@ -98,20 +91,12 @@ class QueueManager:
        while True:
            await asyncio.sleep(2)
            async with async_session() as db:
-                # Casual has bot fill (spacewar/bots/bot_manager.gd) — bots pad
-                # both teams up to GameConfig.bot_min_team_size, so a single
-                # queued player is enough to form a match. Still group in
-                # anyone else who queues in the same tick, up to the real
-                # casual_team_size*2 target, rather than capping at 1v1.
-                # Ranked has no bots, so it still needs the full
-                # ranked_team_size*2 real players queued before forming.
+                # Bot fill (spacewar/bots/bot_manager.gd) pads both teams up
+                # to GameConfig.bot_min_team_size, so a single queued player
+                # is enough to form a match. Still group in anyone else who
+                # queues in the same tick, up to the real casual_team_size*2
+                # target, rather than capping at 1v1.
                await self._try_form_match(Mode.casual, required=1, cap=settings.casual_team_size * 2, db=db)
-                await self._try_form_match(
-                    Mode.ranked,
-                    required=settings.ranked_team_size * 2,
-                    cap=settings.ranked_team_size * 2,
-                    db=db,
-                )


 queue_manager = QueueManager()
@@ -5,7 +5,7 @@ from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession

 from app.database import get_db
-from app.models import Mode, Player
+from app.models import Player
 from app.queue_manager import queue_manager
 from app.schemas import QueueJoinRequest, QueueJoinResponse, QueueStatusResponse

@@ -25,9 +25,8 @@ async def _get_or_create_player(db: AsyncSession, callsign: str) -> Player:
@router.post("/queue/join", response_model=QueueJoinResponse)
 async def join_queue(req: QueueJoinRequest, db: AsyncSession = Depends(get_db)) -> QueueJoinResponse:
    player = await _get_or_create_player(db, req.callsign)
-    mmr = req.mmr if req.mode == Mode.ranked and req.mmr is not None else player.mmr

-    ticket = await queue_manager.join(player.id, player.callsign, req.mode, mmr)
+    ticket = await queue_manager.join(player.id, player.callsign, req.mode, player.mmr)
    return QueueJoinResponse(ticket_id=ticket.ticket_id, status=ticket.status)


@@ -1,9 +1,10 @@
-from datetime import datetime
+from datetime import datetime, timedelta

 from fastapi import APIRouter, Depends
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession

+from app.config import settings
 from app.database import get_db
 from app.models import GameServer, ServerStatus
 from app.schemas import ServerRegisterRequest
@@ -11,24 +12,62 @@ from app.schemas import ServerRegisterRequest
 router = APIRouter(prefix="/servers", tags=["servers"])


-# Real game servers should call this on boot and periodically (heartbeat) once
-# NetworkManager grows that integration. Until then, a dev server is seeded
-# on API startup (see main.py) from DEV_SEED_SERVER_IP/PORT so matchmaking is
-# testable end-to-end without it.
+def _status_for(player_count: int, max_players: int) -> ServerStatus:
+    return ServerStatus.full if player_count >= max_players else ServerStatus.available
+
+
+# spacewar/autoload/network_manager.gd calls this once on server boot and
+# then repeatedly as a heartbeat (every HEARTBEAT_INTERVAL, currently 8s),
+# via MatchmakingClient.register_server(). Same endpoint for both — an
+# unrecognized (ip, port, mode) creates a new row, a recognized one just
+# refreshes it. sweep_stale_servers() (below) is what flips a server back to
+# offline if those heartbeats stop, e.g. the process crashed or was killed
+# without a clean shutdown.
@router.post("/register")
 async def register_server(req: ServerRegisterRequest, db: AsyncSession = Depends(get_db)) -> dict:
    existing = (
        await db.execute(select(GameServer).where(GameServer.ip == req.ip, GameServer.port == req.port, GameServer.mode == req.mode))
    ).scalars().first()
+    status = _status_for(req.player_count, req.max_players)
    if existing:
-        existing.status = ServerStatus.available
+        existing.status = status
+        existing.player_count = req.player_count
+        existing.max_players = req.max_players
        existing.last_heartbeat = datetime.utcnow()
    else:
-        db.add(GameServer(ip=req.ip, port=req.port, mode=req.mode, status=ServerStatus.available))
+        db.add(
+            GameServer(
+                ip=req.ip,
+                port=req.port,
+                mode=req.mode,
+                status=status,
+                player_count=req.player_count,
+                max_players=req.max_players,
+            )
+        )
    await db.commit()
    return {"status": "registered"}


+# Run periodically from main.py's lifespan (same shape as
+# queue_manager.run_matching_loop()). Without this, a server that's killed
+# instead of cleanly shut down (crash, host reboot, `kill -9`) would stay
+# listed as available/full forever — server_select.gd's own UDP ping probe
+# catches that live per-row, but this keeps the DB's status column honest
+# too, e.g. for any future consumer that just reads GET /servers.
+async def sweep_stale_servers(db: AsyncSession) -> None:
+    cutoff = datetime.utcnow() - timedelta(seconds=settings.server_stale_seconds)
+    stale = (
+        await db.execute(
+            select(GameServer).where(GameServer.last_heartbeat < cutoff, GameServer.status != ServerStatus.offline)
+        )
+    ).scalars().all()
+    for server in stale:
+        server.status = ServerStatus.offline
+    if stale:
+        await db.commit()
+
+
@router.get("")
 async def list_servers(db: AsyncSession = Depends(get_db)) -> list[dict]:
    servers = (await db.execute(select(GameServer))).scalars().all()
@@ -38,6 +77,8 @@ async def list_servers(db: AsyncSession = Depends(get_db)) -> list[dict]:
            "port": s.port,
            "mode": s.mode,
            "status": s.status,
+            "player_count": s.player_count,
+            "max_players": s.max_players,
            "last_heartbeat": s.last_heartbeat,
        }
        for s in servers
@@ -8,7 +8,6 @@ from app.models import Mode
 class QueueJoinRequest(BaseModel):
    callsign: str
    mode: Mode
-    mmr: int | None = None  # ignored for casual; defaults to the player's stored mmr for ranked


 class QueueJoinResponse(BaseModel):
@@ -28,6 +27,8 @@ class ServerRegisterRequest(BaseModel):
    ip: str
    port: int
    mode: Mode
+    player_count: int = 0
+    max_players: int = 50


 class PlayerStatsResponse(BaseModel):