# Blob Heist — Game Design Document

> A 3-minute top-down extraction roguelite for Elysium (Hyperliquid L2).
> Blob, the permanently unimpressed mascot of Elysium, robs the vaults of "The Exchange" while Purr, Hyperliquid's cat, talks him through it from the vents. Grab loot, dodge security bots, and decide: **extract now, or go one floor deeper?**
>
> Tagline: *Robs every vault. Enjoys none of it.*

## 1. Pitch

| | |
|---|---|
| Genre | 2D top-down extraction roguelite (stealth + risk/reward) |
| Session | 1–3 minutes per run |
| Platform | Web (desktop + mobile), wallet optional |
| Chain | Elysium (Kinetiq, Arbitrum Orbit L2 settling to HyperEVM), gas in HYPE |
| Inspiration | Extraction tension of Hyperion, distilled to a format a small team can ship |
| Tone | Cartoon, cheeky, crypto-meme humor (bots shaped like bulls and bears, "liquidation" alarms) |

**Why it wins on Elysium:** Hyperion proved the "risk more, extract more" loop resonates with traders, but a full isometric ARPG is expensive and slow. Blob Heist keeps the same emotion (greed vs. safety) in runs short enough to play between trades, starring two mascots the Hyperliquid and Elysium community already knows: Blob (Elysium's official mascot) and Purr (Hyperliquid's cat).

**Characters:**
- **Blob** (player): turquoise plush, half-closed eyes, flat red mouth, small black thief mask. Lore from blobmeme.com: "Goes everywhere. Enjoys nothing." His face never changes, whatever happens.
- **Purr** (advisor): white cat with light blue stripes and a headset. Lives in the vents and talks Blob through every run with contextual tips, plus lines on the hatch and end screens.
- **IP note:** both characters belong to their creators. Before any commercial launch, get permission from the Blob/Elysium and Purr/Hyperliquid communities or teams, and keep the "independent fan game" disclaimer.

## 2. Core loop

```
Enter floor -> sneak & loot -> reach the hatch -> CHOICE
                                                  |-- Extract: bank the bag (safe)
                                                  '-- Go deeper: x1.5 loot value, more bots, less time
Caught by a bot or timer hits 0 -> lose the whole bag
```

### Moment-to-moment
- **Move** with WASD / arrows / virtual joystick.
- **Dash** (Space): short burst, 3 s cooldown. Escapes a chase.
- **Smoke bomb** (E): 1 per floor. Blinds bots in a radius for 3 s.
- **Loot** by walking over it: coins (1), gems (5), golden HYPE bars (20).
- **Bag weight:** every item slows you down a bit. Greed is literally heavy.

### Security bots
- **Bull bot** — patrols a route with a vision cone. Charges when it sees you.
- **Bear bot** (floor 3+) — slower, wider cone, stops to scan.
- Detection fills a meter; at full the bot chases. A chasing bot that touches you catches you.
- Walls block vision (raycast), so line of sight matters.

### Keycard
Each floor hides a **keycard** in a random room. The hatch stays **locked** until you grab it, so you can't rush to the deep, high-multiplier floors without exploring each one.

### Getting caught
- Only a bot that is **chasing** you can catch you.
- Bumping into an unaware bot startles it instead: it turns, gets a 0.7 s stun, then chases. You get a head start, not an instant loss.
- A chasing bot gives up after 3 s without seeing you.
- Bots can't detect you for the first 2 s of each floor, and never start in rooms close to your spawn.

### Escalation per floor
| Floor | Bots | Detection speed | Loot multiplier | Time |
|---|---|---|---|---|
| 1 | 2 | 0.60x | x1.0 | 55 s |
| 2 | 3 | 0.68x | x1.5 | +32 s |
| 3 | 4 (bears appear) | 0.76x | x2.25 | +29 s |
| 4 | 5 | 0.84x | x3.4 | +26 s |
| 5+ | +1 each (max 8) | +0.08x per floor (max 1.3x) | x1.5 per floor | -3 s per floor (min 20 s) |

