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. 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.