| --- |
| title: HuggingWizards |
| emoji: 🧙 |
| colorFrom: purple |
| colorTo: indigo |
| sdk: gradio |
| sdk_version: 5.9.1 |
| app_file: app.py |
| pinned: false |
| short_description: Nemotron-4B is the Game Master |
| tags: |
| - track:wood |
| - sponsor:nvidia |
| - achievement:offgrid |
| - achievement:sharing |
| --- |
| Social Media Post and Demo Video: https://www.linkedin.com/posts/dean-byrne-02a28b191_huggingwizards-for-hugging-face-hackathon-activity-7472041413648502785-K2rP?utm_source=share&utm_medium=member_desktop&rcm=ACoAAC0RumIBxlIKTkKv5tF-hb2OU7TdZ19kxcQ |
| # 🧙 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. |
|
|
