[Taure]

Closes #573.

handle_cast(reap, ...) accepted only on map_size(Entities) =:= 0, and the snapshot machinery wrote everything a zone held. The two halves never met: the only zone allowed to stop was the one whose snapshot had nothing in it.

Who is asking

The manager's reap is a proposal from an idle stamp that can lag real occupancy, so a populated zone declines it. That refusal is correct and stays. What was missing is a way for the game module to say "this zone is done", which is a different question:

• asobi_zone:park/1, bound as game.zone.park() in the zone VM. A cast, like every game.zone.* call, because it runs inside the zone's own tick.
• zone_park_on_idle = true, which lets the idle reaper take a zone that still holds entities - so zone_idle_timeout means something for a world whose zones contain scenery, instead of being dead for any zone that has ever been visited.

Neither can take a zone out from under players: a zone with subscribers declines a park and logs it (rate-limited), and a script_busy zone still declines an idle reap, so a wave spawner is not reaped mid-countdown.

The restore was only half there

maybe_restore_from_snapshot/1 loaded zone_state, spawner, entity_timers and tick - but not entities. It never had to: the only zone that could stop held none, and the world server's restore_entities/4 covered the world-restart case. With a populated zone now able to stop, the zone that next occupies those coords has to bring them back, or the snapshot is written and never read. The ETS crash backup still wins where it has anything, since it is fresher.

Whatever a zone starts life holding is also indexed into the spatial grid before its first tick. sync_spatial_grid/3 is a diff against the previous tick, so an entity that was there at start and never moves was never added - restored scenery would have been invisible to every game.spatial query for as long as it stayed still. That applied to the existing ETS-recovery path too.

Non-persistent worlds

The zone hands its dumped zone_state to the manager before stopping and the next zone at those coords starts from it - the "somewhere to leave what was true here" that games otherwise build a gen_server + named ETS extension for. Only for non-persistent worlds: a persistent one has the whole zone in its snapshot, and a stashed zone_state would actively suppress the snapshot load, since that path only runs for a blank zone_state.

Sent before the stop, not from terminate/2, so it is ordered ahead of the manager's DOWN for the same zone. Capped at max_active_zones entries, because a 2000x2000 grid has four million coords; past the cap the zone comes back blank and asobi logs parked_zone_state_dropped.

Docs

guides/large-worlds.md had a "Zone state is not snapshotted on the way out / no configuration path reaches it" paragraph that stopped being true when #543 wired persistence through. It is replaced with what actually survives a park, per persistent.

Tests

asobi_zone_park_tests (park accepted where reap is refused, declined with subscribers, park_on_idle for reap / subscribers / busy, snapshot-and-restore of a populated zone, the non-persistent stash, and no stash when persistent), plus manager tests for the parked set seeding / being consumed / respecting its cap, and two asobi_lua_api_tests for the binding.

Checks

fmt --check, xref, dialyzer, elp eqwalize-all (156 errors, one fewer than origin/main's 157), elp lint, ex_doc, and the full eunit suite (2421 tests, 0 failures).

[github-actions]

🟡 Code Coverage — 76.8%

9486 of 12355 lines covered.

---

🟡 ELP Lint — 192 warnings

212 diagnostics found. See job logs for details.

---

✅ ELP eqWAlize

No diagnostics.