mollycool/BUILD_PLAN.md

# Molly Cool — Vertical Slice Build Plan

**For the executing agent (Opus 4.8). Read this whole file before writing code.**

You are building a playable **2D browser prototype** of the first ten minutes of *Molly Cool*. This is a **feel-first vertical slice**: the entire point is to prove that the core mechanics are *fun to hold a controller for*. If the moment-to-moment feel isn't satisfying, nothing else matters. Prioritize game feel over completeness at every fork.

This is **not** a science app. There is no real chemistry validation, no accuracy requirement, no molecule database, no pedagogy. "Protons," "charge," "bonds," "acidity" are flavor for mechanics — nothing more. Do not add educational text, quizzes, or explanations. **The game teaches entirely through play, with zero words on screen.**

---

## 1. The design in one screen

Molly is a nanoscale character in a permanently shaking fluid world. She has two hands:

- **Give** — push a proton into a thing → it goes **positive** (hot pink).
- **Take** — rip a proton out → it goes **negative** (cyan).
- Leave it alone → **neutral** (dim gray-white), and it drifts free.

From those two verbs everything follows:

- **Opposites attract, likes repel.** Charged things lunge at their opposite and stick.
- **Bonds** aren't built with a button — you *drag two atoms together, wrestle them through the resistance, and let go.* They snap. Big juice.
- **The membrane wall** blocks anything charged and ignores anything neutral. No guard, no switch — you get through by *becoming neutral*.
- **Zones** (sour / soapy / neutral) re-tune your hands: a sour zone keeps shoving things positive, so neutral won't stay neutral; soapy drains charge away.
- **Heat** shakes everything in a radius (crowbar). **Light** flips one thing (scalpel). Some setups react to them in *opposite* directions.

**The heist:** you're too small to open doors, so you change what things *are*. Strip a thing neutral → it drifts through the wall → the sour room on the far side charges it back up → now it's trapped. You never opened the vault. You made the loot un-leavable.

---

## 2. Non-negotiable pillars

1. **The snap must feel incredible.** The bond hold-and-release (§8) is the heartbeat of the game. Spend disproportionate effort here. If you only get one thing feeling perfect, make it this.
2. **Zero on-screen text during play.** No tutorials, no labels, no tooltips. Every lesson is a thing that happens to the player. (A single title card at the start and an end card are fine.)
3. **Two buttons carry the whole game.** Give + Take, plus Grab, plus two openers (Heat, Light). Resist adding mechanics. Depth comes from combining these, not from more verbs.
4. **The world is always alive.** Everything jitters constantly (Brownian shimmer). Nothing sits perfectly still, including Molly at rest. No coasting — there's drag on everything.
5. **Readable at a glance.** Charge state is legible instantly by both **color AND shape** (see §6), so it reads even for colorblind players and even in motion.

---

## 3. Explicit non-goals (do not build these)

- No 3D, no WebGL, no molecular rendering libraries, no Babylon/Three.
- No real chemistry engine, no force fields, no molecule data files, no PubChem.
- No accuracy claims, no correct bond angles, no periodic table. Charge is an integer; that's the whole model.
- No build framework (no React, no bundler required). No npm dependencies. See §4.
- No menus beyond a start screen, no settings, no save system, no networking, no analytics.
- No art assets, no audio files. Everything is drawn with Canvas primitives and synthesized with WebAudio.

---

## 4. Tech stack

- **Vanilla JavaScript, ES modules.** No dependencies, no bundler, no build step.
- **HTML5 Canvas 2D** for all rendering.
- **WebAudio API** for all sound (synthesized at runtime — no files).
- **Gamepad API** for controller + haptic rumble (the hold-resistance tell).
- Runs by opening `index.html` through any static file server (e.g. `python3 -m http.server`). Must work in current Chrome/Edge/Safari. Must hold **60 fps** on modest hardware.

Logical resolution **1280×720**, letterboxed/scaled to fit the window (integer or fractional scale, preserve aspect). All coordinates in logical pixels.

---

## 5. Project structure (suggested — adapt if you have a better idea)

