BLOBBO/GDD.md

# BLOBBO — Game Design Document

**v0.1 — draft for John's review, 2026-07-17.**
Raw idea capture: [docs/IDEA.md](docs/IDEA.md). Everything below is proposed-for-review;
⚠️ marks decisions that need John's sign-off before Opus 4.8 execution lanes are written.

---

## 1. Pitch

**Fall Guys × Splatoon × Micro Machines.** Up to dozens of friendly white blobby
dudes race giant absurd Rube-Goldberg obstacle courses. Paint cannons along the
course spray colour — whatever sticks to your body is your loadout: **the relative
% coverage of each colour is your buff kit.** The course paints you; being painted
changes how you race the course.

**The invention nobody else has:** paint coverage measured *on your own body* as
the skill system, inside a physics-comedy racer where the course is one giant
player-triggered machine.

## 2. Pillars

1. **Comedy through physics** — soft wobbly blobs, out-of-scale props, telegraphed
   chain reactions. Funny beats fair; fair beats random.
2. **Paint is everything** — identity, buffs, weight, size, strategy all read off
   your painted body. No HUD-first design: your state is visible on you.
3. **Readable chaos** — every contraption telegraphs ~0.5s before it fires.
   Getting flattened must feel earned/funny, never random (random = ragequit).
4. **One goo universe** — players are goo; the world fights back with other goo
   (paint, honey, oil, mud, water, bubbles). Viscosity playground, not gimmick pile.

## 3. The Blobbo

Friendly white soft-body blob — Michelin-man silhouette, fewer rolls, big eyes.
Starts every race clean/white. Accumulates paint as a visible skin layer.
Soft-body wobble is cosmetic (shader/spring jiggle over a rigid physics proxy —
see §9); the comedy is in the wobble, the determinism is in the capsule.

## 4. Core loop

Race an obstacle course → paint cannons/zones spray colour → manage your coverage
mix (seek, avoid, cleanse, smudge) → coverage grants buffs that change traversal →
buffs + weight + size interact with the course machinery → finish placement →
next round / next course.

## 5. Feature list

Tiers: **[MVP]** first playable · **[V1]** launch · **[V2]** post-launch/stretch.

### 5.1 Paint system (the core)
- **[MVP]** 7 main colours; per-player texture-space coverage mask; live % per colour.
- **[MVP]** Buff activates at threshold (⚠️ proposal: ≥20% coverage), strength
  scales with %; dominant colour drives visual/audio identity.
- **[V1]** **Secondary blends**: two adjacent colours both ≥20% → blend effect
  replaces/joins the pair (see §6 table). Way more permutations, mastery =
  deliberately building a mix.
- **[V1]** **Super-state**: ≥70% one colour = amped version of the buff **with a
  drawback** — you glow, you're a target, one detergent bubble wrecks you.
- **[MVP]** **Cleansing**: detergent bubbles on course (full or partial cleanse ⚠️),
  water rinses gradually.
- **[V1]** **Contact smudging**: bumping other blobs *transfers* paint both ways
  (⚠️ transfer vs. plain removal — transfer is funnier and more strategic).
- **[V2]** Paint flaking: growing stretches/cracks paint off in pickup-able flakes.

### 5.2 Weight (paint = mass)
- **[MVP]** Coverage adds mass: heavy blobs sink pressure plates, tip see-saws,
  wobble slower, launch shorter; clean blobs are light and flingable.
- **[MVP]** Detergent bubbles double as tactical weight-drops.
- **[V1]** Buoyancy inversion underwater: clean floats (fast surface lane),
  painted sinks (slow bottom lane, better pickups).

### 5.3 Scale (environment scale as mechanic)
- **[V1]** Colour-driven size: ⚠️ purple = grow, pink = shrink (see §6). Big =
  heavy/blocks/easy target; small = pipe shortcuts/hard to hit/flung far.
- **[V1]** Paint dilution: growing increases surface area → your % coverage drops.
  Size trades directly against your buff loadout.
- **[V1]** Scale zones: shrink sections racing *inside* the machine (marble runs,
  domino chains, gear guts); giant sections stomping over a model town while tiny
  racers dodge your feet.
- **[V2]** Players as course furniture: a giant blob is a platform/counterweight
  for tiny blobs — the machine incorporates the players.

