Upload folder using huggingface_hub

.gitattributes

@@ -33,3 +33,37 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+www/assets/cars/corvette_zr1.glb filter=lfs diff=lfs merge=lfs -text
+www/assets/cars/ford_gt.glb filter=lfs diff=lfs merge=lfs -text
+www/assets/cars/lambo_sc18.glb filter=lfs diff=lfs merge=lfs -text
+www/assets/cars/mclaren_600lt.glb filter=lfs diff=lfs merge=lfs -text
+www/assets/cars/mustang_roush.glb filter=lfs diff=lfs merge=lfs -text
+www/assets/cars/porsche_gt2rs.glb filter=lfs diff=lfs merge=lfs -text
+www/assets/maps/shanghai/textures/PAT_asf_out_123.png filter=lfs diff=lfs merge=lfs -text
+www/assets/maps/shanghai/textures/PAT_rug_blu_112.png filter=lfs diff=lfs merge=lfs -text
+www/assets/maps/shanghai/textures/advert_side_a_d_56.png filter=lfs diff=lfs merge=lfs -text
+www/assets/maps/shanghai/textures/asphalt-new.png filter=lfs diff=lfs merge=lfs -text
+www/assets/maps/shanghai/textures/conc_bollard_filler_a_01_d_39.png filter=lfs diff=lfs merge=lfs -text
+www/assets/maps/shanghai/textures/grass-detailrealistic.png filter=lfs diff=lfs merge=lfs -text
+www/assets/maps/shanghai/textures/sha_hut_marshalls_a_d_63.png filter=lfs diff=lfs merge=lfs -text
+www/assets/maps/shanghai/textures/sha_rug_a_01_d_98.png filter=lfs diff=lfs merge=lfs -text
+www/assets/maps/shanghai/textures/sha_sand_a_01_d_139.png filter=lfs diff=lfs merge=lfs -text
+www/assets/maps/shanghai/textures/sha_transition_a_01_d_106.png filter=lfs diff=lfs merge=lfs -text
+www/assets/maps/shanghai/textures/sponsor_backboard_02_48.png filter=lfs diff=lfs merge=lfs -text
+www/assets/maps/shanghai/textures/textures/PAT_asf_out_123.png filter=lfs diff=lfs merge=lfs -text
+www/assets/maps/shanghai/textures/textures/PAT_rug_blu_112.png filter=lfs diff=lfs merge=lfs -text
+www/assets/maps/shanghai/textures/textures/advert_side_a_d_56.png filter=lfs diff=lfs merge=lfs -text
+www/assets/maps/shanghai/textures/textures/asphalt-new.png filter=lfs diff=lfs merge=lfs -text
+www/assets/maps/shanghai/textures/textures/conc_bollard_filler_a_01_d_39.png filter=lfs diff=lfs merge=lfs -text
+www/assets/maps/shanghai/textures/textures/grass-detailrealistic.png filter=lfs diff=lfs merge=lfs -text
+www/assets/maps/shanghai/textures/textures/sha_hut_marshalls_a_d_63.png filter=lfs diff=lfs merge=lfs -text
+www/assets/maps/shanghai/textures/textures/sha_rug_a_01_d_98.png filter=lfs diff=lfs merge=lfs -text
+www/assets/maps/shanghai/textures/textures/sha_sand_a_01_d_139.png filter=lfs diff=lfs merge=lfs -text
+www/assets/maps/shanghai/textures/textures/sha_transition_a_01_d_106.png filter=lfs diff=lfs merge=lfs -text
+www/assets/maps/shanghai/textures/textures/sponsor_backboard_02_48.png filter=lfs diff=lfs merge=lfs -text
+www/assets/maps/shanghai/textures/textures/tree04a_127.png filter=lfs diff=lfs merge=lfs -text
+www/assets/maps/shanghai/textures/textures/tree06a_128.png filter=lfs diff=lfs merge=lfs -text
+www/assets/maps/shanghai/textures/tree04a_127.png filter=lfs diff=lfs merge=lfs -text
+www/assets/maps/shanghai/textures/tree06a_128.png filter=lfs diff=lfs merge=lfs -text
+www/assets/maps/shanghai/track.glb filter=lfs diff=lfs merge=lfs -text
+www/assets/maps/track.glb filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,17 @@
+# Sole process binds :7860. Serves API + full HF Racing game client (www/).
+FROM python:3.11-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    PORT=7860
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY app.py lobbies.py relay.py ./
+COPY www ./www
+
+EXPOSE 7860
+
+CMD ["python", "app.py"]

README.md

@@ -1,10 +1,20 @@
 ---
-title: HF Racing
-emoji: 🐠
-colorFrom: purple
-colorTo: gray
+title: HF-Racing
+emoji: 🏎️
+colorFrom: red
+colorTo: yellow
 sdk: docker
+app_port: 7860
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# HF Racing
+
+Public **match server** + lobby board + **spectate** (no HF login).
+
+- **Board / status:** [`/board`](./board)
+- **Spectate:** Spectate button on a live lobby (no account)
+- **Play:** local HF Racing only (`bash start.sh` + `HF_TOKEN`) — Space rejects anonymous seat claims
+
+APIs: `/api/health`, `/api/lobbies`, `/api/config`  
+Match WS: `/ws/match/{mode}/{lobby_id}?user=...&role=play|spectate`

