TURNCRAFT/docs/INTEGRATION.md

TURNCRAFT — Integration Guide

Run this phase AFTER the five lanes land, in one session (the integrator may be any agent; it completes src/main.ts and may make minimal cross-lane glue fixes, documenting every one).

Pre-flight

1. npm i && npm run typecheck — must be clean with all lanes merged.
2. Read every lane's HANDOFF.md (in each owned directory). They list stubs and contract friction — resolve friction FIRST, before wiring.
3. Open all five demo pages; each lane's acceptance boxes should be checkable.

Wiring order (src/main.ts)

1. createRenderer(#app) → renderer, scene, camera, setEmissiveBoost.
2. new VoxelWorld(WORLD_X, WORLD_Y, WORLD_Z).
3. buildBooth(world) (Lane C) — time it; expect < 500 ms.
4. ChunkManager(world, scene, atlas) — initial full mesh; expect < 3 s.
5. createMachines(world) (Lane D) with QUEST_POS from src/worldgen/questPositions.ts; add getObject3Ds() to scene.
6. new PlayerController(world, { getColliders: machines.getColliders, camera, domElement, spawn: SPAWN }) (Lane B, spawn from Lane C).
7. new Interaction(world, player, machines, hotbar) (Lane D).
8. AudioEngine + FxSystem({ scene, setEmissiveBoost }) + Hud (Lane E); audio init gated behind Lane E's start overlay click.
9. Loop: fixed-step accumulator at FIXED_DT, max MAX_SUBSTEPS: machines.update(dt) → player.update(dt) → interaction.update(dt) → fx.update(dt) + audio.updateListener(player) per frame → chunkManager.update() → render.

Smoke tests (manual, in order)

1. Spawn: on Deck A plinth, facing mixer, 60 fps, booth fully visible, world dim (pre-repair), groove silent.
2. Ride: press deck A start — platter spins up (no stylus yet = no music), step on: you ride. Center calm, rim brisk. 45 + rim + jump flings you toward the mixer.
3. Mine/build: break dust blocks, place a bridge from plinth to mixer, auto-step up knob stems.
4. Quest end-to-end: complete all five nodes per DESIGN §6 — each fires a subtitle, an LED trace, and one more stem. Power switch finale: win sequence plays, both decks spin, booth fully lit and audio-reactive.
5. Soak: 10 minutes of free play — no console errors, no fps decay (watch for per-frame allocation creep), audio never drifts.

Known integration risks (check these specifically)

• Lane C's duck-typed fillBox fallback vs Lane A's real one — verify the real path is taken (log once).
• Chunk dirty flood during quest LED traces if Lane E ever setBlocks — it must NOT (sprites only); grep setBlock outside A/C/D.
• Platter collider height vs Lane C's platter-well depth: player must step from plinth top onto the record (≤1 voxel lip, B's auto-step covers it).
• Double-grounding: player standing where a kinematic cylinder overlaps voxels (well rim) — B resolves voxels first, then platforms; verify no jitter standing on the rim edge.
• Audio autoplay policy: nothing audible before the start-overlay click.

After integration

• npm run build must produce a deployable static bundle.
• Deploy per the deploy-map skill (partly.party) when John says ship.