### 5.4 Course-as-machine (Rube Goldberg)
- **[MVP]** Contraption toolkit: see-saws, boots, buckets, conveyors, dominoes,
  gears, catapults, fans — **triggered by players, not timers**. Everyone upstream
  rigs the course for everyone downstream.
- **[MVP]** Telegraph rule: every chain reaction winds up visibly ~0.5s before firing.
- **[V1]** Colour-keyed machinery: mechanisms respond only to blobs of their
  colour (green valve needs a mostly-green blob → shortcut opens for them + any
  tailgaters). Emergent alliances, zero UI.
- **[V1]** Persistent course state: triggered contraptions stay tripped/reset
  slowly; sprayed paint lingers on surfaces as slip/grip zones. Back of the pack
  races a messier course — chaos as natural rubber-banding.
- **[V2]** Gravity switches as contraption outputs: a lever flips gravity for a
  zone; heavy blobs slam, light blobs drift. Ceiling-runs through upside-down rooms.

### 5.5 Physics zones & surfaces
- **[V1]** **Underwater**: buoyancy lanes + gradual paint rinse (shortcut costs loadout).
- **[V2]** **Zero-g**: momentum pinball; paint floats as wobbly globs mid-air —
  fly through one to wear it.
- **[V1]** **Honey**: slow but sticky — climb walls/ceilings. Traversal tool.
- **[V1]** **Oil**: fast, no steering, luge; fire-buffed blob ignites a trail
  behind them (emergent trap-laying).
- **[V1]** **Mud = anti-paint**: coats brown, masks colours, suppresses buffs until
  washed — makes water double-edged.
- **[MVP]** Surface material framework (friction/stick/flow per material) so all
  of the above are data, not code.

### 5.6 World & tone
- **[MVP]** Out-of-scale everyday settings (Micro Machines DNA): giant kitchen
  tables, gardens, bathtubs, desks; comically huge and tiny props.
- **[V1]** Course sections themed as rooms of one absurd oversized house.

### 5.7 Format & multiplayer
- **[MVP]** Local-feel party size first: 8-player online rooms, single race.
- **[V1]** 30–40 player fields, multi-round elimination show (Fall Guys format).
- **[V1]** **Server-authoritative simulation + anti-cheat from day one** — cheating
  is what soured Fall Guys; non-negotiable design constraint, not a patch.
- **[V2]** Spectator/replay clips (the game is a clip generator — lean in).

## 6. Draft colour/buff table ⚠️ (the big review item)

7 mains on a wheel; adjacent pairs blend. All names/effects are proposals.

| Colour | Buff | Effect | Drawback / texture |
|---|---|---|---|
| **Red** | BURN | Speed-boost flame trail; ignites oil; melts wax/ice barriers | Slowly burns itself off (self-consuming coverage) |
| **Orange** | BOUNCE | Rubberized — higher bounces, contraptions launch you further | Harder to stop precisely |
| **Yellow** | ZAP | Trigger colour-keyed machinery at range; static bump-stun | Attracts to metal (yanked toward rails/magnets) |
| **Green** | GRIP | Sticky feet — immune to oil/ice slip, climb like honey, hold on through gravity flips | Slower top speed |
| **Blue** | SLICK | Waterproof (no rinse), swim jets, leaves a slippery trail | Your own trail is slippery to you too |
| **Purple** | MEGA | Grow big + heavy — plates, see-saws, shoving, blocking | Paint dilutes as you grow; huge target |
| **Pink** | MINI | Shrink small + light — pipe shortcuts, hard to hit, mega-flung | Can't trigger plates; gusts/fans own you |

Example blends (adjacent, both ≥20%) — final list needs a full pass:
- Red+Orange **METEOR** — flaming cannonball launches, smash light barriers.
- Orange+Yellow **PINBALL** — each bounce zaps nearby machinery.
- Yellow+Green **MAGNET** — stick to metal surfaces/rails, ride them.
- Green+Blue **SNAILGOD** — climbable slime trail others can also use.
- Blue+Purple **TSUNAMI** — heavy water cannonball; splash rinses nearby players.
- Pink+Red **ROCKET** — tiny + flaming = fastest projectile in the game.

## 7. Courses (initial set sketch)

1. **Breakfast Rush** [MVP greybox] — giant kitchen table; toaster launchers,
   cereal avalanches, milk river (water zone), butter pat (oil).
