Spaces:
Sleeping
Sleeping
Codex commited on
Commit ·
fe0b867
1
Parent(s): a8afc36
Update public README
Browse files
README.md
CHANGED
|
@@ -1,210 +1,138 @@
|
|
| 1 |
-
# Tabras
|
| 2 |
-
|
| 3 |
-
An AI-driven roguelite deckbuilder duel. The player and an AI-controlled enemy wizard each draft a 15-card deck from freshly-generated cards, then duel over three rounds. Every drafted card's effect-shape, name, flavor, and art is generated per run — no two runs share a deck. After a run, the cards are gone for good.
|
| 4 |
-
|
| 5 |
-
Built for the **Build Small Hackathon** (Gradio + Hugging Face), track: *An Adventure in Thousand Token Wood*. Constraint: every model ≤32B params, local-first, deployed as a Gradio app on a HF Space.
|
| 6 |
-
|
| 7 |
---
|
| 8 |
-
|
| 9 |
-
|
| 10 |
-
|
| 11 |
-
|
| 12 |
-
|
| 13 |
-
|
| 14 |
-
|
| 15 |
-
|
| 16 |
-
|
| 17 |
-
|
| 18 |
-
|
| 19 |
-
|
| 20 |
-
|
| 21 |
-
-
|
| 22 |
-
-
|
| 23 |
-
|
| 24 |
-
-
|
| 25 |
-
-
|
| 26 |
-
-
|
| 27 |
-
|
| 28 |
-
### Damage anchor
|
| 29 |
-
`1 budget point = 2 damage` for a vanilla attack. All other primitive costs are relative to this.
|
| 30 |
-
|
| 31 |
---
|
| 32 |
|
| 33 |
-
#
|
| 34 |
|
| 35 |
-
|
| 36 |
|
| 37 |
-
|
| 38 |
-
1. **Deal** — direct damage. `1 pt = 2 damage`. The anchor.
|
| 39 |
-
2. **Burn** — deferred damage, X/turn for N turns (decaying or flat). Roughly on-rate; in a short game needs a slight premium to justify the delay. *Deferred-timer effect.*
|
| 40 |
-
3. **Bomb** — big delayed burst: deal X in N turns, telegraphed. High-variance. TUNE. *Deferred-timer effect.* (Fire signature pick: 4 energy → 9 damage in 3 turns.)
|
| 41 |
|
| 42 |
-
|
| 43 |
-
4. **Block** — temporary shield until your next turn. **Stacks.** `1 pt ≈ 3 block` (defense priced slightly cheaper than damage).
|
| 44 |
-
5. **Ward** — persistent shield. **Stacks. Expensive: `1 pt = 1 block`.** All-or-nothing: a ward can only be removed early by a *single hit meeting its threshold* — chip/multi-hit damage bounces off. The breaking hit is **fully absorbed** (a bubble that eats one decisive blow, then vanishes — excess does NOT carry to HP). [DEFAULT — override if you want break-through.] *Deferred/persistent-timer effect.*
|
| 45 |
-
6. **Weak** — opponent deals Y less damage until your next turn. Defensive (damage-prevention). Prices like Block (linear). Mirror of Vulnerable.
|
| 46 |
|
| 47 |
-
|
| 48 |
|
| 49 |
-
|
| 50 |
-
|
| 51 |
-
|
| 52 |
-
|
| 53 |
|
| 54 |
-
|
| 55 |
-
10. **Multi-hit** — apply an effect N times. *Multiplies* the cost of what it hits. The single most dangerous primitive (multi-hit × Deal or × Burn). Overcost hard. Note: multi-hit chip CANNOT break a Ward (each hit is below threshold) — built-in school counterplay.
|
| 56 |
-
11. **Vulnerable** — enemy takes X more damage for N turns. Offensive *multiplier* — combos with Deal/Multi-hit. Prices as a multiplier, not flat. TUNE.
|
| 57 |
-
12. **Conditional** — "if [state], then bonus" (e.g., if enemy below half HP, +damage). Depth via sequencing; prices by how often the condition is live. TUNE.
|
| 58 |
-
13. **Scaling** — effect grows with a counter (cards played this turn, banked shield charge, turns elapsed). Snowball primitive — overcost, runaway games start here. TUNE. Earth scaling spends banked shield charge.
|
| 59 |
|
| 60 |
-
##
|
| 61 |
-
Vulnerable (enemy *takes* X more — affects damage you deal) and Weak (enemy *deals* Y less — affects damage you take) are mirrored levers. Despite the symmetry they price differently: Vulnerable is a multiplier (TUNE), Weak is flat damage-prevention (linear, like Block).
|
| 62 |
|
| 63 |
-
|
| 64 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 65 |
|
| 66 |
-
|
| 67 |
|
| 68 |
-
|
|
|
|
|
|
|
| 69 |
|
| 70 |
-
|
| 71 |
-
|------|------|--------|
|
| 72 |
-
| Attack (weak) | 1 | deal 2 |
|
| 73 |
-
| Attack (medium) | 3 | deal 4 |
|
| 74 |
-
| Attack (strong) | 5 | deal 6 |
|
| 75 |
-
| Block (weak) | 2 | block 3 |
|
| 76 |
-
| Block (medium) | 3 | block 4 |
|
| 77 |
-
| Draw (small) | 2 | draw 1 |
|
| 78 |
|
| 79 |
-
|
| 80 |
|
| 81 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 82 |
|
| 83 |
-
|
| 84 |
|
| 85 |
-
|
| 86 |
|
| 87 |
-
|
| 88 |
|
| 89 |
-
|
| 90 |
-
|
| 91 |
-
|
| 92 |
-
- **Ice — speed (fast tempo).** For players who race: strike first, amplify, burst. NOT defensive — Ice outruns rather than turtles, so it carries no Block. Primitives: Initiative, Vulnerable, Multi-hit, Conditional.
|
| 93 |
-
Anchor: `3 energy: deal 2, opponent goes second next round`.
|
| 94 |
-
- **Earth — slow (durable control).** For players who outlast: grind, stack defense, win late. Half of damage absorbed by Block, rounded down, banks as shield charge; Ward does not bank charge. Earth Scaling releases that banked charge as burst damage, then empties it. Defense concentrates HERE deliberately — this is the school's identity, not a tax. Primitives: Ward, Block, Scaling, Conditional.
|
| 95 |
-
Anchor (refreshing ward): `4 energy: block 3 per turn for the next 2 turns`.
|
| 96 |
-
|
| 97 |
-
Defense is deliberately NOT spread evenly: it concentrates in Earth (the slow school), is absent from Ice (speed doesn't block, it races), and is incidental in Fire (burn just out-damages). This makes the three schools feel different to *play*, not just to read.
|
| 98 |
|
| 99 |
-
|
| 100 |
|
| 101 |
-
|
|
|
|
|
|
|
| 102 |
|
| 103 |
-
|
| 104 |
|
| 105 |
-
|
|
|
|
|
|
|
| 106 |
|
| 107 |
-
|
| 108 |
-
- **Picker / card author:** MiniCPM-V 4.6 (1.3B). Tool-call generation of synergy picks. Llama.cpp-compatible (badge).
|
| 109 |
-
- **Image:** SDXL-Turbo class, fine-tuned to one card-art style (LoRA — Well-Tuned badge).
|
| 110 |
|
| 111 |
-
|
|
|
|
|
|
|
| 112 |
|
| 113 |
-
|
| 114 |
|
| 115 |
```bash
|
| 116 |
-
# MiniCPM through an OpenAI-compatible local chat server.
|
| 117 |
-
TABRAS_CARD_ENDPOINT=http://localhost:8080/v1/chat/completions
|
| 118 |
-
TABRAS_CARD_MODEL=minicpm-v-4.6
|
| 119 |
-
|
| 120 |
-
# MiniCPM direct Transformers model.chat path.
|
| 121 |
TABRAS_CARD_BACKEND=transformers
|
| 122 |
TABRAS_CARD_MODEL=openbmb/MiniCPM-V-4
|
| 123 |
-
|
| 124 |
-
# Nemotron through an OpenAI-compatible chat server.
|
| 125 |
-
TABRAS_AI_BOSS=1
|
| 126 |
-
TABRAS_BOSS_ENDPOINT=http://localhost:8081/v1/chat/completions
|
| 127 |
-
TABRAS_BOSS_MODEL=nvidia/Nemotron-Mini-4B-Instruct
|
| 128 |
-
|
| 129 |
-
# Nemotron through a completion server with the documented <extra_id_*> prompt markers.
|
| 130 |
-
TABRAS_AI_BOSS=1
|
| 131 |
-
TABRAS_BOSS_BACKEND=completion
|
| 132 |
-
TABRAS_BOSS_ENDPOINT=http://localhost:8081/v1/completions
|
| 133 |
-
|
| 134 |
-
# Nemotron direct Transformers path using tokenizer.apply_chat_template.
|
| 135 |
TABRAS_AI_BOSS=1
|
| 136 |
TABRAS_BOSS_BACKEND=transformers
|
| 137 |
TABRAS_BOSS_MODEL=nvidia/Nemotron-Mini-4B-Instruct
|
|
|
|
|
|
|
|
|
|
| 138 |
```
|
| 139 |
|
| 140 |
-
|
| 141 |
-
|
| 142 |
-
## Components
|
| 143 |
-
|
| 144 |
-
### `primitives.py` — THE SPINE, build first
|
| 145 |
-
The 13 primitives above. Each: id, tool-call signature, point cost, templated display string. Nothing else works until this exists.
|
| 146 |
-
|
| 147 |
-
### `budget.py`
|
| 148 |
-
card cost (energy) → point budget → spends budget assigning N to the LLM's chosen primitives → returns a fully-costed, balanced card. Miracle variant: wide but HARD-CAPPED budget multiplier (the only high-variance path).
|
| 149 |
-
|
| 150 |
-
### `generator.py`
|
| 151 |
-
LLM tool call: `(school, theme, current_deck) → effect IDs + counts + name + flavor + art_prompt`. **`current_deck` is mandatory** — deck-awareness is the load-bearing AI. Passes effects to `budget.py`. Schools bias the primitive subset.
|
| 152 |
-
|
| 153 |
-
### `game.py`
|
| 154 |
-
Deterministic. Paired-round turn loop, energy ramp, initiative flip, card resolution (incl. the Ward threshold/bubble rule), Block/Ward stacking, fatigue/deck-out, win/loss. Deferred effects fire on schedule, never targetable. **All rules and numbers live here, never in a model.**
|
| 155 |
|
| 156 |
-
|
| 157 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 158 |
|
| 159 |
-
##
|
| 160 |
-
6 backbone + 9 deck-aware synergy picks = 15. Draft UI structure is a thin swappable layer — finalize after core playtests.
|
| 161 |
|
| 162 |
-
|
| 163 |
-
Gradio Space. Cards = styled containers in rows. No engine, no animations. Core state (both HP, enemy intent, energy, card costs/effects) ALWAYS visible — never behind hover. Effect text TEMPLATED from the primitive schema (fixed per-primitive format), never free prose — parses in ~1s. Custom themed frames (Custom UI badge). Landing/menu loads model-free; generation fires on "Start," not page load (protects compute + cold-start UX).
|
| 164 |
|
| 165 |
-
|
| 166 |
-
|
| 167 |
-
|
| 168 |
-
- Synergy-pick art generates during the draft; cards choosable on mechanical text while art streams in.
|
| 169 |
-
- Backbone art backfills (mechanics instant).
|
| 170 |
-
- Boss deck + art generate during player activity. Boss art lowest priority (seen when played, not drafted).
|
| 171 |
-
- Lazy-load by need. Text instant, art progressive.
|
| 172 |
-
|
| 173 |
-
---
|
| 174 |
-
|
| 175 |
-
## Build order (timeline-driven)
|
| 176 |
-
1. `primitives.py` (the 13)
|
| 177 |
-
2. `budget.py`
|
| 178 |
-
3. `generator.py` + `game.py` — **spell-only, text-only, NO ART YET**
|
| 179 |
-
4. **Playtest for fun on a real human** — the one risk no architecture fixes is whether reading fresh cards every game is fun. Answer this before investing downstream.
|
| 180 |
-
5. `boss.py`
|
| 181 |
-
6. `draft.py` + backbone wiring + Ward threshold rule
|
| 182 |
-
7. Art generation (base SDXL first)
|
| 183 |
-
8. Fine-tune art LoRA + UI polish
|
| 184 |
-
|
| 185 |
-
Art, fine-tuning, polish come LAST. A playable, fun, text-only core is submittable; an unfinished ambitious build is not. Time is the binding constraint, not compute.
|
| 186 |
-
|
| 187 |
-
---
|
| 188 |
-
|
| 189 |
-
## Hard rules
|
| 190 |
-
- The model never sets numbers (except the engine-bounded, hard-capped miracle roll).
|
| 191 |
-
- No board-state entities. Burn/Bomb/Ward/summons are deferred *effects*, never targetable units.
|
| 192 |
-
- v1 scope is fixed: spell-only, 3 schools (Fire/Ice/Earth) × 3 themes, one art style. "If time permits" features stay deferred until the core ships and is tuned.
|
| 193 |
-
- The 9 synergy picks must be generated **deck-aware** — picks that ignore the current deck reduce the generator to a random table.
|
| 194 |
|
| 195 |
-
-
|
| 196 |
|
| 197 |
-
##
|
| 198 |
-
- **Multiplier costs (primitives 10–13):** all TUNE — set conservative overcosted guesses, tighten in playtest. Multi-hit and Scaling are the highest-risk.
|
| 199 |
-
- **Ward break rule:** full-absorb bubble (default) vs. break-through. Affects `game.py` resolution.
|
| 200 |
-
- **Deferred-timer unification:** Burn/Bomb/Ward on one system (default/recommended).
|
| 201 |
-
- **The 3 specific themes** (concept locked, the three not chosen).
|
| 202 |
|
| 203 |
-
|
| 204 |
|
| 205 |
-
##
|
| 206 |
-
- $250 Modal (training/serving GPU) — primary budget, mostly art fine-tune + batch art gen.
|
| 207 |
-
- $20 HF (ZeroGPU/Space hosting) + 40 min/day free ZeroGPU. Thin for live three-model serving — test in focused sessions, gate generation behind intent, don't leave the Space running.
|
| 208 |
|
| 209 |
-
|
| 210 |
-
Space under the `build-small-hackathon` org + demo video + social post.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
---
|
| 2 |
+
title: Tabras
|
| 3 |
+
emoji: 🃏
|
| 4 |
+
colorFrom: purple
|
| 5 |
+
colorTo: indigo
|
| 6 |
+
sdk: gradio
|
| 7 |
+
sdk_version: 6.17.3
|
| 8 |
+
app_file: app_hf.py
|
| 9 |
+
pinned: false
|
| 10 |
+
license: mit
|
| 11 |
+
tags:
|
| 12 |
+
- thousand-token-wood
|
| 13 |
+
- off-brand
|
| 14 |
+
- tiny-titan
|
| 15 |
+
- minicpm
|
| 16 |
+
- nemotron
|
| 17 |
+
models:
|
| 18 |
+
- openbmb/MiniCPM-V-4
|
| 19 |
+
- nvidia/Nemotron-Mini-4B-Instruct
|
| 20 |
+
- stabilityai/sdxl-turbo
|
|
|
|
|
|
|
|
|
|
|
|
|
| 21 |
---
|
| 22 |
|
| 23 |
+
# Tabras
|
| 24 |
|
| 25 |
+
Tabras is a small-model roguelite card duel built for the Build Small Hackathon's **An Adventure in Thousand Token Wood** track.
|
| 26 |
|
| 27 |
+
You name a challenger, choose a world, choose a school of magic, draft a 15-card deck, and fight an AI boss across a short tactical duel. The fun part is that the draft is not a static card list: each run asks a small model to author new card names, flavor, effects, and art direction around your chosen theme and the deck you are already building.
|
|
|
|
|
|
|
|
|
|
| 28 |
|
| 29 |
+
The engine keeps the game fair. The model invents the card identity; deterministic Python code prices and resolves the card mechanics.
|
|
|
|
|
|
|
|
|
|
| 30 |
|
| 31 |
+
## What Makes It AI-Native
|
| 32 |
|
| 33 |
+
- **MiniCPM authors draft cards.** It proposes card concepts, names, flavor text, and effect shapes for the current deck.
|
| 34 |
+
- **Nemotron plays the boss.** The boss reads the public board state and chooses from its hidden hand.
|
| 35 |
+
- **SDXL-Turbo illustrates cards.** Card art is generated lazily so the draft can remain playable while images arrive.
|
| 36 |
+
- **The rules engine owns the numbers.** Damage, block, burn, ward, and tempo values are assigned by deterministic budget code rather than raw model output.
|
| 37 |
|
| 38 |
+
That split is the core design: AI provides surprise and taste, while the engine preserves balance.
|
|
|
|
|
|
|
|
|
|
|
|
|
| 39 |
|
| 40 |
+
## How To Play
|
|
|
|
| 41 |
|
| 42 |
+
1. Click **Play Now**.
|
| 43 |
+
2. Enter your name.
|
| 44 |
+
3. Choose a background world: Dark Fantasy, Cyberpunk, or Anime.
|
| 45 |
+
4. Choose a school of magic: Fire, Ice, or Earth.
|
| 46 |
+
5. Read the short rules page while the first draft pack starts loading.
|
| 47 |
+
6. Draft 9 generated cards onto a 6-card starter backbone.
|
| 48 |
+
7. Duel the boss.
|
| 49 |
|
| 50 |
+
### Schools
|
| 51 |
|
| 52 |
+
- **Fire** is pressure: direct damage, burn, bombs, and fast finishers.
|
| 53 |
+
- **Ice** is tempo: initiative, vulnerable windows, multi-hit pressure, and burst timing.
|
| 54 |
+
- **Earth** is control: block, ward, shield charge, and delayed counterpunches.
|
| 55 |
|
| 56 |
+
## Model Stack
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 57 |
|
| 58 |
+
All listed models are under the hackathon's 32B parameter limit.
|
| 59 |
|
| 60 |
+
| Role | Default model | Use |
|
| 61 |
+
| --- | --- | --- |
|
| 62 |
+
| Card author | `openbmb/MiniCPM-V-4` | Draft pack text and card concepts |
|
| 63 |
+
| Boss AI | `nvidia/Nemotron-Mini-4B-Instruct` | Enemy play decisions |
|
| 64 |
+
| Art | `stabilityai/sdxl-turbo` | Fast card illustration |
|
| 65 |
|
| 66 |
+
The Hugging Face Space entry point is [app_hf.py](app_hf.py). It defaults to Transformers/Diffusers backends so it can run on a CUDA Space without requiring a local llama.cpp server.
|
| 67 |
|
| 68 |
+
## Running Locally
|
| 69 |
|
| 70 |
+
Install dependencies:
|
| 71 |
|
| 72 |
+
```bash
|
| 73 |
+
python3 -m pip install -r requirements.txt
|
| 74 |
+
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 75 |
|
| 76 |
+
Run the Gradio app without local model servers:
|
| 77 |
|
| 78 |
+
```bash
|
| 79 |
+
python3 app.py
|
| 80 |
+
```
|
| 81 |
|
| 82 |
+
For the local AI path, start Tabras through:
|
| 83 |
|
| 84 |
+
```bash
|
| 85 |
+
python3 launch_ai.py
|
| 86 |
+
```
|
| 87 |
|
| 88 |
+
`launch_ai.py` expects the MiniCPM GGUF at:
|
|
|
|
|
|
|
| 89 |
|
| 90 |
+
```text
|
| 91 |
+
models/minicpm-v-4.6-gguf/MiniCPM-V-4.6-Q4_K_M.gguf
|
| 92 |
+
```
|
| 93 |
|
| 94 |
+
You can also configure backends with environment variables:
|
| 95 |
|
| 96 |
```bash
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 97 |
TABRAS_CARD_BACKEND=transformers
|
| 98 |
TABRAS_CARD_MODEL=openbmb/MiniCPM-V-4
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 99 |
TABRAS_AI_BOSS=1
|
| 100 |
TABRAS_BOSS_BACKEND=transformers
|
| 101 |
TABRAS_BOSS_MODEL=nvidia/Nemotron-Mini-4B-Instruct
|
| 102 |
+
TABRAS_ART_BACKEND=diffusers
|
| 103 |
+
TABRAS_ART_MODEL=stabilityai/sdxl-turbo
|
| 104 |
+
python3 app_hf.py
|
| 105 |
```
|
| 106 |
|
| 107 |
+
## Project Structure
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 108 |
|
| 109 |
+
| File | Purpose |
|
| 110 |
+
| --- | --- |
|
| 111 |
+
| `app.py` | Gradio UI and interaction flow |
|
| 112 |
+
| `app_hf.py` | Hugging Face Space entry point |
|
| 113 |
+
| `primitives.py` | Fixed vocabulary of card effects |
|
| 114 |
+
| `budget.py` | Deterministic card costing |
|
| 115 |
+
| `generator.py` | Card authoring and model payload handling |
|
| 116 |
+
| `game.py` | Deterministic combat engine |
|
| 117 |
+
| `boss.py` | Boss decision layer |
|
| 118 |
+
| `ui.py` | Draft and battle rendering helpers |
|
| 119 |
+
| `art.py` | Art generation client |
|
| 120 |
+
| `forge.py` | Background generation queue |
|
| 121 |
|
| 122 |
+
## Development
|
|
|
|
| 123 |
|
| 124 |
+
Run tests:
|
|
|
|
| 125 |
|
| 126 |
+
```bash
|
| 127 |
+
python3 -m pytest -q
|
| 128 |
+
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 129 |
|
| 130 |
+
The deterministic game core is intentionally heavily tested. Model-dependent paths should be tested with mocked clients so tests stay fast and repeatable.
|
| 131 |
|
| 132 |
+
## Status
|
|
|
|
|
|
|
|
|
|
|
|
|
| 133 |
|
| 134 |
+
Tabras is a hackathon prototype. The current build focuses on the full playable loop: setup, generated drafting, lazy art, boss play, and a custom Gradio UI. Balance, card variety, and image quality are still active tuning areas.
|
| 135 |
|
| 136 |
+
## License
|
|
|
|
|
|
|
| 137 |
|
| 138 |
+
MIT
|
|
|