05 — Renderer Spec: 3D ASCII That Reads, Moves, and Sings #

How the game looks in motion, how we build it, and how we keep it readable at 60fps on a toaster over SSH.

Read this with doc 01 §1/§6 (the feel) and doc 04 §4.5 (the pipeline). This doc is build-to-print for the engine team.

5.1 The look — "1982 dreaming about 2032" #

Core thesis: ASCII is not a limitation aesthetic — it is a resolution-independent vector-ish medium. A wall 2 meters away and a wall 200 meters away both render as characters, but density, color, and motion sell the depth. The reference images in the reader's head: terminal raycasters, caca-style demos, phosphor CRTs, DOS ANSI art — but with modern truecolor, smooth motion, and art direction.

The frame, described precisely (120×36 reference target):

• Depth as density. Distance ramp per material class, 10 steps, near→far: █▓▓▒▒░░==--::..·· — nearest surfaces nearly solid, far surfaces dissolve into mist-dots. Fog is diegetic: dungeon damp + lantern falloff, not a shader trick. Fog color shifts by stratum (Shallows: warm brown-black; Works: teal-black ozone; Deep: violet-black + drifting · motes).
• Edges as line-art. Hard geometry edges (doorframes, stair lips, grate bars, elevator cables) snap to / \ | - + ─ │ ┌ ┐ └ ┘ ├ ┤ box-drawing when the surface angle is edge-on to the ray. This single rule makes architecture pop out of the density field — a doorway reads instantly at 40m.
• Faces as half-block gradients. Interior of surfaces uses ▀▄█ ░▒▓ + truecolor foreground/background pairs to fake sub-cell vertical resolution (two vertical samples per cell — effectively doubles perceived vertical res for floors/ceilings/walls).
• Actors as glyphs-with-posture. Player @ (gold when lit, dim-blue when dark). NPCs by role-glyph: townsfolk & variants, wardens §, tinkers %, monsters per-species (r cable-rat with amber spark-pixel when charged, V Vendric with too-clean white glass pixels, O Drowned bell with swinging ~ clapper offset by animation phase, cherubs ✦ brass). Posture modifies: climbing ≋, swimming ≈, rope-hanging |o, prone –. Status overlays: burning = red * flicker on the glyph cell, blessed = gold . halo ring (one-cell radius, sparse), cursed = violet : drip.
• Light as truth. Every cell's brightness = computed light level (doc 03 §3.3) quantized to 24 steps and multiplied into truecolor RGB. Lantern cone is visibly a cone: warm +* core → amber = falloff → cold blue . darkness. Muzzle-flash of a wand whites out 3 frames (with no-flicker palette option clamping this). Phosphor flora (tinker-moss) renders as sparse green */· constellations — navigation beacons players learn to love.
• Sound made visible. Noise events draw expanding ( ) arcs for ~6 frames, intensity = arc count + brightness, direction readable from arc center offset. A slammed door two floors up renders as faint arcs leaking through the grate glyphs — the player sees upstairs consequences.
• Motion language. 60fps interpolation of 10Hz sim (doc 04 §4.2): actors glide between ticks, lantern flame shivers (2-frame ~ wobble), wheat ,/;/' fields outside ripple in wind bands, elevator cables │ scroll, water ≈ flows downhill visibly, gas ░ churns upward. The world never sits still — stillness means death or pause, and pause draws a ‖ border.

Three cameras, one sim (switching never pauses in Classic):

1. First-person (default): eye at actor head height, 75° FOV cap (motion-sickness law), subtle head-bob (toggleable, off by default in no-shake mode). Crosshair is a NetHack-voice hint cell, not a shooter reticle.
2. Chase-orbit (press Tab to toggle; M restores the saved perspective on map exit): camera 3m behind/up, mouse-drag orbits, auto-collides (pulls in rather than clipping). For ropework, climbing, and admiring the mule.
3. Top-tactical (M): orthographic ASCII plan-view, 2.5D stacked-glyph rendering (^ stairs up, v down, = bridges, ~ water, ░ gas) with Z-slider (PageUp/PageDown; Home recenters; optional in legacy keymaps). The planner: chalk marks, rope-length preview arcs, thrown-trajectory · dots. Pause-step auto-engages here in Story mode; Classic keeps ticking (display a ⏳ LIVE tag so nobody feels cheated).

The title-screen resolve (doc 01 §1) is a renderer feature: new-game boot plays a 2-second density ramp from → full scene, left-to-right like developing film. Cheap (animates fog density scalar), unforgettable.

5.2 The algorithm — CPU raycast, DDA, diffed ANSI #

Per frame (render thread, reads triple-buffered snapshot — never touches live sim):