A global timer ("the police are coming") makes waiting for perfect patrols costly. Leftover time carries over, but the timer never banks more than 75 s.

A full bag slows you by up to 38% (0.7% per weight unit), so after a greedy floor a chasing bull is faster than you and you need the dash or the smoke bomb.

All of these values live in the `TUNING` object at the top of the script in `index.html`.

### Measured difficulty
`tools/autopilot.js` plays 80 runs per policy with a bot that ignores enemies (worst case, a real player who sneaks does better):

| Policy | Clears floor 1 | 2 | 3 | 4 | 5 | 6 |
|---|---|---|---|---|---|---|
| Greedy (loots everything nearby) | 88% | 48% | 14% | 6% | 3% | 1% |
| Rush (keycard then hatch, no loot) | 100% | 96% | 88% | 61% | 35% | 25% |

Greedy players lose about half their runs on floor 2, which is the "one more floor?" tension we want. Rushing is safe, but it ends with an almost empty bag, so it scores close to nothing.

Run it in the browser console with the game open: `await eval(await fetch('/tools/autopilot.js').then(r => r.text()))`.

## 3. Modes

1. **Practice (free, off-chain):** play any time, local best score. Onboarding funnel.
2. **Ranked run (paid):** pay an entry fee in HYPE (e.g. 0.05). The extracted bag becomes season points.
3. **Season pool (weekly):** ranked entry fees (minus protocol fee) form the prize pool, split by share of season points among the top 100.

Optional later: **no-loss seasons** funded by kHYPE staking yield instead of fees (less regulatory risk, ties into Kinetiq).

## 4. On-chain design

| Element | Where | How |
|---|---|---|
| Entry fee + season pool | On-chain (Elysium contract) | `enterRanked()` escrows HYPE, emits runId |
| Level seed | On-chain | Commit-reveal: contract commits `hash(serverSeed)`, player adds `clientSeed`; the floor layout comes from `keccak(serverSeed, clientSeed, floor)` |
| Gameplay | Off-chain (client) | Deterministic simulation from the seed |
| Run verification | Server replays inputs | Client sends an input log; server re-simulates deterministically and signs the result |
| Result submission | On-chain | `submitRun(runId, score, sig)` records season points |
| Payout | On-chain | `claimSeason(seasonId)` pulls the share |
| Cosmetics (optional) | NFT | Blob outfits / bags. **Cosmetic only, no pay-to-win** |

Use the Frog Flip lesson: **deposit once, play with no wallet popups** (session balance in the contract).

### Implemented
- **Contract:** `contracts/BlobHeist.sol` compiles with solc 0.8.24. It is unaudited and not deployed.
  - Seasons with seed commit and reveal
  - `enterRun` (payable, emits `runSeed`)
  - `submitRun` with a verifier signature (EIP-191, low-s check)
  - Proportional `claim`
  - Protocol fee capped at 15%
  - No admin withdrawal from the prize pool
- **Wallet:** `js/wallet.js` discovers wallets with EIP-6963, adds or switches to Elysium (99901, testnet 99801), shows the HYPE balance and auto-reconnects. The menu has copy address, explorer link, a testnet/mainnet switch and disconnect.
- **Game page:** practice or ranked mode.
  - Ranked pays `enterRun`, seeds the level from the `RunEntered` event and sends the run to `verifierUrl`.
  - Any run can be signed with `personal_sign`, which is free and sends nothing on-chain.
  - Runs are stored locally and listed on the landing page under "Your runs".
- **Landing page:**
  - live block number from the public RPC
  - season pool and leaderboard read from contract events once an address is configured
  - honest empty states until then

## 5. Economy guardrails
- No "guaranteed returns". Rewards depend only on skill and pool size.
- Protocol fee: 5–10% of entry fees.
- Anti-bot: deterministic replay verification + rate limit per wallet.
- Check the gambling rules per country before launching paid mode; consider the kHYPE no-loss version as the default.

