Save & Exit brings you back to the same dungeon (§8)

[0xward]

Closes the last known bug in GAME-DESIGN.md — §8 flips from [CHANGE] to [TODAY].

No smart contract, ABI, or contract address is touched.

The bug

Save & Exit on floor 3 → Continue → ensureFloor(3) found an empty cache and built a new floor. Different layout, monsters back on their feet, looted containers refilled, smashed props whole.

getSaveSnapshot() persisted 14 fields but never G.floors, and dungeon.js generated from bare Math.random() with no seed — so the same floor could not be reproduced at all.

At risk: XP, ordinary items (→ NullState Point via burn), and Glitch Shards, which are also sold at $1 per 5.
Never at risk: the weekly Paper and Golden Key — guarded both by the saved run caps and by the server's 1-per-wallet-per-week records.

The fix, in two halves

Either half alone fixes nothing.

1. The layout is a pure function of a seed. One runSeed chosen at newGame() and saved with the run; a floor's seed is hash(runSeed, cycle, act, abyss, depth). Same seed, same floor — the map costs zero bytes to persist.

2. What the player did to it is a delta. Which enemies died, which props broke, which containers were opened and what is still inside them, which rooms are lit, and where they stood. Indices into the generated arrays — sound only because of (1).

Measured: 2.6 KB for a whole five-floor bunker with every prop smashed and every container opened. Firestore's limit is 1 MB.

Why Math.random is swapped rather than threaded

Randomness for one floor is spread across four files — dungeon.js lays out rooms, game.js picks archetypes and elites, props.js places and rolls decor, entities.js jitters each enemy. The engine is plain <script> tags with no module system (rule 1 in §10), so there is no shared rng to import and threading one would mean touching every constructor. Generation is synchronous and finishes inside one call, so the global is swapped for exactly that window and a finally restores it.

Two guards, both of which earned their place

A snapshot does not always keep describing the run it was taken from. The shell rewrites campaignActIndex/depth on it when a bunker is cleared (so ENTER points at the next bunker) and again when a raid finishes. Replaying those floors into the new bunker would start it with the monsters already dead and the containers already emptied. The save now records a floorsKey — cycle, act, abyss, raid — and the delta is dropped unless it still matches.

Regeneration can legitimately differ. A Premium Sector cache appears only while that act's blueprint is owned, and ownership lives outside this save. Each floor stores the array lengths its indices came from; a mismatch drops the delta rather than killing the wrong monsters.

A pre-existing bug this surfaced

The snapshot written when a raid finishes was cached during the raid, so it still said raid: true. enterSavedSession() restores RAID_MODE from that flag — so the next Continue resumed as a raid, and clearing that bunker took the raid branch again, fired nullstate-raid-cleared, and advanced nothing.

The campaign silently stopped progressing after any raid. Fixed in the same place the campaign path already fixed up its own snapshot, for the same reason.

Dead code

Scanned all 14 engine files against each other and against the app for functions defined but never referenced. Exactly one: _wtShade(). Removed.

Verification

npm run test:seeded — 15 assertions, fails on the old engine (5 fail with seeding disabled):

Check
run seed survives the save	✓
the floor regenerates IDENTICALLY	✓
a fresh run gets a different floor	✓
3 dead enemies stay dead · 3 smashed props stay smashed	✓
the opened container stays open, holding exactly the loot left in it	✓
a distant lit room stays lit	✓
the player resumes where they stood	✓
a delta that no longer fits is dropped, not misapplied	✓
the NEXT bunker does not inherit the last one's floors, and gets its own seed	✓
a fully-cleared bunker stays small enough to save (2.6 KB)	✓

Full suite: test:seeded 15/15 · test:raid 17/17 · test:contracts 13/13 · test:floors all passed · test:inventory 7/7 · test:traversable 0 failures in 100 floors · tsc --noEmit clean · lint 34 errors (unchanged baseline) · audit · check:copy · check:market · check:cssvars · check:attribution all pass · build succeeds.

Docs: GAME-DESIGN.md §8 rewritten as shipped, build-order item 8 struck through, and game-mechanics.md's "Known limitation" note replaced with what now actually happens.

---

Generated by Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nullstate	Ready	Preview	Jul 31, 2026 6:03am