TURNCRAFT/docs/DESIGN.md

# TURNCRAFT — Design Document

*Honey-I-Shrunk-the-DJ. A Minecraft-style voxel world contained entirely inside
a vinyl DJ booth: two Technics-style 1200 turntables, a 4-channel mixer, cables,
a patch bay, and the plywood console that holds it all.*

Read this together with [CONTRACTS.md](./CONTRACTS.md). Numbers quoted here are
defined once in `src/core/constants.ts` — the code is the source of truth.

---

## 1. Vision

You are ~7 mm tall, standing on a spinning record. The world is finite, dense,
and hand-authored — a diorama, not a landscape. Every zone is a piece of DJ
gear rendered at monumental scale: the mixer is a mesa of faders and knob
forests, the tonearm is a chrome bridge, an unplugged RCA lead is a rope
bridge into a canyon, and beneath the plinths lie glowing circuit-board caves.

The palette is deliberately restrained — greys, silvers, matte blacks, dark
rubber — inside a warm birch-plywood shell, with two loud accents: translucent
**blue vinyl** records and emissive **LEDs** (red/green/amber/blue). Think the
inspiration photo: utilitarian gear, warm wood, blue records.

The fantasy: *the booth is dead when you arrive.* Your job is to bring the mix
back — repair the signal chain, press start, and ride the record while the
whole world lights up in sync with the music.

## 2. Pillars

1. **The world IS the gear.** No abstract terrain. Every structure reads as a
   real DJ-booth object at 4 mm/voxel scale.
2. **The platters spin and you can ride them.** Rotating kinematic platforms
   are the signature mechanic. Everything else is standard voxel play.
3. **Sound is the win state.** Repairs unmute stems of one continuous house
   groove; lights and particles react to it. A silent booth is a broken booth.
4. **Zero external assets.** All textures are procedurally painted, all audio
   is synthesized. The repo builds from `npm i && npm run dev` alone.

## 3. Scale & World Map

1 voxel = 4 mm. Player: 1.8 voxels tall (~7 mm). World: **448 × 160 × 256**
voxels, chunked at 32³ (14 × 5 × 8 = 560 chunks, ~18 M voxels — trivially fits
in Uint8Arrays).

Vertical strata (Y):

| y | what |
|---|------|
| 0–40 | **Under-table**: inside the plywood console — record crate, parts bin, PCB caves under the gear, cable runs |
| 40 | **Tabletop** — plywood plateau the gear sits on |
| 40–80 | Turntable plinths (steel-grey mesas), mixer body |
| 80–81 | Plinth tops; the record surface sits 1 proud of the plinth (81 = vinyl top, auto-steppable), platter body filling the 6-deep well below |
| 67 | Mixer face plate (knob forest, fader alleys) |
| 85–140 | Tonearm bridge, dust-cover glass arcs, booth walls, patch-bay wall |

Horizontal layout (X across, Z deep; see `LAYOUT` in constants.ts):

```
z=256 ─────────────────────────────────────────────── back
      │ plywood back wall (z=200) — PATCH BAY dungeon  │
      │        C A B L E   C A N Y O N (z 140–200)     │
      │  RCA/power leads as rope bridges & tunnels     │
      │ ┌────────────┐  ┌──────────┐  ┌────────────┐  │
      │ │  DECK A    │  │  MIXER   │  │  DECK B    │  │
      │ │ x 24–136   │  │ x183–265 │  │ x 296–408  │  │
      │ │ spindle    │  │ 4ch face │  │ spindle    │  │
      │ │ (80, 96)   │  │ plate    │  │ (352, 96)  │  │
      │ └────────────┘  └──────────┘  └────────────┘  │
      │        front lip / headphone ledge (z<48)      │
z=0   ─────────────────────────────────────────────── front
       x=0                                        x=448
```

## 4. Zones (biomes)

1. **Deck A — "The Blue Record"** (spawn). Steel-grey plinth mesa. On top: the
   platter (rotating machine, not voxels) carrying a translucent blue vinyl
   disc with a cream label. Strobe dots glow on the platter rim. The pitch
   fader is a canyon slot in the plinth; start/stop is a giant press-plate;
   the spindle is a climbable chrome pole. The tonearm arcs overhead as a
   chrome bridge from its rest to over the record.
2. **The Mixer Massif** (center). Tallest mesa. Face plate at y=67 is a
   grid-city: EQ **knob forest** (mushroom-cap knobs on stems), four **fader
   alleys** (deep slots with sliding fader sleds), the **crossfader tram**
   running left–right at the front, **VU towers** at the back — columns of
   LED blocks that light bottom-to-top with the music. Speaker-mesh vents on
   the sides are climbable ladders and the way into the mixer's interior.
