guts/docs/MOLECULES.md

# MOLECULES — a proposal (Lane A, round 2)

**Status: PROTOTYPE + argument.** Nothing here is wired into boot. Pickups are Lane B's
systems, their economy is Lane C's, object art is Lane D's — this document is a pitch to all
three, plus a working renderer they can take or leave.

Fly it: `web/dev/laneA_molecules.html` · code: `web/js/world/molecule.js` ·
evidence: `docs/shots/laneA/round2_molecule_pickups.png`, `round2_molecules_in_canal.png`,
`round2_molecules_truescale.png`

---

## The pitch in one line

**The pickups already in L2 are molecules — so draw them as molecules.**

C authored `nutrient`, `mucin`, `B12`, `antacid ammo` before any of this existed. Those aren't
game-flavoured names; they're the actual biochemistry of a digestive tract. Glucose, cobalamin
and bicarbonate are *real compounds with known shapes*. We don't have to invent a pickup
language — we have to stop hiding the one the fiction already handed us.

## Why this is free sciency-ness, and why it isn't educational

The game does not explain anything and should not start. Nobody needs to know what ATP is.
But a purine reads as *chemistry* to anyone alive, the way a circuit diagram reads as
*electronics* — because it is the real notation, not an impression of one. **The game gets to
feel sciency by not faking it**, which is cheaper than faking it and better.

Consider what's already true: an **eosinophil** is a real white blood cell. **Candida** is a
real yeast. A **bolus** is a real mass of chewed food. The **hiatus** is a real anatomical
choke point. **GUTS is already a science game** — C built it that way. It just doesn't *look*
like one yet, because everything on screen is tinted tissue.

## The one rule that makes it all work: CPK is the scanner

**Everything the ship's scanner has identified is drawn in CPK colours. Everything it hasn't
is monochrome tinted tissue.**

CPK is the standard element palette — oxygen red, nitrogen blue, phosphorus orange, sulfur
yellow, metals pink. Every chemistry textbook and protein viewer on earth uses it. Against six
biomes of tinted tissue, **a CPK molecule is the only saturated foreign colour on screen**, so
it reads as artificial, valuable and targetable at a glance — *with no HUD marker*
(`round2_molecules_in_canal.png` is the proof: a glucose in the esophagus, unmissable).

That's ART_BIBLE's synthetic-scanner fiction paying rent: the ship identifies a compound and
colours it in. → **Lane E**: this is a free HUD language. Accent a readout in an element's CPK
colour and it belongs to that compound with no legend.

## Why procedural, not MODELBEAST — and where MODELBEAST *is* right

I'm authorised to burn GPU on this and I'm not going to, for one reason: **a molecule's shape
is already known exactly.** Glucose is a hexagonal ring because it is a hexagonal ring. FLUX +
TRELLIS would give a plausible blob, in 3–8 minutes, that a chemist clocks as wrong instantly
and that can never be re-derived. Ball-and-stick from an atom list is exact, rebuilds in
milliseconds, and is **one draw call per molecule** (measured: 7 molecules = 7 draws, 26.5k
tris total; glucose alone is 3.7k tris / 1 draw).

**The split, and it's a principle, not a preference:**