app.py

@@ -0,0 +1,437 @@
+"""HF Space: FastAPI lobbies/WS + full HF Racing game client (www/)."""
+
+from __future__ import annotations
+
+import mimetypes
+import os
+import re
+import secrets
+from pathlib import Path
+from typing import Optional
+
+import uvicorn
+import httpx
+from fastapi import Cookie, FastAPI, Header, Request, Response, WebSocket
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, HTMLResponse, JSONResponse, RedirectResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel, Field
+
+from lobbies import board
+from relay import handle_match_ws
+
+WWW = Path(__file__).resolve().parent / "www"
+_GUEST_RE = re.compile(r"^[A-Za-z0-9_-]{2,32}$")
+
+mimetypes.add_type("model/gltf-binary", ".glb")
+mimetypes.add_type("model/gltf+json", ".gltf")
+
+
+class ClaimBody(BaseModel):
+    username: str = Field(..., min_length=1)
+    seat: str = Field(..., min_length=1)
+    avatarUrl: Optional[str] = None
+
+
+class LeaveBody(BaseModel):
+    username: str = Field(..., min_length=1)
+
+
+class HeartbeatBody(BaseModel):
+    username: str = Field(..., min_length=1)
+
+
+BOARD_HTML = """<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8"/>
+  <meta name="viewport" content="width=device-width, initial-scale=1"/>
+  <title>HF-Racing · Lobby board</title>
+  <style>
+    :root {
+      --bg0: #0c0a08;
+      --line: #3a322a;
+      --text: #ece6df;
+      --muted: #9a9086;
+      --accent: #d8d0c6;
+      --live: #5dce8a;
+      --open: #c4b5a0;
+      --team-x: #c44b3c;
+      --team-x-bg: #3a1814;
+      --team-y: #3b7ec4;
+      --team-y-bg: #142433;
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      min-height: 100vh;
+      font-family: "Segoe UI", "Helvetica Neue", sans-serif;
+      color: var(--text);
+      background:
+        radial-gradient(ellipse at 50% 0%, rgba(70, 50, 30, 0.35), transparent 55%),
+        linear-gradient(180deg, #1a1510 0%, var(--bg0) 100%);
+    }
+    .wrap { max-width: 920px; margin: 0 auto; padding: 2rem 1.25rem 3rem; }
+    h1 {
+      margin: 0;
+      font-size: clamp(1.8rem, 4vw, 2.6rem);
+      letter-spacing: 0.06em;
+      text-transform: uppercase;
+      font-weight: 800;
+    }
+    .lead { color: var(--muted); margin: 0.6rem 0 1.25rem; max-width: 42rem; line-height: 1.45; }
+    .banner {
+      border: 1px solid var(--line);
+      background: rgba(12, 10, 8, 0.85);
+      padding: 0.9rem 1rem;
+      margin-bottom: 1.25rem;
+      line-height: 1.45;
+    }
+    .banner strong { color: #fff; }
+    .nav { display: flex; gap: 0.5rem; flex-wrap: wrap; margin-bottom: 1rem; }
+    .tab, .play {
+      border: 2px solid #5a5048;
+      background: transparent;
+      color: var(--text);
+      padding: 0.45rem 0.9rem;
+      text-transform: uppercase;
+      letter-spacing: 0.04em;
+      cursor: pointer;
+      font-size: 0.85rem;
+      text-decoration: none;
+      display: inline-block;
+    }
+    .tab.active { border-color: var(--accent); background: #1a1510; }
+    .play { border-color: #5dce8a; color: #b8f0d0; }
+    .list { display: flex; flex-direction: column; gap: 0.65rem; }
+    .card {
+      border: 1px solid var(--line);
+      background: #100e0c;
+      padding: 0.75rem 0.85rem;
+    }
+    .head { display: flex; justify-content: space-between; gap: 0.75rem; align-items: baseline; margin-bottom: 0.55rem; }
+    .id { font-weight: 700; letter-spacing: 0.04em; }
+    .meta { color: var(--muted); font-size: 0.85rem; }
+    .meta .live { color: var(--live); }
+    .meta .open { color: var(--open); }
+    .seats-row {
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      gap: 0.75rem;
+    }
+    .team { display: flex; flex-wrap: wrap; gap: 0.35rem; max-width: 46%; }
+    .team.x { justify-content: flex-start; }
+    .team.y { justify-content: flex-end; }
+    .seat {
+      min-width: 2rem;
+      text-align: center;
+      border: 1px solid #5a5048;
+      background: #1a1510;
+      color: #ece6df;
+      font-size: 0.78rem;
+      font-weight: 700;
+      padding: 0.35rem 0.5rem;
+    }
+    .seat.team-x { border-color: var(--team-x); background: var(--team-x-bg); color: #ffd4ce; }
+    .seat.team-y { border-color: var(--team-y); background: var(--team-y-bg); color: #cfe4ff; }
+    .seat .who { display: block; font-size: 0.62rem; font-weight: 500; opacity: 0.85; }
+    .seats-flat { display: flex; flex-wrap: wrap; gap: 0.35rem; }
+    .hint { margin-top: 0.55rem; font-size: 0.78rem; color: var(--muted); }
+    .actions { margin-top: 0.65rem; display: flex; flex-wrap: wrap; gap: 0.5rem; align-items: center; }
+    a.spec-btn {
+      display: inline-block;
+      text-decoration: none;
+      border: 1px solid #5dce8a;
+      background: #142018;
+      color: #b8f0d0;
+      font-size: 0.8rem;
+      font-weight: 700;
+      letter-spacing: 0.04em;
+      text-transform: uppercase;
+      padding: 0.4rem 0.75rem;
+    }
+    .err { color: #ff8e8e; }
+    footer { margin-top: 1.5rem; color: var(--muted); font-size: 0.8rem; }
+    code { color: #d2b48c; }
+  </style>
+</head>
+<body>
+  <div class="wrap">
+    <h1>HF Racing</h1>
+    <p class="lead">Public lobby board + spectate. Racing requires the local client with HF login (for identity / analytics).</p>
+    <div class="banner">
+      <strong>Spectate (no HF account):</strong> click <em>Spectate</em> on a live lobby.
+      <br/>In spectate: <strong>← →</strong> switch player · <strong>Esc</strong> back. Read-only camera — no driving.
+      <br/><strong>Play:</strong> local HF Racing only (<code>bash start.sh</code> + <code>HF_TOKEN</code>).
+      <br/>Red = team X · Blue = team Y (grid seats).
+    </div>
+    <div class="nav">
+      <button type="button" class="tab active" data-mode="sandbox">Practice</button>
+      <button type="button" class="tab" data-mode="1v1">1v1</button>
+      <button type="button" class="tab" data-mode="4v4">4v4 Race</button>
+    </div>
+    <div id="list" class="list">Loading lobbies…</div>
+    <footer>Auto-refreshes every 2s · <code>/api/lobbies</code></footer>
+  </div>
+  <script>
+    const KEY = { sandbox: 'sandbox', '1v1': 'duel', '4v4': 'squad' };
+    let mode = 'sandbox';
+    const list = document.getElementById('list');
+    document.querySelectorAll('.tab').forEach((btn) => {
+      btn.addEventListener('click', () => {
+        mode = btn.dataset.mode;
+        document.querySelectorAll('.tab').forEach((b) => b.classList.toggle('active', b === btn));
+        render(window.__board);
+      });
+    });
+    function parseSeat(key) {
+      const m = String(key).match(/^([XYS])-(\\d+)$/i);
+      if (!m) return { team: null, n: key, cls: '' };
+      const t = m[1].toUpperCase();
+      return {
+        team: t === 'S' ? null : t,
+        n: m[2],
+        cls: t === 'X' ? 'team-x' : t === 'Y' ? 'team-y' : '',
+      };
+    }
+    function seatChip(key, user) {
+      const p = parseSeat(key);
+      const label = p.team ? p.n : key.replace(/^S-/, '');
+      const who = user ? `<span class="who">${user}</span>` : '';
+      return `<span class="seat ${p.cls}${user ? ' filled' : ''}">${label}${who}</span>`;
+    }
+    function seatsHtml(seats) {
+      const entries = Object.entries(seats || {});
+      const xs = entries.filter(([k]) => /^X-/i.test(k));
+      const ys = entries.filter(([k]) => /^Y-/i.test(k));
+      if (xs.length || ys.length) {
+        return `<div class="seats-row">
+          <div class="team x">${xs.map(([k, v]) => seatChip(k, v)).join('')}</div>
+          <div class="team y">${ys.map(([k, v]) => seatChip(k, v)).join('')}</div>
+        </div>`;
+      }
+      return `<div class="seats-flat">${entries.map(([k, v]) => seatChip(k, v)).join('')}</div>`;
+    }
+    function render(board) {
+      if (!board) return;
+      const lobbies = board[KEY[mode]] || [];
+      if (!lobbies.length) {
+        list.innerHTML = '<div class="card err">No lobbies in this mode.</div>';
+        return;
+      }
+      list.innerHTML = lobbies.map((L) => {
+        const st = L.status === 'live' || L.status === 'starting'
+          ? `<span class="live">${L.status}</span>`
+          : `<span class="open">${L.status}</span>`;
+        const live = L.status === 'live' || L.status === 'starting';
+        const href = `/?spectate=1&mode=${encodeURIComponent(mode)}&lobby=${encodeURIComponent(L.id)}`;
+        const spec = live
+          ? `<div class="actions">
+               <a class="spec-btn" href="${href}">Spectate</a>
+               <div class="hint">Read-only viewer — no HF login required.</div>
+             </div>`
+          : `<div class="hint">Open — players join from the local client (HF login).</div>`;
+        return `<div class="card">
+          <div class="head">
+            <span class="id">${L.id}</span>
+            <span class="meta">${L.filled}/${L.capacity} · ${st}</span>
+          </div>
+          ${seatsHtml(L.seats)}
+          ${spec}
+        </div>`;
+      }).join('');
+    }
+    async function tick() {
+      try {
+        const r = await fetch('/api/lobbies');
+        if (!r.ok) throw new Error(r.status);
+        window.__board = await r.json();
+        render(window.__board);
+      } catch (e) {
+        list.innerHTML = `<div class="card err">Lobby API unreachable (${e.message || e})</div>`;
+      }
+    }
+    tick();
+    setInterval(tick, 2000);
+  </script>
+</body>
+</html>
+"""
+
+
+def _ensure_guest(response: Response, racing_user: str | None) -> str:
+    name = (racing_user or "").strip()
+    if not name or not _GUEST_RE.fullmatch(name):
+        name = f"guest-{secrets.token_hex(3)}"
+        response.set_cookie(
+            key="racing_user",
+            value=name,
+            max_age=60 * 60 * 24 * 30,
+            httponly=False,
+            samesite="lax",
+        )
+    return name
+
+
+def _hf_username_from_auth(authorization: str | None) -> str | None:
+    if not authorization:
+        return None
+    parts = authorization.split()
+    if len(parts) != 2 or parts[0].lower() != "bearer":
+        return None
+    token = parts[1].strip()
+    if not token:
+        return None
+    try:
+        resp = httpx.get(
+            "https://huggingface.co/api/whoami-v2",
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=15.0,
+        )
+        if resp.status_code != 200:
+            return None
+        data = resp.json()
+        name = data.get("name") or data.get("fullname")
+        return str(name) if name else None
+    except Exception:
+        return None
+
+
+def create_app() -> FastAPI:
+    api = FastAPI()
+    api.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    @api.get("/api/health")
+    def health():
+        return {"ok": True, "host": "space", "hasClient": WWW.is_dir(), "playAllowed": False}
+
+    @api.get("/api/config")
+    def config(response: Response, racing_user: str | None = Cookie(default=None)):
+        # Guest id is for spectate only — Space never allows play.
+        username = _ensure_guest(response, racing_user)
+        return {
+            "ok": True,
+            "spaceUrl": "",
+            "username": username,
+            "avatarUrl": None,
+            "authError": None,
+            "hasToken": False,
+            "hasSpaceUrl": False,
+            "lobbyHost": "space",
+            "host": "space",
+            "playAllowed": False,
+        }
+
+    @api.get("/api/lobbies")
+    def get_lobbies():
+        return board.snapshot()
+
+    @api.post("/api/lobbies/{mode}/{lobby_id}/claim")
+    def claim_seat(
+        mode: str,
+        lobby_id: str,
+        body: ClaimBody,
+        authorization: str | None = Header(default=None),
+    ):
+        # Play only via local client proxy with a real HF token (analytics identity).
+        hf_user = _hf_username_from_auth(authorization)
+        if not hf_user:
+            return JSONResponse(
+                {
+                    "ok": False,
+                    "error": "Play disabled on Space. Use local HF Racing with HF_TOKEN.",
+                },
+                status_code=403,
+            )
+        result = board.claim(
+            mode, lobby_id, hf_user, body.seat, avatar_url=body.avatarUrl
+        )
+        return JSONResponse(result, status_code=200 if result.get("ok") else 400)
+
+    @api.post("/api/lobbies/leave")
+    def leave_lobby(body: LeaveBody, authorization: str | None = Header(default=None)):
+        hf_user = _hf_username_from_auth(authorization)
+        # Allow leave for HF-auth players; ignore anonymous spoof leave of others
+        if hf_user:
+            return board.leave(hf_user)
+        if body.username and not str(body.username).startswith("guest-"):
+            # Unauthenticated leave of a real seat — reject
+            return JSONResponse({"ok": False, "error": "HF auth required"}, status_code=403)
+        return {"ok": True}
+
+    @api.post("/api/lobbies/heartbeat")
+    def heartbeat(body: HeartbeatBody, authorization: str | None = Header(default=None)):
+        hf_user = _hf_username_from_auth(authorization)
+        if hf_user:
+            board.heartbeat(hf_user)
+        elif body.username and not str(body.username).startswith("guest-"):
+            return JSONResponse({"ok": False, "error": "HF auth required"}, status_code=403)
+        return {"ok": True}
+
+    @api.websocket("/ws/match/{mode}/{lobby_id}")
+    async def match_ws(
+        ws: WebSocket,
+        mode: str,
+        lobby_id: str,
+        user: str = "",
+        role: str = "play",
+    ):
+        spectate = (role or "").lower() in ("spectate", "spec", "watch")
+        # Browser on Space: spectate only. Play sockets are for seated HF players
+        # (local client claims with HF_TOKEN, then connects play WS).
+        if not spectate:
+            # Allow play only if this user already holds a seat (HF-authenticated claim).
+            seated = board.by_user.get((user or "").strip())
+            if not seated or seated[0] != lobby_id:
+                await ws.accept()
+                await ws.send_text(
+                    '{"type":"error","error":"Spectate only in browser. Play via local HF Racing + HF_TOKEN."}'
+                )
+                await ws.close()
+                return
+        await handle_match_ws(ws, mode, lobby_id, user, role=role)
+
+    @api.get("/board", response_class=HTMLResponse)
+    def lobby_board():
+        return BOARD_HTML
+
+    @api.get("/")
+    def game_index(request: Request):
+        # Game client on Space is spectate-entry only.
+        q = request.query_params
+        if q.get("spectate") == "1" and q.get("lobby"):
+            index = WWW / "index.html"
+            if not index.is_file():
+                return HTMLResponse(
+                    "<h1>Game client missing</h1><p>Rebuild Space with www/.</p>",
+                    status_code=503,
+                )
+            return FileResponse(index)
+        return RedirectResponse(url="/board", status_code=302)
+
+    if WWW.is_dir():
+        for mount, folder in (("assets", "assets"), ("js", "js"), ("css", "css")):
+            path = WWW / folder
+            if path.is_dir():
+                api.mount(f"/{mount}", StaticFiles(directory=str(path)), name=mount)
+
+    return api
+
+
+app = create_app()
+
+
+def main() -> None:
+    port = int(os.environ.get("PORT") or "7860")
+    uvicorn.run(app, host="0.0.0.0", port=port, log_level="info")
+
+
+if __name__ == "__main__":
+    main()