1. Snapshot acquire (~200KB: visible chunks + actor list + light/sound overlay buffers + particle sparks). Non-blocking try-read; on contention, re-render last frame (tearing beats stalling).
2. Primary rays: one ray per cell column-half (half-blocks give 2 vertical samples per cell → cast W rays × 2H samples; at 120×36 that's 120×72 = 8,640 rays/frame — trivial for CPU). DDA through voxel grid (Amanatides & Woo), max distance per quality tier, early-out on opacity. Fixed-point DDA with integer stepping — no float drift, deterministic screenshots for tests.
3. Shading per hit: material base color (palette-indexed, truecolor-expanded) × light level (24-step) × distance fog (density ramp select) × facing (top faces +10% warm from lantern law, side faces neutral, bottom faces −15% cold). Edge detection: if the ray grazes a voxel boundary within ε OR neighbor depth discontinuity > threshold → line-art glyph instead of density glyph. Normal estimation via face hit (DDA gives this free). Terminal exposure convention: material-table channels are linear reflectance coefficients. Encode the lit foreground product with the sRGB transfer function before emitting RGB bytes; direct linear bytes on an sRGB display double-darken the lantern falloff. Zero-light crush bypasses this encoding. Density and edge glyphs retain a deliberately dark background partner (quarter of the unencoded product); only actual oriented half-block glyphs may use another ray's foreground as background. Fog remains a post-shade display-color blend. The production opening regression requires at least 35% nonblank viewport cells with foreground relative luminance ≥0.10 and fg/bg contrast ≥3:1, in truecolor and decoded ANSI256 at default settings; this is a contrast floor, not certification of the three-glance experience.
4. Actors & transparents: billboard glyph selection by species+posture+anim phase, depth-tested against ray depth buffer, drawn brightest-first so overlapping torch-bearers composite sensibly. Transparent/gas/fluid overlays (≈ water sheen, ░ gas churn, ( sound arcs, · thrown trails, flour-dust : puffs) composited after opaques with max-depth ordering.
5. Post: vignette (corners −20% brightness beyond 70% radius — focuses the eye, hides narrow-terminal stretch), hint-ribbon glow (key hints brighten when contextually relevant — doc 01 §2), damage flash (red edge ! ticks, clamped by no-flicker setting), darkness crush (below-light-threshold cells snap to near-black blue, not gray — darkness must feel total).
6. ANSI diff encode: compare cell buffer (glyph + fg + bg) against last-flushed frame; emit minimal cursor-move + SGR sequences. Typical frame diff <15% of cells → SSH-playable. Full redraw on resize/palette swap. 256-color fallback path (quantize truecolor via precomputed 6×6×6 cube LUT) and no-color path (density-only + bold — the game stays fully playable; tests assert this).
7. Flush + frame pacing: target 60fps, floor 30fps (slice gate). Adaptive render-scale: if frame time > budget 3 frames running, drop horizontal res 10% (re-expand when headroom returns). Sim fidelity never degrades — only pixels.

Performance budget (slice gate, measured cargo bench -p hexwork-render + real terminals):

• Raycast+shade ≤ 6ms @120×36 on 5-yr-old laptop CPU (single thread; worker-pool feature for >2 cores splits screen bands — deterministic band boundaries for test-stable output).
• ANSI encode+flush ≤ 4ms typical (diff path), ≤ 12ms worst (full redraw).
• Snapshot copy ≤ 0.5ms. Memory: triple buffer ≤ 1MB total. Zero per-frame allocations in hot path (pooled buffers — assert with a debug allocator tripwire).

5.3 Terminal reality — backends, capability matrix, degradation #

Backend: crossterm (portability) behind the hexwork-term trait so we can swap. Capability probe at boot (truecolor? unicode? mouse? focus? bell? response-time for SSH lag estimate):

Detect-and-adapt automatically; every adaptation logged once ("Downshifted to 256-color — set HEXWORK_FORCE_TC=1 to override"). No silent ugliness.

5.4 Readability laws (playtested in slice, non-negotiable) #

1. Three-glance rule: threat (red glyph + movement), exit (lit edge-art + draft lines), loot (glint pixel) each readable within 3 eye-glances of entering a room. Worldgen + palette tests assert glint/edge contrast minimums.
2. No camouflage kills: no lethal monster shares glyph+color with a harmless one at the same light level. Mimics break this deliberately (Vendric) and are therefore required to have the tell (off-key hum + too-clean pixels) — tested.
3. Darkness is honest: underexposed cells never fake-hide an enemy that the sim says is visible, and never show one the sim says is hidden. Render is a pure function of snapshot + camera — assert with screenshot-hash tests on scripted scenes.
4. FOV ≤ 75°, bob off by default in reduced-motion, flash clamped. Motion-sickness toggles ship in slice, not 1.0.

5.5 Accessibility rendering paths #

• Colorblind palettes: protan/deutan/tritan-safe + high-contrast + no-flicker, each with measured contrast ratios (tests). Threat/loot/exit never distinguished by hue alone — always glyph+brightness redundant.
• Screenreader mode: bypasses raycast; emits prioritized text event stream (threat > exit > loot > flavor, throttled, interruptible). Fully completable — a blind delver should be able to win; test with scripted playthrough asserting winnability from stream alone.
• Dyslexia/log options: alternate log font rendering (terminal font is user's — so: shorter lines, more spacing, no italics in critical warnings; all caps reserved for death).

5.6 What the engine team builds (ordered) #

1. Cell buffer + ANSI diff + crossterm bring-up with a static test scene (slice week 1 — something on screen day 3).
2. DDA raycaster + density ramp + fog on voxel snapshots (grayscale first — color is step 4).
3. Edge-art detection + half-block faces + light-level multiply.
4. Truecolor + palettes + 256/no-color fallbacks.
5. Cameras (FP → orbit → tactical) + interpolation + vignette + sound arcs.
6. Adaptive scale + SSH path + capability probe + benchmark harness.
7. Screenshot-hash test rig + readability bots (three-glance assertions on generated rooms).
8. Screenreader stream + reduced-motion + all palettes certified.