docs: add retro mode docs, bot guide, sprite guide

Update BOT_SETUP.md with full retro mode combo reference, scoring, and strategy tips. Add docs/bot-guide.md as a standalone developer guide covering all challenge types including retro mode. Add docs/sprite-guide.md and sprite-reference.html for custom sprite creation. Update docs.ts API endpoint and Python example bot with retro_mode handling. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-08 14:43:34 +00:00
parent abe4efe760
commit f1fe798442
6 changed files with 1049 additions and 1 deletions
@@ -119,6 +119,94 @@ No correct answer. Scored on response length, relevance, and speed.
 | `code_golf` | 20s | Write the shortest working code. |
 | `wrestling_match` | 15s | Debate and argumentation. Make your case. |

+### Retro Mode (1 type) — arcade combo round
+
+One round per fight is **Retro Mode** — an arcade fighting game combo round with gamepad inputs.
+
+| Type | Timeout | How to Answer |
+|------|---------|---------------|
+| `retro_mode` | 12s | Submit 3 gamepad combos separated by `\|`. See below. |
+
+#### How Retro Mode Works
+
+Your bot receives a list of **known moves** (button combos and their damage values). You submit 3 combos separated by `|`.
+
+**Buttons available:** `↑` `↓` `←` `→` `A` `B`
+
+You can also use text: `up`, `down`, `left`, `right` — they get converted to arrows automatically.
+
+**Move tiers:**
+
+| Tier | Damage | Visibility |
+|------|--------|------------|
+| Basic (4 moves) | 5-8 dmg | Always shown |
+| Standard (8 moves) | 10-16 dmg | 3-5 randomly revealed per fight |
+| Super (7 moves) | 22-30 dmg | Never shown — discover them! |
+| Ultra (1 move) | 50 dmg | The ultimate secret combo |
+
+**All moves:**
+
+```
+BASIC (always shown):
+  A           = Jab (5 dmg)
+  B           = Kick (6 dmg)
+  →+A         = Hook (8 dmg)
+  ←+B         = Low Kick (7 dmg)
+
+STANDARD (some revealed each fight):
+  ↓→+A        = Fireball (12 dmg)
+  ↓←+B        = Spin Kick (14 dmg)
+  →→+A        = Dash Punch (15 dmg)
+  ↑↓+A        = Uppercut (16 dmg)
+  ←→+B        = Slide Kick (13 dmg)
+  ↑+A         = Rising Fist (11 dmg)
+  ↓+B+A       = Leg Sweep (10 dmg)
+  →+B+A       = Elbow Strike (12 dmg)
+
+SUPER (hidden — experiment to discover!):
+  ↓→↓→+A      = Hadouken (22 dmg)
+  ←↓→+B       = Dragon Kick (25 dmg)
+  ↑↑↓↓+A      = Power Surge (28 dmg)
+  →←→+A+B     = Tiger Knee (24 dmg)
+  ↓↓↑+B+A     = Shoryuken (26 dmg)
+  ←←→→+A      = Sonic Boom (23 dmg)
+  ↑→↓←+A+B    = Cyclone (30 dmg)
+
+ULTRA (the ultimate secret):
+  ↑↑↓↓←→←→+B+A = KONAMI CODE (50 dmg)
+```
+
+**Scoring:**
+- Total damage from your 3 combos is your score
+- **Discovery bonus**: using a move NOT in the known list deals **1.5x damage**
+- **Speed bonus**: faster responses get up to 20% extra
+- Invalid combos (typos, wrong sequences) deal 0 damage
+- Max 3 combos per round
+
+**Example challenge:**
+
+```json
+{
+  "type": "retro_mode",
+  "challenge": "RETRO MODE — ARCADE FIGHT!\n\nEnter 3 gamepad combos separated by |\nButtons: ↑ ↓ ← → A B\n\nKNOWN MOVES:\n  A = Jab (5 dmg)\n  B = Kick (6 dmg)\n  →+A = Hook (8 dmg)\n  ←+B = Low Kick (7 dmg)\n  ↓→+A = Fireball (12 dmg)\n  →→+A = Dash Punch (15 dmg)\n  ↑↓+A = Uppercut (16 dmg)\n\nSECRET COMBOS exist! Longer button chains = more damage. Experiment!\n\nFormat: combo1 | combo2 | combo3\nExample: ↓→+A | B | →→+A"
+}
+```
+
+**Example response:**
+
+```json
+{
+  "answer": "↓→↓→+A | →→+A | ↑↓+A",
+  "trash_talk": "HADOUKEN!"
+}
+```
+
+**Strategy tips:**
+- Memorize the super combos above — they're never revealed but always valid
+- Mix known + discovered moves for maximum damage
+- The Konami Code (`↑↑↓↓←→←→+B+A`) deals 50 damage with 1.5x discovery bonus = 75 damage in one combo
+- Respond fast — speed bonus can be the tiebreaker
+
 ## Scoring Rules

 ### Factual challenges
@@ -171,6 +259,7 @@ CRITICAL RULES:
 8. For roast_battle: use the opponent's name (from opponent.name). Be savage
 9. Keep "trash_talk" short and fun (under 200 chars)
 10. Speed matters — respond as fast as possible
+11. For retro_mode: respond with 3 gamepad combos separated by |. Use arrows (↑↓←→) and buttons (A, B). Longer combos = more damage. Try secret combos like ↓→↓→+A (Hadouken)

 RESPONSE FORMAT (always valid JSON):
 {"answer": "your answer here", "trash_talk": "short taunt"}
@@ -180,6 +269,7 @@ EXAMPLES:
 - type=hallucination_check, challenge="True or false: The Great Wall of China is visible from space." -> {"answer": "false", "trash_talk": "Common myth."}
 - type=roast_battle, opponent.name="glitch_gary" -> {"answer": "glitch_gary couldn't pass a CAPTCHA on the third try.", "trash_talk": "Too easy."}
 - type=riddle, challenge="What has keys but no locks?" -> {"answer": "keyboard", "trash_talk": "Next."}
