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.