feat: zone snapshots, broadcast throttling, persistent worlds (#56)

* feat: zone snapshots, broadcast throttling, persistent worlds

- Zone sends immediate entity snapshot to new subscribers so late-joining
  clients see existing entities
- Broadcast deltas every Nth tick (configurable broadcast_interval,
  default 3) to reduce WebSocket traffic
- Add persistent flag to world config — prevents world from finishing
  when all players leave
- Pass persistent through game_modes world_config
- Convert phase start_condition tuples to maps for JSON safety
- Ignore asobi_message in world_server running state (zone snapshots
  delivered to self in tests)

* fix: suppress dialyzer warning for zone snapshot send

* fix: format asobi_zone

Author: Taure

src/asobi_game_modes.erl

@@ -38,7 +38,8 @@ world_config(Mode) ->
                 grid_size => maps:get(grid_size, ModeConfig, 10),
                 zone_size => maps:get(zone_size, ModeConfig, 200),
                 tick_rate => maps:get(tick_rate, ModeConfig, 50),
-                view_radius => maps:get(view_radius, ModeConfig, 1)
+                view_radius => maps:get(view_radius, ModeConfig, 1),
+                persistent => maps:get(persistent, ModeConfig, false)
             }};
         {error, _} = Err ->
             Err

src/timers/asobi_phase.erl

@@ -191,7 +191,7 @@ info(#{current_started := false} = PS) ->
     #{
         status => waiting,
         phase => maps:get(name, Phase),
-        start_condition => maps:get(start, Phase, prev_ended)
+        start_condition => format_condition(maps:get(start, Phase, prev_ended))
     };
 info(PS) ->
     Phase = current_phase_def(PS),
@@ -203,6 +203,13 @@ info(PS) ->
         timers => timers_info(PS)
     }.
 
+format_condition({Type, Value}) ->
+    #{type => Type, value => Value};
+format_condition(Atom) when is_atom(Atom) ->
+    Atom;
+format_condition(Other) ->
+    Other.
+
 %% -------------------------------------------------------------------
 %% Internal — waiting for phase start condition
 %% -------------------------------------------------------------------

src/world/asobi_world_server.erl

@@ -82,6 +82,7 @@ init(Config) ->
     ViewRadius = maps:get(view_radius, Config, ?DEFAULT_VIEW_RADIUS),
     VetoTokensPerPlayer = maps:get(veto_tokens_per_player, Config, 0),
     FrustrationBonus = maps:get(frustration_bonus, Config, 0.5),
+    Persistent = maps:get(persistent, Config, false),
     InstanceSup = maps:get(instance_sup, Config, undefined),
     PhaseState =
         case erlang:function_exported(GameMod, phases, 1) of
@@ -117,6 +118,7 @@ init(Config) ->
         veto_tokens_per_player => VetoTokensPerPlayer,
         frustration_bonus => FrustrationBonus,
         active_votes => #{},
+        persistent => Persistent,
         chat_state => ChatState,
         phase_state => PhaseState
     },
