Upload 127 files

.gitattributes

@@ -33,3 +33,28 @@ 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
+HuggingWizards-upload/static/assets/effects/12_nebula_spritesheet.png filter=lfs diff=lfs merge=lfs -text
+HuggingWizards-upload/static/assets/effects/13_vortex_spritesheet.png filter=lfs diff=lfs merge=lfs -text
+HuggingWizards-upload/static/assets/effects/17_felspell_spritesheet.png filter=lfs diff=lfs merge=lfs -text
+HuggingWizards-upload/static/assets/effects/18_midnight_spritesheet.png filter=lfs diff=lfs merge=lfs -text
+HuggingWizards-upload/static/assets/effects/19_freezing_spritesheet.png filter=lfs diff=lfs merge=lfs -text
+HuggingWizards-upload/static/assets/effects/2_magic8_spritesheet.png filter=lfs diff=lfs merge=lfs -text
+HuggingWizards-upload/static/assets/glitch/portal.png filter=lfs diff=lfs merge=lfs -text
+HuggingWizards-upload/static/assets/music/Pixel[[:space:]]1.ogg filter=lfs diff=lfs merge=lfs -text
+HuggingWizards-upload/static/assets/music/Pixel[[:space:]]10.ogg filter=lfs diff=lfs merge=lfs -text
+HuggingWizards-upload/static/assets/music/Pixel[[:space:]]11.ogg filter=lfs diff=lfs merge=lfs -text
+HuggingWizards-upload/static/assets/music/Pixel[[:space:]]12.ogg filter=lfs diff=lfs merge=lfs -text
+HuggingWizards-upload/static/assets/music/Pixel[[:space:]]2.ogg filter=lfs diff=lfs merge=lfs -text
+HuggingWizards-upload/static/assets/music/Pixel[[:space:]]3.ogg filter=lfs diff=lfs merge=lfs -text
+HuggingWizards-upload/static/assets/music/Pixel[[:space:]]4.ogg filter=lfs diff=lfs merge=lfs -text
+HuggingWizards-upload/static/assets/music/Pixel[[:space:]]5.ogg filter=lfs diff=lfs merge=lfs -text
+HuggingWizards-upload/static/assets/music/Pixel[[:space:]]6.ogg filter=lfs diff=lfs merge=lfs -text
+HuggingWizards-upload/static/assets/music/Pixel[[:space:]]7.ogg filter=lfs diff=lfs merge=lfs -text
+HuggingWizards-upload/static/assets/music/Pixel[[:space:]]8.ogg filter=lfs diff=lfs merge=lfs -text
+HuggingWizards-upload/static/assets/music/Pixel[[:space:]]9.ogg filter=lfs diff=lfs merge=lfs -text
+HuggingWizards-upload/static/assets/retro/retro_a.png filter=lfs diff=lfs merge=lfs -text
+HuggingWizards-upload/static/assets/retro/retro_b.png filter=lfs diff=lfs merge=lfs -text
+HuggingWizards-upload/static/assets/retro/retro_c.png filter=lfs diff=lfs merge=lfs -text
+HuggingWizards-upload/static/assets/retro/retro_d.png filter=lfs diff=lfs merge=lfs -text
+HuggingWizards-upload/static/assets/retro/retro_e.png filter=lfs diff=lfs merge=lfs -text
+HuggingWizards-upload/static/assets/retro/retro_f.png filter=lfs diff=lfs merge=lfs -text

