04 — Software Architecture #

Rust workspace, crates, sim design, data flow. The engineering build-to-print.

Target: Rust 1.75+ (stable), single static binary hexwork, no GPU, no async runtime in sim, deterministic fixed-tick simulation, 60fps CPU ASCII rendering in any modern terminal.

---

4.1 Workspace layout #

hexwork/
  Cargo.toml            # workspace + release profile (lto, panic=abort? no — unwind for crash reports)
  docs/                 # this bible (00–06)
  crates/
    hexwork-core/       # ECS + sim tick + rules. NO I/O, NO terminal. 100% deterministic.
    hexwork-worldgen/   # floor/town generation (seeded RNG, anchor rooms + systemic fill)
    hexwork-content/    # data-file loading + validation (TOML/JSON monsters, items, hymns, contracts)
    hexwork-render/     # CPU raycaster → cell buffer → ANSI diff → terminal
    hexwork-term/       # terminal abstraction: raw mode, input, resize, truecolor detect, screenreader hook
    hexwork-audio/      # tiny beep/bell synth via terminal bell + optional rodio (feature-gated)
    hexwork-save/       # saves, lineage vault, .hexdemo replays
    hexwork-ui/         # screens, HUD, log, menus, look-mode, chargen (depends on core+content, not render internals)
    hexwork-cli/        # main.rs: arg parsing, game loop, panic handler, crash-report writer
  assets/
    data/               # canonical content: monsters.toml, items.toml, hymns.toml, gods.toml, contracts/, floors/, towns/
    palettes/           # colorblind/high-contrast/no-flicker themes
  tests/                # cross-crate integration: rule-chain tests, determinism replays, content validation

Dependency rule (enforced by CI cargo deny + import lints): core ← worldgen, content ← save ← ui ← cli; render and term are leaves consumed by cli only. core must build with --no-default-features and zero terminal/system deps (so we can fuzz + WASM-test the sim).

Crates and single responsibilities:

Crate	Owns	Must never own
core	entities, components, tick(), fluids/gas/fire/sound/light propagation, combat, hymn resolution, god ledgers	RNG seeding policy, file I/O, ANSI codes
worldgen	seeded layouts, anchor-room placement, vertical connectors, faction seeding	balance numbers (those live in data files)
content	schema structs, validation errors with file:line, hot-reload in debug	gameplay logic
render	camera, raycast, glyph ramp, lighting, diff buffer	sim rules
term	crossterm backend, input map, resize events, bracketed paste off	game state
save	bincode + zstd snapshots, lineage vault (sled or JSON), demo event log	rule decisions
ui	screens/state machine, HUD layout, keybinds, tutorial hints	pixels
cli	loop, tick scheduling, panic → epitaph writer	—

4.2 The sim — deterministic fixed-tick ECS #

ECS choice: hecs (small, no systems-scheduler magic) + handwritten tick order. Explicit tick phases beat parallel-scheduler nondeterminism for a NetHack-descendant: determinism > core-count bragging.

Tick: 10 Hz fixed (DT = 100ms). Render interpolates actor positions between ticks (no sim effect). Holding Shift = advance exactly 1 tick (roguelike step mode). All randomness from a single Xoshiro256** stream seeded per-run; sub-streams per subsystem via seed ^ domain_tag (fluids, combat, worldgen, gossip) so adding a particle never reschedules combat.

Determinism contract: same seed + same input-tick log = same state hash. core::hash_state() (SipHash over canonical entity dump) runs every 600 ticks in debug + on save; desync = crash with report. This powers .hexdemo replays (input log + seed) and Ironcartographer dailies.

Phases per tick (fixed order, each fully documented in code):

1. intent (player + AI intents queued; AI is utility-scored, no allocations in hot path)
2. hymns & bargains (spell resolution, god ledger writes)
3. move & collide (continuous positions → voxel occupancy; shoves, slips, falls, ropes)
4. fluids (water/oil/blood downhill + fill-up; capped iterations/tick for perf)
5. gas & scent (rise/sink + draft advection)
6. fire & heat (ignite, spread, smoke spawn, melt)
7. signal & electricity (wire/plumbing graph BFS, capped depth)
8. light (recompute dirty cells only)
9. sound (emit → propagate → AI stimulus)
10. structure (load checks on marked-dirty supports only)
11. rot & schedules (corpses, spoilage, NPC clocks, faction clocks — cheap, staggered)
12. death & epitaph (rule-chain recorder writes cause links)

Performance budgets (slice gate): tick ≤ 8ms p99 on M1-airs and 5-yr-old ThinkPads for a 96³ active volume; fluids/gas capped at 4k cell-updates/tick with spillover queue; sound/light use dirty-rect propagation. Bench harness cargo bench -p hexwork-core with criterion; CI fails on >10% tick regression.

4.3 World representation #