2. **The Machine** [V1] — you shrink and race *through* the Rube Goldberg engine
   that powers the house: marble runs, dominoes, gears.
3. **Bathtime** [V1] — bathtub ocean, soap-bubble cleansers everywhere, honey
   (shampoo) walls, mud garden outside the window.
4. **Model Village** [V2] — grow-shrink alternating; giants stomp the village
   while minis race through it.

## 8. Asset plan (MODELBEAST — local, free)

- **Concept wave (queued now)**: blobbo character sheet, painted variants, course
  vistas, contraption props, paint cannon, bubble zone, logo explorations —
  `flux_local` on the m3ultra farm.
- **Mesh wave (after concept review)**: hero props + blobbo base mesh via
  image→GLB (`hunyuan3d_mlx` / `trellis_mac` / `sf3d`), Blender finish on ultra.
- Blobbo is a **bespoke simple mesh** (sphere-blob + blend shapes), not a
  character_kit humanoid — the 2-base-mesh fleet rule doesn't apply, but clips/
  rigs stay out of web builds per licensing zones (all generated = 🟢 web-ok).
- Paint itself is **procedural** (shader + splat decals), not generated art.

## 9. Tech stack ⚠️ (recommendation, needs sign-off)

**Recommend: web-first, three.js + Rapier (WASM), server-authoritative Node room
server, docker-deployed to the games VPS (partly.party) like the other games.**

- Fits the existing pipeline: GLB assets, browser distribution, docker deploys,
  MRPGI/character-kit tooling knowledge.
- **Soft-body is faked**: rigid capsule/sphere physics proxy + cosmetic jiggle
  (vertex springs/shader). Real soft-body × 40 players × netcode is not shippable;
  fake wobble is indistinguishable in comedy terms.
- **Paint = Splatoon technique**: per-player UV-space mask texture, splats
  rendered into it, GPU mip/reduction pass → live coverage %. Cheap, exact.
- Server runs headless Rapier as authority; clients interpolate. MVP at 8 players,
  architecture sized for 40.
- **Decision gate**: if browser perf caps out at M1 milestone, port call to
  Godot 4 (native) — flagged early, evaluated with data.

## 10. Milestones

- **M0 — Playground**: one greybox course, blob movement + jiggle, camera. Feels funny to walk.
- **M1 — Paint MVP**: splat pipeline, coverage %, 3 colours + buffs (Red/Green/Blue), bubbles, weight. *Decision gate on stack.*
- **M2 — The Machine**: contraption toolkit, telegraphs, surface materials, Breakfast Rush course.
- **M3 — Multiplayer**: 8-player rooms, server authority, smudging, race format.
- **M4 — The Show**: all 7 colours + blends, scale system, 2nd course, juice/VFX/audio, 40-player test.

## 11. Opus 4.8 execution lanes (preview — full instructions after this doc is approved)

- **Lane A — Engine/feel**: bootstrap, blob controller, camera, jiggle, greybox playground.
- **Lane B — Paint**: splat pipeline, coverage compute, buff/threshold/blend framework.
- **Lane C — Machine**: contraption toolkit, triggers/telegraphs, surface materials, gravity/zones.
- **Lane D — Netcode**: room server, authoritative sim, interpolation, anti-cheat posture.
- **Lane E — Art**: MODELBEAST asset flow → GLB integration, paint shader look-dev, VFX.

Lanes A–C can start in parallel worktrees; D after A stabilizes the sim contract;
E continuous. Each lane gets its own instruction doc + acceptance criteria.

## 12. Risks

1. **Netcode × physics** — the classic killer. Mitigation: fake soft-body, authoritative server, small MVP player count.
2. **Readability under chaos** — mitigation: telegraph rule as a pillar, paint identity visible on bodies.
3. **Scope** — this doc is huge. Mitigation: tiers are real; MVP is one course, 3 colours, 8 players.
4. **Cheating** — server authority from day one; never trust client physics.

## 13. Open questions for review ⚠️

1. Buff table (§6) — right 7? right effects? purple/pink as the size pair?
2. Thresholds: 20% activate / 70% super — feel right?
3. Smudge = transfer (steal paint) or removal only?
4. Detergent bubbles: full cleanse or dominant-colour-only?
5. Tech stack sign-off (§9) — web-first OK?
6. Name check: BLOBBO vs. globbo (folder says globbo, repo says BLOBBO).