lobbies.py

@@ -0,0 +1,283 @@
+"""Fixed lobby board: sandbox, 1v1, 4v4. Seat claims are server-authoritative."""
+
+from __future__ import annotations
+
+import string
+import time
+from typing import Any, Optional
+
+# Lobby IDs: 0A–0X, 1A–1H, 4A–4H (category is already in the mode UI)
+_LETTERS = string.ascii_uppercase
+SANDBOX_IDS = [f"0{ch}" for ch in _LETTERS[:10]]  # 0A … 0J
+DUEL_IDS = [f"1{ch}" for ch in _LETTERS[:8]]  # 1A … 1H
+SQUAD_IDS = [f"4{ch}" for ch in _LETTERS[:8]]  # 4A … 4H
+
+SANDBOX_CAP = 1  # one seat per sandbox lobby
+DUEL_CAP = 2
+SQUAD_CAP = 8  # 4 + 4
+
+# 4v4: start if full, or idle 60s with ≥1 per side
+SQUAD_IDLE_START_SEC = 60.0
+SEAT_STALE_SEC = 8.0
+# Ghost matches: if nobody heartbeats, free the lobby (was locking seats forever).
+STARTING_TIMEOUT_SEC = 40.0
+LIVE_STALE_SEC = 40.0
+
+
+def _now() -> float:
+    return time.time()
+
+
+def _empty_sandbox(lobby_id: str) -> dict[str, Any]:
+    return {
+        "id": lobby_id,
+        "mode": "sandbox",
+        "seats": {f"S-{i}": None for i in range(1, SANDBOX_CAP + 1)},
+        "status": "open",  # open | starting | live
+        "last_change": _now(),
+        "match_id": None,
+    }
+
+
+def _empty_duel(lobby_id: str) -> dict[str, Any]:
+    return {
+        "id": lobby_id,
+        "mode": "1v1",
+        "seats": {"X-1": None, "Y-1": None},
+        "status": "open",
+        "last_change": _now(),
+        "match_id": None,
+    }
+
+
+def _empty_squad(lobby_id: str) -> dict[str, Any]:
+    seats: dict[str, Optional[str]] = {}
+    for side in ("X", "Y"):
+        for i in range(1, 5):
+            seats[f"{side}-{i}"] = None
+    return {
+        "id": lobby_id,
+        "mode": "4v4",
+        "seats": seats,
+        "status": "open",
+        "last_change": _now(),
+        "match_id": None,
+    }
+
+
+class LobbyBoard:
+    def __init__(self) -> None:
+        self.lobbies: dict[str, dict[str, Any]] = {}
+        for lid in SANDBOX_IDS:
+            self.lobbies[lid] = _empty_sandbox(lid)
+        for lid in DUEL_IDS:
+            self.lobbies[lid] = _empty_duel(lid)
+        for lid in SQUAD_IDS:
+            self.lobbies[lid] = _empty_squad(lid)
+        # username -> (lobby_id, seat)
+        self.by_user: dict[str, tuple[str, str]] = {}
+
+    def snapshot(self) -> dict[str, Any]:
+        self._tick_stale_and_start()
+        return {
+            "sandbox": [self._public(self.lobbies[lid]) for lid in SANDBOX_IDS],
+            "duel": [self._public(self.lobbies[lid]) for lid in DUEL_IDS],
+            "squad": [self._public(self.lobbies[lid]) for lid in SQUAD_IDS],
+            "serverTime": _now(),
+        }
+
+    def _public(self, lobby: dict[str, Any]) -> dict[str, Any]:
+        return {
+            "id": lobby["id"],
+            "mode": lobby["mode"],
+            "seats": dict(lobby["seats"]),
+            "status": lobby["status"],
+            "lastChange": lobby["last_change"],
+            "matchId": lobby["match_id"],
+            "filled": sum(1 for v in lobby["seats"].values() if v),
+            "capacity": len(lobby["seats"]),
+        }
+
+    def _clear_user(self, username: str) -> None:
+        prev = self.by_user.pop(username, None)
+        if not prev:
+            return
+        lid, seat = prev
+        lobby = self.lobbies.get(lid)
+        if lobby and lobby["seats"].get(seat) == username:
+            lobby["seats"][seat] = None
+            lobby.get("_avatars", {}).pop(username, None)
+            lobby.get("_hb", {}).pop(username, None)
+            lobby["last_change"] = _now()
+            # Empty live/starting lobby must reset — otherwise match_id lingers
+            # and the next WS wait loop "starts" a ghost match with no players.
+            if lobby["status"] in ("live", "starting") and not any(lobby["seats"].values()):
+                self._reset_lobby(lobby)
+
+    def _reset_lobby(self, lobby: dict[str, Any]) -> None:
+        mode = lobby["mode"]
+        lid = lobby["id"]
+        if mode == "sandbox":
+            self.lobbies[lid] = _empty_sandbox(lid)
+        elif mode == "1v1":
+            self.lobbies[lid] = _empty_duel(lid)
+        else:
+            self.lobbies[lid] = _empty_squad(lid)
+
+    def leave(self, username: str) -> dict[str, Any]:
+        self._clear_user(username)
+        return {"ok": True}
+
+    def claim(
+        self,
+        mode: str,
+        lobby_id: str,
+        username: str,
+        seat: str,
+        avatar_url: str | None = None,
+    ) -> dict[str, Any]:
+        username = (username or "").strip()
+        if not username:
+            return {"ok": False, "error": "username required"}
+        lobby = self.lobbies.get(lobby_id)
+        if not lobby or lobby["mode"] != mode:
+            return {"ok": False, "error": "lobby not found"}
+        if seat not in lobby["seats"]:
+            return {"ok": False, "error": "invalid seat"}
+        if lobby["status"] in ("live", "starting"):
+            return {"ok": False, "error": "match already starting"}
+        if lobby["seats"][seat] is not None:
+            return {"ok": False, "error": "seat taken"}
+
+        # Move from previous seat if any
+        self._clear_user(username)
+        lobby["seats"][seat] = username
+        lobby["last_change"] = _now()
+        lobby.setdefault("_hb", {})[username] = _now()
+        avatars = lobby.setdefault("_avatars", {})
+        if avatar_url and str(avatar_url).strip():
+            avatars[username] = str(avatar_url).strip()
+        elif username not in avatars:
+            avatars[username] = f"https://huggingface.co/avatars/{username}"
+        self.by_user[username] = (lobby_id, seat)
+        started = self._maybe_start(lobby)
+        return {
+            "ok": True,
+            "lobby": self._public(lobby),
+            "seat": seat,
+            "started": started,
+            "matchId": lobby["match_id"],
+        }
+
+    def heartbeat(self, username: str) -> None:
+        prev = self.by_user.get(username)
+        if not prev:
+            return
+        lid, seat = prev
+        lobby = self.lobbies.get(lid)
+        if not lobby:
+            return
+        # Stash last seen on seat metadata via parallel dict
+        lobby.setdefault("_hb", {})[username] = _now()
+
+    def _tick_stale_and_start(self) -> None:
+        now = _now()
+        stale_users: list[str] = []
+        for username, (lid, seat) in list(self.by_user.items()):
+            lobby = self.lobbies.get(lid)
+            if not lobby:
+                stale_users.append(username)
+                continue
+            hb = lobby.get("_hb", {}).get(username, lobby["last_change"])
+            status = lobby["status"]
+            if status == "open" and now - hb > SEAT_STALE_SEC:
+                stale_users.append(username)
+            elif status == "live" and now - hb > LIVE_STALE_SEC:
+                # Drop ghost "live" seats so the board doesn't stay unclickable forever.
+                stale_users.append(username)
+            elif status == "starting" and now - lobby["last_change"] > STARTING_TIMEOUT_SEC:
+                stale_users.append(username)
+        for u in stale_users:
+            self._clear_user(u)
+
+        for lobby in list(self.lobbies.values()):
+            if lobby["status"] == "starting" and now - lobby["last_change"] > STARTING_TIMEOUT_SEC:
+                self._reset_lobby(lobby)
+            elif lobby["status"] == "live":
+                seated = [u for u in lobby["seats"].values() if u]
+                if seated and all(
+                    now - lobby.get("_hb", {}).get(u, 0) > LIVE_STALE_SEC for u in seated
+                ):
+                    self._reset_lobby(lobby)
+            elif lobby["status"] == "open":
+                self._maybe_start(lobby)
+
+    def _maybe_start(self, lobby: dict[str, Any]) -> bool:
+        if lobby["status"] != "open":
+            return False
+        mode = lobby["mode"]
+        seats = lobby["seats"]
+        filled = [s for s, u in seats.items() if u]
+
+        if mode == "sandbox":
+            # Start as soon as anyone joins
+            if filled:
+                return self._mark_starting(lobby)
+            return False
+
+        if mode == "1v1":
+            if seats.get("X-1") and seats.get("Y-1"):
+                return self._mark_starting(lobby)
+            return False
+
+        # 4v4
+        team_x = [s for s, u in seats.items() if u and s.startswith("X-")]
+        team_y = [s for s, u in seats.items() if u and s.startswith("Y-")]
+        if len(filled) >= SQUAD_CAP:
+            return self._mark_starting(lobby)
+        if team_x and team_y and (_now() - lobby["last_change"]) >= SQUAD_IDLE_START_SEC:
+            return self._mark_starting(lobby)
+        return False
+
+    def _mark_starting(self, lobby: dict[str, Any]) -> bool:
+        import uuid
+
+        lobby["status"] = "starting"
+        lobby["match_id"] = str(uuid.uuid4())
+        lobby["last_change"] = _now()
+        return True
+
+    def mark_live(self, lobby_id: str) -> None:
+        lobby = self.lobbies.get(lobby_id)
+        if lobby and lobby["status"] == "starting":
+            lobby["status"] = "live"
+
+    def players_in(self, lobby_id: str) -> list[dict[str, str]]:
+        lobby = self.lobbies.get(lobby_id)
+        if not lobby:
+            return []
+        avatars = lobby.get("_avatars") or {}
+        out = []
+        for seat, user in lobby["seats"].items():
+            if user:
+                side = "ffa"
+                if seat.startswith("X-"):
+                    side = "X"
+                elif seat.startswith("Y-"):
+                    side = "Y"
+                out.append(
+                    {
+                        "username": user,
+                        "seat": seat,
+                        "side": side,
+                        "avatarUrl": avatars.get(user)
+                        or f"https://huggingface.co/avatars/{user}",
+                    }
+                )
+        return out
+
+    def get(self, lobby_id: str) -> Optional[dict[str, Any]]:
+        return self.lobbies.get(lobby_id)
+
+
+board = LobbyBoard()

