README.md

metadata

title: HuggingWizards 🍄 Thousand Token Wood Entry:#3 (Nvidia Based Entry)
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

🧙 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

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.