# Stacksmith — technical architecture

## Prototype

The workbook is a dependency-free static site. `engine.js` contains pure falling-block, weighted-bag, and sent-block rules shared by browser play and Node tests. `app.js` owns rendering, enemy curse timing, input, persistence, and workbook interactions.

## Production direction

Use Godot 4 for production while preserving deterministic, data-driven rules outside scene code.

- **Simulation:** fixed-step 12 × 22 board state, active piece, queue, unlocked hold state, bag weights, enemy health, curse schedule, sent-block income, survival bonus, rewards, and seeded random state.
- **Presentation:** board renderer, animation, particles, audio, UI, tutorial, accessibility, and camera.
- **Content:** validated shape cells, cursecaster patterns, curse effects, upgrade families, reward pools, relic effects, routes, and localization keys.
- **Networking:** authoritative match host or server; clients submit timestamped input and receive reconciled simulation snapshots.
- **Persistence:** profile unlocks, settings, run seed/state, input maps, and replay summaries.
- **Telemetry:** opt-in aggregate events for selections, top-outs, run endings, and readability gates. Never capture raw keyboard input or chat.

## Determinism contract

- The seed, content version, ordered inputs, and fixed timestep reproduce a fight.
- Random draws and enemy curse selections use named, serializable random streams.
- Presentation timing never changes simulation order.
- Content migrations preserve old replay interpretation or explicitly invalidate it.

## Network proofs

1. Two clients reproduce 10,000 seeded pieces and curse selections exactly.
2. A reconnect restores board, queue, bag, unlocked augments, enemy health, money, curse clock, active curse counters, and ownership.
3. Simulated 120 ms latency does not double-place or lose a hard-drop input.
4. Match results validate from the replay log without trusting either client's rendered state.
5. Spectators receive sufficient state without joining the simulation authority path.

## Test layers

- Unit tests for rotations, collision, line clearing, weights, sent-block damage, rewards, and curse-state transitions.
- Seeded replay tests for full fights and reward transitions.
- Integration tests for input buffering, pause, relay ownership, top-out, win, loss, and reconnect.
- Browser/device smoke tests for layout, focus, remapping, reduced motion, and color-safe readability.
- Human tests for bag comprehension, curse readability, stack planning, communication, and replay desire.