| kind | how | why |
|---|---|---|
| **Small molecules** — glucose, ATP, caffeine, bicarbonate, capsaicin, B12, ions | **procedural ball-and-stick** | exact geometry is known; generation can only degrade it |
| **Proteins / enzymes** — pepsin, trypsin, lipase, mucin | **MODELBEAST** (flux → sf3d → trellis) | real ones are 3000-atom blobs; nobody reads their structure. A blob is the honest render, and PIPELINE says blobby organics are TRELLIS's sweet spot |
| **Cells / creatures** — eosinophil, candida, bolus, ENDO-1 | **MODELBEAST** (Lane D's round-2 headline, gated on concept sign-off) | organic, no canonical geometry, exactly what it's for |

So MODELBEAST still does the heavy lifting — on the things where invention is the right answer.

## The library (built, rendering, in the sheet)

Every one of these is really in the human gut. That constraint does the design work: the pickup
table *is* the biochemistry of digestion, so nothing has to be invented and the fiction is
automatic.

| molecule | proposed role | why it's the right object |
|---|---|---|
| **Glucose** `C₆H₁₂O₆` | nutrient / score | Food. The reason the canal exists. Common, stacks. |
| **ATP** `C₁₀H₁₆N₅O₁₃P₃` | **boost** | Literally the cell's energy currency. The orange triphosphate tail *is* the charge — a body spends ATP by snapping one off. A boost pickup that visibly carries three charges is a diagram of its own mechanic. |
| **Bicarbonate** `HCO₃⁻` | **antacid ammo** | Already in L2. `HCO₃⁻ + HCl → salt + H₂O + CO₂` is the real reaction that neutralises stomach acid — fire it into the acid sea and it genuinely fizzes. |
| **Caffeine** `C₈H₁₀N₄O₂` | **overdrive** | Really absorbed through the gut wall. Everyone knows what it does to a body: throttle up, twitchier, wears off badly. Needs no tutorial. |
| **Capsaicin** `C₁₈H₂₇NO₃` | **burn hazard** | Chilli. Long greasy tail + aromatic ring = a silhouette that reads *wrong* across a room, and it tumbles unlike any compact pickup. Free readability. |
| **Vitamin B₁₂** `C₆₃H₈₈CoN₁₄O₁₄P` | **rare treasure** | C already authored B12 as a pickup. It's the most complex vitamin and the *only one with a metal at its heart* — a cobalt in a corrin cage. It renders as a jewel in a setting. |
| **Water** `H₂O` | trickle / chaff | Everywhere, worth a sliver. The size floor. |

**Size is a free rarity signal.** `buildMolecule(id, {unit})` keeps molecules at their TRUE
relative sizes: water is a speck, B12 is a chandelier (`round2_molecules_truescale.png`). The
player learns what's worth chasing before reading a single colour, and it costs nothing because
it's just true. (`{fit}` normalises them all to one size instead, if a pickup must occupy a
fixed box — B's call.)

## Cheap next molecules, if this lands

- **Ions as basic ammo/energy**: Na⁺, K⁺, Cl⁻, Ca²⁺ — single coloured spheres, ~30 tris, and
  they're the real electrolytes. Violet, green, purple: instant colour-coded ammo types.
- **Ethanol** `C₂H₅OH` — a *powerdown*. Controls drift, aim lags. Funny, real, gut-absorbed.
- **Vitamin C** `C₆H₈O₆` — coat repair (it's the antioxidant). Pairs with B12 as a vitamin tier.
- **Mucin** — the coat itself, and it's already a pickup. It's a glycoprotein → MODELBEAST blob,
  not ball-and-stick. Good first test of the split above.
- **HCl** — the acid sea's own molecule. One green Cl, one white H. The sea could *shed* them.

## Other ways to be sciency that cost ~nothing

1. **Show the real pH.** L3's identity is "ambient pH drains the coat". Stomach pH really is
   ~1.5–3.5. A HUD readout ticking `pH 1.8` as you descend is instantly sciency, is true, and
   is one number. → Lane E / C.
2. **Name the real reaction when it fires.** Antacid hit → `HCO₃⁻ + HCl → NaCl + H₂O + CO₂↑`
   flashed for half a second in the feed. Never explained. Reads as an instrument log.
3. **Let CO₂ be the fizz.** The bicarbonate reaction really produces gas. Bubbles from a
   neutralised acid patch are the reaction being visible, not a particle effect.
4. **The enemies are already real** — lean in. `eosinophil_swarm` is a real immune response to
   an invader. The player IS the invader. That's the whole game's joke and it's science.

## What I'd need from each lane

- **→ C**: are these the roles you want? The economy is yours. If `nutrient` should be glucose
  and `antacid` bicarbonate, they're built. Tell me which molecules a level needs.
- **→ B**: `buildMolecule(id, {fit|unit, detail, material})` returns one `THREE.Mesh`, one draw,
  `.userData` carries name/formula/role. Share ONE material across all of them (colour is
  per-vertex, so they still batch). Use `detail: 1` for live pickups, `2` for hero/close.
- **→ D**: this doesn't touch your pack and doesn't want your GPU time. It *asks* for the split
  above — proteins and cells are yours, small molecules are arithmetic. Your round-2 hero list
  is unaffected.
- **→ E**: CPK as the scanner's identification language is a free HUD palette. `ELEMENTS` in
  `molecule.js` exports the hexes.
- **→ F**: `world/molecule.js` sits in my dir because it's my dir, not because molecules are
  "world". If this is adopted it probably wants a shared `web/js/fx/` — your call.

## Honest limitations

- **Geometry is idealised, not crystallographic**: correct connectivity, ring sizes and bond
  orders, believable angles, authored mostly flat because a flat ring reads instantly and spins
  well. Real molecules pucker (glucose is a chair, not a hexagon). This is a game, not PyMOL —
  but nobody should mistake this table for a structure database later.
- **The B12 is a simplified corrin core** — the real thing has a nucleotide tail and far more
  side chains. It reads as "jewel in a cage", which is the job.
- **Not performance-tested at pickup density.** 7 on screen is 7 draws / 26k tris. Fifty would
  want instancing or a merged batch, and neither exists yet.