TURNCRAFT/docs/briefs/LANE_A_ENGINE.md

LANE A — Voxel Engine & Rendering

Read first: docs/DESIGN.md, docs/CONTRACTS.md, everything in src/core/. You own: src/engine/**, src/demo/engineDemo.ts, demo-engine.html. You may not touch anything else.

Mission

Build the voxel core: chunked block storage, greedy meshing with a procedural texture atlas and per-vertex AO, and the Three.js renderer/scene/lighting rig. Everything the player sees that is made of blocks goes through you. Target: the full 448×160×256 world renders at 60 fps on a mid-range laptop.

Provides (consumed by other lanes)

• VoxelWorld — implements IVoxelWorld from src/core/types.ts
• createRenderer(container: HTMLElement) → { renderer, scene, camera, setEmissiveBoost(v: number), render() } — the one place Three.js is set up
• ChunkManager — builds/updates chunk meshes from a VoxelWorld, adds them to the scene, and remeshes dirty chunks with a per-frame budget
• buildAtlas() — the procedural texture atlas (CanvasTexture)

Tasks

A1. VoxelWorld storage

• One Uint8Array per 32³ chunk, allocated lazily (empty chunks read as AIR).
• getBlock: out of bounds → AIR for y ≥ 0, a solid sentinel below y < 0 (per the IVoxelWorld doc comment). setBlock: ignore out-of-bounds.
• setBlock marks the containing chunk dirty, plus each adjacent chunk when the voxel lies on a shared face (otherwise cross-chunk faces go stale).
• Expose forEachDirtyChunk(cb) / clearDirty(cx,cy,cz) for the ChunkManager.
• Bulk-fill fast path: fillBox(x0,y0,z0,x1,y1,z1,id) (worldgen will paint millions of voxels; per-voxel setBlock with dirty bookkeeping is too slow — fillBox writes raw and dirties each touched chunk once).

A2. Procedural texture atlas

• One canvas atlas of 16×16 px tiles, one tile per block id (index = id), built from BLOCKS in src/core/blocks.ts: paint each tile with its pattern + tint. Implement all patterns in the Pattern union: solid (±6% value noise), brushed (fine horizontal streaks), plywood (wavy grain lines, slightly darker for ply_edge with laminate stripes), speckle, grooves (fine concentric-ish dark lines — straight parallel lines are fine at tile scale), pcb (traces + pads), mesh (dark hole grid), glass (faint diagonal streaks, low alpha), led (bright core, radial falloff), felt (soft high-frequency noise).
• NearestFilter, no mips (or NearestMipmapLinear with generated mips if you handle bleeding via 1px tile padding — your call, document it).
• Two materials: opaque (alphaTest off) and transparent pass (for glass, vinyl_blue) — both from the same atlas. Emissive: vertex-color or a second emissive atlas so emissive > 0 blocks glow; expose setEmissiveBoost(v) multiplying emissive intensity (Lane E pulses it to the beat; default 1.0).

A3. Greedy mesher

• Per chunk: greedy meshing over the 6 face directions, merging coplanar faces with identical (blockId, AO tuple). Neighbor lookups read through VoxelWorld so chunk borders cull correctly.
• Transparent blocks: don't occlude opaque neighbors; mesh them into the separate transparent geometry, don't merge across different transparent ids.
• Per-vertex AO: classic 3-neighbor corner darkening (the Minecraft 0–3 levels), baked into vertex colors. Flip quad triangulation on the AO anisotropy case.
• Output non-indexed or indexed BufferGeometry — your call — with position, uv (atlas tile + repeat handled by writing uvs per merged quad using a tiny shader patch or by splitting quads; greedy + atlas needs one of: (a) uv wrap via shader fract, or (b) cap merge length and tile uvs. Choose (a): patch onBeforeCompile to fract the uv within the tile. Document the approach in code).

A4. ChunkManager

• Initial full-world mesh build must complete < 3 s (parallelize nothing — just be efficient; greedy over 560 mostly-empty chunks is fast).
• Per-frame remesh budget (e.g. 4 chunks/frame) draining the dirty set; listens to nothing — poll forEachDirtyChunk from its update().
• Frustum culling is Three.js default per chunk mesh; nothing fancier needed.

A5. Renderer rig

• createRenderer(container): WebGLRenderer (antialias off, pixelRatio capped at 2), sRGB output, ACES tone mapping, PerspectiveCamera 75°.
• Lighting per DESIGN §7: warm key DirectionalLight, cool ambient/hemi fill, fog colored warm plywood-brown, background near-black warm.
• No OrbitControls in the delivered API (demo may use one).

Demo (demo-engine.html)

Standalone scene: build a VoxelWorld, fill a test pattern that exercises everything — a 60×60 plywood floor, stepped mesas of every block id in a labeled row (one pillar per id), a glass arch, an LED wall, a hollowed cave — OrbitControls to fly around, on-screen text: draw calls, triangles, remesh time. A button "torture" edits 500 random blocks/sec to prove dirty remeshing keeps 60 fps. A slider drives setEmissiveBoost 0→3.

Acceptance

• Full-size empty-ish world + test pattern ≥ 60 fps, < 300 draw calls
• AO visibly darkens inner corners; no cracks/z-fighting at chunk borders
• Transparent blue vinyl & glass render correctly against opaque blocks
• Torture button: no frame drops below ~55 fps, edits appear within 2 frames
• All 10 patterns visually distinct at demo-engine.html
• npm run typecheck clean; HANDOFF.md written

Out of scope

Player, physics, worldgen content, machines, audio, UI. No web workers in v1 (note in HANDOFF if meshing budget suggests they're needed later).