## 6. Art direction
- Top-down cartoon, thick outlines, warm vault lighting against a dark navy floor.
- Blob: turquoise pear-shaped plush, half-closed bored eyes, flat red mouth, black thief mask and a loot sack that grows with the bag. He jiggles when he walks and stretches when he dashes.
- Purr: white cat, light blue stripes, pink ears, black headset.
- Bots: chunky robots with bull horns / bear ears and red/amber vision cones.
- Juice: screen shake on alarm, coin pop text, a sack that bulges, siren color pulses in the last 20 s.
- Copy voice: short and cheeky ("bag secured", "rekt by a bull bot", "one more floor?").

### Implemented in the prototype
- **Key art:** `images/key-art-blob.png` (Nano Banana, made from the Blob and Purr references in `images/ref/`) is the title screen background and the social preview image.
- **Portraits:** `portrait-blob`, `portrait-purr`, `portrait-bull-bot`, `portrait-bear-bot`, plus `purr-avatar` for the tip bubbles and `logo-blob` for the brand mark.
- **Level art** is drawn by code and pre-rendered once per floor. Each room gets a style:
  - Vault: marble floor, deposit-box wall, round safe door
  - Office: carpet, desk with a monitor, plant
  - Server: tech grid floor, racks with LEDs
  - Cash: warm marble, stacks of banknotes

  Walls have a top cap, a brick front face and contact shadows on the floor.
- **Lighting:** a darkness layer with holes cut out for room lamps, Blob, the keycard, the hatch, valuable loot and the bots' flashlight cones. It turns reddish when time is running out.
- **Sprites** match the key art, all with dark outlines:
  - Blob: drawn in code with the dip on top, clasped hands, thief mask, bored eyes, red mouth, stubby feet, jelly wobble and a dash stretch.
- **Purr advisor:** a bubble with Purr's avatar pops up during play, with a chirp. It triggers on:
  - floor start, and when bears first appear
  - a curious bot, a chase, a bump, losing a pursuer
  - a heavy sack, the keycard, a locked hatch
  - smoke, low time, and standing idle

  Purr also gives advice on the hatch screen and a verdict on the end screen.
  - Bots: tank treads, bull horns or bear ears, a glowing visor that changes colour with alert level, and a siren that flashes while chasing.
- **Juice:** footstep dust, a dash trail, sparkles on gems, bars and the keycard, and outlined floating text.

## 6b. Sound
All sound is synthesized live with WebAudio, so there are no audio files.
- **SFX:** coin, gem, gold bar, keycard, dash, smoke bomb, bot alert, bump, locked hatch, hatch reached, go deeper, extract fanfare, caught, police siren, footsteps.
- **Music:** a sneaky minor-key loop with three intensity modes, driven by game state:
  - `sneak`: the default
  - `chase`: any bot is chasing you; faster, with driving hi-hats
  - `panic`: under 20 s left; fastest, with a siren lead
- **Mute:** the `M` key or the on-screen button, remembered between visits.

## 7. Prototype scope (this repo)
`index.html` is a single-file, playable off-chain prototype:
- Procedural floors (rooms + corridors) from a seed
- Blob movement, dash, smoke bomb, weight slowdown
- Bull/bear bots with patrols, vision cones, wall raycasts, chase
- Loot, keycard, timer, hatch with an Extract / Go deeper choice
- Central `TUNING` config + `tools/autopilot.js` difficulty simulator
- Score screen + local best

- Final-style art pass, lighting and synthesized sound/music (see sections 6 and 6b)

Not included yet: wallet, contracts, server verification.

## 8. Roadmap
1. Prototype -> playtest feel and difficulty (now)
2. Final art pass (sprites) + sound (done in the prototype)
3. Deterministic sim + input-log replay verifier
4. Elysium contracts (entry, commit-reveal seed, season pool) on testnet
5. Ranked beta + weekly season
6. Mainnet launch, cosmetics, kHYPE no-loss seasons