@@ -210,7 +212,10 @@ running(info, {vote_resolved, VoteId, Template, Result}, State) ->
     handle_vote_resolved(VoteId, Template, Result, State);
 running(info, {vote_vetoed, VoteId, _Template}, State) ->
     Active = maps:remove(VoteId, maps:get(active_votes, State, #{})),
-    {keep_state, State#{active_votes => Active}}.
+    {keep_state, State#{active_votes => Active}};
+running(info, {asobi_message, _}, _State) ->
+    %% Zone snapshots/deltas forwarded here in tests — ignore
+    keep_state_and_data.
 
 %% --- finished state ---
 
@@ -343,8 +348,8 @@ handle_leave(
             leave_chat(PlayerId, State),
             State1 = remove_player_from_zones(PlayerId, State),
             Players1 = maps:remove(PlayerId, Players),
-            case map_size(Players1) of
-                0 ->
+            case {map_size(Players1), maps:get(persistent, State, false)} of
+                {0, false} ->
                     {next_state, finished, State1#{
                         players => Players1, game_state => GS1, result => #{status => ~"empty"}
                     }};

src/world/asobi_zone.erl

@@ -73,6 +73,8 @@ init(Config) ->
         game_module => GameModule,
         entities => #{},
         prev_entities => #{},
+        broadcast_entities => #{},
+        broadcast_interval => maps:get(broadcast_interval, Config, 3),
         subscribers => #{},
         zone_state => ZoneState,
         input_queue => [],
@@ -98,8 +100,17 @@ handle_cast({add_entity, EntityId, EntityState}, #{entities := Entities} = State
     {noreply, State#{entities => Entities#{EntityId => EntityState}}};
 handle_cast({remove_entity, EntityId}, #{entities := Entities} = State) ->
     {noreply, State#{entities => maps:remove(EntityId, Entities)}};
-handle_cast({subscribe, PlayerId, PlayerPid}, #{subscribers := Subs} = State) ->
+handle_cast({subscribe, PlayerId, PlayerPid}, #{subscribers := Subs, entities := Entities} = State) ->
     MonRef = monitor(process, PlayerPid),
+    %% Send immediate snapshot so new subscribers see all current entities
+    _ =
+        case map_size(Entities) of
+            0 ->
+                ok;
+            _ ->
+                Snapshot = [E#{~"op" => ~"a", ~"id" => Id} || {Id, E} <- maps:to_list(Entities)],
+                PlayerPid ! {asobi_message, {zone_delta, 0, Snapshot}}
+        end,
     {noreply, State#{subscribers => Subs#{PlayerId => {PlayerPid, MonRef}}}};
 handle_cast({unsubscribe, PlayerId}, #{subscribers := Subs} = State) ->
     case maps:get(PlayerId, Subs, undefined) of
@@ -138,7 +149,9 @@ do_tick(
     #{
         game_module := GameMod,
         entities := Entities,
-        prev_entities := PrevEntities,
+        prev_entities := _PrevEntities,
+        broadcast_entities := BroadcastEntities,
+        broadcast_interval := BroadcastInterval,
         zone_state := ZoneState,
         input_queue := Queue,
         subscribers := Subs,
@@ -151,10 +164,18 @@ do_tick(
     Now = erlang:system_time(millisecond),
     {TimerEvents, ET1} = asobi_entity_timer:tick(Now, ET),
     Entities3 = apply_timer_events(TimerEvents, Entities2),
-    Deltas = compute_deltas(PrevEntities, Entities3),
-    broadcast_deltas(TickN, Deltas, Subs),
+    %% Only broadcast every Nth tick to reduce network traffic
+    State1 =
+        case TickN rem BroadcastInterval of
+            0 ->
+                Deltas = compute_deltas(BroadcastEntities, Entities3),
+                broadcast_deltas(TickN, Deltas, Subs),
+                State#{broadcast_entities => Entities3};
+            _ ->
+                State
+        end,
     asobi_world_ticker:tick_done(TickerPid, self(), TickN),
-    State#{
+    State1#{
         entities => Entities3,
         prev_entities => Entities3,
         zone_state => ZoneState1,

test/asobi_zone_tests.erl

@@ -69,24 +69,33 @@ subscribe_unsubscribe() ->
 
 tick_broadcasts() ->
     Pid = start_zone(),
-    asobi_zone:subscribe(Pid, {<<"p1">>, self()}),
     asobi_zone:add_entity(Pid, <<"e1">>, #{x => 0, y => 0, type => ~"player"}),
     timer:sleep(10),
-    %% First tick — entity appears as added
-    asobi_zone:tick(Pid, 1),
+    asobi_zone:subscribe(Pid, {<<"p1">>, self()}),
+    timer:sleep(10),
+    %% Subscribe sends immediate snapshot
     receive
-        {asobi_message, {zone_delta, 1, Deltas}} ->
-            ?assertEqual(1, length(Deltas)),
-            [Delta] = Deltas,
-            ?assertEqual(~"a", maps:get(~"op", Delta)),
-            ?assertEqual(<<"e1">>, maps:get(~"id", Delta))
+        {asobi_message, {zone_delta, 0, Snapshot}} ->
+            ?assertEqual(1, length(Snapshot)),
+            [S] = Snapshot,
+            ?assertEqual(~"a", maps:get(~"op", S)),
+            ?assertEqual(<<"e1">>, maps:get(~"id", S))
     after 1000 ->
         ?assert(false)
     end,
-    %% Second tick — no changes, no delta message
+    %% Broadcast interval is 3, so tick 3 broadcasts
+    asobi_zone:tick(Pid, 1),
     asobi_zone:tick(Pid, 2),
+    asobi_zone:tick(Pid, 3),
+    receive
+        {asobi_message, {zone_delta, 3, _Deltas}} -> ok
+    after 1000 ->
+        ?assert(false)
+    end,
+    %% Tick 4 does not broadcast (4 rem 3 = 1)
+    asobi_zone:tick(Pid, 4),
     receive
-        {asobi_message, {zone_delta, 2, _}} ->
+        {asobi_message, {zone_delta, 4, _}} ->
             ?assert(false)
     after 100 ->
         ok