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>

matchmaking-api/app/config.py

@@ -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()

matchmaking-api/app/main.py

@@ -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)

matchmaking-api/app/models.py

@@ -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):

matchmaking-api/app/queue_manager.py

@@ -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()

matchmaking-api/app/routers/matchmaking.py

@@ -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)
 
 

matchmaking-api/app/routers/servers.py

@@ -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

matchmaking-api/app/schemas.py

@@ -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):