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 (the set + roles), round2_molecule_materials.png (flat vs matcap vs space-filling, in the real canal), 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.

The division of labour: procedural geometry, generated materials

MODELBEAST makes the materials. Procedural makes the shapes. Both halves matter and they are not in competition — the first version of this doc framed it as "don't use the GPU", which was the wrong axis and is corrected below.

Geometry is not a generation problem, because 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).

Material is exactly a generation problem, and it's what separates a diagram from an object — see the next section.

What MODELBEAST did do: the materials (round 2, second pass)

Geometry is exact and free. Material is where the GPU earns its keep — and it's the whole difference between a textbook diagram and a game object. GUTS has no real-time lights by law, so a matcap (a lit-sphere image) is the only way to make something look made of anything.

Five greyscale matcaps, flux_local, 69 seconds, $0.00, 68 KB total:

matcap	elements	what it does
mol_glass	O, N	the big win. Oxygen becomes a deep red glass marble with internal glow.
mol_matte	C	graphite soot. Carbon is scaffold, and now it reads as scaffold.
mol_chrome	Co, Fe, Na	polished metal — B₁₂'s cobalt is a chrome bearing in a cage.
mol_molten	P	ATP's phosphate tail is incandescent, and pulses (uTime, free).
mol_pearl	H	soft satin white; hydrogens stop shouting.

The trick that makes it cheap is Lane D's own law, applied to spheres: author the luminance, tint in-shader. derive_maps greyscales every matcap already, so one glass ball serves oxygen and nitrogen at their own CPK hues. Five balls dress the whole periodic table we care about, and they pack into one strip atlas indexed per-vertex by aMat — so a molecule is still exactly one draw call no matter how many materials its atoms are made of. ?matcap=0 falls back to the built-in fake-lit path: the assets-optional law holds.

Two things that only showed up by rendering it, both fixed:

• Tint × luminance darkens twice. CPK carbon is already 0.4 and a matte ball averages 0.5, so soot × soot vanished — the first pass sank glucose, caffeine and the cobalt into the background. Floored the matcap at 0.22, the same floor the fallback's key light has always had.
• The molten matcap was my own bad prompt: I asked for an "incandescent white hot core" and got exactly that — a black ball with a hot spot, so the phosphorus lost its orange entirely. Re-rolled asking for the whole sphere to glow. Lesson for the kit, next to the organ/tissue one: a matcap is a luminance lookup, so a dark-dominant ball makes a dark-dominant object. Ask for bright, always.

What the canal decided: space-filling wins for pickups

buildMolecule(id, {repr}) now does 'ball-stick' (default) or 'space-filling' — every atom at its real van der Waals radius, no sticks, atoms merging into one solid lump. A/B'd at real pickup size against the real L2 wall, same camera (round2_molecule_materials.png):

Ball-and-stick goes spindly and starts dissolving. Space-filling holds its silhouette — and it is CHEAPER (21k vs 26k tris across the set: no bond cylinders). It's also more true, since that is how a molecule occupies space.

→ Recommendation to B: space-filling for anything in flight, ball-stick for hero, UI, the medal card and the collect close-up — where the chemistry is legible and worth reading. The obvious LOD (blob far, sticks near) is untested and I'm not claiming it.

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 (13 draws / 87k with the canal behind them). Fifty would want instancing or a merged batch, and neither exists yet.
• The matcap atlas is built at runtime from a canvas. Fine, but it means a one-frame hitch on first build and it bypasses assets.matcap() (it reads assets.get('matcaps', …).url — the documented floor — and loads the images itself, because an atlas needs pixels and matcap() hands back a THREE.Texture that may not have decoded yet). If this is adopted, baking the atlas offline in derive_maps.py would be tidier and D may prefer it.
• repr: 'space-filling' hides the bonds by definition, so a molecule's chemistry stops being readable — that's the trade for silhouette, and it's why ball-stick stays the default for anything the player is meant to look AT rather than fly at.