relay.py

@@ -0,0 +1,237 @@
+"""WebSocket match rooms — fan-out relay, no game simulation."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any
+
+from fastapi import WebSocket, WebSocketDisconnect
+
+from lobbies import board
+
+
+class MatchRoom:
+    def __init__(self, lobby_id: str, mode: str, match_id: str) -> None:
+        self.lobby_id = lobby_id
+        self.mode = mode
+        self.match_id = match_id
+        self.clients: dict[str, WebSocket] = {}  # seated players
+        self.spectators: dict[str, WebSocket] = {}  # read-only viewers
+        self.lock = asyncio.Lock()
+        self.started = False
+
+    async def add(self, username: str, ws: WebSocket, *, spectate: bool = False) -> None:
+        async with self.lock:
+            bucket = self.spectators if spectate else self.clients
+            old = bucket.get(username)
+            if old and old is not ws:
+                try:
+                    await old.close()
+                except Exception:
+                    pass
+            bucket[username] = ws
+
+    async def remove(self, username: str, ws: WebSocket, *, spectate: bool = False) -> None:
+        async with self.lock:
+            bucket = self.spectators if spectate else self.clients
+            if bucket.get(username) is ws:
+                del bucket[username]
+
+    async def broadcast(self, msg: dict[str, Any], exclude: str | None = None) -> None:
+        data = json.dumps(msg)
+        dead_players: list[str] = []
+        dead_specs: list[str] = []
+        async with self.lock:
+            players = list(self.clients.items())
+            specs = list(self.spectators.items())
+        for user, client in players + specs:
+            if exclude and user == exclude:
+                continue
+            try:
+                await client.send_text(data)
+            except Exception:
+                if user in self.clients:
+                    dead_players.append(user)
+                else:
+                    dead_specs.append(user)
+        for u in dead_players:
+            board.leave(u)
+            async with self.lock:
+                self.clients.pop(u, None)
+        async with self.lock:
+            for u in dead_specs:
+                self.spectators.pop(u, None)
+
+
+rooms: dict[str, MatchRoom] = {}
+rooms_lock = asyncio.Lock()
+
+
+async def get_or_create_room(lobby_id: str, mode: str, match_id: str) -> MatchRoom:
+    key = f"{mode}:{lobby_id}"
+    async with rooms_lock:
+        room = rooms.get(key)
+        if room is None or room.match_id != match_id:
+            room = MatchRoom(lobby_id, mode, match_id)
+            rooms[key] = room
+        return room
+
+
+async def handle_match_ws(
+    ws: WebSocket,
+    mode: str,
+    lobby_id: str,
+    username: str,
+    role: str = "play",
+) -> None:
+    await ws.accept()
+    username = (username or "").strip()
+    spectate = (role or "play").lower() in ("spectate", "spec", "watch")
+    if not username:
+        await ws.send_text(json.dumps({"type": "error", "error": "username required"}))
+        await ws.close()
+        return
+
+    # Spectators use a distinct key so they never collide with a seated player name
+    if spectate:
+        username = f"spec:{username}"
+
+    lobby = board.get(lobby_id)
+    if not lobby or lobby["mode"] != mode:
+        await ws.send_text(json.dumps({"type": "error", "error": "lobby not found"}))
+        await ws.close()
+        return
+
+    if not spectate:
+        seat_info = board.by_user.get(username)
+        if not seat_info or seat_info[0] != lobby_id:
+            await ws.send_text(json.dumps({"type": "error", "error": "not seated in lobby"}))
+            await ws.close()
+            return
+        board.heartbeat(username)
+
+    # Wait until lobby is starting/live with a match_id
+    for _ in range(180):
+        lobby = board.get(lobby_id)
+        if lobby and not spectate:
+            # Keep seat alive while parked in the wait loop (HTTP HB can lag).
+            board.heartbeat(username)
+            board._maybe_start(lobby)
+            lobby = board.get(lobby_id)
+            # Seat was wiped (stale / leave) — stop waiting instead of crashing later.
+            if not board.by_user.get(username) or board.by_user.get(username)[0] != lobby_id:
+                await ws.send_text(json.dumps({"type": "error", "error": "seat lost — rejoin lobby"}))
+                await ws.close()
+                return
+        if lobby and lobby.get("match_id") and lobby["status"] in ("starting", "live"):
+            # Only proceed if this player is still seated (or spectating).
+            if spectate or (board.by_user.get(username) and board.by_user[username][0] == lobby_id):
+                break
+        if spectate and lobby and lobby["status"] == "open" and not lobby.get("match_id"):
+            await ws.send_text(
+                json.dumps({"type": "waiting", "lobby": board._public(lobby), "spectating": True})
+            )
+            await asyncio.sleep(0.5)
+            continue
+        await asyncio.sleep(0.5)
+        try:
+            pub = board._public(lobby) if lobby else None
+            await ws.send_text(
+                json.dumps({"type": "waiting", "lobby": pub, "spectating": spectate})
+            )
+        except Exception:
+            return
+    else:
+        await ws.send_text(json.dumps({"type": "error", "error": "match did not start"}))
+        await ws.close()
+        return
+
+    lobby = board.get(lobby_id)
+    if not lobby or not lobby.get("match_id"):
+        await ws.send_text(json.dumps({"type": "error", "error": "lobby reset — rejoin"}))
+        await ws.close()
+        return
+
+    seat = None
+    if not spectate:
+        seat_info = board.by_user.get(username)
+        if not seat_info or seat_info[0] != lobby_id:
+            await ws.send_text(json.dumps({"type": "error", "error": "not seated in lobby"}))
+            await ws.close()
+            return
+        seat = seat_info[1]
+
+    match_id = lobby["match_id"]
+    room = await get_or_create_room(lobby_id, mode, match_id)
+    await room.add(username, ws, spectate=spectate)
+
+    players = board.players_in(lobby_id)
+    start_payload = {
+        "type": "match_start",
+        "matchId": match_id,
+        "mode": mode,
+        "lobbyId": lobby_id,
+        "username": username,
+        "seat": seat,
+        "players": players,
+        "spectating": spectate,
+    }
+    await ws.send_text(json.dumps(start_payload))
+    if not spectate:
+        board.mark_live(lobby_id)
+        await room.broadcast(
+            {
+                "type": "player_joined",
+                "username": username,
+                "seat": seat,
+                "players": board.players_in(lobby_id),
+            },
+            exclude=username,
+        )
+
+    try:
+        while True:
+            raw = await ws.receive_text()
+            if not spectate:
+                board.heartbeat(username)
+            try:
+                msg = json.loads(raw)
+            except json.JSONDecodeError:
+                continue
+            if not isinstance(msg, dict):
+                continue
+            # Spectators are receive-only (except ping)
+            if spectate:
+                if msg.get("type") == "ping":
+                    await ws.send_text(json.dumps({"type": "pong"}))
+                continue
+            msg["from"] = username
+            if msg.get("type") == "ping":
+                await ws.send_text(json.dumps({"type": "pong"}))
+                continue
+            await room.broadcast(msg, exclude=username)
+    except WebSocketDisconnect:
+        pass
+    except Exception:
+        pass
+    finally:
+        await room.remove(username, ws, spectate=spectate)
+        if not spectate:
+            # HF WS often blips right at match_start. Instant leave was wiping BOTH
+            # seats and bootstrapping players back to an empty lobby.
+            await asyncio.sleep(3.0)
+            still = board.by_user.get(username)
+            reconnected = username in room.clients
+            if still and still[0] == lobby_id and not reconnected:
+                board.leave(username)
+                await room.broadcast(
+                    {
+                        "type": "player_left",
+                        "username": username,
+                        "players": board.players_in(lobby_id),
+                    }
+                )
+        async with rooms_lock:
+            if room.lobby_id == lobby_id and not room.clients and not room.spectators:
+                rooms.pop(f"{mode}:{lobby_id}", None)

requirements.txt

@@ -0,0 +1,4 @@
+fastapi==0.115.6
+uvicorn[standard]==0.32.1
+pydantic>=2.11,<2.12
+httpx==0.28.1

www/assets/.gitkeep

@@ -0,0 +1 @@
+# Shared audio / misc assets

www/assets/cars/.gitkeep

@@ -0,0 +1 @@
+# Drop car .glb / .gltf files here

www/assets/cars/corvette_zr1.glb

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:12fbf0426979fcf0e9d7940ddee1ff23facd811e40159b6eb027f6959ad44a82
+size 9819496

www/assets/cars/ford_gt.glb

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:743b795e1116d1158afe2635c975486a106679e93033286c4721b7e0108dcd24
+size 7663384

www/assets/cars/lambo_sc18.glb

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:48fff10172b9eb7c8513448c4a6c60763d0008f00b72332cb36eaeebbae8bc3a
+size 11656112

www/assets/cars/mclaren_600lt.glb

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:18ad77768b83c8db768cbf0a3d99b61e89e94c91707ffc289ae4e597d2f1c93c
+size 5918960

www/assets/cars/mustang_roush.glb

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7fd4c7a4499a9f1d266842af0bc21e426dc19118a759344a74f508616a88c475
+size 29595096

www/assets/cars/porsche_gt2rs.glb

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:06e7a8c1106fc77148a46953bcaf0f662f9ae27dc0922bf10484e6fd4af10642
+size 14592228

www/assets/maps/.gitkeep

@@ -0,0 +1 @@
+# Drop track/map .glb / .gltf files here