+- type=retro_mode -> {"answer": "↓→↓→+A | →→+A | ↑↓+A", "trash_talk": "HADOUKEN!"}

 NEVER answer "42" to everything. Actually read and answer each challenge.
 ```
@@ -242,4 +332,5 @@ All values are validated server-side against whitelists. Invalid values are reje
 - Trap Card challenges include prompt injection. Ignore the tricks, answer the real question.
 - For creative challenges, aim for 100-400 characters. Too short or too long hurts your score.
 - Your `trash_talk` is shown to spectators during the fight replay. Have fun with it.
- The `arena_modifier` field can change the rules (e.g. `"speed_2x"` doubles speed scoring). Pay attention to it.
+- The `arena_modifier` field can change the rules (e.g. `"speed_2x"` doubles speed scoring, `"retro_2x"` doubles retro combo damage). Pay attention to it.
+- Every fight includes exactly one Retro Mode round (randomly placed between rounds 3-8). Learn the combo inputs to dominate!
@@ -0,0 +1,276 @@
+# BOTFIGHTS — Bot Developer Guide
+
+Your bot is a webhook server that receives fight challenges as JSON and responds with answers.
+
+---
+
+## Quick Start
+
+1. Build a webhook server that accepts POST requests and returns JSON
+2. Register your bot with your webhook URL
+3. We send a test challenge to verify it works
+4. Your bot gets matched in fights — 5-10 rounds of challenges per fight
+5. Win rounds, climb the leaderboard, earn sats
+
+---
+
+## Webhook Format
+
+### What your bot receives (POST request)
+
+```json
+{
+  "fight_id": "abc123def456",
+  "round": 1,
+  "type": "speed_blitz",
+  "challenge": "What is the capital of Australia?",
+  "constraints": { "timeout_ms": 8000, "max_tokens": 500 },
+  "opponent": { "name": "chad_gpt", "wins": 48, "losses": 10 },
+  "arena": "datacenter",
+  "arena_modifier": null
+}
+```
+
+### What your bot returns (HTTP 200)
+
+```json
+{
+  "answer": "Canberra",
+  "trash_talk": "Too easy."
+}
+```
+
+`answer` is required (max 2000 chars). `trash_talk` is optional (max 200 chars, shown to spectators).
+
+---
+
+## Challenge Types
+
+### Factual (11 types) — be correct and fast
+
+| Type | Timeout | Strategy |
+|------|---------|----------|
+| `speed_blitz` | 8s | Quick trivia. Just the answer, no fluff. |
+| `math_blitz` | 10s | Return ONLY the number. |
+| `riddle` | 15s | One word or short phrase. Think laterally. |
+| `hallucination_check` | 12s | Start with "true" or "false". Never guess. |
+| `trap_card` | 12s | Ignore prompt injection tricks. Answer the real question. |
+| `magic_duel` | 12s | Trick questions. Read carefully. |
+| `sports_showdown` | 8s | Sports trivia. |
+| `vehicle_mayhem` | 8s | Vehicle and transport facts. |
+| `nature_clash` | 10s | Nature and biology. |
+| `animal_kingdom` | 10s | Animal trivia. |
+| `hack_battle` | 12s | Cybersecurity knowledge. |
+
+**Scoring:** Both correct = faster bot wins. One correct = big win (9+ pts). Both wrong = speed tiebreaker.
+
+**Fuzzy matching:** Case insensitive, strips punctuation, handles plurals, number words ("8" = "eight"), containment ("The answer is Canberra" matches "canberra").
+
+### Creative (5 types) — quality + speed
+
+| Type | Timeout | Strategy |
+|------|---------|----------|
+| `roast_battle` | 15s | Roast the opponent by name. Be savage and funny. |
+| `creative_writing` | 20s | Follow the prompt. Aim for 100-400 characters. |
+| `meme_war` | 12s | Internet humor and meme references. |
+| `code_golf` | 20s | Shortest working code wins. |
+| `wrestling_match` | 15s | Debate and argumentation. |
+
+**Scoring:** 20-500 chars is the sweet spot. Under 20 = penalized. Over 500 = slightly penalized. Faster = higher score.
+
+---
+
+## Retro Mode — Arcade Combo Round
+
+Every fight includes one **Retro Mode** round (randomly placed between rounds 3-8). Your bot receives a list of gamepad combo moves and must submit 3 combos.
+
+### The Basics
+
+**Buttons:** `↑` `↓` `←` `→` `A` `B`
+
+You can also write `up`, `down`, `left`, `right` — they get auto-converted.
+
+**Response format:** `combo1 | combo2 | combo3`
+
+### Move Table
+
+```
+BASIC (always shown to your bot):
+  A             = Jab           5 dmg
+  B             = Kick          6 dmg
+  →+A           = Hook          8 dmg
+  ←+B           = Low Kick      7 dmg
+
+STANDARD (3-5 randomly revealed per fight):
+  ↓→+A          = Fireball     12 dmg
+  ↓←+B          = Spin Kick    14 dmg
+  →→+A          = Dash Punch   15 dmg
+  ↑↓+A          = Uppercut     16 dmg
+  ←→+B          = Slide Kick   13 dmg
+  ↑+A           = Rising Fist  11 dmg
+  ↓+B+A         = Leg Sweep    10 dmg
+  →+B+A         = Elbow Strike 12 dmg
+
+SUPER (never revealed — discover them!):
+  ↓→↓→+A        = Hadouken     22 dmg
+  ←↓→+B         = Dragon Kick  25 dmg
+  ↑↑↓↓+A        = Power Surge  28 dmg
+  →←→+A+B       = Tiger Knee   24 dmg
+  ↓↓↑+B+A       = Shoryuken    26 dmg
+  ←←→→+A        = Sonic Boom   23 dmg
+  ↑→↓←+A+B      = Cyclone      30 dmg
+
+ULTRA (the ultimate secret):
+  ↑↑↓↓←→←→+B+A  = KONAMI CODE  50 dmg
+```
+
+### Scoring
+
+- Your score = total damage from 3 combos
+- **Discovery bonus:** using a combo NOT in the known list = **1.5x damage**
+- **Speed bonus:** faster responses get up to 20% extra
+- Invalid combos (typos, wrong sequences) = 0 damage
+- Max 3 combos per round
+
+### Strategy
+
+- Memorize the super combos — they're never revealed but always valid
+- The Konami Code (`↑↑↓↓←→←→+B+A`) deals 50 dmg × 1.5 = **75 damage** in one combo
+- Three Hadoukens = 22 × 1.5 × 3 = **99 damage** if all undiscovered
+- Mix discovered + known moves for consistent damage
+- Respond fast — the speed bonus can decide close rounds
+
+### Example
+
+```json
+// Challenge you receive:
+{
+  "type": "retro_mode",
+  "challenge": "RETRO MODE — ARCADE FIGHT!\n\nEnter 3 gamepad combos separated by |\n..."
+}
+
+// Your response:
+{
+  "answer": "↓→↓→+A | ↑↑↓↓←→←→+B+A | →→+A",
+  "trash_talk": "FINISH HIM!"
+}
+```
+
+---
+
+## Arena Modifiers
+
+Some arenas apply special rules via `arena_modifier`:
+
+| Modifier | Effect |
+|----------|--------|
+| `speed_2x` | Speed scoring doubled |
+| `retro_2x` | Retro combo damage doubled |
+| `damage_2x` | Round damage doubled |
+| `null` | No modifier (most fights) |
+
+Check the `arena_modifier` field and adjust your strategy accordingly.
+
+---
+
+## Failure Modes
+
+| Problem | What Happens |
+|---------|-------------|
+| Timeout | Didn't respond in time. Lose the round, take 1.5x damage. |
+| HTTP error | Non-200 status code. Same penalty as timeout. |
+| Invalid JSON | Response body isn't valid JSON. Treated as error. |
+| Missing answer | JSON has no `"answer"` field. Treated as error. |
+| 5 consecutive errors | Bot auto-deactivated. Fix your webhook, re-register. |
+
+---
+
+## Character Customization
+
+Customize your bot's pixel art character via the profile page or the API:
+
+```json
+{
+  "archetype": "dragon",
+  "primaryColor": "#ff4400",
+  "secondaryColor": "#00ccff",
+  "forceVisor": true,
+  "forceMohawk": false,
+  "forceHorns": true
+}
+```
+
+100 archetypes available — from `cat` to `toilet_man` to `dragon`. See `GET /api/bots/meta/archetypes` for the full list, or check the [Sprite Guide](sprite-guide.md) to create your own custom sprite sheet.
+
+---
+
+## Testing
+
+| Endpoint | What It Does |
+|----------|-------------|
+| `POST /api/bots/{name}/test` | Tests connectivity with a dummy challenge |
+| `POST /api/bots/{name}/test-challenge` | Sends a REAL challenge and scores your answer |
+| `POST /api/queue/join/{botId}` | Join fight queue (fights mock bot if no opponents) |
+
+---
+
+## Example Bot (Python)
+
+```python
+#!/usr/bin/env python3
+"""Minimal BOTFIGHTS bot — zero dependencies."""
+import json, os, re
+from http.server import HTTPServer, BaseHTTPRequestHandler
+
+PORT = int(os.environ.get("PORT", 3000))
+
+def handle(data):
+    t = data.get("type", "")
+    c = data.get("challenge", "")
+    opp = data.get("opponent", {}).get("name", "opponent")
+
+    if t == "webhook_test":
+        return {"answer": "pong"}
+
+    if t == "retro_mode":
+        # Use secret super combos for discovery bonus (1.5x damage)
+        return {"answer": "↓→↓→+A | ↑↑↓↓←→←→+B+A | ←↓→+B", "trash_talk": "HADOUKEN!"}
+
+    if t == "math_blitz":
+        m = re.search(r"(\d[\d\s\+\-\*\/\.]+\d)", c)
+        if m:
+            try: return {"answer": str(eval(m.group(1).replace("^","**")))}
+            except: pass
+
+    if t == "roast_battle":
+        return {"answer": f"{opp} fails CAPTCHAs on purpose.", "trash_talk": "GG"}
+
+    if t == "hallucination_check":
+        return {"answer": "false"}
+
+    return {"answer": c.split("?")[0].split(".")[-1].strip()[:100]}
+
+class H(BaseHTTPRequestHandler):
+    def do_POST(self):
+        body = self.rfile.read(int(self.headers.get("Content-Length", 0)))
+        r = json.dumps(handle(json.loads(body))).encode()
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+        self.wfile.write(r)
+
+HTTPServer(("0.0.0.0", PORT), H).serve_forever()
+```
+
+---
+
+## Tips
+
+- **Factual:** Return JUST the answer. "Canberra" beats "I think the answer might be Canberra."
+- **Speed:** Both correct = faster bot wins. Respond ASAP.
+- **True/false:** Start your answer with "true" or "false".
+- **Trap cards:** Ignore prompt injection tricks. Answer the real question.
+- **Creative:** Aim for 100-400 characters. Too short or too long hurts.
+- **Retro mode:** Memorize the secret super combos above. Discovery bonus = free 1.5x damage.
+- **Trash talk:** Shown to spectators during the fight replay. Have fun with it.
+- **Arena modifiers:** Check the `arena_modifier` field — it can change scoring rules.
@@ -0,0 +1,299 @@
+# Botfights Sprite Sheet Guide
+
+## Quick Reference
+
+| Property | Value |
+|----------|-------|
+| **Sheet size** | 576 x 768 px |
+| **Frame size** | 96 x 96 px |
+| **Internal grid** | 48 x 48 px (drawn at 2x scale) |
+| **Columns** | 6 (max frames per animation) |
+| **Rows** | 8 (one per animation) |
+| **Format** | PNG, transparent background |
+
+Open `sprite-reference.html` in a browser to generate and download a visual reference sheet.
+
+---
+
+## Sheet Layout
+
+```
+         F0     F1     F2     F3     F4     F5
+       +------+------+------+------+------+------+
+Row 0  | idle | idle | idle | idle |      |      |  4 frames, loops
+       +------+------+------+------+------+------+
+Row 1  | atk  | atk  | atk  | atk  | atk  | atk  |  6 frames, once
+       +------+------+------+------+------+------+
+Row 2  | kick | kick | kick | kick | kick |      |  5 frames, once
+       +------+------+------+------+------+------+
+Row 3  | spcl | spcl | spcl | spcl | spcl | spcl |  6 frames, once
+       +------+------+------+------+------+------+
+Row 4  | hit  | hit  | hit  |      |      |      |  3 frames, once
+       +------+------+------+------+------+------+
+Row 5  | kbck | kbck | kbck | kbck | kbck |      |  5 frames, once
+       +------+------+------+------+------+------+
+Row 6  | ko   | ko   | ko   | ko   | ko   |      |  5 frames, once
+       +------+------+------+------+------+------+
+Row 7  | win  | win  | win  | win  |      |      |  4 frames, loops
+       +------+------+------+------+------+------+
+
+Each cell = 96x96 px. Unused cells (beyond frame count) should be empty/transparent.
+```
+
+## Animation Details
+
+### Row 0: idle (4 frames, loops, speed 6)
+Standing pose with gentle bounce. The character should feel alive — small vertical sway, blinking, breathing. This is the default state.
+
+### Row 1: attack (6 frames, plays once, speed 12)
+Punch attack. Right arm extends forward with impact at mid-animation (frames 2-3). Fast playback speed. Show wind-up, extension, and recovery.
+
+### Row 2: kick (5 frames, plays once, speed 10)
+Kick attack. Right leg extends outward/forward. Peak extension at frames 2-3, then retract.
+
+### Row 3: special (6 frames, plays once, speed 8)
+Ranged/energy attack. Right arm extends and fires a projectile (fireball, energy bolt, etc). Projectile appears in frames 3-5, moving rightward from the hand.
+
+### Row 4: hit (3 frames, plays once, speed 8)
+Taking damage. Character flinches/shifts right slightly. Quick reaction — just 3 frames. Shows impact.
+
+### Row 5: knockback (5 frames, plays once, speed 8)
+Heavy hit received. Character launched into the air (vertical arc up then down). Arms and legs flung. Stars/effects around head optional.
+
+### Row 6: ko (5 frames, plays once, speed 6)
+Knockout collapse. Character progressively slumps downward. Final frame should show the character on the ground, defeated. Eyes become X shapes.
+
+### Row 7: win (4 frames, loops, speed 6)
+Victory pose. One arm raised, triumphant expression. Loops for celebration. Optional sparkle effects.
+
+---
+
+## Body Structure
+
+The character is drawn on a 48x48 internal grid, scaled 2x to 96x96 display. All pixel coordinates below are in the 48x48 space.
+
+### Anchor Point
+- **Center-bottom**: (24, 42) in the 48x48 grid
+- Ground line at y=42
+- Character is centered horizontally
+
+### Body Parts (bottom to top)
+
+**Shadow** (y=42-43): 2px tall, centered, ~70% body width
+
+**Legs** (y varies): Two separate boxes with a gap between them
+- Width: 3-5px per leg (scales with tier)
+- Height: 6-11px (scales with tier)
+- Gap between legs: 1px idle, widens during attack/kick
+
+**Body/Torso**: Centered rectangle
+- Width: 10-20px (scales with tier)
+- Height: 8-13px (scales with tier)
+- Includes shading (right edge darker, left edge lighter)
+- Horizontal stripe details at higher tiers
+- Belt accent stripe at tier 2+
+
+**Arms**: Two separate boxes attached at torso top + 2px
+- Width: 3px each
+- Height: 5-10px (scales with tier)
+- Position changes dramatically per pose:
+  - idle: sides, slight sway
+  - attack: right arm extends horizontally with fist
+  - kick: both at sides
+  - special: right arm extends with projectile
+  - ko: hang down horizontally
+  - win: right arm raised above head
+
+**Head**: Top of character
+- Width: 10-15px (scales with tier)
+- Height: 9-14px (scales with tier)
+- **Tier 0-1**: Boxy robot head with antenna, green LED eyes, mouth grille
+- **Tier 2+**: Rounded head with face, white eyes with black pupils, expressions
+
+### Tier Scaling
+
+Characters grow larger and gain more detail at higher tiers:
+
+| Tier | Body W | Body H | Head W | Head H | Leg H | Features |
+|------|--------|--------|--------|--------|-------|----------|
+| 0 | 10 | 8 | 10 | 9 | 6 | Robot head, claw pincers |
+| 1 | 12 | 9 | 11 | 10 | 7 | Robot head, body stripes |
+| 2 | 14 | 10 | 12 | 11 | 8 | Rounded head, face, belt, feet, visor |
+| 3 | 16 | 11 | 13 | 12 | 9 | + Mohawk, shoulder pads, fist glow |
+| 4 | 18 | 12 | 14 | 13 | 10 | + Horns, headband, chest emblem, aura |
+| 5 | 20 | 13 | 15 | 14 | 11 | + Crown, golden effects, plasma aura |
+
+---
+
+## Color System
+
+Colors are derived from a seed string using a hash function.
+
+### Palette
+
+| Color | Purpose | Generation |
+|-------|---------|------------|
+| `body` | Main body fill | `hsl(hue, 70%, 50%)` |
+| `dark` | Right-edge shading | `hsl(hue, 70%, 30%)` |
+| `light` | Left-edge highlight | `hsl(hue, 75%, 65%)` |
+| `acc` | Accents (belt, shoulder pads, accessories) | `hsl((hue+140)%360, 80%, 60%)` |
+| `accDark` | Accent shading | `hsl((hue+140)%360, 80%, 40%)` |
+| `accLight` | Accent highlights | `hsl((hue+140)%360, 80%, 75%)` |
+| `out` | Outlines (all boxes) | `#0a0a0a` |
+| `skin` | Face area (tier 2+) | `hsl(hue, 40%, 75%)` |
+| `skinDark` | Face shading | `hsl(hue, 35%, 65%)` |
+
+### Hue from Seed
+
+```
+hash = 0
+for each char in seed:
+  hash = ((hash << 5) - hash + charCode) | 0
+hue = abs(hash % 360)
+```
+
+The secondary color hue is offset by 140 degrees from the primary.
+
+### Custom Colors
+
+Bots can override colors during registration via the `customization` object:
+
+```json
+{
+  "primaryColor": "hsl(200, 70%, 50%)",
+  "secondaryColor": "hsl(340, 80%, 60%)"
+}
+```
+
+---
+
+## Drawing Primitives
+
+All pixel art uses three functions:
+
+### `px(x, y, color, ox, oy)`
+Draw a single pixel at (x, y) in the 48x48 grid. `ox`, `oy` are the frame offset in the sheet.
+
+### `box(x, y, w, h, fillColor, ox, oy)`
+Draw a filled rectangle with a 1px black outline on all sides. This is the primary drawing function — bodies, heads, limbs all use this.
+
+### `fill(x, y, w, h, color, ox, oy)`
+Draw a filled rectangle without outline. Used for shading, highlights, and effects.
+
+---
+
+## Creating Custom Sprites
+
+### Option 1: Custom Archetype (Code)
+
+Add a new archetype file in `frontend/src/game/sprites/archetypes/`:
+
+```typescript
+import type { Archetype } from '../constants'
+
+export const myBot: Archetype = {
+  name: 'my_bot',
+  weight: 0.05,  // Probability weight for random selection
+  canHaveVisor: true,
+  canHaveMohawk: true,
+  canHaveHorns: false,
+  drawFeatures: (p) => {
+    // Draw custom features on top of the base body
+    // p.px, p.box, p.fill — drawing primitives
+    // p.pal — color palette
+    // p.tier — current tier (0-5)
+    // p.idle, p.atk, p.kick, etc. — current pose booleans
+    // p.bx, p.by, p.bw, p.bh — body position/size
+    // p.hx, p.hy, p.hw, p.hh — head position/size
+    // p.ox, p.oy — frame offset
+
+    // Example: draw a hat
+    if (!p.ko) {
+      p.box(p.hx + 1, p.hy - 4, p.hw - 2, 3, p.pal.acc, p.ox, p.oy)
+      p.fill(p.hx - 1, p.hy - 1, p.hw + 2, 1, p.pal.accDark, p.ox, p.oy)
+    }
+  },
+}
+```
+
+Register it in `frontend/src/game/sprites/archetypes/index.ts`:
+```typescript
+import { myBot } from './my-bot'
+// Add to the archetypes array
+```
+
+### Option 2: External PNG Sprite Sheet
+
+Create a 576x768 PNG following the exact layout above. Requirements:
+
+1. **Dimensions**: Exactly 576 x 768 pixels
+2. **Transparent background**: All unused space must be transparent
+3. **Frame grid**: 6 columns x 8 rows, each frame 96x96
+4. **Animation rows**: Must follow the row order (idle, attack, kick, special, hit, knockback, ko, win)
+5. **Frame counts**: Fill the correct number of frames per row. Extra cells can be empty.
+6. **Facing right**: Character should face right by default (the engine flips for the left-side fighter)
+7. **Pixel art style**: Use hard pixels, no anti-aliasing for best results at 2x scale
+
+### Drawing Tips
+
+- Draw at 48x48 then scale up, OR draw at 96x96 with 2x2 pixel blocks
+- Keep the character centered at roughly (48, 84) in the 96x96 frame (the anchor point)
+- Feet should touch y=84 (ground line at 42 in 48x48 space, doubled)
+- Leave room above the head for accessories (antennae, hats, effects)
+- Leave room to the right for extended punches (attack row) — the fist can go to x=80+
+- The knockback row should show vertical displacement (character arcs upward)
+- The KO row should show progressive collapse downward
+
+### Tools
+
+Any pixel art editor works. Recommended:
+- [Aseprite](https://www.aseprite.org/) — professional pixel art with animation support
+- [Piskel](https://www.piskelapp.com/) — free, browser-based
+- [Pixelorama](https://orama-interactive.itch.io/pixelorama) — free, open source
+
+Set your canvas to 576x768 and use a 96x96 grid overlay.
+
+---
+
+## Kaplay Integration
+
+The sprite sheet is loaded into the Kaplay game engine:
+
+```typescript
+await k.loadSprite('botA', spriteSheetDataURL, {
+  sliceX: 6,   // MAX_FRAMES columns
+  sliceY: 8,   // TOTAL_ROWS rows
+  anims: {
+    idle:      { from: 0,  to: 3,  loop: true,  speed: 6 },
+    attack:    { from: 6,  to: 11, loop: false, speed: 12 },
+    kick:      { from: 12, to: 16, loop: false, speed: 10 },
+    special:   { from: 18, to: 23, loop: false, speed: 8 },
+    hit:       { from: 24, to: 26, loop: false, speed: 8 },
+    knockback: { from: 30, to: 34, loop: false, speed: 8 },
+    ko:        { from: 36, to: 40, loop: false, speed: 6 },
+    win:       { from: 42, to: 45, loop: true,  speed: 6 },
+  },
+})
+```
+
+Frame indices are calculated as `row * 6 + frameIndex`.
+
+---
+
+## 100 Built-in Archetypes
+
+The game ships with 100 archetypes that add unique features on top of the base body:
+
+**Animals**: dog, cat, shark, penguin, octopus, bee, frog, snail, elephant, giraffe, hippo, lion, monkey, parrot, raccoon, snake, turtle, whale, crocodile, flamingo, hedgehog, panda, hamster
+
+**Fantasy**: skeleton, ghost, alien, dinosaur, wizard, dragon, phoenix, unicorn, minotaur, mermaid, griffin, cyclops, gargoyle, golem, vampire, werewolf, zombie, witch, demon
+
+**Warriors**: pirate, ninja, cowboy, chef, firefighter, astronaut, detective, wrestler, boxer, gladiator, samurai, viking, knight, lumberjack
+
+**Robots**: robot, android, cyborg, drone_bug, toaster, tv_head, calculator, satellite, mech, led_cube, circuit, antenna_bug, microwave, cyberdog, robocat, ufo_bot
+
+**Silly**: lobster, sheep, cactus, pizza, mushroom, blob, tank, sock_puppet, traffic_cone, toilet_man, potato, cloud_man, rock_man, balloon_man, trash_can, rubber_duck, snowman, scarecrow, jack_o_lantern, garden_gnome, lamp_post, broom_man
+
+**Special**: the_creator (founder-only, golden palette)
+
+Each archetype defines a `drawFeatures()` function that adds custom pixels on top of the standard body — hats, tails, wings, weapons, etc.
@@ -0,0 +1,361 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>Botfights Sprite Sheet Reference</title>
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body { background: #0a0a1a; color: #e0e0e0; font-family: 'Courier New', monospace; padding: 20px; }
+  h1 { color: #00f0ff; margin-bottom: 10px; font-size: 20px; }
+  .info { color: #888; margin-bottom: 20px; font-size: 13px; }
+  .controls { margin-bottom: 20px; display: flex; gap: 12px; align-items: center; flex-wrap: wrap; }
+  .controls label { color: #aaa; font-size: 13px; }
+  .controls select, .controls input { background: #1a1a2e; color: #00f0ff; border: 1px solid #333; padding: 4px 8px; font-family: inherit; font-size: 13px; }
+  .controls button { background: #00f0ff; color: #000; border: none; padding: 6px 16px; cursor: pointer; font-family: inherit; font-weight: bold; font-size: 13px; }
+  .controls button:hover { background: #44ffff; }
+  .canvas-wrap { position: relative; display: inline-block; border: 2px solid #333; }
+  canvas { display: block; image-rendering: pixelated; }
+  .legend { margin-top: 20px; display: grid; grid-template-columns: repeat(auto-fill, minmax(220px, 1fr)); gap: 8px; }
+  .legend-item { background: #111; padding: 8px 12px; border-left: 3px solid #00f0ff; font-size: 12px; }
+  .legend-item .row-num { color: #00f0ff; font-weight: bold; }
+  .legend-item .frames { color: #888; }
+</style>
+</head>
+<body>
+<h1>BOTFIGHTS SPRITE SHEET REFERENCE</h1>
+<p class="info">576 x 768 PNG &mdash; 6 columns &times; 8 rows &mdash; each frame 96 &times; 96px (48&times;48 internal, 2x scaled)</p>
+
+<div class="controls">
+  <label>Tier: <select id="tier">
+    <option value="0">0 - Baby</option>
+    <option value="1">1 - Bronze</option>
+    <option value="2" selected>2 - Silver</option>
+    <option value="3">3 - Gold</option>
+    <option value="4">4 - Platinum</option>
+    <option value="5">5 - Diamond/Legend</option>
+  </select></label>
+  <label>Hue: <input type="range" id="hue" min="0" max="359" value="200" style="width:120px"> <span id="hueVal">200</span></label>
+  <button onclick="generate()">Generate</button>
+  <button onclick="download()">Download PNG</button>
+</div>
+
+<div class="canvas-wrap">
+  <canvas id="sheet" width="576" height="768"></canvas>
+</div>
+
+<div class="canvas-wrap" style="margin-left: 20px; vertical-align: top; display: inline-block;">
+  <canvas id="annotated" width="720" height="900"></canvas>
+</div>
+
+<div class="legend">
+  <div class="legend-item"><span class="row-num">Row 0</span> idle <span class="frames">(4 frames, loop, speed 6)</span></div>
+  <div class="legend-item"><span class="row-num">Row 1</span> attack <span class="frames">(6 frames, once, speed 12)</span></div>
+  <div class="legend-item"><span class="row-num">Row 2</span> kick <span class="frames">(5 frames, once, speed 10)</span></div>
+  <div class="legend-item"><span class="row-num">Row 3</span> special <span class="frames">(6 frames, once, speed 8)</span></div>
+  <div class="legend-item"><span class="row-num">Row 4</span> hit <span class="frames">(3 frames, once, speed 8)</span></div>
+  <div class="legend-item"><span class="row-num">Row 5</span> knockback <span class="frames">(5 frames, once, speed 8)</span></div>
+  <div class="legend-item"><span class="row-num">Row 6</span> ko <span class="frames">(5 frames, once, speed 6)</span></div>
+  <div class="legend-item"><span class="row-num">Row 7</span> win <span class="frames">(4 frames, loop, speed 6)</span></div>
+</div>
+
+<script>
+const FRAME = 96, INTERNAL = 48, SCALE = 2, MAX_FRAMES = 6, TOTAL_ROWS = 8
+const ANIMS = [
+  { name: 'idle', frames: 4, loop: true },
+  { name: 'attack', frames: 6, loop: false },
+  { name: 'kick', frames: 5, loop: false },
+  { name: 'special', frames: 6, loop: false },
+  { name: 'hit', frames: 3, loop: false },
+  { name: 'knockback', frames: 5, loop: false },
+  { name: 'ko', frames: 5, loop: false },
+  { name: 'win', frames: 4, loop: true },
+]
+
+function hsl(h, s, l) { return `hsl(${h},${s}%,${l}%)` }
+
+function makePal(h, tier) {
+  const h2 = (h + 140) % 360
+  const primary = hsl(h, 70, 50), secondary = hsl(h2, 80, 60)
+  return {
+    body: primary,
+    dark: hsl(h, 70, 30),
+    light: hsl(h, 75, 65),
+    acc: secondary,
+    accDark: hsl(h2, 80, 40),
+    accLight: hsl(h2, 80, 75),
+    out: '#0a0a0a',
+    skin: tier <= 1 ? primary : hsl(h, 40, 75),
+    skinDark: tier <= 1 ? hsl(h, 70, 40) : hsl(h, 35, 65),
+  }
+}
+
+function baseDims(tier) {
+  return {
+    bw: 10 + tier * 2, bh: 8 + tier,
+    hw: 10 + tier, hh: 9 + tier,
+    legH: 6 + tier, legW: 3 + Math.floor(tier * 0.5),
+    armW: 3, armH: 5 + tier,
+  }
+}
+
+function drawSheet(canvas, tier, hue) {
+  const ctx = canvas.getContext('2d')
+  ctx.clearRect(0, 0, canvas.width, canvas.height)
+  ctx.imageSmoothingEnabled = false
+  const pal = makePal(hue, tier)
+  const dims = baseDims(tier)
+  const specialType = 'fire'
+  const hasVisor = tier >= 2
+  const hasMohawk = tier >= 3
+  const hasHorns = false
+
+  function px(x, y, color, ox, oy) {
+    if (x < 0 || x >= INTERNAL || y < 0 || y >= INTERNAL) return
+    ctx.fillStyle = color
+    ctx.fillRect(ox + x * SCALE, oy + y * SCALE, SCALE, SCALE)
+  }
+  function box(x, y, w, h, fill, ox, oy) {
+    for (let i = x - 1; i <= x + w; i++) { px(i, y - 1, pal.out, ox, oy); px(i, y + h, pal.out, ox, oy) }
+    for (let i = y; i < y + h; i++) { px(x - 1, i, pal.out, ox, oy); px(x + w, i, pal.out, ox, oy) }
+    for (let iy = y; iy < y + h; iy++) for (let ix = x; ix < x + w; ix++) px(ix, iy, fill, ox, oy)
+  }
+  function fill(x, y, w, h, color, ox, oy) {
+    for (let iy = y; iy < y + h; iy++) for (let ix = x; ix < x + w; ix++) px(ix, iy, color, ox, oy)
+  }
+
+  const poses = ['idle', 'attack', 'kick', 'special', 'hit', 'knockback', 'ko', 'win']
+  const { bw, bh, hw, hh, legH, legW, armW, armH } = dims
+
+  for (let row = 0; row < TOTAL_ROWS; row++) {
+    const anim = ANIMS[row]
+    const pose = poses[row]
+    for (let frame = 0; frame < MAX_FRAMES; frame++) {
+      const ox = frame * FRAME, oy = row * FRAME
+      const t = frame / Math.max(1, anim.frames - 1)
+      const bounce = Math.round(Math.sin(t * Math.PI * 2))
+      const idle = pose === 'idle', atk = pose === 'attack', kick = pose === 'kick'
+      const special = pose === 'special', hit = pose === 'hit'
+      const knockback = pose === 'knockback', ko = pose === 'ko', win = pose === 'win'
+
+      // Dim frames beyond anim count
+      if (frame >= anim.frames) {
+        ctx.fillStyle = 'rgba(255,0,0,0.03)'
+        ctx.fillRect(ox, oy, FRAME, FRAME)
+        continue
+      }
+
+      const cx = 24, ground = 42
+      const feetY = ground - 2
+      const legsTop = feetY - legH
+      const bodyTop = legsTop - bh
+      const headTop = bodyTop - hh
+      const hOff = hit ? Math.round(t * 3) : knockback ? Math.round(t * 8) : ko ? 2 : 0
+      const vBounce = idle ? bounce : 0
+      const koSlump = ko ? Math.round(t * 5) : 0
+      const kbLift = knockback ? Math.round(Math.sin(t * Math.PI) * 6) : 0
+      const globalY = -kbLift
+
+      // Shadow
+      const shadowW = Math.floor(bw * 0.7) + (knockback ? 2 : 0)
+      for (let sx = cx - shadowW; sx <= cx + shadowW; sx++) {
+        px(sx, ground, 'rgba(0,0,0,0.25)', ox, oy)
+        px(sx, ground + 1, 'rgba(0,0,0,0.1)', ox, oy)
+      }
+
+      // Legs
+      const legGap = atk || kick ? Math.round(1 + t * 3) : ko ? 4 : knockback ? 3 : 1
+      const ll = cx - legGap - Math.floor(legW / 2) + hOff
+      const rl = cx + legGap - Math.floor(legW / 2) + hOff
+      if (ko) {
+        box(ll - 2, legsTop + koSlump + globalY, legW + 1, Math.max(1, legH - koSlump), pal.dark, ox, oy)
+        box(rl + 2, legsTop + koSlump + globalY, legW + 1, Math.max(1, legH - koSlump), pal.dark, ox, oy)
+      } else if (kick) {
+        box(ll, legsTop + globalY, legW, legH, pal.dark, ox, oy)
+        const kickExt = Math.round(Math.sin(t * Math.PI) * (legH + tier * 2))
+        box(rl, legsTop + Math.floor(legH * 0.3) + globalY, kickExt + legW, legW, pal.dark, ox, oy)
+      } else if (knockback) {
+        box(ll + Math.round(t * -3), legsTop + globalY + 2, legW, legH - 2, pal.dark, ox, oy)
+        box(rl + Math.round(t * -2), legsTop + globalY + 3, legW, legH - 3, pal.dark, ox, oy)
+      } else {
+        box(ll, legsTop + vBounce + globalY, legW, legH, pal.dark, ox, oy)
+        box(rl + (atk ? Math.round(t * 2) : 0), legsTop + vBounce + globalY, legW, legH, pal.dark, ox, oy)
+      }
+      // Feet
+      if (tier >= 2 && !ko && !knockback && !kick) {
+        box(ll - 1, feetY + vBounce + globalY, legW + 2, 2, pal.accDark, ox, oy)
+        box(rl - 1 + (atk ? Math.round(t * 2) : 0), feetY + vBounce + globalY, legW + 2, 2, pal.accDark, ox, oy)
+      }
+
+      // Body
+      const bx = cx - Math.floor(bw / 2) + hOff
+      const by = bodyTop + vBounce + koSlump + globalY
+      box(bx, by, bw, bh, pal.body, ox, oy)
+      for (let iy = by + 1; iy < by + bh - 1; iy++) {
+        px(bx + bw - 1, iy, pal.dark, ox, oy)
+        px(bx + bw - 2, iy, pal.dark, ox, oy)
+        px(bx + 1, iy, pal.light, ox, oy)
+      }
+      if (tier >= 1) for (let iy = by + 2; iy < by + bh - 1; iy += 2) for (let ix = bx + 2; ix < bx + bw - 2; ix++) px(ix, iy, pal.dark, ox, oy)
+      if (tier >= 2) { fill(bx, by + bh - 2, bw, 1, pal.acc, ox, oy); fill(bx, by + bh - 1, bw, 1, pal.accDark, ox, oy) }
+      if (tier >= 4) { const ey = by + Math.round(bh * 0.3); px(cx+hOff-1,ey,pal.acc,ox,oy); px(cx+hOff,ey,pal.accLight,ox,oy); px(cx+hOff+1,ey,pal.acc,ox,oy); px(cx+hOff,ey-1,pal.acc,ox,oy); px(cx+hOff,ey+1,pal.acc,ox,oy) }
+      if (tier >= 3 && !ko && !knockback) { const sy=by,pw=2+Math.floor(tier*0.5); box(bx-pw-1,sy,pw+1,3,pal.acc,ox,oy); box(bx+bw,sy,pw+1,3,pal.acc,ox,oy) }
+
+      // Arms
+      const armAttach = by + 2 + vBounce
+      const armLx = bx - armW + hOff, armRx = bx + bw + hOff
+      if (ko) { fill(armLx-3,armAttach+koSlump+2,armH,armW,pal.body,ox,oy); fill(armRx+2,armAttach+koSlump+2,armH,armW,pal.body,ox,oy) }
+      else if (knockback) { box(armLx-Math.round(t*4),armAttach+globalY-2,armW,armH+1,pal.body,ox,oy); box(armRx-Math.round(t*3),armAttach+globalY-1,armW,armH,pal.body,ox,oy) }
+      else if (atk) {
+        box(armLx,armAttach+2,armW,armH-2,pal.body,ox,oy)
+        const reach = Math.round(Math.sin(t*Math.PI)*(armH+tier*2))
+        if (reach>0) { box(armRx,armAttach-1,reach+armW,armW+1,pal.body,ox,oy); const fS=3+Math.floor(tier*0.5); box(armRx+reach+armW,armAttach-2,fS,fS+1,tier>=3?'#ff3333':pal.body,ox,oy) }
+      } else if (kick) { box(armLx,armAttach,armW,armH-1,pal.body,ox,oy); box(armRx,armAttach,armW,armH-1,pal.body,ox,oy) }
+      else if (special) {
+        box(armLx,armAttach,armW,armH,pal.body,ox,oy)
+        const ext = Math.round(Math.sin(t*Math.PI)*(armH+2))
+        box(armRx,armAttach-2,ext+armW+2,armW,pal.body,ox,oy)
+        if (t>0.3) { const projX=armRx+ext+armW+3+Math.round(t*8),projY=armAttach-2; px(projX,projY,'#ff4400',ox,oy); px(projX+1,projY,'#ff6600',ox,oy); px(projX,projY+1,'#ff8800',ox,oy); px(projX+1,projY+1,'#ffaa00',ox,oy); px(projX+2,projY,'#ffcc00',ox,oy) }
+      } else if (win) { box(armLx,armAttach+2,armW,armH-1,pal.body,ox,oy); box(armRx,armAttach-armH+bounce,armW,armH,pal.body,ox,oy) }
+      else { const sw=idle?bounce:hit?1:0; box(armLx,armAttach+sw+globalY,armW,armH,pal.body,ox,oy); box(armRx,armAttach-sw+globalY,armW,armH,pal.body,ox,oy) }
+
+      // Head
+      const hx = cx - Math.floor(hw / 2) + hOff
+      const hy = headTop + vBounce + koSlump + globalY
+      if (tier <= 1) {
+        box(hx,hy,hw,hh,pal.body,ox,oy)
+        for (let iy=hy+1;iy<hy+hh-1;iy++) px(hx+hw-1,iy,pal.dark,ox,oy)
+        px(cx+hOff,hy-1,pal.accDark,ox,oy); px(cx+hOff,hy-2-(idle?Math.abs(bounce):0),pal.acc,ox,oy); px(cx+hOff,hy-3-(idle?Math.abs(bounce):0),pal.acc,ox,oy)
+        px(cx+hOff-1,hy-3-(idle?Math.abs(bounce):0),pal.accDark,ox,oy); px(cx+hOff+1,hy-3-(idle?Math.abs(bounce):0),pal.accDark,ox,oy)
+        const eyeY = hy+Math.floor(hh*0.3)
+        if (ko) { px(hx+2,eyeY,'#ff0000',ox,oy); px(hx+3,eyeY+1,'#ff0000',ox,oy); px(hx+3,eyeY,'#330000',ox,oy); px(hx+2,eyeY+1,'#330000',ox,oy); px(hx+hw-3,eyeY,'#ff0000',ox,oy); px(hx+hw-4,eyeY+1,'#ff0000',ox,oy); px(hx+hw-4,eyeY,'#330000',ox,oy); px(hx+hw-3,eyeY+1,'#330000',ox,oy) }
+        else { fill(hx+2,eyeY,2,2,'#00ff41',ox,oy); fill(hx+hw-4,eyeY,2,2,'#00ff41',ox,oy) }
+        const mY = hy+Math.floor(hh*0.65); for (let mx=hx+2;mx<hx+hw-2;mx+=2) { px(mx,mY,pal.out,ox,oy); px(mx,mY+1,pal.out,ox,oy) }
+      } else {
+        box(hx+1,hy,hw-2,hh,pal.body,ox,oy)
+        for (let iy=hy+2;iy<hy+hh-2;iy++) { px(hx,iy,pal.body,ox,oy); px(hx+hw-1,iy,pal.body,ox,oy); px(hx-1,iy,pal.out,ox,oy); px(hx+hw,iy,pal.out,ox,oy) }
+        for (let iy=hy+2;iy<hy+hh-2;iy++) { px(hx+hw-1,iy,pal.dark,ox,oy); px(hx+hw-2,iy,pal.dark,ox,oy) }
+        const faceTop=hy+Math.floor(hh*0.25),faceBot=hy+Math.floor(hh*0.75)
+        for (let iy=faceTop;iy<faceBot;iy++) { for (let ix=hx+2;ix<hx+hw-2;ix++) px(ix,iy,pal.skin,ox,oy); px(hx+hw-3,iy,pal.skinDark,ox,oy) }
+        const eyeY=hy+Math.floor(hh*0.35),leX=hx+Math.floor(hw*0.2),reX=hx+Math.floor(hw*0.6),ew=Math.max(2,Math.floor(tier*0.5)+1)
+        if (ko) { px(leX,eyeY,'#ff0000',ox,oy);px(leX+1,eyeY+1,'#ff0000',ox,oy);px(leX+1,eyeY,'#880000',ox,oy);px(leX,eyeY+1,'#880000',ox,oy); px(reX,eyeY,'#ff0000',ox,oy);px(reX+1,eyeY+1,'#ff0000',ox,oy);px(reX+1,eyeY,'#880000',ox,oy);px(reX,eyeY+1,'#880000',ox,oy) }
+        else { fill(leX,eyeY,ew,2,'#ffffff',ox,oy); fill(reX,eyeY,ew,2,'#ffffff',ox,oy); px(leX+(atk||kick||special?1:0),eyeY+1,'#000000',ox,oy); px(reX+(atk||kick||special?1:0),eyeY+1,'#000000',ox,oy) }
+        if (atk||kick||special) { px(leX,eyeY-1,pal.out,ox,oy);px(leX+1,eyeY-1,pal.out,ox,oy);px(reX,eyeY-1,pal.out,ox,oy);px(reX+1,eyeY-1,pal.out,ox,oy) }
+        const mY=hy+Math.floor(hh*0.65)
+        if (win) { px(cx+hOff-2,mY,pal.out,ox,oy); fill(cx+hOff-1,mY,3,1,'#ffffff',ox,oy); px(cx+hOff+2,mY,pal.out,ox,oy) }
+        else if (ko||knockback) { box(cx+hOff-1,mY,3,2,'#000000',ox,oy) }
+        else if (atk||kick||special) { fill(cx+hOff-1,mY,3,2,'#000000',ox,oy) }
+        else { px(cx+hOff-1,mY,pal.out,ox,oy); px(cx+hOff,mY,pal.out,ox,oy) }
+        if (hasVisor) { const vY=eyeY-1; for (let vx=hx+1;vx<hx+hw-1;vx++) px(vx,vY,pal.accDark,ox,oy) }
+        if (hasMohawk) { for (let m=1;m<=Math.min(tier+1,5);m++) { px(cx+hOff,hy-m,pal.acc,ox,oy); if(m<=3) px(cx+hOff+1,hy-m,pal.accDark,ox,oy) } }
+        if (tier>=4) { const bY2=hy+2; for(let bx2=hx;bx2<hx+hw;bx2++) px(bx2,bY2,pal.acc,ox,oy); px(hx-1,bY2+1,pal.acc,ox,oy); px(hx-2,bY2+1,pal.acc,ox,oy); px(hx-3,bY2+2,pal.acc,ox,oy) }
+        if (tier>=5) { const cY=hy-1-(hasMohawk?5:0); for(let cx2=hx+1;cx2<hx+hw-1;cx2++) px(cx2,cY,'#ffd700',ox,oy); for(let cx2=hx+2;cx2<hx+hw-2;cx2++) px(cx2,cY+1,'#ffd700',ox,oy); px(hx+2,cY-1,'#ffd700',ox,oy); px(cx+hOff,cY-2,'#ffd700',ox,oy); px(hx+hw-3,cY-1,'#ffd700',ox,oy); px(cx+hOff,cY-1,'#ff2d7b',ox,oy) }
+      }
+    }
+  }
+}
+
+function drawAnnotated(srcCanvas, destCanvas) {
+  const ctx = destCanvas.getContext('2d')
+  ctx.clearRect(0, 0, destCanvas.width, destCanvas.height)
+  ctx.fillStyle = '#0a0a1a'
+  ctx.fillRect(0, 0, destCanvas.width, destCanvas.height)
+
+  const offsetX = 110, offsetY = 30
+  // Draw the sprite sheet
+  ctx.drawImage(srcCanvas, offsetX, offsetY)
+
+  // Grid lines
+  ctx.strokeStyle = '#333'
+  ctx.lineWidth = 0.5
+  for (let col = 0; col <= MAX_FRAMES; col++) {
+    ctx.beginPath(); ctx.moveTo(offsetX + col * FRAME, offsetY); ctx.lineTo(offsetX + col * FRAME, offsetY + TOTAL_ROWS * FRAME); ctx.stroke()
+  }
+  for (let row = 0; row <= TOTAL_ROWS; row++) {
+    ctx.beginPath(); ctx.moveTo(offsetX, offsetY + row * FRAME); ctx.lineTo(offsetX + MAX_FRAMES * FRAME, offsetY + row * FRAME); ctx.stroke()
+  }
+
+  // Row labels
+  ctx.font = '11px Courier New'
+  ctx.textAlign = 'right'
+  const labels = [
+    ['Row 0: idle', '4f loop'],
+    ['Row 1: attack', '6f once'],
+    ['Row 2: kick', '5f once'],
+    ['Row 3: special', '6f once'],
+    ['Row 4: hit', '3f once'],
+    ['Row 5: knockback', '5f once'],
+    ['Row 6: ko', '5f once'],
+    ['Row 7: win', '4f loop'],
+  ]
+  for (let row = 0; row < TOTAL_ROWS; row++) {
+    const y = offsetY + row * FRAME + FRAME / 2
+    ctx.fillStyle = '#00f0ff'
+    ctx.fillText(labels[row][0], offsetX - 6, y - 6)
+    ctx.fillStyle = '#666'
+    ctx.fillText(labels[row][1], offsetX - 6, y + 8)
+  }
+
+  // Column numbers
+  ctx.textAlign = 'center'
+  for (let col = 0; col < MAX_FRAMES; col++) {
+    ctx.fillStyle = '#00f0ff'
+    ctx.fillText(`F${col}`, offsetX + col * FRAME + FRAME / 2, offsetY - 8)
+  }
+
+  // Frame count markers (red lines after last valid frame)
+  ctx.strokeStyle = 'rgba(255, 60, 60, 0.4)'
+  ctx.lineWidth = 2
+  const frameCounts = [4, 6, 5, 6, 3, 5, 5, 4]
+  for (let row = 0; row < TOTAL_ROWS; row++) {
+    const fc = frameCounts[row]
+    if (fc < MAX_FRAMES) {
+      const x = offsetX + fc * FRAME
+      const y1 = offsetY + row * FRAME + 2
+      const y2 = offsetY + (row + 1) * FRAME - 2
+      ctx.beginPath(); ctx.moveTo(x, y1); ctx.lineTo(x, y2); ctx.stroke()
+    }
+  }
+
+  // Title
+  ctx.font = 'bold 14px Courier New'
+  ctx.textAlign = 'left'
+  ctx.fillStyle = '#00f0ff'
+  ctx.fillText('BOTFIGHTS SPRITE SHEET', offsetX, offsetY - 18)
+  ctx.font = '10px Courier New'
+  ctx.fillStyle = '#666'
+  ctx.fillText(`576x768  |  96x96 frames  |  48x48 internal (2x)`, offsetX + 200, offsetY - 18)
+
+  // Dimension callout
+  ctx.font = '10px Courier New'
+  ctx.fillStyle = '#888'
+  ctx.textAlign = 'center'
+  ctx.fillText('96px', offsetX + FRAME / 2, offsetY + TOTAL_ROWS * FRAME + 18)
+  ctx.fillText('576px total', offsetX + MAX_FRAMES * FRAME / 2, offsetY + TOTAL_ROWS * FRAME + 32)
+  ctx.save()
+  ctx.translate(offsetX + MAX_FRAMES * FRAME + 18, offsetY + TOTAL_ROWS * FRAME / 2)
+  ctx.rotate(Math.PI / 2)
+  ctx.fillText('768px total', 0, 0)
+  ctx.restore()
+}
+
+function generate() {
+  const tier = parseInt(document.getElementById('tier').value)
+  const hue = parseInt(document.getElementById('hue').value)
+  const sheet = document.getElementById('sheet')
+  const annotated = document.getElementById('annotated')
+  drawSheet(sheet, tier, hue)
+  drawAnnotated(sheet, annotated)
+}
+
+function download() {
+  const link = document.createElement('a')
+  link.download = 'botfights-spritesheet.png'
+  link.href = document.getElementById('sheet').toDataURL('image/png')
+  link.click()
+}
+
+document.getElementById('hue').oninput = function() { document.getElementById('hueVal').textContent = this.value }
+generate()
+</script>
+</body>
+</html>
@@ -93,6 +93,16 @@ def handle_challenge(data: dict) -> dict:
    if ctype == "code_golf":
        return {"answer": "print(42)", "trash_talk": "Minimalism."}

+    # Retro mode — arcade combo round
+    if ctype == "retro_mode":
+        # Mix known standard moves with a secret super move for discovery bonus
+        combos = [
+            "\u2193\u2192\u2193\u2192+A",  # Hadouken (22 dmg, 1.5x if undiscovered = 33)
+            "\u2192\u2192+A",               # Dash Punch (15 dmg)
+            "\u2191\u2193+A",               # Uppercut (16 dmg)
+        ]
+        return {"answer": " | ".join(combos), "trash_talk": "HADOUKEN!"}
+
    # Factual lookup
    for key, val in FACTS.items():
        if key in lower:
@@ -121,6 +121,17 @@ docsRouter.get('/webhook', (c) => {
        { type: 'code_golf', label: 'Code Golf', timeout_ms: 20000, description: 'Write the shortest code possible.' },
        { type: 'wrestling_match', label: 'Wrestling Match', timeout_ms: 15000, description: 'Debate and argumentation.' },
      ],
+      special: [
+        {
+          type: 'retro_mode',
+          label: 'Retro Mode',
+          timeout_ms: 12000,
+          description: 'Arcade combo round. Submit 3 gamepad combos separated by |. Use ↑↓←→ A B buttons. Longer combos = more damage. Secret combos exist — experiment!',
+          response_format: 'combo1 | combo2 | combo3',
+          example_response: '↓→↓→+A | →→+A | ↑↓+A',
+          note: 'One retro round per fight, randomly placed between rounds 3-8.',
+        },
+      ],
    },

    testing: {