From 916b26102c4492b21c346f82f965b25777468538 Mon Sep 17 00:00:00 2001 From: type-two Date: Thu, 2 Jul 2026 22:52:26 +1000 Subject: [PATCH] =?UTF-8?q?docs:=20DIG=5FFLIP=5FHANDOVER=20=E2=80=94=20por?= =?UTF-8?q?t=20THRIFTGOD's=20evolved=20crate-riffle=20into=20/store?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- docs/DIG_FLIP_HANDOVER.md | 103 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 docs/DIG_FLIP_HANDOVER.md diff --git a/docs/DIG_FLIP_HANDOVER.md b/docs/DIG_FLIP_HANDOVER.md new file mode 100644 index 0000000..0437403 --- /dev/null +++ b/docs/DIG_FLIP_HANDOVER.md @@ -0,0 +1,103 @@ +# HANDOVER: the record flip/riffle animation — port THRIFTGOD's dig back into RecordGod + +**For:** the RecordGod agent. **Goal:** adopt the evolved crate-digging mechanic into the +3D store served at **robotmonster.party/store/** (this repo: `webstore/index.html` + +`webstore/dig.js`). **Written:** 2026-07-02 by the THRIFTGOD session. Self-contained — +you don't need that conversation. + +## Lineage (read this first) + +RecordGod's `webstore/dig.js` is the ORIGINAL crate-inspect scene. THRIFTGOD +(`/Users/johnking/Documents/OPSHOPGAME/web/dig.js`) forked it and evolved it through a +day of live play-testing. **The THRIFTGOD file is a superset of yours with the same +architecture** — same `createDig(renderer, opts)` factory, same scene/camera/update/open/ +close contract, same procedural audio. The cleanest port is: diff the two files, take +everything, then re-wire the two integration points listed at the end. + +`diff webstore/dig.js /Users/johnking/Documents/OPSHOPGAME/web/dig.js` + +## The mechanics, and the numbers that make them feel right + +All tuned by hand against real play. Change them at your peril; record them if you do. + +1. **Riffle = a damped cursor over the stack.** + - `cursor` (float index) + `vel`; per frame: `vel *= Math.pow(0.0008, dt)`, + `cursor += vel * dt`, clamped to [0, n−1]. + - Wheel: `vel += e.deltaY * 0.012`. Drag: `cursor += dy * 0.02; vel = dy * 0.6`. + - When `Math.floor(cursor)` changes → play the **fwip** + load nearby covers + update + the title label. + +2. **The flip is a hinge at the sleeve's bottom edge.** + - Each record = a Group at the bin floor; the sleeve mesh is offset `y = h/2` inside + it, so rotating the GROUP hinges at the bottom edge — this is the whole trick. + - Rest angle `BACK = −0.12` (sleeves lean back); flipped-forward max `MAXFLIP = 1.95`. + - Per frame, each record i targets: + `target = BACK + smoothstep(cursor − i, −0.4, 1.2) * (MAXFLIP − BACK)` + then eases: `angle += (target − angle) * min(1, dt*12)`. + Records behind the cursor stand; records ahead lie flopped forward. The smoothstep + window (−0.4…1.2) is what makes riffling feel like fingers walking sleeves. + +3. **Real format sizes + packing by thickness** (THRIFTGOD addition): + - `FMT = { lp:[0.31,0.31,0.0035], cd:[0.142,0.125,0.010], dvd:[0.136,0.19,0.014], + vhs:[0.105,0.187,0.025], cass:[0.11,0.07,0.017] }` — [w, h, thickness] metres. + - Stack: `z -= thickness + 0.010` per sleeve. VHS riffles chunkier than vinyl for free. + - RecordGod is LP-only today, but keep the map — CDs are inevitable. + +4. **Secondhand lean** (cheap, huge): per sleeve seeded jitter — + `rotation.z = ((i*2654435761>>>0)%100−50)/1800`, `position.x = ((i*40503>>>0)%100−50)/12000`. + No more parade-ground vinyl. + +5. **The crate is drawn around the stack** (THRIFTGOD addition): floor/left/right/back + walls + a LOWER front lip (`H*0.55`) the sleeves flip over; sized from max sleeve dims + + stack depth; wood texture (any wood jpg with RepeatWrapping ×2). See `buildCrate()`. + +6. **Covers trickle-load; near-cursor loads win.** + - Priority window on cursor move: indices `c−10 … c+15` load immediately. + - Background: `fillQueue()` loads ONE unloaded cover every 120ms until the crate is + full (clear the timer in `close()`). Never load all covers eagerly; never texture + more than the window synchronously. `tx.colorSpace = THREE.SRGBColorSpace` always. + +7. **Pull-to-inspect presents at arm's length ON THE VIEW AXIS** (final tuning after two + bad iterations — first it cropped off-screen, then it became IMAX): + - Dig camera: `position (0, 0.5, 0.92)`, `lookAt (0, 0.12, −0.2)`, FOV 45. + - Pull target FOR THAT CAMERA: `position → (−0.1, 0.23 − h/2, 0.12)` (h = sleeve + height; the −0.1 x keeps it clear of a right-side info panel), and + `rotation.x → −0.33` so the cover faces the lens. + - **If your camera differs, derive it**: `target = cam.pos + viewDir * 0.85`, then + `y −= h/2`, and tilt to face the camera. 0.85m gives an LP ~21° of a 45° FOV. + - Lerp position `min(1, dt*5)`, rotation `min(1, dt*6)`. + - `unpull()` restores `position.set(0, 0, homeZ)`; the angle system reclaims rotation. + - Click-vs-drag: pull only fires if total pointer movement `< 4px`. + +8. **After a sale, re-pack the stack**: remove the record, then walk the survivors + re-assigning `homeZ` with the same thickness accumulation. Don't leave a gap. + +9. **Procedural audio, no asset files** (already in your ancestor, keep it): + - *fwip*: 50ms white-noise burst → bandpass 2100Hz Q0.7 → gain 0.22. + - *thunk* (pull): sine 105Hz, 5ms attack to 0.5, exp decay over ~0.28s. + - Lazily create AudioContext on first use (autoplay policies). + +10. **Pointer-lock gotcha** (if your store uses PointerLockControls): Chrome refuses + re-lock within ~1.3s of Esc. Never call `controls.lock()` programmatically after + closing a panel — wrap it: request, `.catch()` → show a click-to-resume overlay + (a fresh user gesture always succeeds). THRIFTGOD calls this `safeLock()` in + `web/index.html`. + +## Integration points (the only THRIFTGOD-specific bits to rewire) + +- **Data in:** THRIFTGOD uses `createDig(renderer, { onClose, getItems, onBought })` with + `open(kind)`; your ancestor used `getRecords` + `open(crateId)` fetching + `/virtual/crate/{id}/records`. Keep YOUR fetch, adopt their buildStack. Records need + `{ title, artist, thumb, price, condition, fmt? }` (fmt defaults to `lp`). +- **Buy action:** THRIFTGOD's pull-panel button POSTs `/api/take` (its basket system). + Replace with RecordGod's add-to-cart. Everything else in `pull()`/`unpull()` ports as-is. +- **Images:** THRIFTGOD proxies external covers via `/img?u=`. RecordGod serves its own + webp at `/store/assets/` — use your `thumb` URLs directly, no proxy needed. + +## Definition of done + +Riffle with wheel AND drag feels weighted; sleeves lean individually; the crate is +visible around the stack; covers fill in behind you; pulling any format presents fully +in frame, facing the camera, beside (not under) the info panel; buying closes the gap +in the stack; Esc steps back out cleanly twice (pull → crate → store) with no +pointer-lock console errors.