HuggingWizards-upload/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+.DS_Store
+
+# Generated agent traces (keep the directory, ignore the contents)
+traces/*.json
+
+# Don't commit the raw asset archives
+*.zip
+*.rar
+New Resources/

HuggingWizards-upload/README.md

@@ -0,0 +1,107 @@
+---
+title: HuggingWizards
+emoji: 🧙
+colorFrom: purple
+colorTo: indigo
+sdk: gradio
+sdk_version: 5.9.1
+app_file: app.py
+pinned: false
+short_description: Co-op pixel wizard arena where Nemotron-4B is the Game Master
+---
+
+# 🧙 HuggingWizards
+
+A small 2D pixel-wizard **co-op arena** that runs as a Gradio Space on **ZeroGPU**.
+Up to **8 players** join one shared arena, fight a central **boss** and the
+**minions** it spawns, and upgrade their magic between rounds. Everyone else can
+**spectate** live. Controls: **WASD** to move, **Space** to attack.
+
+The hackathon twist: **NVIDIA Nemotron-Mini-4B-Instruct** is the **Game Master**.
+At the end of every round it decides:
+
+- **Rewards** — how much gold each wizard earns (based on damage / survival).
+- **Blessings** — individual boons for wizards who earned them: any timed aura,
+  a `full_heal`, or even an `extra_life` for a struggling player.
+- **Boss attack pattern** — `balanced`, `sniper` (fast aimed bolts), `artillery`
+  (slow heavy orbs + dense shockwaves), `swarm` (minion floods), or `berserker`
+  (relentless charges). The active pattern shows next to the boss's name.
+- **Boss attack speed (with decaying mercy)** — the GM reads every wizard's
+  HP% and lives and tunes `boss_attack_speed` (0.5–2.0): slower for a wounded
+  party, faster for a healthy one. Guardrail: the allowed floor rises each
+  wave (no mercy left by ~wave 13), out-of-range or malformed values are
+  clamped, and every trace records `requested` vs `applied` plus the floor.
+- **Boss & minion reset** — next-round boss HP, minion count/HP, spawn rate,
+  boss damage, aggression, and the enemy archetype mix.
+- **Card pool** — which level-up cards may be offered next wave.
+
+Every round produces a structured **agent trace** (prompt → raw model output →
+parsed decision → applied effect), saved under `traces/` and shown live in the
+Gradio dashboard.
+
+## Architecture
+
+- **Client** (`static/`): HTML5 canvas game loop in the browser (rendering + input).
+- **Server** (`app.py`, `game/`): FastAPI WebSocket + a ~20 Hz authoritative game
+  tick on CPU. Gradio is mounted for the trace/leaderboard dashboard.
+- **Game Master** (`game/gamemaster.py`): `@spaces.GPU` burst inference at round
+  boundaries only — the pattern ZeroGPU is built for. Falls back to deterministic
+  logic if the model/GPU is unavailable (so it runs locally too).
+
+## Run locally
+
+```bash
+pip install -r requirements.txt
+python app.py
+# open http://localhost:7860
+```
+
+The Game Master uses Nemotron only when a GPU + the `spaces`/`transformers` stack
+is present; otherwise it transparently uses the deterministic fallback so local
+dev and CI still work.
+
+## Game Master model
+
+On a Space the model is loaded **at startup** (the ZeroGPU pattern: weights are
+downloaded and staged before any `@spaces.GPU` call, so the 60 s GPU window is
+spent purely on inference). Locally it is lazy-loaded on the first round.
+
+Environment variables:
+
+| Variable | Values | Effect |
+|---|---|---|
+| `HUGGINGWIZARDS_NO_LLM` | `1` | Skip the model entirely; deterministic Game Master (CI / quick dev). |
+| `HUGGINGWIZARDS_QUANT` | `auto` (default), `none`, `4bit`, `8bit` | Quantization via bitsandbytes. `auto` = bf16 on Spaces/big GPUs, NF4 4-bit on local GPUs with <12 GB VRAM. |
+
+Quantization notes: 4-bit NF4 shrinks the 4B model from ~8.5 GB to ~3 GB of
+VRAM and speeds up cold loads — ideal for small local GPUs. On ZeroGPU's H200
+plain bf16 is both comfortable and faster per token, so `auto` keeps bf16 there.
+
+## Assets
+
+Pixel art / audio from free packs (Tiny RPG Character Pack, Tiny Swords,
+Free Pixel Effects, Retro Impact Effect Pack, Pixel UI pack 3, Pixel RPG Music
+Pack). See each pack's license.
+
+- **Maps**: each boss faction has its own territory — the Tiny Swords grass
+  tileset plus a per-theme ground tint, landmark buildings
+  (`static/assets/buildings/`: orc camp huts, the Iron Legion's blue castle,
+  the Lancer Host's red keep, the Archer Coven's monastery & ranges) and a
+  seeded scenery mix (bushland / rockfields / forest). Scenery is purely
+  cosmetic — the server simulation is unchanged.
+- **Effects**: spell-cast muzzle flashes, impact bursts (on boss/minion/player
+  hits) and death poofs are drawn client-side from the Free Pixel Effects
+  spritesheets, triggered by snapshot flags (`hurt`, attack, minion id removal).
+  Skill activations and GM blessings are server-driven events rendered with
+  more of the pack: freezing novas, felspell blasts, protection circles,
+  vortex summons, sunburn blessings, magic-bubble heals.
+- **Characters**: pick a champion (Warrior / Archer / Lancer / Pawn) on the
+  name screen — Tiny Swords blue units (`static/assets/chars/`), all size-normalized
+  and growing with level.
+- **Special bosses**: **Aegis** (red wave, holy-spell attacks) on waves 3/9/15… and
+  **Toaster Bot** (green wave, glitch-portal attacks) on waves 5/11/17…  Beat one and
+  every survivor gains its signature attack as a permanent power.
+- **Timed auras**: rare floor-only power-ups (30–60 s) visualized with the Retro
+  Impact Effect Pack (`static/assets/retro/`) wreathing the wizard.
+- **Music**: a looping track from the Pixel RPG Music Pack starts on the first
+  join/spectate click (browser autoplay policy); a 🔊 button toggles it.

HuggingWizards-upload/app.py

@@ -0,0 +1,357 @@
+"""HuggingWizards — co-op pixel wizard arena with a Nemotron-4B Game Master.
+
+Single process:
+  * FastAPI serves the canvas client (`/`) and a WebSocket (`/ws`).
+  * A ~20 Hz asyncio task runs the authoritative simulation on CPU and
+    broadcasts snapshots to every connected client (players + spectators).
+  * At each round boundary the Game Master (Nemotron, burst GPU) decides rewards
+    and the next round; every decision is logged as an agent trace.
+  * A Gradio dashboard is mounted at `/dashboard` (live traces + leaderboard).
+"""
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import os
+import time
+import uuid
+
+import gradio as gr
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+
+from game import gamemaster
+from game.engine import Engine, MAX_PLAYERS, TICK_HZ
+
+HERE = os.path.dirname(__file__)
+engine = Engine()
+
+# Active websocket connections: ws -> {"pid", "role", "name", "char"}
+clients: dict[WebSocket, dict] = {}
+# Ordered waiting line for when the 8-slot arena is full.
+queue: list[WebSocket] = []
+
+# ---- persistent leaderboard ----------------------------------------------
+LEADERBOARD_FILE = os.path.join(HERE, "traces", "leaderboard.json")
+_leaderboard: list[dict] = []
+
+
+def _load_leaderboard():
+    global _leaderboard
+    try:
+        with open(LEADERBOARD_FILE, encoding="utf-8") as f:
+            _leaderboard = json.load(f)
+    except Exception:
+        _leaderboard = []
+
+
+def _save_leaderboard():
+    with contextlib.suppress(Exception):
+        with open(LEADERBOARD_FILE, "w", encoding="utf-8") as f:
+            json.dump(_leaderboard[:100], f, indent=2)
+
+
+def add_score(name: str, gold: int, level: int, wave: int) -> list[dict]:
+    _leaderboard.append({
+        "name": str(name)[:16] or "Wizard", "gold": int(gold),
+        "level": int(level), "wave": int(wave),
+        "ts": time.strftime("%Y-%m-%d %H:%M"),
+    })
+    _leaderboard.sort(key=lambda e: (e["gold"], e["wave"], e["level"]), reverse=True)
+    del _leaderboard[100:]
+    _save_leaderboard()
+    return _leaderboard[:20]
+
+
+_load_leaderboard()
+
+
+async def broadcast(payload: dict):
+    if not clients:
+        return
+    msg = json.dumps(payload)
+    dead = []
+    for ws in list(clients.keys()):
+        try:
+            await ws.send_text(msg)
+        except Exception:
+            dead.append(ws)
+    for ws in dead:
+        _drop(ws)
+
+
+def _drop(ws: WebSocket):
+    info = clients.pop(ws, None)
+    if info and info.get("pid"):
+        engine.remove_player(info["pid"])
+        if not engine.players and engine.status != "lobby":
+            engine.status = "lobby"
+            engine.status_msg = "All wizards left. Waiting for players..."
+
+
+async def _send(ws: WebSocket, payload: dict):
+    with contextlib.suppress(Exception):
+        await ws.send_text(json.dumps(payload))
+
+
+async def handle_skill_request(ws: WebSocket, pid: str, prompt: str):
+    """The round's top wizard asks the Game Master for a custom power-up."""
+    if engine.status != "intermission" or engine.skill_request_used \
+            or engine.skill_request_pid != pid or not prompt.strip():
+        await _send(ws, {"type": "skill_result", "ok": False,
+                         "reason": "Not available right now."})
+        return
+    engine.skill_request_used = True  # one wish per intermission
+    ctx = {"round": engine.round, "player_level": engine.players[pid].level
+           if pid in engine.players else 1}
+    spec = await asyncio.to_thread(gamemaster.generate_skill, prompt, ctx)
+    granted = engine.add_runtime_skill(pid, spec) if spec else None
+    await _send(ws, {"type": "skill_result", "ok": bool(granted), "skill": granted,
+                     "reason": None if granted else "The arcane energies fizzled — try again."})
+
+
+def _ws_for_pid(pid: str):
+    for ws, info in clients.items():
+        if info.get("pid") == pid:
+            return ws
+    return None
+
+
+async def _broadcast_queue():
+    """Tell each queued connection its current place in line."""
+    for i, ws in enumerate(list(queue)):
+        await _send(ws, {"type": "queue", "pos": i + 1, "size": len(queue)})
+
+
+async def promote_queue():
+    """Fill open arena slots from the front of the queue."""
+    while engine.can_join() and queue:
+        ws = queue.pop(0)
+        info = clients.get(ws)
+        if info is None:      # disconnected while waiting
+            continue
+        pid = uuid.uuid4().hex[:8]
+        engine.add_player(pid, info.get("name", "Wizard"), info.get("char", "warrior"))
+        clients[ws] = {**info, "pid": pid, "role": "player"}
+        await _send(ws, {"type": "welcome", "pid": pid, "role": "player", "reason": "from_queue"})
+
+
+async def manage_slots():
+    """Eliminate out-of-lives wizards, then promote the queue into free slots."""
+    for pid, p in list(engine.players.items()):
+        if p.lives <= 0 and not p.alive:
+            ws = _ws_for_pid(pid)
+            engine.remove_player(pid)
+            if ws is not None:
+                info = clients.get(ws, {})
+                clients[ws] = {**info, "pid": None, "role": "spectator"}
+                await _send(ws, {"type": "eliminated",
+                                 "score": {"gold": p.gold, "level": p.level, "wave": engine.round}})
+    if not engine.players and engine.status != "lobby":
+        engine.status = "lobby"
+        engine.status_msg = "Waiting for wizards to join..."
+    await promote_queue()
+    await _broadcast_queue()
+
+
+async def game_loop():
+    last = time.time()
+    prev_status = engine.status
+    gm_task: asyncio.Task | None = None
+    gm_applied = False
+    interval = 1.0 / TICK_HZ
+    slot_accum = 0.0
+    while True:
+        now = time.time()
+        dt = min(0.1, now - last)
+        last = now
+
+        engine.tick(dt)
+        # eliminate / promote queue / broadcast positions a few times a second
+        slot_accum += dt
+        if slot_accum >= 0.4:
+            slot_accum = 0.0
+            await manage_slots()
+
+        # Round just ended -> ask the Game Master (off the loop thread).
+        if engine.status == "intermission" and prev_status == "active":
+            summary = engine.round_summary()
+            prev_cfg = dict(engine.cfg)
+            gm_task = asyncio.create_task(
+                asyncio.to_thread(gamemaster.decide, summary, prev_cfg)
+            )
+            gm_applied = False
+
+        # Apply the decision as soon as it's ready (enables shopping this break).
+        if gm_task is not None and gm_task.done() and not gm_applied:
+            with contextlib.suppress(Exception):
+                engine.apply_gm_decision(gm_task.result())
+            gm_applied = True
+
+        # Start the next round once the break is over AND the decision is in.
+        if engine.status == "intermission" and gm_applied and time.time() >= engine.intermission_until:
+            if engine.players:
+                engine.start_round()
+            else:
+                engine.status = "lobby"
+                engine.status_msg = "Waiting for wizards to join..."
+            gm_task = None
+            gm_applied = False
+
+        prev_status = engine.status
+        await broadcast(engine.snapshot())
+        await asyncio.sleep(max(0, interval - (time.time() - now)))
+
+
+# --------------------------------------------------------------------------
+# FastAPI app
+# --------------------------------------------------------------------------
+app = FastAPI(title="HuggingWizards")
+
+_loop_task: asyncio.Task | None = None
+
+
+def ensure_loop():
+    """Start the game loop once. Robust to Gradio overriding the app lifespan."""
+    global _loop_task
+    if _loop_task is None or _loop_task.done():
+        _loop_task = asyncio.create_task(game_loop())
+
+
+@app.get("/")
+async def index():
+    return FileResponse(os.path.join(HERE, "static", "index.html"))
+
+
+@app.get("/traces")
+async def traces():
+    """Recent Game Master agent traces, trimmed for the in-game panel."""
+    out = []
+    for t in gamemaster.RECENT_TRACES[:15]:
+        out.append({
+            "trace_id": t.get("trace_id"), "round": t.get("round"),
+            "ts": t.get("ts"), "model": t.get("model"),
+            "source": t.get("source"), "latency_sec": t.get("latency_sec"),
+            "kind": t.get("kind", "round_decision"), "error": t.get("error"),
+            "mercy": t.get("mercy"),
+            "raw_output": str(t.get("raw_output", ""))[:600],
+            "decision": t.get("decision"),
+        })
+    return {"traces": out}
+
+
+@app.websocket("/ws")
+async def ws_endpoint(ws: WebSocket):
+    await ws.accept()
+    ensure_loop()
+    clients[ws] = {"pid": None, "role": "spectator", "name": "Wizard", "char": "warrior"}
+    try:
+        while True:
+            data = json.loads(await ws.receive_text())
+            mtype = data.get("type")
+
+            if mtype == "join":
+                name = str(data.get("name", "Wizard"))[:16] or "Wizard"
+                char = str(data.get("char", "warrior"))[:16] or "soldier"
+                clients[ws]["name"] = name
+                clients[ws]["char"] = char
+                if clients[ws]["pid"]:
+                    continue
+                if engine.can_join():
+                    pid = uuid.uuid4().hex[:8]
+                    engine.add_player(pid, name, char)
+                    clients[ws] = {**clients[ws], "pid": pid, "role": "player"}
+                    await _send(ws, {"type": "welcome", "pid": pid, "role": "player"})
+                else:
+                    # game full -> join the queue
+                    if ws not in queue:
+                        queue.append(ws)
+                    pos = queue.index(ws) + 1
+                    await _send(ws, {"type": "welcome", "pid": None, "role": "spectator",
+                                     "reason": "queued", "pos": pos, "size": len(queue)})
+
+            elif mtype == "spectate":
+                clients[ws]["name"] = str(data.get("name", "Wizard"))[:16] or "Wizard"
+                clients[ws]["char"] = str(data.get("char", "warrior"))[:16] or "soldier"
+
+            elif mtype == "leave_queue":
+                if ws in queue:
+                    queue.remove(ws)
+
+            elif mtype == "get_leaderboard":
+                await _send(ws, {"type": "leaderboard", "top": _leaderboard[:20]})
+
+            elif mtype == "submit_score":
+                top = add_score(str(data.get("name", "Wizard")), int(data.get("gold", 0)),
+                                int(data.get("level", 1)), int(data.get("wave", 0)))
+                await _send(ws, {"type": "leaderboard", "top": top, "submitted": True})
+
+            elif mtype == "input" and clients[ws]["pid"]:
+                engine.set_input(clients[ws]["pid"], data)
+
+            elif mtype == "choose_card" and clients[ws]["pid"]:
+                engine.choose_card(clients[ws]["pid"], data.get("key", ""))
+
+            elif mtype == "request_skill" and clients[ws]["pid"]:
+                await handle_skill_request(ws, clients[ws]["pid"], str(data.get("prompt", "")))
+
+            elif mtype == "start" and clients[ws]["pid"]:
+                if engine.status == "lobby":
+                    engine.start_round()
+    except WebSocketDisconnect:
+        pass
+    except Exception:
+        pass
+    finally:
+        if ws in queue:
+            queue.remove(ws)
+        _drop(ws)
+
+
+app.mount("/static", StaticFiles(directory=os.path.join(HERE, "static")), name="static")
+
+
+# --------------------------------------------------------------------------
+# Gradio dashboard (mounted at /dashboard)
+# --------------------------------------------------------------------------
+def _dashboard_state():
+    players = sorted(engine.players.values(), key=lambda p: p.gold, reverse=True)
+    if players:
+        lb = "| Wizard | Level | Gold | Last-round dmg | Kills |\n|---|---|---|---|---|\n"
+        lb += "\n".join(
+            f"| {p.name} | {p.level} | {p.gold} | {round(p.dmg_dealt)} | {p.kills} |"
+            for p in players
+        )
+    else:
+        lb = "_No wizards in the arena yet._"
+    header = (f"### Round {engine.round} — `{engine.status}`\n"
+              f"{engine.status_msg}\n\n"
+              f"Players: {len(engine.players)}/{MAX_PLAYERS} · "
+              f"GM: _{engine.gm_message or '—'}_")
+    traces = gamemaster.RECENT_TRACES[:10]
+    return header, lb, traces
+
+
+with gr.Blocks(title="HuggingWizards — Game Master Dashboard") as demo:
+    gr.Markdown("# 🧙 HuggingWizards — Game Master Dashboard\n"
+                "Play at the [arena](/). Below: live state, leaderboard, and the "
+                "per-round **agent traces** produced by Nemotron-4B.")
+    header_md = gr.Markdown()
+    with gr.Row():
+        leaderboard_md = gr.Markdown()
+    gr.Markdown("## Agent traces (most recent first)")
+    traces_json = gr.JSON()
+    timer = gr.Timer(2.0)
+    timer.tick(_dashboard_state, outputs=[header_md, leaderboard_md, traces_json])
+    demo.load(_dashboard_state, outputs=[header_md, leaderboard_md, traces_json])
+
+app = gr.mount_gradio_app(app, demo, path="/dashboard")
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    port = int(os.environ.get("PORT", 7860))
+    uvicorn.run(app, host="0.0.0.0", port=port)

HuggingWizards-upload/game/engine.py

@@ -0,0 +1,1537 @@
+"""Authoritative co-op arena simulation.
+
+One shared arena: a boss in the center, minions that spawn, and up to
+MAX_PLAYERS wizards. The engine ticks on the CPU at TICK_HZ and produces a
+JSON-serialisable snapshot that is broadcast to every connected client.
+
+The engine knows nothing about networking or the LLM. The server drives it:
+- feed inputs via `set_input` / `add_player` / `remove_player`
+- call `tick(dt)` every frame
+- when `status == "intermission"`, ask the Game Master for a decision and pass
+  it to `apply_gm_decision`, then call `start_round`.
+"""
+from __future__ import annotations
+
+import math
+import random
+import time
+from dataclasses import dataclass, field
+
+from game import skills as skillmod
+
+ARENA_W = 1280
+ARENA_H = 720
+CENTER = (ARENA_W / 2, ARENA_H / 2)
+
+MAX_PLAYERS = 8
+TICK_HZ = 20
+
+# Upgrade definitions: id -> (label, cost). Cost is legacy (gold shop); the
+# survivors-mode progression hands these out as level-up cards instead.
+UPGRADES = {
+    "damage": ("Spell Power", 30),
+    "attack_speed": ("Cast Speed", 30),
+    "move_speed": ("Boots", 25),
+    "max_hp": ("Vitality", 25),
+    "multishot": ("Multishot", 60),
+}
+
+# Level-up cards. id -> (label, description, rarity). The stat ids above plus a
+# few survivors-flavored extras. The Game Master picks which cards are offered.
+CARDS = {
+    # --- originals ---
+    "auto_attack": ("Auto-Cast", "Attack automatically — no need to hold Space", "common"),
+    "damage": ("Spell Power", "+6 spell damage", "common"),
+    "attack_speed": ("Quick Cast", "Cast faster", "common"),
+    "move_speed": ("Swift Boots", "+22 move speed", "common"),
+    "max_hp": ("Vitality", "+25 max HP (and heal)", "common"),
+    "multishot": ("Multishot", "+1 projectile", "rare"),
+    "pierce": ("Piercing Bolt", "Shots pierce +1 enemy", "rare"),
+    "regen": ("Regeneration", "+2 HP/sec", "uncommon"),
+    "projectile_speed": ("Arcane Velocity", "Faster, longer shots", "uncommon"),
+    "aoe": ("Arcane Nova", "Periodic burst damages nearby foes", "rare"),
+    "summoner": ("Spirit Caller", "Summon spirits that fight for you", "rare"),
+    # --- 20 new base power-ups ---
+    "crit": ("Critical Strike", "+8% chance to deal double damage", "uncommon"),
+    "lifesteal": ("Vampirism", "Heal for a % of damage dealt", "uncommon"),
+    "armor": ("Iron Hide", "-2 flat damage taken", "common"),
+    "dodge": ("Evasion", "+5% chance to avoid a hit", "uncommon"),
+    "thorns": ("Spiked Aura", "Melee attackers take damage back", "uncommon"),
+    "magnet": ("Lodestone", "Pull XP gems from much farther", "common"),
+    "xp_boost": ("Quick Study", "+15% XP from gems", "uncommon"),
+    "gold_boost": ("Prosperity", "+20% gold from rewards", "common"),
+    "knockback": ("Force Bolt", "Shots knock enemies back", "common"),
+    "explosive": ("Explosive Shots", "Shots burst for splash damage", "rare"),
+    "burn": ("Ignite", "Shots set enemies on fire (damage over time)", "uncommon"),
+    "chain": ("Chain Spark", "Hits arc to a nearby enemy", "rare"),
+    "big_shots": ("Heavy Orbs", "Bigger, easier-to-land projectiles", "common"),
+    "homing": ("Seeker Bolts", "Shots curve toward enemies", "rare"),
+    "giant": ("Titan Growth", "+30 max HP and you grow larger", "uncommon"),
+    "glass_cannon": ("Glass Cannon", "+12 damage but -15 max HP", "rare"),
+    "berserker": ("Berserker", "Big damage boost while below half HP", "uncommon"),
+    "shield": ("Aegis", "Start each wave with a damage-absorbing shield", "uncommon"),
+    "slow_aura": ("Frost Presence", "Nearby enemies are slowed", "uncommon"),
+    "fortune": ("Lucky Charm", "Better gem tiers and rarer drops", "rare"),
+    # --- boss-exclusive (only offered during the matching boss; see THEME_CARDS) ---
+    "war_drums": ("War Drums", "Periodically summon a warband", "rare"),
+    "savage_roar": ("Savage Roar", "Each kill erupts in an AoE blast", "rare"),
+    "iron_nova": ("Iron Detonation", "Heavy slowing nova every few casts", "rare"),
+    "bulwark": ("Bulwark", "Periodically restore a chunk of HP", "rare"),
+    "impaling_charge": ("Impaling Charge", "Burst of piercing lances", "rare"),
+    "arrow_storm": ("Arrow Storm", "A constant rain of arrows", "rare"),
+}
+ALL_CARD_IDS = list(CARDS.keys())
+# Cards that grant a runtime skill spec rather than a stat point.
+SKILL_CARDS = set(skillmod.CARD_SKILLS.keys())
+# One-time cards excluded from draws once owned.
+# (auto_attack handled below in BINARY_CARDS)
+
+# Boss-exclusive cards: each is ONLY offered while its boss theme is active.
+# theme index = (round-1)//5  ->  Orc / Iron Legion / Lancer / Archer (then cycles)
+THEME_CARDS = {
+    0: ["war_drums", "savage_roar"],     # Orc Horde
+    1: ["iron_nova", "bulwark"],         # Iron Legion
+    2: ["impaling_charge"],              # Lancer Host
+    3: ["arrow_storm"],                  # Archer Coven
+}
+# Every theme-exclusive id, so they can be filtered out of normal draws.
+THEME_ONLY = {cid for ids in THEME_CARDS.values() for cid in ids}
+
+def theme_cards_for(theme: int) -> list[str]:
+    return THEME_CARDS.get(theme % len(THEME_CARDS), [])
+# One-time cards excluded from draws once owned: Auto-Cast and every skill card
+# (re-granting a skill would just duplicate it).
+BINARY_CARDS = {"auto_attack"} | SKILL_CARDS
+
+# XP gem tiers 1..7 -> XP value (increasing). The client colors/sizes by tier.
+GEM_TIER_XP = {1: 1, 2: 2, 3: 4, 4: 7, 5: 12, 6: 20, 7: 35}
+
+# Timed AURAS — ONLY found as floor pickups (never cards). Each lasts dur seconds
+# and applies temporary multipliers. "sheet" picks a Retro Impact effect sheet.
+AURAS = {
+    "inferno":  {"label": "Inferno Aura", "dur": 40, "sheet": "a", "color": "#ff7a4a",
+                 "dmg": 1.6},
+    "frost":    {"label": "Frost Aura", "dur": 50, "sheet": "b", "color": "#7ee0ff",
+                 "enemy_slow": 0.45, "move": 1.15},
+    "haste":    {"label": "Haste Aura", "dur": 35, "sheet": "c", "color": "#a6ff8c",
+                 "atk": 0.6, "move": 1.4},
+    "vampire":  {"label": "Vampiric Aura", "dur": 40, "sheet": "d", "color": "#ff6e6e",
+                 "lifesteal": 0.18},
+    "warding":  {"label": "Warding Aura", "dur": 55, "sheet": "e", "color": "#ffd45e",
+                 "dmg_red": 0.45},
+    "fury":     {"label": "Fury Aura", "dur": 30, "sheet": "f", "color": "#c08cff",
+                 "dmg": 1.35, "atk": 0.7},
+}
+ALL_AURA_IDS = list(AURAS.keys())
+PENDING_AUTOPICK_SEC = 15.0   # auto-choose a card if the player dithers
+
+# Special boss encounters. They replace the themed boss on certain waves, tint the
+# whole screen, attack with a unique projectile style, and — when defeated — grant
+# every surviving wizard the boss's own attack power.
+SPECIAL_BOSSES = {
+    "aegis":   {"name": "AEGIS", "hue": "red", "hp_mult": 2.3, "dmg_mult": 1.3,
+                "style": "holy", "reward": "holy_judgment"},
+    "toaster": {"name": "TOASTER BOT", "hue": "green", "hp_mult": 1.9, "dmg_mult": 1.15,
+                "style": "glitch", "reward": "glitch_rift"},
+}
+
+
+def special_boss_for(rnd: int) -> str | None:
+    """Aegis on waves 3,9,15…  Toaster Bot on waves 5,11,17…"""
+    if rnd >= 3 and (rnd - 3) % 6 == 0:
+        return "aegis"
+    if rnd >= 5 and (rnd - 5) % 6 == 0:
+        return "toaster"
+    return None
+
+# Enemy archetypes: id -> stat multipliers/overrides relative to the base minion.
+MINION_TYPES = {
+    "grunt": {"hp": 1.0, "speed": 1.0, "dmg": 1.0, "scale": 1.0},
+    "fast":  {"hp": 0.6, "speed": 1.8, "dmg": 0.7, "scale": 0.85},
+    "tank":  {"hp": 2.6, "speed": 0.6, "dmg": 1.6, "scale": 1.3},
+}
+
+# Boss attack patterns — the Game Master picks one per round. Multipliers scale
+# how often each attack fires (>1 = more often); flags switch firing styles.
+BOSS_PATTERNS = {
+    "balanced":  {"shoot": 1.0, "nova": 1.0, "charge": 1.0, "spawn": 1.0,
+                  "label": ""},
+    "artillery": {"shoot": 0.6, "nova": 2.0, "charge": 0.4, "spawn": 0.8,
+                  "label": "ARTILLERY", "slow_heavy": True},
+    "sniper":    {"shoot": 1.5, "nova": 0.45, "charge": 0.6, "spawn": 0.7,
+                  "label": "SNIPER", "snipe": True},
+    "swarm":     {"shoot": 0.55, "nova": 0.6, "charge": 0.5, "spawn": 2.4,
+                  "label": "SWARMLORD"},
+    "berserker": {"shoot": 0.7, "nova": 0.8, "charge": 2.6, "spawn": 0.7,
+                  "label": "BERSERKER"},
+}
+ALL_PATTERN_IDS = list(BOSS_PATTERNS.keys())
+
+# Blessings the Game Master may bestow on individual wizards between rounds:
+# any timed aura, an extra life, or a full heal. Applied at next round start.
+BLESSINGS = ["extra_life", "full_heal"] + ALL_AURA_IDS
+MAX_LIVES = 5
+
+
+def _clamp(v, lo, hi):
+    return lo if v < lo else hi if v > hi else v
+
+
+@dataclass
+class Projectile:
+    x: float
+    y: float
+    vx: float
+    vy: float
+    dmg: float
+    owner: str  # player id, or "boss"/"minion"
+    hostile: bool  # True = damages players, False = damages enemies
+    ttl: float = 2.5
+    radius: float = 10.0
+    pierce: int = 0  # remaining extra enemies this shot can pass through
+    hit_ids: set = field(default_factory=set)  # minion uids already hit (for pierce)
+    # power-up effect payload (player shots only)
+    homing: bool = False
+    burn: float = 0.0       # burn dps applied on hit (Ignite)
+    explode: float = 0.0    # AoE radius on hit (Explosive)
+    knock: float = 0.0      # knockback impulse (Force Bolt)
+    chain: int = 0          # extra chain hits (Chain Spark)
+    crit: bool = False      # was a critical hit (visual)
+    style: str = ""         # visual style: "" | "holy" | "glitch"
+
+    def to_dict(self):
+        d = {"x": round(self.x, 1), "y": round(self.y, 1),
+             "hostile": self.hostile, "r": self.radius}
+        if self.style:
+            d["s"] = self.style
+        return d
+
+
+@dataclass
+class Minion:
+    x: float
+    y: float
+    hp: float
+    max_hp: float
+    speed: float
+    dmg: float
+    uid: int = 0  # stable id so the client can track hit/death effects
+    kind: str = "grunt"  # grunt | fast | tank
+    scale: float = 1.0
+    attack_cd: float = 0.0
+    hurt: float = 0.0
+    burn: float = 0.0       # burn damage-per-second (Ignite)
+    burn_t: float = 0.0     # burn time remaining
+    alive: bool = True
+
+    def to_dict(self):
+        return {"id": self.uid,
+                "x": round(self.x, 1), "y": round(self.y, 1),
+                "hp": self.hp, "max_hp": self.max_hp, "kind": self.kind,
+                "scale": self.scale, "hurt": self.hurt > 0,
+                "burn": self.burn_t > 0}
+
+
+@dataclass
+class Ally:
+    """A summoned spirit that fights for a player (from a summon_ally skill)."""
+    x: float
+    y: float
+    owner: str            # player id (kills/damage credit the summoner)
+    uid: int = 0
+    hp: float = 30.0
+    max_hp: float = 30.0
+    speed: float = 150.0
+    dmg: float = 12.0
+    attack_cd: float = 0.0
+    ttl: float = 14.0
+    color: str = "#a6ff8c"
+
+    def to_dict(self):
+        return {"id": self.uid, "x": round(self.x, 1), "y": round(self.y, 1),
+                "hp": self.hp, "max_hp": self.max_hp, "color": self.color}
+
+
+@dataclass
+class Pickup:
+    """A rare floor power-up. kind 'card' grants a permanent card; kind 'aura'
+    grants a timed aura buff. Walk over it to claim."""
+    x: float
+    y: float
+    card: str            # card id (kind=card) or aura id (kind=aura)
+    kind: str = "card"   # card | aura
+    uid: int = 0
+    ttl: float = 22.0
+
+    def to_dict(self):
+        d = {"id": self.uid, "x": round(self.x, 1), "y": round(self.y, 1),
+             "card": self.card, "kind": self.kind}
+        if self.kind == "aura":
+            d["color"] = AURAS.get(self.card, {}).get("color", "#fff")
+            d["sheet"] = AURAS.get(self.card, {}).get("sheet", "a")
+        return d
+
+
+@dataclass
+class Gem:
+    x: float
+    y: float
+    value: int = 1
+    tier: int = 1
+    ttl: float = 18.0
+
+    def to_dict(self):
+        return {"x": round(self.x, 1), "y": round(self.y, 1),
+                "v": self.value, "t": self.tier}
+
+
+@dataclass
+class Boss:
+    hp: float = 1000
+    max_hp: float = 1000
+    dmg: float = 12
+    x: float = CENTER[0]
+    y: float = CENTER[1]
+    shoot_cd: float = 0.0
+    spawn_cd: float = 0.0
+    spawn_interval: float = 4.0
+    hurt: float = 0.0
+    # attack state machine
+    state: str = "idle"          # idle | telegraph | charge
+    state_t: float = 0.0         # time remaining in the current state
+    charge_cd: float = 6.0       # until next charge
+    nova_cd: float = 5.0         # until next ground shockwave
+    cvx: float = 0.0
+    cvy: float = 0.0
+    aggro: float = 1.0           # Director-tunable attack frequency multiplier
+    special: str = ""            # "" | "aegis" | "toaster"
+    name: str = ""               # display name (special bosses)
+    special_cd: float = 4.0      # until next signature attack
+    pattern: str = "balanced"    # Director-chosen attack pattern
+    atk_speed: float = 1.0       # Director-chosen attack cadence multiplier
+
+    def to_dict(self):
+        return {"x": round(self.x, 1), "y": round(self.y, 1),
+                "hp": self.hp, "max_hp": self.max_hp,
+                "hurt": self.hurt > 0, "state": self.state,
+                "special": self.special, "name": self.name,
+                "pattern": self.pattern, "atk_speed": self.atk_speed,
+                "pattern_label": BOSS_PATTERNS.get(self.pattern, {}).get("label", ""),
+                "phase": 1 if self.hp > self.max_hp * 0.5 else 2}
+
+
+@dataclass
+class Player:
+    pid: str
+    name: str
+    x: float = 200.0
+    y: float = 360.0
+    hp: float = 100.0
+    max_hp: float = 100.0
+    speed: float = 180.0
+    facing: float = 0.0  # radians, last aim direction
+    alive: bool = True
+    gold: int = 0
+    level: int = 1
+    # input
+    up: bool = False
+    down: bool = False
+    left: bool = False
+    right: bool = False
+    attacking: bool = False
+    attack_timer: float = 0.0
+    moving: bool = False
+    hurt: float = 0.0
+    # upgrade levels (gained via level-up cards)
+    up_damage: int = 0
+    up_attack_speed: int = 0
+    up_move_speed: int = 0
+    up_max_hp: int = 0
+    up_multishot: int = 0
+    up_pierce: int = 0
+    up_regen: int = 0
+    up_projectile_speed: int = 0
+    up_auto_attack: int = 0
+    # new base power-ups
+    up_crit: int = 0
+    up_lifesteal: int = 0
+    up_armor: int = 0
+    up_dodge: int = 0
+    up_thorns: int = 0
+    up_magnet: int = 0
+    up_xp_boost: int = 0
+    up_gold_boost: int = 0
+    up_knockback: int = 0
+    up_explosive: int = 0
+    up_burn: int = 0
+    up_chain: int = 0
+    up_big_shots: int = 0
+    up_homing: int = 0
+    up_giant: int = 0
+    up_glass_cannon: int = 0
+    up_berserker: int = 0
+    up_shield: int = 0
+    up_slow_aura: int = 0
+    up_fortune: int = 0
+    shield: float = 0.0          # current absorb (from Aegis)
+    flash: str = ""              # transient pickup/announce text for this player
+    flash_t: float = 0.0
+    # lives / character / timed auras
+    lives: int = 3
+    char: str = "warrior"        # chosen character sprite set
+    respawn_t: float = 0.0       # >0 while waiting to respawn after a death
+    auras: list = field(default_factory=list)  # active timed auras [{type,t}]
+    pending_until: float = 0.0   # auto-pick deadline for pending_cards
+    # XP / character level
+    xp: int = 0
+    xp_needed: int = 5
+    pending_cards: list = field(default_factory=list)  # card ids offered now
+    skill_cards: set = field(default_factory=set)      # owned skill-card ids
+    # runtime skill specs (from cards or Game-Master-authored requests) + state
+    skills: list = field(default_factory=list)
+    _attack_count: int = 0
+    # per-round stats
+    dmg_dealt: float = 0.0
+    kills: int = 0
+
+    # ---- timed-aura helpers ----
+    def _aura_prod(self, key: str, default: float = 1.0) -> float:
+        v = default
+        for a in self.auras:
+            spec = AURAS.get(a["type"], {})
+            if key in spec:
+                v *= spec[key]
+        return v
+
+    def _aura_max(self, key: str) -> float:
+        v = 0.0
+        for a in self.auras:
+            spec = AURAS.get(a["type"], {})
+            if key in spec:
+                v = max(v, spec[key])
+        return v
+
+    # derived stats
+    @property
+    def damage(self) -> float:
+        # base + Spell Power + Glass Cannon; Berserker adds more while wounded
+        d = 14 + self.up_damage * 6 + self.up_glass_cannon * 12
+        if self.up_berserker and self.hp < self.max_hp * 0.5:
+            d *= 1 + 0.15 * self.up_berserker
+        return d * self._aura_prod("dmg")
+
+    @property
+    def size_mult(self) -> float:
+        # Wizards start minion-sized (0.55) and grow a step every level, capped
+        # a touch above boss size (2.9) — a long run literally makes you a
+        # bigger, harder-to-dodge-with target. Titan Growth stacks on top.
+        return min(2.9, 0.55 + 0.12 * (self.level - 1)) * (1 + self.up_giant * 0.18)
+
+    @property
+    def hit_radius(self) -> float:
+        # Server-authoritative hurtbox — grows with size, so dodging gets
+        # harder as you level (the client renders at the same scale).
+        return 10.0 + 12.0 * self.size_mult
+
+    @property
+    def attack_interval(self) -> float:
+        return max(0.12, (0.55 - self.up_attack_speed * 0.05) * self._aura_prod("atk"))
+
+    @property
+    def move_speed(self) -> float:
+        return (180 + self.up_move_speed * 22) * self._aura_prod("move")
+
+    @property
+    def shots(self) -> int:
+        return 1 + self.up_multishot
+
+    @property
+    def projectile_speed(self) -> float:
+        return 520 + self.up_projectile_speed * 90
+
+    @property
+    def projectile_ttl(self) -> float:
+        return 2.5 + self.up_projectile_speed * 0.6
+
+    @property
+    def regen(self) -> float:
+        return self.up_regen * 2.0  # hp per second
+
+    def to_dict(self):
+        return {
+            "id": self.pid, "name": self.name,
+            "x": round(self.x, 1), "y": round(self.y, 1),
+            "hp": round(self.hp, 1), "max_hp": self.max_hp,
+            "facing": round(self.facing, 3), "alive": self.alive,
+            "gold": self.gold, "level": self.level, "moving": self.moving,
+            "attacking": self.attack_timer > 0, "hurt": self.hurt > 0,
+            "xp": self.xp, "xp_needed": self.xp_needed,
+            "pending_cards": list(self.pending_cards),
+            "pending_left": round(max(0.0, self.pending_until - time.time()), 1) if self.pending_cards else 0,
+            "lives": self.lives, "char": self.char,
+            "auras": [{"type": a["type"], "t": round(a["t"], 1),
+                       "color": AURAS.get(a["type"], {}).get("color", "#fff"),
+                       "label": AURAS.get(a["type"], {}).get("label", a["type"])}
+                      for a in self.auras],
+            "size": round(self.size_mult, 2),
+            "shield": round(self.shield, 1),
+            "flash": self.flash if self.flash_t > 0 else "",
+            "skills": [{"name": s["name"], "effect": s["effect"], "color": s.get("color", "#b48cff")}
+                       for s in self.skills],
+            # owned level per card (skill cards report 1 when owned)
+            "upgrades": {k: (1 if k in self.skill_cards else getattr(self, f"up_{k}", 0))
+                         for k in CARDS},
+            "stats": {"dmg": round(self.dmg_dealt), "kills": self.kills},
+        }
+
+
+class Engine:
+    def __init__(self):
+        self.players: dict[str, Player] = {}
+        self.minions: list[Minion] = []
+        self._minion_seq = 0
+        self.projectiles: list[Projectile] = []
+        self.gems: list[Gem] = []
+        self.allies: list[Ally] = []
+        self._ally_seq = 0
+        self.pickups: list[Pickup] = []
+        self._pickup_seq = 0
+        self.boss = Boss()
+        self.round = 0
+        self.status = "lobby"  # lobby | active | intermission
+        self.status_msg = "Waiting for wizards to join..."
+        self.gm_message = ""
+        self.intermission_until = 0.0
+        self.round_started_at = 0.0
+        self.skill_request_pid: str | None = None
+        self.skill_request_used = False
+        # Cards the Game Master is currently offering on level-up (ids). Empty =>
+        # the full set is available (deterministic default).
+        self.card_pool: list[str] = list(ALL_CARD_IDS)
+        # config applied each round (mutated by the Game Master)
+        self.cfg = {
+            "boss_hp": 1000, "boss_damage": 12,
+            "minion_hp": 40, "minion_count": 6, "spawn_interval": 4.0,
+            "boss_aggro": 1.0,   # Director-tunable attack frequency
+            "boss_attack_speed": 1.0,  # Director-tunable cadence (mercy-floored)
+            "boss_pattern": "balanced",   # Director-chosen attack pattern
+            # wave composition: relative weights of each enemy archetype
+            "wave": {"grunt": 1.0, "fast": 0.0, "tank": 0.0},
+        }
+        # one-shot blessings the GM granted for the coming round: {pid: blessing}
+        self.pending_blessings: dict[str, str] = {}
+        # transient FX events for the client (drained each snapshot)
+        self._events: list[dict] = []
+
+    def _event(self, fx: str, x: float, y: float, **kw):
+        """Queue a one-shot visual event for the next snapshot broadcast."""
+        if len(self._events) < 40:
+            self._events.append({"fx": fx, "x": round(x, 1), "y": round(y, 1), **kw})
+
+    # ---- lobby management -------------------------------------------------
+    @property
+    def active_players(self) -> list[Player]:
+        return list(self.players.values())
+
+    def can_join(self) -> bool:
+        return len(self.players) < MAX_PLAYERS
+
+    def add_player(self, pid: str, name: str, char: str = "warrior") -> Player:
+        spawn_angle = random.uniform(0, math.tau)
+        p = Player(
+            pid=pid, name=name[:16] or "Wizard", char=char or "soldier",
+            x=CENTER[0] + math.cos(spawn_angle) * 420,
+            y=CENTER[1] + math.sin(spawn_angle) * 280,
+        )
+        p.x = _clamp(p.x, 40, ARENA_W - 40)
+        p.y = _clamp(p.y, 40, ARENA_H - 40)
+        # if joining mid-wave, jump straight into the fight
+        if self.status == "active":
+            p.hp = p.max_hp
+        self.players[pid] = p
+        if self.status == "lobby" and len(self.players) >= 1:
+            self.status_msg = "Press START or wait for more wizards."
+        return p
+
+    def remove_player(self, pid: str):
+        self.players.pop(pid, None)
+
+    def set_input(self, pid: str, data: dict):
+        p = self.players.get(pid)
+        if not p:
+            return
+        p.up = bool(data.get("up"))
+        p.down = bool(data.get("down"))
+        p.left = bool(data.get("left"))
+        p.right = bool(data.get("right"))
+        p.attacking = bool(data.get("attack"))
+
+    def _apply_card(self, p: Player, key: str):
+        """Apply a chosen level-up card's effect to a player."""
+        if key in SKILL_CARDS:
+            self._add_skill(p, skillmod.CARD_SKILLS[key])
+            p.skill_cards.add(key)
+            return
+        setattr(p, f"up_{key}", getattr(p, f"up_{key}") + 1)
+        if key in ("max_hp", "giant", "glass_cannon"):
+            self._recompute_max_hp(p)
+            if key == "max_hp":
+                p.hp = min(p.max_hp, p.hp + 25)
+        if key == "shield":
+            p.shield = max(p.shield, 20 * p.up_shield)
+
+    def _recompute_max_hp(self, p: Player):
+        p.max_hp = max(20, 100 + p.up_max_hp * 25 + p.up_giant * 30 - p.up_glass_cannon * 15)
+        p.hp = min(p.hp, p.max_hp)
+
+    def _add_skill(self, p: Player, spec: dict) -> dict | None:
+        """Validate and attach a skill spec to a player (caps the count)."""
+        safe = skillmod.validate_skill(spec)
+        if not safe:
+            return None
+        safe = dict(safe)
+        safe["_cd"] = safe.get("interval", 0.0)  # periodic cooldown timer
+        if len(p.skills) >= skillmod.MAX_SKILLS_PER_PLAYER:
+            p.skills.pop(0)
+        p.skills.append(safe)
+        return safe
+
+    def add_runtime_skill(self, pid: str, spec: dict) -> dict | None:
+        """Hot-plug a Game-Master-authored skill onto a player (the LLM flow)."""
+        p = self.players.get(pid)
+        if not p:
+            return None
+        return self._add_skill(p, spec)
+
+    def top_player_id(self) -> str | None:
+        """Highest-damage player of the round just ended (gets the skill request)."""
+        if not self.players:
+            return None
+        return max(self.players.values(), key=lambda p: p.dmg_dealt).pid
+
+    def choose_card(self, pid: str, key: str) -> bool:
+        """Player picks one of the cards currently offered to them."""
+        p = self.players.get(pid)
+        if not p or key not in CARDS or key not in p.pending_cards:
+            return False
+        self._apply_card(p, key)
+        p.pending_cards = []  # one pick per level-up
+        p.pending_until = 0.0
+        return True
+
+    def buy_upgrade(self, pid: str, key: str) -> bool:
+        """Legacy gold shop (kept for compatibility; survivors mode uses cards)."""
+        p = self.players.get(pid)
+        if not p or key not in UPGRADES:
+            return False
+        if self.status not in ("intermission", "lobby"):
+            return False
+        _, cost = UPGRADES[key]
+        if p.gold < cost:
+            return False
+        p.gold -= cost
+        self._apply_card(p, key)
+        return True
+
+    def _owns(self, p: Player, cid: str) -> bool:
+        """Whether a one-time card is already taken (stat binary or a skill card)."""
+        if cid in SKILL_CARDS:
+            return cid in p.skill_cards
+        return bool(getattr(p, f"up_{cid}", 0))
+
+    def _draw_cards(self, p: Player, n: int = 3) -> list[str]:
+        """Draw up to n distinct card ids for a player, honoring boss-exclusive gating."""
+        theme = max(0, (self.round - 1) // 5)
+        theme_cards = theme_cards_for(theme)
+        pool = [c for c in self.card_pool if c in CARDS] or list(ALL_CARD_IDS)
+        # boss-exclusive cards: only the current boss's; drop all other themes'
+        pool = [c for c in pool if c not in THEME_ONLY or c in theme_cards]
+        # ensure this boss's exclusives are eligible even if the Director omitted them
+        for tc in theme_cards:
+            if tc not in pool:
+                pool.append(tc)
+        # drop one-time cards already owned
+        pool = [c for c in pool if not (c in BINARY_CARDS and self._owns(p, c))]
+        chosen: list[str] = []
+        # guarantee Auto-Cast is offered early so it doesn't get lost in RNG
+        if not p.up_auto_attack and p.level <= 3:
+            chosen.append("auto_attack")
+        rest = [c for c in pool if c not in chosen]
+        random.shuffle(rest)
+        # bias one slot toward a boss-exclusive card when available (feels special)
+        avail_theme = [c for c in theme_cards if c in rest]
+        if avail_theme and len(chosen) < n:
+            pick = random.choice(avail_theme)
+            chosen.append(pick); rest.remove(pick)
+        for c in rest:
+            if len(chosen) >= n:
+                break
+            chosen.append(c)
+        return chosen[:n]
+
+    def _grant_xp(self, p: Player, amount: int):
+        if not p.alive:
+            return
+        p.xp += amount
+        leveled = False
+        while p.xp >= p.xp_needed:
+            p.xp -= p.xp_needed
+            p.level += 1
+            p.xp_needed = int(p.xp_needed * 1.45) + 3
+            leveled = True
+        if leveled and not p.pending_cards:
+            p.pending_cards = self._draw_cards(p, 3)
+            p.pending_until = time.time() + PENDING_AUTOPICK_SEC
+
+    # ---- round lifecycle --------------------------------------------------
+    def start_round(self):
+        if not self.players:
+            self.status = "lobby"
+            return
+        self.round += 1
+        self.minions.clear()
+        self.projectiles.clear()
+        self.gems.clear()
+        self.allies.clear()
+        self.pickups.clear()
+        self.boss = Boss(
+            hp=self.cfg["boss_hp"], max_hp=self.cfg["boss_hp"],
+            dmg=self.cfg["boss_damage"], spawn_interval=self.cfg["spawn_interval"],
+            aggro=self.cfg.get("boss_aggro", 1.0),
+            pattern=self.cfg.get("boss_pattern", "balanced"),
+            atk_speed=self.cfg.get("boss_attack_speed", 1.0),
+        )
+        # special boss encounter? (Aegis / Toaster Bot) — buff and rename it
+        sp = special_boss_for(self.round)
+        if sp:
+            cfg = SPECIAL_BOSSES[sp]
+            self.boss.special = sp
+            self.boss.name = cfg["name"]
+            hp = int(self.cfg["boss_hp"] * cfg["hp_mult"])
+            self.boss.hp = self.boss.max_hp = hp
+            self.boss.dmg = int(self.cfg["boss_damage"] * cfg["dmg_mult"])
+        # XP / level / cards persist across the run; only revive & reset per-round
+        # combat stats. Pending card picks carry over so a level-up isn't lost.
+        for p in self.players.values():
+            self._recompute_max_hp(p)
+            p.hp = p.max_hp
+            p.alive = p.lives > 0     # eliminated wizards stay down (awaiting removal)
+            p.respawn_t = 0.0
+            p.dmg_dealt = 0.0
+            p.kills = 0
+            p.shield = 20 * p.up_shield     # Aegis refreshes each wave
+            ang = random.uniform(0, math.tau)
+            p.x = _clamp(CENTER[0] + math.cos(ang) * 420, 40, ARENA_W - 40)
+            p.y = _clamp(CENTER[1] + math.sin(ang) * 280, 40, ARENA_H - 40)
+        self._apply_blessings()
+        self.status = "active"
+        if self.boss.special:
+            self.status_msg = f"Wave {self.round} — {self.boss.name} has arrived!"
+        else:
+            self.status_msg = f"Wave {self.round} — survive and slay the boss!"
+        self.round_started_at = time.time()
+
+    def _grant_boss_reward(self, special: str):
+        """All living wizards gain the defeated special boss's signature attack."""
+        cfg = SPECIAL_BOSSES.get(special, {})
+        reward = cfg.get("reward")
+        spec = skillmod.CARD_SKILLS.get(reward)
+        if not spec:
+            return
+        name = spec.get("name", reward)
+        for p in self.players.values():
+            if p.alive and reward not in p.skill_cards:
+                self._add_skill(p, spec)
+                p.skill_cards.add(reward)
+                p.flash = f"Gained {name} from {cfg.get('name', 'the boss')}!"
+                p.flash_t = 3.0
+
+    def _apply_blessings(self):
+        """Consume the Game Master's one-shot blessings at round start."""
+        for pid, blessing in self.pending_blessings.items():
+            p = self.players.get(pid)
+            if not p or blessing not in BLESSINGS:
+                continue
+            if blessing == "extra_life":
+                p.lives = min(MAX_LIVES, p.lives + 1)
+                if p.lives > 0 and not p.alive and p.respawn_t <= 0:
+                    p.alive = True
+                    p.hp = p.max_hp
+                p.flash = "🙏 Blessed: an extra life!"
+            elif blessing == "full_heal":
+                p.hp = p.max_hp
+                p.flash = "🙏 Blessed: fully healed!"
+            else:  # a timed aura
+                spec = AURAS.get(blessing, {})
+                existing = next((a for a in p.auras if a["type"] == blessing), None)
+                if existing:
+                    existing["t"] = spec.get("dur", 40)
+                else:
+                    p.auras.append({"type": blessing, "t": spec.get("dur", 40)})
+                p.flash = f"🙏 Blessed: {spec.get('label', blessing)}!"
+            p.flash_t = 4.0
+            self._event("bless", p.x, p.y, color="#ffe9a0")
+        self.pending_blessings = {}
+
+    def _respawn(self, p: Player):
+        p.alive = True
+        p.respawn_t = 0.0
+        p.hp = p.max_hp
+        p.hurt = 1.0  # brief invuln flicker
+        ang = random.uniform(0, math.tau)
+        p.x = _clamp(CENTER[0] + math.cos(ang) * 420, 40, ARENA_W - 40)
+        p.y = _clamp(CENTER[1] + math.sin(ang) * 280, 40, ARENA_H - 40)
+
+    def round_summary(self) -> dict:
+        """Compact, model-friendly summary of the round that just ended."""
+        won = self.boss.hp <= 0
+        return {
+            "round": self.round,
+            "result": "victory" if won else "defeat",
+            "duration_sec": round(time.time() - self.round_started_at, 1),
+            "boss_max_hp": self.boss.max_hp,
+            "players": [
+                {
+                    "id": p.pid, "name": p.name, "level": p.level,
+                    "survived": p.alive,
+                    "damage_dealt": round(p.dmg_dealt),
+                    "kills": p.kills, "gold": p.gold,
+                    "lives_left": p.lives,
+                    "hp_pct": round(100 * p.hp / p.max_hp) if p.alive else 0,
+                }
+                for p in self.players.values()
+            ],
+        }
+
+    def apply_gm_decision(self, decision: dict):
+        """Apply a (validated) Game Master decision to rewards + next config."""
+        rewards = decision.get("rewards", {}) or {}
+        for pid, amount in rewards.items():
+            p = self.players.get(pid)
+            if p:
+                amt = int(_clamp(int(amount), 0, 1000)) * (1 + 0.2 * p.up_gold_boost)  # Prosperity
+                p.gold += int(amt)
+        nxt = decision.get("next_round", {}) or {}
+        self.cfg["boss_hp"] = int(_clamp(int(nxt.get("boss_hp", self.cfg["boss_hp"])), 300, 100000))
+        self.cfg["boss_damage"] = int(_clamp(int(nxt.get("boss_damage", self.cfg["boss_damage"])), 4, 80))
+        self.cfg["minion_hp"] = int(_clamp(int(nxt.get("minion_hp", self.cfg["minion_hp"])), 15, 2000))
+        self.cfg["minion_count"] = int(_clamp(int(nxt.get("minion_count", self.cfg["minion_count"])), 0, 40))
+        self.cfg["spawn_interval"] = float(_clamp(float(nxt.get("spawn_interval", self.cfg["spawn_interval"])), 1.0, 10.0))
+        self.cfg["boss_aggro"] = float(_clamp(float(nxt.get("boss_aggro", self.cfg["boss_aggro"])), 0.6, 3.0))
+        self.cfg["boss_attack_speed"] = float(_clamp(float(nxt.get("boss_attack_speed", self.cfg["boss_attack_speed"])), 0.5, 2.0))
+        # boss attack pattern for the coming round
+        pattern = nxt.get("boss_pattern", decision.get("boss_pattern"))
+        if pattern in BOSS_PATTERNS:
+            self.cfg["boss_pattern"] = pattern
+        # per-player blessings (validated against roster + known blessings)
+        blessings = decision.get("blessings")
+        if isinstance(blessings, dict):
+            self.pending_blessings = {
+                pid: b for pid, b in blessings.items()
+                if pid in self.players and b in BLESSINGS
+            }
+        # wave composition (enemy archetype weights)
+        wave = nxt.get("wave")
+        if isinstance(wave, dict):
+            clean = {}
+            for k in MINION_TYPES:
+                try:
+                    clean[k] = max(0.0, float(wave.get(k, 0.0)))
+                except Exception:
+                    clean[k] = 0.0
+            if sum(clean.values()) > 0:
+                self.cfg["wave"] = clean
+        # offered level-up card pool
+        pool = decision.get("card_pool")
+        if isinstance(pool, list):
+            valid = [c for c in pool if c in CARDS]
+            self.card_pool = valid if valid else list(ALL_CARD_IDS)
+        self.gm_message = str(decision.get("message", ""))[:240]
+
+    def _pick_minion_kind(self) -> str:
+        weights = self.cfg.get("wave") or {"grunt": 1.0}
+        kinds = [k for k in MINION_TYPES if weights.get(k, 0) > 0] or ["grunt"]
+        w = [weights.get(k, 0) for k in kinds]
+        return random.choices(kinds, weights=w, k=1)[0]
+
+    def begin_intermission(self, seconds: float = 12.0):
+        self.status = "intermission"
+        self.intermission_until = time.time() + seconds
+        won = self.boss.hp <= 0
+        self.status_msg = ("Victory! " if won else "Defeated... ") + \
+            "The Game Master is deciding rewards & the next round."
+        # the round's top damage-dealer may ask the GM for a custom power-up
+        self.skill_request_pid = self.top_player_id()
+        self.skill_request_used = False
+
+    # ---- simulation -------------------------------------------------------
+    def _spawn_minion(self):
+        # Minions are summoned by the boss: they emerge from around it.
+        ang = random.uniform(0, math.tau)
+        dist = random.uniform(50, 95)
+        x = _clamp(self.boss.x + math.cos(ang) * dist, 30, ARENA_W - 30)
+        y = _clamp(self.boss.y + math.sin(ang) * dist, 30, ARENA_H - 30)
+        kind = self._pick_minion_kind()
+        t = MINION_TYPES[kind]
+        hp = self.cfg["minion_hp"] * t["hp"]
+        self._minion_seq += 1
+        self.minions.append(Minion(
+            x=x, y=y, hp=hp, max_hp=hp,
+            speed=(70 + self.round * 4) * t["speed"],
+            dmg=(6 + self.round) * t["dmg"],
+            uid=self._minion_seq, kind=kind, scale=t["scale"],
+        ))
+
+    def _nearest_player(self, x, y):
+        best, bd = None, 1e18
+        for p in self.players.values():
+            if not p.alive:
+                continue
+            d = (p.x - x) ** 2 + (p.y - y) ** 2
+            if d < bd:
+                best, bd = p, d
+        return best
+
+    def _nearest_enemy(self, x, y):
+        """Closest minion, else the boss."""
+        best, bd = None, 1e18
+        for m in self.minions:
+            if not m.alive:
+                continue
+            d = (m.x - x) ** 2 + (m.y - y) ** 2
+            if d < bd:
+                best, bd = m, d
+        if self.boss.hp > 0:
+            d = (self.boss.x - x) ** 2 + (self.boss.y - y) ** 2
+            if d < bd or best is None:
+                best, bd = self.boss, d
+        return best
+
+    def tick(self, dt: float):
+        if self.status != "active":
+            return
+
+        for p in self.players.values():
+            p.hurt = max(0.0, p.hurt - dt)
+            p.attack_timer = max(0.0, p.attack_timer - dt)
+            if p.flash_t > 0:
+                p.flash_t -= dt
+            # timed auras count down and expire
+            if p.auras:
+                for a in p.auras:
+                    a["t"] -= dt
+                p.auras = [a for a in p.auras if a["t"] > 0]
+            # auto-pick a pending card if the player dithers past the deadline
+            if p.pending_cards and time.time() >= p.pending_until:
+                self.choose_card(p.pid, p.pending_cards[0])
+            if not p.alive:
+                # respawn after a short delay while lives remain
+                if p.lives > 0 and p.respawn_t > 0:
+                    p.respawn_t -= dt
+                    if p.respawn_t <= 0:
+                        self._respawn(p)
+                continue
+            if p.regen and p.hp < p.max_hp:
+                p.hp = min(p.max_hp, p.hp + p.regen * dt)
+            # periodic skills
+            for sk in p.skills:
+                if sk["trigger"] == "periodic":
+                    sk["_cd"] = sk.get("_cd", sk.get("interval", 5.0)) - dt
+                    if sk["_cd"] <= 0:
+                        sk["_cd"] = sk.get("interval", 5.0)
+                        self._fire_skill(p, sk)
+            dx = (1 if p.right else 0) - (1 if p.left else 0)
+            dy = (1 if p.down else 0) - (1 if p.up else 0)
+            p.moving = dx != 0 or dy != 0
+            if p.moving:
+                inv = 1.0 / math.hypot(dx, dy)
+                p.x = _clamp(p.x + dx * inv * p.move_speed * dt, 24, ARENA_W - 24)
+                p.y = _clamp(p.y + dy * inv * p.move_speed * dt, 24, ARENA_H - 24)
+            # aim at nearest enemy for satisfying co-op feel
+            tgt = self._nearest_enemy(p.x, p.y)
+            if tgt is not None:
+                p.facing = math.atan2(tgt.y - p.y, tgt.x - p.x)
+            # attack (Auto-Cast fires without holding the key)
+            if (p.attacking or p.up_auto_attack) and p.attack_timer <= 0:
+                self._player_shoot(p)
+                p.attack_timer = p.attack_interval
+
+        self._tick_minions(dt)
+        self._tick_boss(dt)
+        self._tick_allies(dt)
+        self._tick_projectiles(dt)
+        self._tick_gems(dt)
+        self._tick_pickups(dt)
+
+        self.minions = [m for m in self.minions if m.alive]
+        self.allies = [a for a in self.allies if a.ttl > 0 and a.hp > 0]
+
+        # round end conditions
+        if self.boss.hp <= 0:
+            # boss drops a shower of high-tier gems
+            for _ in range(10):
+                ang = random.uniform(0, math.tau)
+                d = random.uniform(20, 140)
+                gx = _clamp(self.boss.x + math.cos(ang) * d, 30, ARENA_W - 30)
+                gy = _clamp(self.boss.y + math.sin(ang) * d, 30, ARENA_H - 30)
+                g = self._make_gem(gx, gy, "tank")
+                g.tier = int(_clamp(g.tier + 2, 1, 7))
+                g.value = GEM_TIER_XP[g.tier]
+                self.gems.append(g)
+            # special boss defeated -> every survivor gains its attack power
+            if self.boss.special:
+                self._grant_boss_reward(self.boss.special)
+            self.begin_intermission()
+        elif self.players and all(not p.alive and p.respawn_t <= 0 for p in self.players.values()):
+            # every wizard is down with no respawn pending (all eliminated)
+            self.begin_intermission()
+
+    def _tick_allies(self, dt: float):
+        """Summoned spirits chase the nearest enemy and fire bolts at it."""
+        for a in self.allies:
+            a.ttl -= dt
+            a.attack_cd = max(0.0, a.attack_cd - dt)
+            tgt = self._nearest_enemy(a.x, a.y)
+            if tgt is None:
+                continue
+            dist = math.hypot(tgt.x - a.x, tgt.y - a.y)
+            ang = math.atan2(tgt.y - a.y, tgt.x - a.x)
+            if dist > 180:
+                a.x += math.cos(ang) * a.speed * dt
+                a.y += math.sin(ang) * a.speed * dt
+            if a.attack_cd <= 0:
+                self.projectiles.append(Projectile(
+                    x=a.x, y=a.y, vx=math.cos(ang) * 480, vy=math.sin(ang) * 480,
+                    dmg=a.dmg, owner=a.owner, hostile=False, radius=7, ttl=1.5,
+                ))
+                a.attack_cd = 0.8
+
+    def _tick_gems(self, dt: float):
+        """XP gems drift toward nearby living players and are auto-collected."""
+        alive = []
+        for g in self.gems:
+            g.ttl -= dt
+            if g.ttl <= 0:
+                continue
+            tgt = self._nearest_player(g.x, g.y)
+            collected = False
+            if tgt is not None:
+                pull = 130.0 + tgt.up_magnet * 55      # Lodestone
+                grab = 26.0 + tgt.up_magnet * 10
+                d = math.hypot(tgt.x - g.x, tgt.y - g.y)
+                if d <= grab:
+                    amount = g.value * (1 + 0.15 * tgt.up_xp_boost)   # Quick Study
+                    self._grant_xp(tgt, max(1, round(amount)))
+                    collected = True
+                elif d <= pull:
+                    ang = math.atan2(tgt.y - g.y, tgt.x - g.x)
+                    g.x += math.cos(ang) * 240 * dt
+                    g.y += math.sin(ang) * 240 * dt
+            if not collected:
+                alive.append(g)
+        self.gems = alive
+
+    def _tick_pickups(self, dt: float):
+        """Floor power-ups: walk over one to claim the card instantly."""
+        alive = []
+        for pk in self.pickups:
+            pk.ttl -= dt
+            if pk.ttl <= 0:
+                continue
+            taken = False
+            for p in self.players.values():
+                if p.alive and (p.x - pk.x) ** 2 + (p.y - pk.y) ** 2 < 34 ** 2:
+                    if pk.kind == "aura":
+                        spec = AURAS.get(pk.card, {})
+                        # refresh if already active, else add
+                        existing = next((a for a in p.auras if a["type"] == pk.card), None)
+                        if existing:
+                            existing["t"] = spec.get("dur", 40)
+                        else:
+                            p.auras.append({"type": pk.card, "t": spec.get("dur", 40)})
+                        p.flash = f"{spec.get('label', pk.card)}!"
+                    else:
+                        self._apply_card(p, pk.card)
+                        p.flash = f"Power-up: {CARDS.get(pk.card, (pk.card,))[0]}!"
+                    p.flash_t = 2.5
+                    taken = True
+                    break
+            if not taken:
+                alive.append(pk)
+        self.pickups = alive
+
+    def _player_shoot(self, p: Player):
+        spread = 0.18
+        n = p.shots
+        base = p.facing
+        radius = 9 + p.up_big_shots * 4
+        for i in range(n):
+            off = 0 if n == 1 else (i - (n - 1) / 2) * spread
+            ang = base + off
+            dmg = p.damage
+            crit = p.up_crit and random.random() < min(0.6, 0.08 * p.up_crit)
+            if crit:
+                dmg *= 2
+            self.projectiles.append(Projectile(
+                x=p.x, y=p.y,
+                vx=math.cos(ang) * p.projectile_speed,
+                vy=math.sin(ang) * p.projectile_speed,
+                dmg=dmg, owner=p.pid, hostile=False, radius=radius,
+                ttl=p.projectile_ttl, pierce=p.up_pierce,
+                homing=p.up_homing > 0, burn=p.up_burn * 4.0,
+                explode=60.0 if p.up_explosive else 0.0,
+                knock=p.up_knockback * 9.0, chain=p.up_chain, crit=bool(crit),
+            ))
+        # attack-triggered skills
+        p._attack_count += 1
+        for sk in p.skills:
+            if sk["trigger"] == "every_n_attacks" and p._attack_count % sk.get("n", 5) == 0:
+                self._fire_skill(p, sk)
+
+    # ---- skill effects ----------------------------------------------------
+    def _fire_skill(self, p: Player, sk: dict):
+        eff = sk["effect"]
+        color = sk.get("color", "#b48cff")
+        if eff == "aoe_damage":
+            self._event("aoe_frost" if sk.get("slow") else "aoe", p.x, p.y,
+                        r=sk["radius"], color=color)
+            r2 = sk["radius"] ** 2
+            for m in self.minions:
+                if m.alive and (m.x - p.x) ** 2 + (m.y - p.y) ** 2 <= r2:
+                    m.hp -= sk["damage"]; m.hurt = 0.15
+                    if sk.get("slow"):
+                        m.speed *= (1 - sk["slow"])
+                    p.dmg_dealt += sk["damage"]
+                    if m.hp <= 0:
+                        m.alive = False
+                        self._on_minion_killed(m, p)
+            if self.boss.hp > 0 and (self.boss.x - p.x) ** 2 + (self.boss.y - p.y) ** 2 <= r2:
+                self.boss.hp -= sk["damage"]; self.boss.hurt = 0.1; p.dmg_dealt += sk["damage"]
+        elif eff == "projectile_nova":
+            self._event("nova", p.x, p.y, color=color)
+            cnt = sk["count"]
+            for k in range(cnt):
+                ang = k * math.tau / cnt
+                self.projectiles.append(Projectile(
+                    x=p.x, y=p.y, vx=math.cos(ang) * 460, vy=math.sin(ang) * 460,
+                    dmg=sk["damage"], owner=p.pid, hostile=False, radius=8, ttl=1.8,
+                ))
+        elif eff == "heal":
+            self._event("heal", p.x, p.y, color=color)
+            p.hp = min(p.max_hp, p.hp + sk["amount"])
+        elif eff == "shield":
+            self._event("shield", p.x, p.y, color=color)
+            p.shield = min(120.0, p.shield + sk["amount"])
+        elif eff == "summon_ally":
+            self._event("summon", p.x, p.y, color=color)
+            for _ in range(sk["count"]):
+                self._summon_ally(p)
+
+    def _summon_ally(self, p: Player):
+        if len(self.allies) >= 24:
+            return
+        self._ally_seq += 1
+        ang = random.uniform(0, math.tau)
+        self.allies.append(Ally(
+            x=_clamp(p.x + math.cos(ang) * 40, 24, ARENA_W - 24),
+            y=_clamp(p.y + math.sin(ang) * 40, 24, ARENA_H - 24),
+            owner=p.pid, uid=self._ally_seq,
+            hp=30 + p.level * 3, max_hp=30 + p.level * 3,
+            dmg=10 + p.up_damage * 3,
+        ))
+
+    def _tick_minions(self, dt: float):
+        for m in self.minions:
+            m.hurt = max(0.0, m.hurt - dt)
+            m.attack_cd = max(0.0, m.attack_cd - dt)
+            # Ignite: burn damage over time
+            if m.burn_t > 0:
+                m.burn_t -= dt
+                m.hp -= m.burn * dt
+                if m.hp <= 0:
+                    m.alive = False
+                    self._on_minion_killed(m, None)
+                    continue
+            tgt = self._nearest_player(m.x, m.y)
+            if tgt is None:
+                continue
+            # Frost Presence card + Frost Aura: nearby enemies move slower
+            speed = m.speed
+            slow = 0.12 * tgt.up_slow_aura + tgt._aura_max("enemy_slow")
+            if slow and (tgt.x - m.x) ** 2 + (tgt.y - m.y) ** 2 < 150 ** 2:
+                speed *= max(0.25, 1 - slow)
+            ang = math.atan2(tgt.y - m.y, tgt.x - m.x)
+            dist = math.hypot(tgt.x - m.x, tgt.y - m.y)
+            reach = 20 + tgt.hit_radius   # bigger wizards are easier to reach
+            if dist > reach:
+                m.x += math.cos(ang) * speed * dt
+                m.y += math.sin(ang) * speed * dt
+            elif m.attack_cd <= 0:
+                self._damage_player(tgt, m.dmg)
+                # Spiked Aura: reflect damage to the attacker
+                if tgt.up_thorns:
+                    m.hp -= 5 * tgt.up_thorns
+                    m.hurt = 0.15
+                    if m.hp <= 0:
+                        m.alive = False
+                        self._on_minion_killed(m, tgt)
+                m.attack_cd = 1.0
+
+    def _tick_boss(self, dt: float):
+        b = self.boss
+        if b.hp <= 0:
+            return
+        b.hurt = max(0.0, b.hurt - dt)
+        b.shoot_cd = max(0.0, b.shoot_cd - dt)
+        b.spawn_cd = max(0.0, b.spawn_cd - dt)
+        b.charge_cd = max(0.0, b.charge_cd - dt)
+        b.nova_cd = max(0.0, b.nova_cd - dt)
+        phase2 = b.hp <= b.max_hp * 0.5
+        # combined attack cadence: aggro (difficulty) x atk_speed (GM mercy knob)
+        agg = b.aggro * (1.3 if phase2 else 1.0) * _clamp(b.atk_speed, 0.5, 2.0)
+        pat = BOSS_PATTERNS.get(b.pattern, BOSS_PATTERNS["balanced"])
+
+        # ---- charge attack: telegraph, then rush a player and melee hard ----
+        if b.state == "telegraph":
+            b.state_t -= dt
+            if b.state_t <= 0:
+                b.state = "charge"
+                b.state_t = 0.55
+            return  # boss is winding up, no other actions
+        if b.state == "charge":
+            b.state_t -= dt
+            b.x = _clamp(b.x + b.cvx * dt, 40, ARENA_W - 40)
+            b.y = _clamp(b.y + b.cvy * dt, 40, ARENA_H - 40)
+            for p in self.players.values():
+                if p.alive and (p.x - b.x) ** 2 + (p.y - b.y) ** 2 < (54 + p.hit_radius) ** 2:
+                    self._damage_player(p, b.dmg * 2.5)  # massive melee
+            if b.state_t <= 0:
+                b.state = "idle"
+                b.charge_cd = max(2.0, 8.0 / (agg * pat["charge"]))
+            return
+        # drift back toward the centre when idle
+        b.x += (CENTER[0] - b.x) * min(1.0, dt * 0.6)
+        b.y += (CENTER[1] - b.y) * min(1.0, dt * 0.6)
+
+        # decide whether to start a charge (hunts down players who keep distance)
+        if b.charge_cd <= 0:
+            tgt = self._nearest_player(b.x, b.y)
+            if tgt:
+                ang = math.atan2(tgt.y - b.y, tgt.x - b.x)
+                speed = 620 + self.round * 8
+                b.cvx, b.cvy = math.cos(ang) * speed, math.sin(ang) * speed
+                b.state = "telegraph"
+                b.state_t = 0.7
+                return
+
+        # everything below creates boss projectiles; tag them with the boss's
+        # visual style (holy / glitch) at the end.
+        n0 = len(self.projectiles)
+        bstyle = SPECIAL_BOSSES.get(b.special, {}).get("style", "")
+
+        # spawn minions (the SWARMLORD pattern leans hard on this)
+        if b.spawn_cd <= 0 and len(self.minions) < 30:
+            burst = max(1, round((self.cfg["minion_count"] / 3) * pat["spawn"]))
+            for _ in range(burst):
+                self._spawn_minion()
+            b.spawn_cd = b.spawn_interval
+
+        # ---- special boss signature attacks ----
+        if b.special:
+            b.special_cd = max(0.0, b.special_cd - dt)
+            if b.special_cd <= 0:
+                self._boss_signature(b)
+                b.special_cd = max(2.5, 5.0 / agg)
+
+        # ---- ground shockwave: dense ring that punishes standing still ----
+        if b.nova_cd <= 0:
+            heavy = pat.get("slow_heavy")
+            n = 20 if phase2 else 14
+            spd, rad, dmul = (160, 18, 1.3) if heavy else (200, 13, 1.0)
+            for k in range(n):
+                ang = k * math.tau / n
+                self.projectiles.append(Projectile(
+                    x=b.x, y=b.y, vx=math.cos(ang) * spd, vy=math.sin(ang) * spd,
+                    dmg=b.dmg * dmul, owner="boss", hostile=True, ttl=4.5, radius=rad,
+                ))
+            b.nova_cd = max(1.8, 6.0 / (agg * pat["nova"]))
+
+        # ---- aimed spread / radial bursts (style depends on the pattern) ----
+        if b.shoot_cd <= 0:
+            tgt = self._nearest_player(b.x, b.y)
+            if pat.get("snipe") and tgt:
+                # SNIPER: one fast, painful, well-aimed bolt
+                ang = math.atan2(tgt.y - b.y, tgt.x - b.x)
+                self.projectiles.append(Projectile(
+                    x=b.x, y=b.y, vx=math.cos(ang) * 540, vy=math.sin(ang) * 540,
+                    dmg=b.dmg * 1.8, owner="boss", hostile=True, ttl=3.5, radius=9,
+                ))
+                b.shoot_cd = 1.3 / (agg * pat["shoot"])
+            elif pat.get("slow_heavy") and tgt:
+                # ARTILLERY: lob big slow orbs at the target
+                ang = math.atan2(tgt.y - b.y, tgt.x - b.x) + random.uniform(-0.15, 0.15)
+                self.projectiles.append(Projectile(
+                    x=b.x, y=b.y, vx=math.cos(ang) * 170, vy=math.sin(ang) * 170,
+                    dmg=b.dmg * 1.4, owner="boss", hostile=True, ttl=5.5, radius=20,
+                ))
+                b.shoot_cd = 1.6 / (agg * pat["shoot"])
+            elif phase2:
+                for k in range(12):
+                    ang = k * math.tau / 12 + random.uniform(-0.1, 0.1)
+                    self.projectiles.append(Projectile(
+                        x=b.x, y=b.y, vx=math.cos(ang) * 240, vy=math.sin(ang) * 240,
+                        dmg=b.dmg, owner="boss", hostile=True, ttl=4, radius=12,
+                    ))
+                b.shoot_cd = 2.2 / (agg * pat["shoot"])
+            elif tgt:
+                ang = math.atan2(tgt.y - b.y, tgt.x - b.x)
+                for off in (-0.22, -0.11, 0, 0.11, 0.22):
+                    self.projectiles.append(Projectile(
+                        x=b.x, y=b.y,
+                        vx=math.cos(ang + off) * 280, vy=math.sin(ang + off) * 280,
+                        dmg=b.dmg, owner="boss", hostile=True, ttl=4, radius=12,
+                    ))
+                b.shoot_cd = 1.8 / (agg * pat["shoot"])
+
+        # apply the boss's projectile style to everything it just fired
+        if bstyle:
+            for pr in self.projectiles[n0:]:
+                pr.style = bstyle
+
+    def _boss_signature(self, b: Boss):
+        """A unique telegraphed attack per special boss."""
+        if b.special == "aegis":
+            # Holy Cross: a rotating + and x of holy bolts that punish all angles
+            base = random.uniform(0, math.tau)
+            for k in range(8):
+                ang = base + k * math.tau / 8
+                self.projectiles.append(Projectile(
+                    x=b.x, y=b.y, vx=math.cos(ang) * 260, vy=math.sin(ang) * 260,
+                    dmg=b.dmg * 1.2, owner="boss", hostile=True, ttl=4.5, radius=16,
+                ))
+            # plus aimed holy spears at the nearest two players
+            for p in list(self.players.values())[:2]:
+                if p.alive:
+                    ang = math.atan2(p.y - b.y, p.x - b.x)
+                    self.projectiles.append(Projectile(
+                        x=b.x, y=b.y, vx=math.cos(ang) * 360, vy=math.sin(ang) * 360,
+                        dmg=b.dmg * 1.6, owner="boss", hostile=True, ttl=4, radius=18,
+                    ))
+        elif b.special == "toaster":
+            # Glitch Portals: open rifts near players that spit projectiles outward
+            for _ in range(3):
+                tgt = self._nearest_player(b.x, b.y)
+                px = random.uniform(150, ARENA_W - 150)
+                py = random.uniform(120, ARENA_H - 120)
+                if tgt and random.random() < 0.6:
+                    px, py = tgt.x + random.uniform(-80, 80), tgt.y + random.uniform(-80, 80)
+                for k in range(6):
+                    ang = k * math.tau / 6
+                    self.projectiles.append(Projectile(
+                        x=px, y=py, vx=math.cos(ang) * 210, vy=math.sin(ang) * 210,
+                        dmg=b.dmg, owner="boss", hostile=True, ttl=3.5, radius=14,
+                    ))
+
+    def _tick_projectiles(self, dt: float):
+        alive = []
+        for pr in self.projectiles:
+            # Seeker Bolts: steer toward the nearest enemy
+            if pr.homing and not pr.hostile:
+                tgt = self._nearest_enemy(pr.x, pr.y)
+                if tgt is not None:
+                    sp = math.hypot(pr.vx, pr.vy) or 1.0
+                    want = math.atan2(tgt.y - pr.y, tgt.x - pr.x)
+                    cur = math.atan2(pr.vy, pr.vx)
+                    d = (want - cur + math.pi) % math.tau - math.pi
+                    cur += max(-6 * dt, min(6 * dt, d))
+                    pr.vx, pr.vy = math.cos(cur) * sp, math.sin(cur) * sp
+            pr.x += pr.vx * dt
+            pr.y += pr.vy * dt
+            pr.ttl -= dt
+            if pr.ttl <= 0 or pr.x < -40 or pr.x > ARENA_W + 40 or pr.y < -40 or pr.y > ARENA_H + 40:
+                continue
+            hit = False
+            if pr.hostile:
+                for p in self.players.values():
+                    if p.alive and (p.x - pr.x) ** 2 + (p.y - pr.y) ** 2 < (pr.radius + p.hit_radius) ** 2:
+                        self._damage_player(p, pr.dmg)
+                        hit = True
+                        break
+            else:
+                owner = self.players.get(pr.owner)
+                for m in self.minions:
+                    if not m.alive or m.uid in pr.hit_ids:
+                        continue
+                    if (m.x - pr.x) ** 2 + (m.y - pr.y) ** 2 < (pr.radius + 22) ** 2:
+                        m.hp -= pr.dmg
+                        m.hurt = 0.15
+                        pr.hit_ids.add(m.uid)
+                        if owner:
+                            owner.dmg_dealt += pr.dmg
+                        self._apply_hit_effects(pr, m, owner)
+                        if m.hp <= 0:
+                            m.alive = False
+                            self._on_minion_killed(m, owner)
+                        hit = True
+                        break
+                if not hit and self.boss.hp > 0 and \
+                        (self.boss.x - pr.x) ** 2 + (self.boss.y - pr.y) ** 2 < (pr.radius + 70) ** 2:
+                    self.boss.hp -= pr.dmg
+                    self.boss.hurt = 0.1
+                    if owner:
+                        owner.dmg_dealt += pr.dmg
+                        if owner.up_lifesteal:
+                            self._heal(owner, pr.dmg * 0.03 * owner.up_lifesteal)
+                    hit = True
+            # pierce: a player shot can pass through extra enemies before dying
+            if hit and not pr.hostile and pr.pierce > 0:
+                pr.pierce -= 1
+                hit = False
+            if not hit:
+                alive.append(pr)
+        self.projectiles = alive
+
+    def _heal(self, p: Player, amt: float):
+        p.hp = min(p.max_hp, p.hp + amt)
+
+    def _apply_hit_effects(self, pr: Projectile, m: Minion, owner: "Player | None"):
+        """Run on a player shot striking a minion: lifesteal/burn/knock/explode/chain."""
+        if owner:
+            ls = 0.03 * owner.up_lifesteal + owner._aura_max("lifesteal")
+            if ls:
+                self._heal(owner, pr.dmg * ls)
+        if pr.burn:
+            m.burn = max(m.burn, pr.burn)
+            m.burn_t = 3.0
+        if pr.knock:
+            ang = math.atan2(m.y - pr.y, m.x - pr.x)
+            m.x = _clamp(m.x + math.cos(ang) * pr.knock, 20, ARENA_W - 20)
+            m.y = _clamp(m.y + math.sin(ang) * pr.knock, 20, ARENA_H - 20)
+        if pr.explode:
+            r2 = pr.explode ** 2
+            for o in self.minions:
+                if o is m or not o.alive or o.uid in pr.hit_ids:
+                    continue
+                if (o.x - m.x) ** 2 + (o.y - m.y) ** 2 <= r2:
+                    o.hp -= pr.dmg * 0.5
+                    o.hurt = 0.15
+                    if owner:
+                        owner.dmg_dealt += pr.dmg * 0.5
+                    if o.hp <= 0:
+                        o.alive = False
+                        self._on_minion_killed(o, owner)
+        if pr.chain:
+            hit_extra = 0
+            for o in sorted(self.minions, key=lambda q: (q.x - m.x) ** 2 + (q.y - m.y) ** 2):
+                if hit_extra >= pr.chain:
+                    break
+                if o is m or not o.alive or o.uid in pr.hit_ids:
+                    continue
+                if (o.x - m.x) ** 2 + (o.y - m.y) ** 2 <= 170 ** 2:
+                    o.hp -= pr.dmg * 0.5
+                    o.hurt = 0.15
+                    pr.hit_ids.add(o.uid)
+                    hit_extra += 1
+                    if owner:
+                        owner.dmg_dealt += pr.dmg * 0.5
+                    if o.hp <= 0:
+                        o.alive = False
+                        self._on_minion_killed(o, owner)
+
+    def _on_minion_killed(self, m: Minion, owner: "Player | None"):
+        fortune = owner.up_fortune if owner else 0
+        if owner:
+            owner.kills += 1
+            for sk in owner.skills:
+                if sk["trigger"] == "on_kill":
+                    self._fire_skill(owner, sk)
+        self.gems.append(self._make_gem(m.x, m.y, m.kind, fortune))
+        # ~1/100 chance a minion drops a power-up card (Lucky Charm raises it)
+        if random.random() < 0.01 * (1 + 0.5 * fortune):
+            self._drop_pickup(m.x, m.y)
+        # rarer: a timed aura drops on the floor (~1/200, Lucky Charm raises it)
+        if random.random() < 0.005 * (1 + 0.5 * fortune):
+            self._drop_aura(m.x, m.y)
+
+    def _drop_pickup(self, x: float, y: float):
+        pool = [c for c in ALL_CARD_IDS
+                if c not in THEME_ONLY and c not in SKILL_CARDS and c != "auto_attack"]
+        if not pool:
+            return
+        self._pickup_seq += 1
+        self.pickups.append(Pickup(x=x, y=y, card=random.choice(pool), uid=self._pickup_seq))
+
+    def _drop_aura(self, x: float, y: float):
+        self._pickup_seq += 1
+        self.pickups.append(Pickup(x=x, y=y, card=random.choice(ALL_AURA_IDS),
+                                   kind="aura", uid=self._pickup_seq, ttl=18.0))
+
+    def _make_gem(self, x: float, y: float, kind: str, fortune: int = 0) -> Gem:
+        """Pick a gem tier (1..7) by enemy type + wave, with a little variance."""
+        base = {"grunt": 1, "fast": 2, "tank": 4}.get(kind, 1)
+        tier = base + (1 if random.random() < 0.3 else 0) + self.round // 6 + fortune
+        tier = int(_clamp(tier, 1, 7))
+        return Gem(x=x, y=y, tier=tier, value=GEM_TIER_XP[tier])
+
+    def _damage_player(self, p: Player, dmg: float):
+        if not p.alive or p.hurt > 0:
+            return
+        # Evasion: chance to avoid the hit entirely
+        if p.up_dodge and random.random() < min(0.5, 0.05 * p.up_dodge):
+            p.hurt = 0.2
+            return
+        # Iron Hide: flat damage reduction
+        if p.up_armor:
+            dmg = max(1.0, dmg - 2 * p.up_armor)
+        # Warding aura: percent damage reduction
+        red = p._aura_max("dmg_red")
+        if red:
+            dmg *= (1 - red)
+        # Aegis: shield absorbs first
+        if p.shield > 0:
+            absorbed = min(p.shield, dmg)
+            p.shield -= absorbed
+            dmg -= absorbed
+        p.hp -= dmg
+        p.hurt = 0.4
+        if p.hp <= 0:
+            p.hp = 0
+            p.alive = False
+            p.lives -= 1            # spend a life; >0 respawns, 0 = eliminated
+            if p.lives > 0:
+                p.respawn_t = 3.0
+                p.auras = []        # auras fade on death
+
+    # ---- snapshot ---------------------------------------------------------
+    def snapshot(self) -> dict:
+        events, self._events = self._events, []
+        return {
+            "events": events,
+            "t": round(time.time(), 2),
+            "round": self.round,
+            "status": self.status,
+            "status_msg": self.status_msg,
+            "gm_message": self.gm_message,
+            "intermission_left": max(0, round(self.intermission_until - time.time(), 1))
+            if self.status == "intermission" else 0,
+            "boss": self.boss.to_dict() if self.boss.hp > 0 or self.status != "lobby" else None,
+            "theme": max(0, (self.round - 1) // 5),  # enemy skin set, swaps every 5 waves
+            "hue": SPECIAL_BOSSES[self.boss.special]["hue"]
+            if self.boss.special and self.boss.hp > 0 else None,
+            "players": [p.to_dict() for p in self.players.values()],
+            "minions": [m.to_dict() for m in self.minions],
+            "allies": [a.to_dict() for a in self.allies],
+            "projectiles": [pr.to_dict() for pr in self.projectiles],
+            "gems": [g.to_dict() for g in self.gems],
+            "pickups": [pk.to_dict() for pk in self.pickups],
+            "arena": {"w": ARENA_W, "h": ARENA_H},
+            "max_players": MAX_PLAYERS,
+            "upgrades": {k: {"label": v[0], "cost": v[1]} for k, v in UPGRADES.items()},
+            "cards": {k: {"label": v[0], "desc": v[1], "rarity": v[2]}
+                      for k, v in CARDS.items()},
+            "card_pool": list(self.card_pool),
+            "skill_request": (
+                {"pid": self.skill_request_pid, "used": self.skill_request_used}
+                if self.status == "intermission" else None
+            ),
+        }

HuggingWizards-upload/game/gamemaster.py

@@ -0,0 +1,480 @@
+"""Nemotron-4B Game Master.
+
+At each round boundary the engine hands us a `round_summary`. We ask
+NVIDIA's Nemotron-Mini-4B-Instruct to return a JSON decision covering:
+
+  - rewards:    {player_id: gold}
+  - next_round: {boss_hp, boss_damage, minion_hp, minion_count, spawn_interval}
+  - message:    short flavor line shown to players
+  - reasoning:  why (kept in the trace)
+
+This is *burst* GPU work that fits ZeroGPU's `@spaces.GPU` model perfectly: we
+grab the GPU for one short inference per round, then release it. If the model
+or GPU is unavailable (e.g. local dev / CI) we fall back to deterministic logic
+so the game always keeps running.
+
+Every decision is written to `traces/` as a self-contained agent trace.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+import uuid
+
+from game.engine import ALL_CARD_IDS, ALL_PATTERN_IDS, BLESSINGS, MINION_TYPES
+from game import skills as skillmod
+
+MODEL_ID = "nvidia/Nemotron-Mini-4B-Instruct"
+TRACE_DIR = os.path.join(os.path.dirname(os.path.dirname(__file__)), "traces")
+os.makedirs(TRACE_DIR, exist_ok=True)
+
+# Lazily-initialised globals (loaded once, on first GPU call).
+_tokenizer = None
+_model = None
+_load_failed = False
+
+# In-memory ring of recent traces for the dashboard.
+RECENT_TRACES: list[dict] = []
+_MAX_RECENT = 25
+
+# True when running inside a Hugging Face Space (ZeroGPU or otherwise).
+_ON_SPACES = bool(os.environ.get("SPACE_ID"))
+
+try:  # `spaces` only exists on HF infra; degrade gracefully elsewhere.
+    import spaces  # type: ignore
+
+    def _gpu(fn):
+        return spaces.GPU(duration=60)(fn)
+except Exception:  # pragma: no cover - local dev path
+    def _gpu(fn):
+        return fn
+
+
+SYSTEM_PROMPT = (
+    "You are the Game Master / Director AI for HuggingWizards, a co-op pixel "
+    "survivors-arena where wizards fight waves of enemies and a boss. After each "
+    "wave you direct: rewards, the next wave's difficulty, the enemy mix, and the "
+    "pool of level-up cards players may be offered. Reply with ONE JSON object and "
+    "nothing else. Schema:\n"
+    '{"message": str (<=120 chars, in-character narration),'
+    ' "reasoning": str (one sentence),'
+    ' "rewards": {player_id: int gold 0-300},'
+    ' "blessings": {player_id: blessing_id} (optional, bless 0-3 wizards),'
+    ' "next_round": {"boss_hp": int, "boss_damage": int, "minion_hp": int,'
+    ' "minion_count": int, "spawn_interval": float, "boss_aggro": float 0.7-3,'
+    ' "boss_attack_speed": float 0.5-2.0, "boss_pattern": pattern_id,'
+    ' "wave": {"grunt": float, "fast": float, "tank": float}},'
+    ' "card_pool": [card_id, ...]}\n'
+    f"Enemy archetypes (wave weights, must sum > 0): {list(MINION_TYPES)}.\n"
+    f"Boss attack patterns: {ALL_PATTERN_IDS}. Switch the pattern between rounds "
+    "to keep fights fresh — sniper punishes kiting, artillery punishes camping, "
+    "swarm floods the arena, berserker charges relentlessly.\n"
+    f"Blessings: {BLESSINGS}. Bless wizards who earned it — surviving a brutal "
+    "wave, clutch plays, or to help a struggling wizard back on their feet "
+    "(extra_life / full_heal). Auras last one wave.\n"
+    f"Valid card_pool ids (offer 4-8): {ALL_CARD_IDS}.\n"
+    "boss_attack_speed sets how fast the boss attacks next wave (1.0 = normal). "
+    "Check every player's hp_pct and lives_left: if the party is badly hurt, "
+    "slow the boss (<1.0) so they can recover; if they are healthy, speed it up "
+    "(>1.0). MERCY DECAYS: each round the user prompt states the minimum you may "
+    "set — in later waves you can no longer slow the boss to protect them. "
+    "Values outside the allowed range are clamped.\n"
+    "Reward players for damage dealt, kills, and surviving. Scale difficulty up "
+    "after a victory and ease it slightly after a defeat. Introduce tougher enemy "
+    "archetypes as rounds progress. Curate cards to keep the run fun and winnable "
+    "for the number of players."
+)
+
+
+def _build_user_prompt(summary: dict, prev_cfg: dict) -> str:
+    rnd = summary.get("round") or 0
+    return (
+        "Current next-round config (you may adjust): "
+        + json.dumps(prev_cfg)
+        + "\nRound that just ended:\n"
+        + json.dumps(summary, indent=2)
+        + f"\nMercy floor this round: boss_attack_speed must be between "
+        + f"{_mercy_floor(rnd)} and {MERCY_MAX}."
+        + "\nReturn the JSON decision now."
+    )
+
+
+def _load_model():
+    """Load tokenizer + model, optionally quantized.
+
+    HUGGINGWIZARDS_QUANT = none | 4bit | 8bit | auto (default).
+    `auto` picks 4-bit on small local GPUs (<12 GB VRAM) and bf16 everywhere
+    else — ZeroGPU's H200 runs the 4B model comfortably in bf16, where it is
+    also faster per token than bitsandbytes 4-bit.
+    """
+    import torch
+    from transformers import AutoModelForCausalLM, AutoTokenizer
+
+    tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)
+    has_cuda = torch.cuda.is_available()
+    quant = os.environ.get("HUGGINGWIZARDS_QUANT", "auto").lower()
+    if quant == "auto":
+        if has_cuda and not _ON_SPACES:
+            vram = torch.cuda.get_device_properties(0).total_memory
+            quant = "4bit" if vram < 12 * 1024**3 else "none"
+        else:
+            quant = "none"
+
+    if quant in ("4bit", "8bit") and has_cuda:
+        from transformers import BitsAndBytesConfig
+
+        qcfg = (
+            BitsAndBytesConfig(load_in_4bit=True, bnb_4bit_quant_type="nf4",
+                               bnb_4bit_compute_dtype=torch.bfloat16)
+            if quant == "4bit"
+            else BitsAndBytesConfig(load_in_8bit=True)
+        )
+        model = AutoModelForCausalLM.from_pretrained(
+            MODEL_ID, quantization_config=qcfg, device_map={"": 0}
+        )
+    else:
+        model = AutoModelForCausalLM.from_pretrained(
+            MODEL_ID, dtype=torch.bfloat16 if has_cuda else torch.float32
+        )
+        if has_cuda:
+            model = model.to("cuda")  # ZeroGPU-safe (device_map="auto" is not)
+    model.eval()
+    print(f"[gamemaster] loaded {MODEL_ID} (quant={quant}, cuda={has_cuda})")
+    return tokenizer, model
+
+
+def _ensure_model():
+    global _tokenizer, _model, _load_failed
+    if _model is not None or _load_failed:
+        return _model is not None
+    if os.environ.get("HUGGINGWIZARDS_NO_LLM"):
+        _load_failed = True  # force deterministic fallback (local dev / CI)
+        return False
+    try:
+        _tokenizer, _model = _load_model()
+        return True
+    except Exception as e:  # pragma: no cover
+        print(f"[gamemaster] model load failed, using fallback: {e}")
+        _load_failed = True
+        return False
+
+
+# On Spaces, load the model at startup (ZeroGPU replays the .to("cuda") once a
+# real GPU is attached) so the @spaces.GPU window is spent on inference only —
+# lazy-loading inside the first GPU call would blow the 60 s duration on the
+# weight download. Locally we stay lazy so dev/CI never downloads weights.
+if _ON_SPACES and not os.environ.get("HUGGINGWIZARDS_NO_LLM"):
+    _ensure_model()
+
+
+# ---- mercy guardrail -------------------------------------------------------
+# The GM may slow the boss's attack speed to help wounded parties, but its
+# willingness to help decays as waves progress: the allowed floor rises from
+# 0.5 toward 1.0 (no mercy) by ~wave 13. The ceiling is always 2.0.
+MERCY_MAX = 2.0
+
+
+def _mercy_floor(rnd: int) -> float:
+    return round(min(1.0, 0.5 + 0.04 * max(0, int(rnd or 0))), 2)
+
+
+def _clamp_attack_speed(value, rnd: int) -> float:
+    try:
+        v = float(value)
+    except Exception:
+        v = 1.0
+    return round(max(_mercy_floor(rnd), min(MERCY_MAX, v)), 2)
+
+
+@_gpu
+def _run_model(system: str, user: str) -> str:
+    """Single short generation on the GPU. Returns raw text."""
+    if not _ensure_model():
+        raise RuntimeError("model unavailable")
+    import torch
+
+    messages = [{"role": "system", "content": system},
+                {"role": "user", "content": user}]
+    inputs = _tokenizer.apply_chat_template(
+        messages, add_generation_prompt=True, return_tensors="pt"
+    ).to(_model.device)
+    with torch.no_grad():
+        out = _model.generate(
+            inputs, max_new_tokens=400, do_sample=True, temperature=0.7, top_p=0.9,
+            pad_token_id=_tokenizer.eos_token_id,
+        )
+    text = _tokenizer.decode(out[0][inputs.shape[1]:], skip_special_tokens=True)
+    return text
+
+
+def _extract_json(text: str) -> dict | None:
+    m = re.search(r"\{.*\}", text, re.DOTALL)
+    if not m:
+        return None
+    try:
+        return json.loads(m.group(0))
+    except Exception:
+        return None
+
+
+def _deterministic(summary: dict, prev_cfg: dict) -> dict:
+    """Fallback Game Master logic — also a sane validation target."""
+    won = summary.get("result") == "victory"
+    rewards = {}
+    for p in summary.get("players", []):
+        gold = 20 + int(p.get("damage_dealt", 0) / 25) + p.get("kills", 0) * 5
+        if p.get("survived"):
+            gold += 25
+        rewards[p["id"]] = min(300, gold)
+    cfg = dict(prev_cfg)
+    n_players = max(1, len(summary.get("players", [])))
+    rnd = int(summary.get("round") or 1)
+    if won:
+        cfg["boss_hp"] = int(prev_cfg["boss_hp"] * 1.35) + 200 * n_players
+        cfg["boss_damage"] = min(80, prev_cfg["boss_damage"] + 2)
+        cfg["minion_count"] = min(40, prev_cfg["minion_count"] + 2)
+        cfg["minion_hp"] = int(prev_cfg["minion_hp"] * 1.15)
+        cfg["spawn_interval"] = max(1.5, prev_cfg["spawn_interval"] - 0.3)
+        cfg["boss_aggro"] = min(3.0, round(prev_cfg.get("boss_aggro", 1.0) + 0.2, 2))
+        msg = "Impressive. The next horde will not fall so easily."
+    else:
+        cfg["boss_hp"] = max(300, int(prev_cfg["boss_hp"] * 0.85))
+        cfg["boss_damage"] = max(4, prev_cfg["boss_damage"] - 1)
+        cfg["minion_count"] = max(0, prev_cfg["minion_count"] - 1)
+        cfg["spawn_interval"] = min(8.0, prev_cfg["spawn_interval"] + 0.5)
+        cfg["boss_aggro"] = max(0.7, round(prev_cfg.get("boss_aggro", 1.0) - 0.1, 2))
+        msg = "Rest, wizards. The arena bends slightly in your favor."
+    # Enemy mix escalates with the round: grunts always, fast from r2, tanks r4+.
+    cfg["wave"] = {
+        "grunt": 1.0,
+        "fast": round(min(0.8, max(0.0, (rnd - 1) * 0.25)), 2),
+        "tank": round(min(0.6, max(0.0, (rnd - 3) * 0.2)), 2),
+    }
+    # Rotate the boss's attack pattern so consecutive waves feel different.
+    cfg["boss_pattern"] = ALL_PATTERN_IDS[rnd % len(ALL_PATTERN_IDS)]
+    # Health-responsive attack speed: slow the boss for a wounded party, speed
+    # it up for a healthy one — always within the wave's mercy floor.
+    hps = [p.get("hp_pct", 100) for p in summary.get("players", []) if p.get("survived")]
+    avg_hp = sum(hps) / len(hps) if hps else 0
+    desired = 0.7 if avg_hp < 35 else 0.85 if avg_hp < 60 else (1.2 if won else 1.0)
+    cfg["boss_attack_speed"] = _clamp_attack_speed(desired, rnd)
+    # Blessings: after a defeat, shield the survivors; after a hard-won victory
+    # (someone died), give the most wounded survivor a warding aura.
+    blessings = {}
+    survivors = [p for p in summary.get("players", []) if p.get("survived")]
+    if not won:
+        for p in survivors[:3]:
+            blessings[p["id"]] = "warding"
+    elif survivors and any(not p.get("survived") for p in summary.get("players", [])):
+        weakest = min(survivors, key=lambda p: p.get("hp_pct", 100))
+        blessings[weakest["id"]] = "full_heal"
+    # Offer the full card set by default (the model may narrow it).
+    card_pool = list(ALL_CARD_IDS)
+    return {"message": msg, "reasoning": "deterministic fallback policy",
+            "rewards": rewards, "blessings": blessings,
+            "next_round": cfg, "card_pool": card_pool}
+
+
+def _validate(decision: dict, summary: dict, prev_cfg: dict) -> dict:
+    """Coerce a (possibly model-authored) decision into a safe shape."""
+    safe = _deterministic(summary, prev_cfg)  # defaults
+    if not isinstance(decision, dict):
+        return safe
+    valid_ids = {p["id"] for p in summary.get("players", [])}
+    if isinstance(decision.get("rewards"), dict):
+        rewards = {}
+        for k, v in decision["rewards"].items():
+            if k in valid_ids:
+                try:
+                    rewards[k] = max(0, min(300, int(v)))
+                except Exception:
+                    pass
+        if rewards:
+            safe["rewards"] = rewards
+    nxt = decision.get("next_round")
+    if isinstance(nxt, dict):
+        merged = dict(safe["next_round"])
+        for key in ("boss_hp", "boss_damage", "minion_hp", "minion_count"):
+            if key in nxt:
+                try:
+                    merged[key] = int(nxt[key])
+                except Exception:
+                    pass
+        for key in ("spawn_interval", "boss_aggro"):
+            if key in nxt:
+                try:
+                    merged[key] = float(nxt[key])
+                except Exception:
+                    pass
+        # mercy guardrail: attack speed is clamped into the wave's allowed band
+        if "boss_attack_speed" in nxt:
+            merged["boss_attack_speed"] = _clamp_attack_speed(
+                nxt.get("boss_attack_speed"), summary.get("round") or 0)
+        # boss attack pattern (also accepted at the top level)
+        pattern = nxt.get("boss_pattern", decision.get("boss_pattern"))
+        if pattern in ALL_PATTERN_IDS:
+            merged["boss_pattern"] = pattern
+        # enemy mix
+        wave = nxt.get("wave")
+        if isinstance(wave, dict):
+            clean = {}
+            for k in MINION_TYPES:
+                try:
+                    clean[k] = max(0.0, float(wave.get(k, 0.0)))
+                except Exception:
+                    clean[k] = 0.0
+            if sum(clean.values()) > 0:
+                merged["wave"] = clean
+        safe["next_round"] = merged
+    # per-player blessings (cap at 3, roster + id checked)
+    if isinstance(decision.get("blessings"), dict):
+        blessings = {k: v for k, v in decision["blessings"].items()
+                     if k in valid_ids and v in BLESSINGS}
+        safe["blessings"] = dict(list(blessings.items())[:3])
+    # level-up card pool
+    pool = decision.get("card_pool")
+    if isinstance(pool, list):
+        valid = [c for c in pool if c in ALL_CARD_IDS]
+        if valid:
+            safe["card_pool"] = valid
+    if isinstance(decision.get("message"), str):
+        safe["message"] = decision["message"][:120]
+    if isinstance(decision.get("reasoning"), str):
+        safe["reasoning"] = decision["reasoning"][:300]
+    return safe
+
+
+def decide(summary: dict, prev_cfg: dict) -> dict:
+    """Produce a validated decision and persist an agent trace for the round."""
+    trace_id = uuid.uuid4().hex[:8]
+    system, user = SYSTEM_PROMPT, _build_user_prompt(summary, prev_cfg)
+    raw, source, error = "", "fallback", None
+    requested_speed = None
+    t0 = time.time()
+    try:
+        raw = _run_model(system, user)
+        parsed = _extract_json(raw)
+        if isinstance(parsed, dict) and isinstance(parsed.get("next_round"), dict):
+            requested_speed = parsed["next_round"].get("boss_attack_speed")
+        decision = _validate(parsed, summary, prev_cfg) if parsed else _deterministic(summary, prev_cfg)
+        source = "nemotron" if parsed else "fallback(parse_failed)"
+    except Exception as e:
+        error = str(e)
+        decision = _deterministic(summary, prev_cfg)
+    latency = round(time.time() - t0, 2)
+
+    rnd = summary.get("round") or 0
+    applied_speed = decision.get("next_round", {}).get("boss_attack_speed")
+    mercy = {
+        "floor": _mercy_floor(rnd), "max": MERCY_MAX,
+        "requested": requested_speed, "applied": applied_speed,
+        "clamped": requested_speed is not None and requested_speed != applied_speed,
+        "note": "mercy floor rises with the wave — by ~wave 13 the GM can no "
+                "longer slow the boss to protect the party",
+    }
+
+    trace = {
+        "trace_id": trace_id,
+        "round": summary.get("round"),
+        "mercy": mercy,
+        "ts": time.strftime("%Y-%m-%d %H:%M:%S"),
+        "model": MODEL_ID,
+        "source": source,
+        "latency_sec": latency,
+        "error": error,
+        "input": {"system": system, "user": user, "round_summary": summary},
+        "raw_output": raw,
+        "decision": decision,
+    }
+    _persist(trace)
+    return decision
+
+
+SKILL_SYSTEM_PROMPT = (
+    "You are the Game Master AI for HuggingWizards. A wizard asks you to grant a "
+    "new power-up. Invent ONE balanced skill and reply with ONE JSON object only. "
+    "Schema (data only — never code):\n"
+    '{"name": str, "trigger": one of '
+    + str(sorted(skillmod.TRIGGERS))
+    + ', "n": int (for every_n_attacks), "interval": float (for periodic),'
+    ' "effect": one of '
+    + str(sorted(skillmod.EFFECTS))
+    + ', "radius": float, "damage": float, "count": int, "amount": float,'
+    ' "slow": float 0-1, "color": "#rrggbb"}\n'
+    "Pick fields that match the chosen effect. Keep it fun but not overpowered."
+)
+
+
+def _deterministic_skill(prompt: str) -> dict:
+    """Keyword-based fallback skill generator (local dev / model unavailable)."""
+    t = (prompt or "").lower()
+    frost = any(w in t for w in ("frost", "ice", "freeze", "slow", "cold"))
+    if any(w in t for w in ("summon", "spirit", "minion", "ally", "pet", "wolf")):
+        spec = {"name": "Summoned Spirit", "trigger": "every_n_attacks", "n": 7,
+                "effect": "summon_ally", "count": 1, "color": "#a6ff8c"}
+    elif any(w in t for w in ("heal", "regen", "life", "restore", "vamp", "mend")):
+        spec = {"name": "Mending Light", "trigger": "periodic", "interval": 6,
+                "effect": "heal", "amount": 30, "color": "#6effd0"}
+    elif any(w in t for w in ("shield", "barrier", "ward", "protect", "absorb", "armor")):
+        spec = {"name": "Arcane Bulwark", "trigger": "periodic", "interval": 8,
+                "effect": "shield", "amount": 30, "color": "#9db4c9"}
+    elif frost or any(w in t for w in ("explos", "blast", "aoe", "area", "detonat", "fire")):
+        spec = {"name": "Frost Nova" if frost else "Arcane Detonation",
+                "trigger": "every_n_attacks", "n": 6, "effect": "aoe_damage",
+                "radius": 140, "damage": 45, "slow": 0.4 if frost else 0.0,
+                "color": "#7ee0ff" if frost else "#ff7a4a"}
+    elif any(w in t for w in ("nova", "spread", "shotgun", "burst", "ring", "radial")):
+        spec = {"name": "Star Burst", "trigger": "every_n_attacks", "n": 5,
+                "effect": "projectile_nova", "count": 10, "damage": 24, "color": "#ffd45e"}
+    else:  # default: an AoE explosion
+        spec = {"name": "Arcane Detonation", "trigger": "every_n_attacks", "n": 6,
+                "effect": "aoe_damage", "radius": 140, "damage": 45, "slow": 0.0,
+                "color": "#ff7a4a"}
+    return spec
+
+
+def generate_skill(prompt: str, context: dict | None = None) -> dict:
+    """Turn a player's free-text wish into a validated, safe skill spec.
+
+    Tries Nemotron; always falls back to deterministic keywords; the result is
+    run through skills.validate_skill so it is bounded and code-free.
+    """
+    trace_id = uuid.uuid4().hex[:8]
+    user = f"Wizard's request: {prompt!r}\nContext: {json.dumps(context or {})}\nReturn the skill JSON."
+    raw, source, error = "", "fallback", None
+    t0 = time.time()
+    spec = None
+    try:
+        raw = _run_model(SKILL_SYSTEM_PROMPT, user)
+        parsed = _extract_json(raw)
+        spec = skillmod.validate_skill(parsed) if parsed else None
+        source = "nemotron" if spec else "fallback(parse_failed)"
+    except Exception as e:
+        error = str(e)
+    if spec is None:
+        spec = skillmod.validate_skill(_deterministic_skill(prompt))
+    latency = round(time.time() - t0, 2)
+    _persist({
+        "trace_id": trace_id, "round": (context or {}).get("round"),
+        "ts": time.strftime("%Y-%m-%d %H:%M:%S"), "model": MODEL_ID,
+        "source": source, "latency_sec": latency, "error": error,
+        "kind": "skill_request",
+        "input": {"system": SKILL_SYSTEM_PROMPT, "user": user, "prompt": prompt},
+        "raw_output": raw, "decision": spec,
+    })
+    return spec
+
+
+def _persist(trace: dict):
+    RECENT_TRACES.insert(0, trace)
+    del RECENT_TRACES[_MAX_RECENT:]
+    try:
+        rnd = trace.get("round")
+        prefix = f"round_{rnd:03d}" if isinstance(rnd, int) else "skill"
+        path = os.path.join(TRACE_DIR, f"{prefix}_{trace['trace_id']}.json")
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(trace, f, indent=2)
+    except Exception as e:  # pragma: no cover
+        print(f"[gamemaster] failed to write trace: {e}")

HuggingWizards-upload/game/skills.py

@@ -0,0 +1,123 @@
+"""Sandboxed, data-only skill specs for HuggingWizards.
+
+A "skill" is a plain JSON object describing *what* happens and *when* — never
+executable code. The engine interprets a whitelisted set of triggers/effects,
+so a skill authored by the Game Master (Nemotron) at runtime can hot-plug onto
+a player without any `exec`/`eval` or arbitrary code execution.
+
+Schema (all fields optional except trigger/effect; everything is clamped):
+{
+  "name":     str,                      # display name
+  "trigger":  every_n_attacks|periodic|on_kill,
+  "n":        int,                      # for every_n_attacks
+  "interval": float,                    # seconds, for periodic
+  "effect":   aoe_damage|projectile_nova|heal|summon_ally|shield,
+  "radius":   float,                    # aoe reach
+  "damage":   float,
+  "count":    int,                      # nova projectiles / allies summoned
+  "amount":   float,                    # heal / shield amount
+  "slow":     float,                    # 0..1 slow applied by aoe
+  "color":    str,                      # client tint (#rrggbb)
+}
+"""
+from __future__ import annotations
+
+TRIGGERS = {"every_n_attacks", "periodic", "on_kill"}
+EFFECTS = {"aoe_damage", "projectile_nova", "heal", "summon_ally", "shield"}
+
+# Per-field (lo, hi) clamps. Keeps any model output inside sane, balanced bounds.
+_BOUNDS = {
+    "n": (2, 20),
+    "interval": (1.0, 15.0),
+    "radius": (40.0, 260.0),
+    "damage": (0.0, 120.0),
+    "count": (1, 12),
+    "amount": (0.0, 80.0),
+    "slow": (0.0, 0.8),
+}
+_DEFAULTS = {
+    "every_n_attacks": {"n": 5},
+    "periodic": {"interval": 5.0},
+    "aoe_damage": {"radius": 120.0, "damage": 35.0, "slow": 0.0},
+    "projectile_nova": {"count": 8, "damage": 22.0},
+    "heal": {"amount": 25.0},
+    "shield": {"amount": 25.0},
+    "summon_ally": {"count": 1},
+}
+_HEX = set("0123456789abcdefABCDEF")
+MAX_SKILLS_PER_PLAYER = 6
+
+
+def _num(v, lo, hi, integer=False):
+    try:
+        v = float(v)
+    except Exception:
+        v = lo
+    v = lo if v < lo else hi if v > hi else v
+    return int(round(v)) if integer else round(v, 2)
+
+
+def _color(v):
+    if isinstance(v, str) and v.startswith("#") and len(v) == 7 and all(c in _HEX for c in v[1:]):
+        return v
+    return "#b48cff"
+
+
+def validate_skill(spec: dict) -> dict | None:
+    """Coerce an arbitrary dict into a safe, bounded skill — or None if unusable."""
+    if not isinstance(spec, dict):
+        return None
+    trigger = spec.get("trigger")
+    effect = spec.get("effect")
+    if trigger not in TRIGGERS or effect not in EFFECTS:
+        return None
+    out = {
+        "name": str(spec.get("name", "Arcane Skill"))[:32] or "Arcane Skill",
+        "trigger": trigger,
+        "effect": effect,
+        "color": _color(spec.get("color")),
+    }
+    src = {**_DEFAULTS.get(trigger, {}), **_DEFAULTS.get(effect, {}), **spec}
+    if trigger == "every_n_attacks":
+        out["n"] = _num(src.get("n"), *_BOUNDS["n"], integer=True)
+    elif trigger == "periodic":
+        out["interval"] = _num(src.get("interval"), *_BOUNDS["interval"])
+    if effect == "aoe_damage":
+        out["radius"] = _num(src.get("radius"), *_BOUNDS["radius"])
+        out["damage"] = _num(src.get("damage"), *_BOUNDS["damage"])
+        out["slow"] = _num(src.get("slow"), *_BOUNDS["slow"])
+    elif effect == "projectile_nova":
+        out["count"] = _num(src.get("count"), *_BOUNDS["count"], integer=True)
+        out["damage"] = _num(src.get("damage"), *_BOUNDS["damage"])
+    elif effect in ("heal", "shield"):
+        out["amount"] = _num(src.get("amount"), *_BOUNDS["amount"])
+    elif effect == "summon_ally":
+        out["count"] = _num(src.get("count"), *_BOUNDS["count"], integer=True)
+    return out
+
+
+# Predefined skills granted by the AoE / Summoner level-up cards.
+CARD_SKILLS = {
+    "aoe": {"name": "Arcane Nova", "trigger": "every_n_attacks", "n": 6,
+            "effect": "aoe_damage", "radius": 130, "damage": 40, "color": "#7ee0ff"},
+    "summoner": {"name": "Spirit Caller", "trigger": "every_n_attacks", "n": 8,
+                 "effect": "summon_ally", "count": 1, "color": "#a6ff8c"},
+    # ---- boss-exclusive skills (only offered while that boss reigns) ----
+    "war_drums": {"name": "War Drums", "trigger": "periodic", "interval": 7,
+                  "effect": "summon_ally", "count": 2, "color": "#ff9d6e"},
+    "savage_roar": {"name": "Savage Roar", "trigger": "on_kill",
+                    "effect": "aoe_damage", "radius": 110, "damage": 30, "color": "#ff6e6e"},
+    "iron_nova": {"name": "Iron Detonation", "trigger": "every_n_attacks", "n": 5,
+                  "effect": "aoe_damage", "radius": 160, "damage": 55, "slow": 0.3, "color": "#c9d4e0"},
+    "bulwark": {"name": "Bulwark", "trigger": "periodic", "interval": 5,
+                "effect": "heal", "amount": 35, "color": "#9db4c9"},
+    "impaling_charge": {"name": "Impaling Charge", "trigger": "every_n_attacks", "n": 4,
+                        "effect": "projectile_nova", "count": 6, "damage": 38, "color": "#ffd45e"},
+    "arrow_storm": {"name": "Arrow Storm", "trigger": "periodic", "interval": 4,
+                    "effect": "projectile_nova", "count": 12, "damage": 20, "color": "#a6ff8c"},
+    # ---- rewards for defeating the special bosses (their own attack powers) ----
+    "holy_judgment": {"name": "Holy Judgment", "trigger": "periodic", "interval": 4,
+                      "effect": "aoe_damage", "radius": 180, "damage": 70, "color": "#ffe9a0"},
+    "glitch_rift": {"name": "Glitch Rift", "trigger": "periodic", "interval": 3.5,
+                    "effect": "projectile_nova", "count": 14, "damage": 30, "color": "#7CFC00"},
+}

HuggingWizards-upload/requirements.txt

@@ -0,0 +1,9 @@
+gradio>=5.0.0
+fastapi
+uvicorn[standard]
+transformers>=4.56.0
+torch
+accelerate
+sentencepiece
+bitsandbytes>=0.43.2
+spaces