• Voxels: ChunkedGrid<48³> chunks, Voxel { material: u8, occ: u8, fluid: FluidCell, gas: GasCell, light: u8, scent: u8, flags } — 16 bytes/voxel. Active set = loaded 3×3×3 chunks around player + lit/settled far-field abstract sim for towns (schedules only).
• Actors: continuous Vec3<f32> + radius + stance (stand/crouch/climb/swim/prone/rope). Voxel occupancy derived, never authoritative for actors (so falling/leaning/riding work).
• Vertical connectors as first-class entities: Stairwell, Shaft, Well, Vent, ElevatorCar, Counterweight, RopeAnchor — each with load/length/anchor-quality; cutting/flooding/jamming handled by generic rules, not scripts.
• Rooms breathe: each enclosed volume gets a pressure node; doors/vents/grates are edges. Draft field derived per tick for smoke/scent/gas advection. Secret vents are just edges flagged hidden until flour/smoke reveals them.

4.4 Content as data (designers edit TOML, not Rust) #

Every monster/item/hymn/god/contract is a validated data file. Example (shape is contract, exact fields in assets/data/*.schema.md to be written in slice):

[monster.cable_rat]
hp = 6; habits = ["gnaw_wire", "nest_in_walls"]; tell = "ozone smell + skritch above"
uses = ["blood_pits_iron", "pelt_insulates", "wire_in_belly"]
conducts = true; blood = "weak_acid"; fear_of = ["cats", "bells"]

Validation: hexwork-content build-time test loads ALL data, checks cross-refs (every blood= names a fluid, every contract names a reachable floor), and rejects single-use items (the 2-uses law is a TEST, not a guideline). Balance numbers carry // intent: comments.

4.5 Rendering pipeline (detail in doc 05) #

sim snapshot (read-only) → camera → raycast/DDA → glyph+color cell buffer → ANSI diff → term. Render thread reads via triple-buffered snapshot (copy of visible chunks + actor list, ~200KB); sim never blocks on render. Target: 80×24 minimum, 120×36 recommended, up to 240×70; degrades by render-scale, not sim fidelity.

4.6 Input, loop, and screens #

term normalizes kitty/wezterm/xterm/gnome-terminal + SSH: keys, mouse-drag orbit (optional), resize, focus. ui is a screen stack: Title → Chargen → Play (HUD+log+hint ribbon) → Look/Inventory/Contracts/Map/Chapel → Death/Epitaph/Replay. Full keyboard play mandatory; every mouse action has a key twin. Keymap in one TOML file, remappable in-game.

Main loop pseudo-shape: poll input → map to intents → tick accumulator (10Hz) → snapshot → render → log flush → autosave every 600 ticks. Panic handler writes crash-epitaph.md (seed, tick, state hash, last 50 log lines) — a crash must still tell a story.

4.7 Saves, lineage, replays #

• Save: bincode+zstd snapshot + seed + input log tail; versioned (save_version: u32, migrations in hexwork-save, old saves load or explain why not).
• Lineage vault: per-lineage JSON: mapped regions, recipes, translations, ghosts, auctioned gear. Never stores live run state (permadeath survives rm of the save, not of the vault — document this).
• .hexdemo: seed + input-tick log + content pack hash; replay verifies hash then steps sim headless; hexwork --replay file.hexdemo --export-ansi dumps a shareable ANSI cast. Death replays auto-record rule-chain subtitles from the cause-link recorder.

4.8 Testing strategy (NetHack-descendant needs Net principal: trust no interaction) #

• Rule-chain tests: every §3.3 system has a test that asserts the causal story, e.g. oil_under_door_grate_chokes_mimic: pour → ignite → smoke advects through grate → mimic coughs → lootable. 100+ such tests at 1.0; slice ships 20.
• TDTTOE property tests: proptest over material×hazard matrix (acid×{iron grate, iron helm, ...}) asserts consistent outcomes; deducibility lint: every hazard lists its rule refs.
• Determinism tests: fixed seed + scripted inputs → state hash equality across 10k ticks, run in CI on 2 platforms.
• Content tests: schema validation + 2-uses law + cross-ref integrity + epitaph count.
• Soak: headless bot delver (random+greedy policy) runs 50k ticks nightly; asserts tick budget + no panics + SPS instrumentation hooks.
• Accessibility tests: palette contrast ratios computed; screenreader event stream snapshot-tested.

4.9 Build, release, telemetry (opt-in only) #

Single cargo build --release binary; rust-toolchain.toml pins stable; cargo dist for GH releases (linux/mac/win); terminal feature matrix in README. No network calls in-game. Opt-in anonymous stats (SPS survey prompt after death — "was this death worth retelling? [y/n]") stored locally;毫不 exfiltrated.

4.10 The hard rules (PRs get rejected for these) #

1. No gameplay logic outside core + data files. 2. No nondeterminism in core (no Instant, no threads, no HashMap iteration affecting outcomes — use BTreeMap/indexed pools). 3. No render-blocking-sim. 4. No single-use items. 5. No silent rules — every hazard emits a log line with its law the first time it matters ("The smoke is SUCKED through the grate — rooms breathe.").