asobi_zone_manager (asobi v0.35.4)

View Source

Lazy zone lifecycle manager for the world server.

Replaces the static zone_pids map with on-demand zone creation and idle reaping. For large worlds (2000x2000 grids), spawning all zones at startup is untenable — this module creates zones on first access and reaps them after an idle timeout.

Hot-path lookups go through ETS directly, bypassing the gen_server.

Summary

Functions

ensure_zone(Ref, Coords)

Return existing zone or start a new one. ETS fast path first.

get_active_zones/1

Return all active zone pids. For the ticker.

get_zone(Ref, Coords)

Non-creating lookup. ETS only.

handle_call/3
handle_cast/2
handle_info/2
init(Opts)
pre_warm(Ref)

Spawn all zones in grid. Backward compat for small grids.

register_zone(Ref, Coords, ZonePid)

Register an externally-spawned zone with the manager.

release_zone(Ref, Coords)

Hint that zone can be unloaded.

set_initial_zone_states(Ref, ZoneStates)

Provide per-coord initial zone_state. Used to thread per-zone state from GameMod:generate_world/2 (e.g. lua_state for the asobi_lua_world bridge, or station/planet seeds for sc_game) through to each zone's init. Without this, zones would all start with empty zone_state and any callback that needs per-zone setup would silently no-op.

set_zone_config(Ref, Config)

Update the base zone config used when spawning new zones.

start_link(Opts)

Start the zone manager.

terminate/2
touch_zone(Ref, Coords)

Reset idle timer for a zone. Fire-and-forget.

zone_terminated(Ref, Coords, ZonePid)

Called by zone on terminate. Cleans up ETS entry.

Functions

ensure_zone(Ref, Coords)

-spec ensure_zone(pid() | atom(), {integer(), integer()}) -> {ok, pid()} | {error, term()}.

Return existing zone or start a new one. ETS fast path first.

get_active_zones/1

-spec get_active_zones(pid() | atom()) -> [pid()].

Return all active zone pids. For the ticker.

get_zone(Ref, Coords)

-spec get_zone(pid() | atom(), {integer(), integer()}) -> {ok, pid()} | not_loaded.

Non-creating lookup. ETS only.

handle_call/3

-spec handle_call(term(), gen_server:from(), map()) -> {reply, term(), map()}.

handle_cast/2

-spec handle_cast(term(), map()) -> {noreply, map()}.

handle_info/2

-spec handle_info(term(), map()) -> {noreply, map()}.

init(Opts)

-spec init(map()) -> {ok, map()}.

pre_warm(Ref)

-spec pre_warm(pid() | atom()) -> ok.

Spawn all zones in grid. Backward compat for small grids.

register_zone(Ref, Coords, ZonePid)

-spec register_zone(pid() | atom(), {integer(), integer()}, pid()) -> ok.

Register an externally-spawned zone with the manager.

release_zone(Ref, Coords)

-spec release_zone(pid() | atom(), {integer(), integer()}) -> ok.

Hint that zone can be unloaded.

set_initial_zone_states(Ref, ZoneStates)

-spec set_initial_zone_states(pid() | atom(), map()) -> ok.

Provide per-coord initial zone_state. Used to thread per-zone state from GameMod:generate_world/2 (e.g. lua_state for the asobi_lua_world bridge, or station/planet seeds for sc_game) through to each zone's init. Without this, zones would all start with empty zone_state and any callback that needs per-zone setup would silently no-op.

set_zone_config(Ref, Config)

-spec set_zone_config(pid() | atom(), map()) -> ok.

Update the base zone config used when spawning new zones.

start_link(Opts)

-spec start_link(map()) -> gen_server:start_ret().

Start the zone manager.

terminate/2

-spec terminate(term(), map()) -> ok.

touch_zone(Ref, Coords)

-spec touch_zone(pid() | atom(), {integer(), integer()}) -> ok.

Reset idle timer for a zone. Fire-and-forget.

zone_terminated(Ref, Coords, ZonePid)

-spec zone_terminated(pid() | atom(), {integer(), integer()}, pid()) -> ok.

Called by zone on terminate. Cleans up ETS entry.