recordstoreguy/ENGINE.md

# RECORD STORE GUY engine spec — FMV QTE player

Pure static web app: no build step, no framework, no server logic. One HTML file,
one JS file, one CSS file, one JSON scene graph, a folder of mp4 clips. Must run
from `python3 -m http.server` locally and from nginx on the games VPS unchanged.

## Files
```
engine/
  index.html      shell: <video>, overlay divs, HUD
  player.js       all logic (~400 lines, vanilla ES6, no deps)
  styles.css      arcade look: scanlines, CRT vignette, neon HUD
  scenes.json     the scene graph (authored data, engine reads it verbatim)
  clips/*.mp4     24fps 1280x720 h264+aac, named <scene_id>_<kind>.mp4
```

## scenes.json schema
```jsonc
{
  "meta": { "title": "RECORD STORE GUY", "lives": 5, "version": 1 },
  "start": "s01_entrance",
  "scenes": {
    "s01_entrance": {
      "clip": "clips/s01_action.mp4",       // the scene's action clip
      "death": "clips/s01_death.mp4",       // played on fail, then retry scene
      "windows": [                           // 1..n QTE windows within the clip
        {
          "t": [3.2, 3.9],                  // seconds: window open..close
          "input": "right",                 // right|left|up|down|action (action = space/enter/click)
          "cue": true                        // show the flashing direction cue at t[0]
        }
      ],
      "onSuccess": "s02_aisles",            // next scene id, or "WIN"
      "checkpoint": false                    // true = death respawns here, not act start
    }
  }
}
```
Rules the engine enforces:
- Input BEFORE the window opens = instant fail (Dragon's Lair rule — no button mashing).
  Grace: inputs in the 250ms before t[0] fail; earlier inputs are ignored (idle fidget).
- No input by t[1] = fail. Wrong direction = fail.
- Multiple windows per clip run in sequence; all must pass.
- On fail: swap to death clip immediately (seek 0, play), then decrement lives.
  Lives 0 → game-over screen → attract. Otherwise retry the scene (or last checkpoint).
- On success of last window: let action clip finish, then advance to onSuccess.

## Branching / choice windows (NEW — required by THE SHIFT scenes in WORLDS.md)
A window may replace `input` with `choices`, mapping inputs to outcomes:
```jsonc
{ "t": [2.5, 4.0], "cue": true,
  "choices": {
    "left":  { "goto": "sh1_house_ok" },          // proceed/branch to scene
    "up":    { "death": "clips/sh1_death_pit.mp4",
               "goto": "misfile_dimension" },      // custom death THEN branch (pit!)
    "right": { "death": "clips/sh1_death_acct.mp4" } // custom death, normal retry
  } }
```
Rules: cue shows all choice glyphs side by side; no-input-by-close uses the scene's
default death; a `choices` window must be the clip's last window; `random: ["a","b"]`
on a scene picks one of two clip/outcome sets per attempt (for THE TAPE mimic gag).
Choice windows default to longer durations (1.5s) — they're decisions, not reflexes.

## v2 mechanics (BUILT 2026-07-20 — as implemented in player.js)
- `mirrorOk: true` scene flag: scene is mirror-eligible. The engine mirrors it
  (CSS scaleX(-1) + left/right swap in inputs and cues) when it comes back in the
  replay queue — free variety, "the Dead Wax remembers... backwards".
- Replay queue: `onSuccess: "REPLAY"` (on sh6) queues died-in scenes (unique,
  cap 8, choice/random scenes excluded), needle_skip.mp4 transition between each,
  then t7s1. Needledrop/collect are disabled during replays.
- `needledrop: {t, clip, bonus, label?, skipTo?}` on a scene: optional action
  input during the flash branches to the alt clip; ignoring it is not a fail.
  `label` grants a white label, `skipTo` overrides onSuccess (t6s1 alt skips t6s2).
- `collect: {t, input, label}` on a scene: unprompted input during a background
  flash grabs white label N (+250, toast); wrong unprompted inputs stay ignored.
  All 7 labels → stinger.mp4 plays after win.mp4.
- Endurance: `onMiss: "restart"` + `maxRestarts` on a scene — misses replay the
  clip with window closes tightened 0.15s per restart; the Nth miss is a real death.
- Hold windows: `hold: true` — input held from open (0.35s slack) to close.
- Soft fail: `failGoto: "id"` on a scene — fail costs no life, plays the death
  clip if any, and respawns at the given scene (t5s4 platter lock → t5s1).
- Choice deaths can branch: `{death, goto}` respawns at goto after the death
  (sh1 wrong file → Misfile Dimension). Scene-level `score`/`label` grant on clear
  (sh5_bonus). Choice window timeout uses the scene's default death.
- NOT built (cut for now): difficulty tiers, gamepad, touch-hold windows.

## Player loop (player.js structure)
1. **Boot**: fetch scenes.json → preload manifest.
2. **Preloader**: two `<video>` elements, A/B swap. While A plays scene N, B preloads
   scene N's death clip first (most likely next need), then N+1's action clip, via
   `preload="auto"` + `load()`. Also `fetch()` + blob-URL cache for clips ≤ ~8MB to
   guarantee gapless swap. Show % bar on boot for first 3 clips only.
3. **Clock**: drive QTE timing off `video.currentTime` polled in `requestAnimationFrame`
   (NOT wall-clock setTimeout — survives decode stutter/tab throttling).
4. **Input**: keydown (arrows + space/enter) and touch (swipe quadrants + tap = action).
   Map gamepad later (Gamepad API, d-pad + A). Ignore key auto-repeat.
5. **Cue rendering**: at window open, flash a chunky neon arrow (direction) or ring
   (action) center-low on screen, CSS animation ~300ms pulse. Dragon's Lair barely
   cued; we cue by default — `cue:false` per window for hard mode later.
6. **HUD**: lives as record icons top-left, scene name bottom-left (debug only), score
   = scenes cleared × 1000 minus deaths × 100, arcade font.
7. **States**: ATTRACT (loop attract.mp4 or title card + "PRESS ANY KEY", high-score
   from localStorage) → PLAYING → DEATH → GAMEOVER → WIN (win.mp4 → credits → attract).
8. **Debug mode** (`?debug=1`): timeline scrubber, windows drawn as colored bands on a
   bar under the video, current input state, frame-step keys (,/.), scene jump dropdown.
   This is how we'll tune every window against real Flow clips — build it FIRST.

## Feel-tuning constants (top of player.js, tweak in one place)
```js
const WINDOW_DEFAULT = 0.7;   // s — default window length if authoring shorthand used
const EARLY_GRACE   = 0.25;   // s before open where input = fail
const DEATH_HOLD    = 0.6;    // s to hold last death frame before retry fade
const CUE_LEAD      = 0.0;    // s to show cue before window opens (bump to 0.15 if too hard)
```

## Placeholder clips — tools/make_placeholders.sh
Generates test clips so the whole game is playable before any Flow spend. For each
scene in scenes.json: 5s 1280x720 clip, solid color per scene, huge scene-id text,
and at each QTE window a white flash + 1kHz beep + arrow glyph burned in at exactly
t[0]..t[1] (drawtext + sine + overlay enable='between(t,A,B)'). Death placeholders =
red background + "DEATH sXX". ffmpeg one-liner per clip; script reads scenes.json
with python3 -c json. Also make attract/gameover/win placeholders.
Ship scenes.json with 3 authored placeholder scenes so the loop is provable end-to-end.

## Post-processing real clips — tools/postprocess.sh
`postprocess.sh <in.mp4|dir> <scene_id> <action|death>` → trim silence/dead frames
(args for in/out points), scale/pad to 1280x720, 24fps, `-c:v libx264 -crf 20
-pix_fmt yuv420p -movflags +faststart`, silent aac track if none (uniform streams =
gapless swaps), output to engine/clips/ with canonical name, print duration so the
author can set windows. Keep originals in production/raw/ untouched.

## Deploy
rsync engine/ to botchat games VPS per deploy-map skill; it's static. Cache-bust
scenes.json + player.js with ?v= query from meta.version. Verify live by curling
the URL and loading in browser. ship-check before public link.