3. **Cable Canyon** (behind the gear, z 140–200). Tangled RCA and power leads
   spanning tabletop to back wall — walkable rope bridges (2×2 cable-block
   tubes with red/white/gold RCA plug heads). Dust drifts here; dust-block
   boulders to mine.
4. **The Patch Bay** (back wall, y 90–118). The wall-mounted RCA switcher from
   the photo, scaled to a cliff-face dungeon: gold jack sockets are round
   doorways into shallow rooms; one socket needs its plug pushed home (quest).
5. **PCB Depths** (under-table, y 0–40). Mine down through a plinth vent:
   green circuit-board floors, copper-trace paths that glow faintly, solder
   blob stalagmites, capacitor pillar rooms, the fuse box (quest), and the
   record crate — a plywood cavern of giant vinyl slabs to spelunk between.
6. **Deck B — "The Silent Deck"** (mirror of A, but stopped, dust-covered, its
   half-open glass dust cover forming a crystal cave overhead). Comes alive
   only at the end.

## 5. Mechanics

- **Standard voxel play**: mine breakable blocks (dust, vinyl, knobs, LEDs…),
  carry them in a 9-slot hotbar, place them to build bridges/stairs anywhere.
  Structural blocks (plywood shell, cables) are unbreakable — the booth keeps
  its shape.
- **Riding the record**: platters are kinematic rotating cylinders. Standing
  on one adds its surface velocity to you. At "33" (2.0 game-RPM) the label
  area is a lazy carousel and the rim is a brisk travelator; at "45" the rim
  will fling you — which is a legitimate traversal move (record-edge launch
  onto the mixer).
- **The needle plow**: while a deck plays, the stylus tracks slowly inward
  along the groove spiral. Its contact shoe is a kinematic pusher — get in
  front of it and it shoves you along the groove. Jumping the tonearm's
  moving shadow is a mini-game.
- **Machine interactions** (press E / tap): start/stop plates toggle platters,
  33/45 buttons switch speed, pitch faders scale RPM ±50%, channel faders and
  crossfader slide (and duck their stem's volume live), the cue lamp toggles
  headlamp-style local light.
- **No mobs in v1.** Ambience only: drifting dust motes, LED pulses. (Stretch:
  static-spark wisps in Cable Canyon.)

## 6. The Quest — "Bring Back the Mix"

The booth starts silent and dim. Five signal-chain breaks (order-agnostic,
tracked in `SIGNAL_NODES`):

| node | where | fix |
|---|---|---|
| `stylus` | Deck A headshell is empty | find the chrome stylus block in the PCB Depths parts bin, carry it up, place it in the headshell socket |
| `rca` | Patch bay socket, back wall | walk Cable Canyon's loose lead to its plug, push the plug block into the gold socket |
| `crossfader` | Mixer crossfader slot | a dust boulder jams the tram — mine it out |
| `fuse` | Fuse box in PCB Depths | swap the blackened fuse block for a fresh one from the parts bin |
| `power` | Master switch, mixer rear | climb and press it (only lights up once the other four are done — it's the finale trigger) |

Each repair: a `signal:repair` event → an LED trace lights along the *actual
signal path* through the world (cartridge → tonearm → RCA → mixer → out), and
one more stem of the groove unmutes (drums → bass → chords → lead → full mix
with sweeps). Final repair: both platters spin up, every LED in the world goes
audio-reactive, `game:win` fires, and the player just… gets to ride records in
a living booth. Sandbox continues after the win.

## 7. Look & Feel

- **Rendering**: chunky voxels, per-face procedural 16×16 textures from a
  canvas atlas (see palette in `src/core/blocks.ts`), soft baked-ish AO at
  voxel corners, one warm key light + cool fill + emissive LED blocks.
  Fog tinted warm plywood-brown at the world edges so the booth walls fade
  like a horizon.
- **Audio**: one endless synthesized 118 BPM house groove in stems. Platter
  start/stop bends pitch (the classic Technics spin-up/brake). Positional:
  the music comes *from the decks*.
- **Feel targets**: 60 fps on a mid laptop; Minecraft-familiar controls
  (WASD, space, mouse-look, E interact, LMB break, RMB place, 1–9 hotbar,
  F toggles fly for debugging).

## 8. Out of Scope (v1)

Mobs, crafting, survival/health, saving, multiplayer, infinite terrain,
mobile controls. The diffusion-terrain research that inspired this project is
explicitly *not* needed: the world is a finite authored diorama.