```
index.html            # canvas + module entry, title card, start button
src/
  main.js             # boot, game loop, state machine (title → play → end)
  config.js           # ALL tunable feel constants live here. One file.
  input.js            # keyboard + mouse + gamepad → unified InputState, rumble
  camera.js           # follow + screenshake (trauma model) + world↔screen
  audio.js            # WebAudio synth: pop, hum, snap, ambience, bounce
  world.js            # holds particles, membranes, zones; steps the sim
  particle.js         # Particle entity + charge/jitter/bond state
  molly.js            # player: movement, hands, grab, self-charge
  physics.js          # forces: jitter, charge interaction, zones, membrane, bonds
  bonds.js            # the hold-and-release mechanic + bond constraints
  render.js           # draw world, particles, glow/shape by charge, effects
  fx.js               # particles/sparks, hitstop, flashes, trauma helpers
  rooms.js            # room definitions (data) + RoomManager
  rooms.data.js       # the ten scripted beats as data
```

Keep `config.js` authoritative for every feel number. Feel is tuned by editing that one file; don't scatter magic numbers through the code.

---

## 6. Core data model

**Particle** (a mote / atom):
```
{
  pos: {x, y}, vel: {x, y},
  charge: -1 | 0 | +1,        // slice uses three states; allow ±2 later
  displayCharge: float,        // lerps toward `charge` for smooth color/shape
  radius: ~10,
  slots: 1..4,                 // "valence" dots drawn around it (visual only in slice)
  bonds: [particleRef, ...],   // spring-linked partners
  zoneTimer: float,            // accumulates while in a re-tuning zone
  grabbedBy: null | 'L' | 'R', // which hand is holding it
  fixed: bool,                 // scenery anchors (raft targets, etc.)
  tag: string                  // e.g. 'key', 'debris', for room scripting
}
```

**Molly** (player):
```
{ pos, vel, charge: -1|0|+1, displayCharge, aim:{x,y}, radius:~14,
  handL: {holding: particleRef|null}, handR: {holding: particleRef|null} }
```

**Membrane:** a line segment `{a:{x,y}, b:{x,y}, thickness}` that repels charged things, ignores neutral ones.

**Zone:** `{shape:'rect'|'circle', ...bounds, type:'sour'|'soapy'|'neutral', tint}`.

**Room:** `{ id, molly:{x,y}, particles:[...], membranes:[...], zones:[...],
  exit:{rect}, ambient:{hum, tint}, onEnter?:fn, onExit?:fn }`.

**Charge → appearance** (both color and shape, always redundant):

| Charge | Color | Shape signature | Halo |
|---|---|---|---|
| **+1 positive** | hot pink `#FF2D9B` | **spiky** outline (outward points) | tight bright rim |
| **0 neutral** | dim gray-white `#C8D0D8` | smooth circle, flat | none, slightly translucent |
| **−1 negative** | cyan `#2DB8FF` | smooth circle, **soft pulsing** halo | wide gentle glow |

Positive = aggressive/spiky, negative = smooth/glowing, neutral = quiet/flat. This makes charge readable without color, and just reads better in motion. `displayCharge` lerps over ~150 ms so transitions feel physical, not instant.

---

## 7. The simulation (physics.js) — update order per frame

Run at a fixed timestep (e.g. accumulate real time, step at `dt = 1/120 s`, render interpolated). Order each step:

1. **Jitter (the storm).** Every non-grabbed particle gets a random impulse: `vel += randUnit() * JITTER_ACCEL * dt`. Molly gets a much smaller idle jitter so she never sits dead still. Tune `JITTER_ACCEL` (start ~400 px/s²) so the world *shimmers* — alive, not chaotic.
2. **Charge interaction.** For each pair of *charged* particles within `CHARGE_RANGE` (~180 px): Coulomb-ish force `F = K_CHARGE * q1 * q2 / max(d, D_MIN)²`, attractive for opposite signs, repulsive for like. Cap magnitude to avoid explosions. Skip neutral–neutral pairs (cheap). Start `K_CHARGE` so two opposites within ~120 px visibly lunge together over ~0.3 s.
3. **Zone re-tuning.** For each particle inside a zone:
   - **sour:** if `charge < +1`, accrue `zoneTimer += dt`; when it exceeds `ZONE_FLIP_TIME` (~1.2 s), bump `charge += 1` and reset. (So neutral won't *stay* neutral here — the sour air keeps shoving it positive. This IS the "your take hand has to fight the current" feel.)
   - **soapy:** if `charge != 0`, accrue timer; on threshold move `charge` one step toward 0.
   - **neutral zone / outside:** decay `zoneTimer` toward 0.
   - Reset a particle's `zoneTimer` whenever the player just acted on it, so player action feels responsive and the zone "reclaims" it afterward.
4. **Membrane repulsion.** For each *charged* particle (and Molly if charged) near a membrane within `thickness`: apply a strong force along the segment normal, pushing it back to its current side. Neutral particles get **zero** force — they pass freely. Tune so charged things clearly bounce and cannot muscle through; neutral things ignore it entirely.
5. **Bond springs.** For each bonded pair: spring toward `BOND_LENGTH` (~24 px), stiff, damped, so molecules hold shape but wobble slightly in the storm.
6. **Grab springs.** Grabbed particles are pulled toward their hand anchor (§8).
7. **Integrate.** `vel *= damping` (drag — start so speed halves ~every 0.1 s at rest), `pos += vel * dt`. Clamp to world bounds.

Keep it cheap: a few dozen particles per room max. No spatial hashing needed at this scale.

---

## 8. THE SIGNATURE MECHANIC: bond hold-and-release (bonds.js)

This is the game. Get it feeling *physical and earned*. The challenge is the **wrestle**, not the click.

**Grab.** Hold the Grab input near a particle → it tethers to a *hand anchor* that tracks the aim reticle via a stiff spring. Molly can carry it. Grab again → second particle on the other hand (hold up to two). The two anchors sit slightly apart so the player positions each.

**The activation barrier (this is what makes it fun).** When two grabbed opposite-charge particles approach:
- Beyond ~60 px: mild attraction, easy.
- Between ~25–45 px: a **repulsive bump** they must be shoved *through* — plus the constant jitter knocking them off line. This is the resistance. The player has to *force* them together and hold against the push-back.
- Below `BOND_LOCK_DIST` (~22 px): they **snap** — bond forms, both auto-release from the hands, and the snap event fires (§9).

**Feedback while wrestling:**
- **Rumble ramps** with effort — low as they approach, peaking at the barrier. (Gamepad haptics; on keyboard, substitute a rising audio hum + a subtle screen tremor.)
- A **rising hum** (audio.js) climbs in pitch/gain as they near the barrier.
- The particles visibly *shove back* against the player's drag at the barrier.

**Release / fail.** Let go of Grab while still fighting → the particles fly apart on the jitter, no bond, no punishment. Just try again. Failure is instant and cheap.

**The payoff — snap event:**
- **Hitstop** ~50 ms (freeze the sim, keep rendering).
- **Screenshake:** add ~0.6 trauma (§9).
- **Bass thunk + noise burst** (audio.js).
- **Spark burst** at the bond point, colored by the two charges.
- **Molly knockback:** shove her velocity away from the bond point.
- The new bond glows at the seam for ~0.5 s.

Tune the whole sequence until you'd do it fifty times just because it feels good. That's the bar.

---

## 9. Juice spec (fx.js, camera.js)

Feel lives here. Starting values — tune freely.

- **Screenshake (trauma model, à la "The Art of Screenshake").** Keep a `trauma` float 0..1. Offset = `MAX_SHAKE * trauma² * noise()`, plus small rotation `MAX_ROT * trauma² * noise()`. `MAX_SHAKE` ~20 px, `MAX_ROT` ~2°. Decay `trauma -= 1.5 * dt`. Snap adds ~0.6; membrane bounce ~0.15; charge pop ~0.05.
- **Hitstop.** On big events set `freeze = 0.05 s`; during freeze `dt = 0` for the sim but rendering + effects continue. Sells impact.
- **Particles/sparks.** Cheap circles/lines with velocity + fade. Bursts on snap, charge change, membrane bounce, heat pulse.
- **Charge transitions.** `displayCharge` lerps ~150 ms; color and shape morph with it. A quick bright flash on the moment of change.
- **Trails.** Fast-moving motes leave a short fading trail (a few ghost positions or additive alpha). Sells speed and the fluid.
- **Ambient bloom.** Charged particles have an additive glow. Use `globalCompositeOperation = 'lighter'` for glows/sparks over a dark ground.

**Audio (all synthesized, no files):**
- **Charge pop:** short sine blip; pitch *up* for Give, *down* for Take.
- **Hold hum:** oscillator whose gain + pitch ramp with bond proximity; kill on release/snap.
- **Snap:** sine sweeping 80→50 Hz over ~120 ms + a filtered white-noise burst + short decay tail. The money sound — make it satisfying.
- **Membrane bounce:** dull filtered thud.
- **Zone ambience:** low drone / filtered noise, timbre tinted per zone; crossfade on zone change.

---

## 10. Zones & membrane recap (behavior already specced in §7)

- **Zones** apply a subtle full-screen **tint** (sour = yellow-green, soapy = blue-violet, neutral = none) and swap the **ambient hum**. The gameplay effect is the recharge/discharge timer in §7.3. Keep the visual subtle — a wash, not a filter that hurts readability.
- **Membrane** renders as a shimmering oily band. When a charged thing bounces, ripple + bounce thud. When a neutral thing passes, a soft "phase-through" shimmer. Molly passes only while neutral — desaturate the screen and drop the hum while she's neutral to sell "gone quiet."

---

## 11. Controls

**Keyboard + mouse (must be fully playable):**
- Move: WASD / arrows. Aim: mouse reticle.
- **Give (right hand):** Left Mouse. **Take (left hand):** Right Mouse.
- **Grab (hold):** Space (or hold Left Mouse variant — pick what feels best).
- **Heat:** Q. **Light:** E.
- **Self-charge:** if the reticle isn't over a particle, Give/Take act on **Molly herself** (this is how she strips neutral to cross the wall). Clean and discoverable.

**Gamepad (support + rumble):**
- Move: left stick. Aim: right stick (reticle offset from Molly).
- Give: RT. Take: LT. Grab: A/×  (hold). Heat: LB. Light: RB.
- Rumble ramps during the bond wrestle (the core use of haptics).

Unify both into a single `InputState` each frame so game code never checks device type.

---

## 12. Heat & Light (openers)

- **Heat:** area impulse at the reticle, radius ~150 px — kicks all particles outward + spikes their jitter briefly; can break a bond if it stretches past `BOND_BREAK_DIST`. Loud, indiscriminate. Big trauma, big noise.
- **Light:** single target under the reticle — flips its "mood." In the slice, Light toggles a target's charge sign (or triggers a scripted state on a special object). Silent, precise, one thing.
- **The opposite-directions hook:** include at least one scripted "lock" object that moves its state one way under Heat and the other way under Light. It can be a stretch beat (Milestone G) — wire the hook even if only one puzzle uses it.

---

## 13. The scripted sequence (rooms.data.js)

Ten beats. Each is a small hand-authored room (data). Camera follows Molly; reaching a room's `exit` rect loads the next. Some beats can merge if it plays better — use judgment. **No text in any of them.**

| # | Room | What the player learns | How it's taught (no words) |
|---|---|---|---|
| 0 | **Wake** | Give/Take = push/pull | Dark, one drifting mote. Poking it charges it and it pushes away / pulls back. Fade in from black. |
| 1 | **First toy** | Opposites grab | A cluster; charge one +, one −, they lunge together and stick. A gap to reach behind them. |
| 2 | **The raft** | Bonds = hold-and-release | Two raft-halves drift apart, jittering. Wrestle them together → SNAP → ride the raft across a gap. |
| 3 | **The wall** | The membrane reads charge | Throw charged debris → it bounces, no reaction. Drift a neutral bit → it passes through. |
| 4 | **Go quiet** | Neutral = sneak | Strip Molly neutral (Take on herself) → screen desaturates → drift through the membrane. |
| 5 | **Sour** | Zones re-tune your hands | World tints yellow-green. A mote you neutralize keeps snapping back to +. |
| 6 | **The vault** | (setup) | A second membrane with the exit behind it, and a "key" object. Sour air present. |
| 7 | **The heist** | Combine everything | Key is charged → bounces. Strip it neutral → it drifts through → sour air on the far side charges it → **trapped.** Exit opens. |
| 8 | **Scale** | (tease) | Zoom/parallax reveal: this was one droplet; thousands more; something huge pulsing far off. Fade to end card. |

Give each room optional `onEnter`/`onExit` hooks for the few scripted moments (Room 0 fade-in, Room 8 reveal). Don't build a scripting engine — just callbacks.

---

## 14. Build order — milestones (each independently runnable & testable)

Build in this order. **After each milestone, stop and verify the stated test before moving on.** Do not build later milestones until the current one feels right.

- **A — Grey box & life.** Canvas, fixed-timestep loop, letterbox scaling. Molly moves with drag + idle jitter; camera follows. A dozen particles drift with the storm jitter. No charge yet.
  *Test: does moving around and watching the shimmer feel alive and fluid, not floaty or dead?*

- **B — Give/Take + charge + opposites-grab.** The core toy. Reticle targeting, Give/Take change charge, color+shape by charge (§6), charge interaction force (§7.2), charge pop audio.
  *Test (the kill-test): poke a mote and it charges; make two opposites lunge together and stick. Is just this fun to mess with for a minute?*

- **C — Bond hold-and-release + full snap juice.** Grab/anchor springs, the activation barrier, rumble/hum ramp, hitstop, screenshake, sparks, knockback, snap audio (§8, §9). **Spend the most time here.**
  *Test: would you trigger the snap fifty times for fun? If not, keep tuning before proceeding.*

- **D — Membrane.** Charged repulsion, neutral pass-through, Molly self-charge to cross, bounce/phase FX.
  *Test: charged things bounce, neutral things pass, and going neutral to sneak through feels sneaky.*

- **E — Zones.** Sour/soapy/neutral recharge fields, tint wash, ambient hum crossfade.
  *Test: in a sour zone a neutralized mote visibly refuses to stay neutral.*

- **F — Rooms & the sequence.** RoomManager, `rooms.data.js`, exit triggers, room transitions, wire beats 0–7. The heist must be solvable using only mechanics the earlier rooms taught.
  *Test: play start→heist with no instructions and no text. Does the heist click as "my own idea"?*

- **G — Heat & Light + the opposite-directions lock.** The two openers and at least one puzzle using the heat-vs-light hook.
  *Test: heat feels like a crowbar, light like a scalpel; the opposite-reaction lock reads.*

- **H — Bookends & polish.** Title card + start, Room 8 scale reveal, end card, audio mix pass, one full feel-tuning pass across `config.js`.
  *Test: the whole ten minutes plays clean, start to finish, 60 fps.*

If time is short, **A–F is the real slice** (it contains the whole thesis). G and H are enhancement.

---

## 15. Definition of done

- All beats 0–7 are playable start to finish, **with zero text on screen** during play.
- The **bond snap feels genuinely good** (the fifty-times bar).
- Charge state is readable instantly by **color and shape**, even in motion.
- Keyboard+mouse fully playable; gamepad supported with rumble during the wrestle.
- Holds **60 fps** in Chrome on modest hardware.
- **All feel constants live in `config.js`** and can be tuned without touching logic.
- Runs from a plain static server with no build step and no dependencies.

---

## 16. Tuning notes for whoever plays it next

The feel lives in `config.js`. The three knobs that matter most, in order:
1. **`JITTER_ACCEL`** — the life of the world. Too low = dead; too high = unplayable soup.
2. **The bond barrier** (`BOND_ATTEMPT_RANGE`, barrier strength, `BOND_LOCK_DIST`) — the wrestle. This is the whole game's feel in three numbers.
3. **Snap juice** (`MAX_SHAKE`, hitstop duration, snap audio envelope) — the payoff.

Tune those first, by feel, before touching anything else.

---

*This is a prototype to answer one question: is the core loop fun? Build the smallest thing that answers it honestly. Everything else waits.*