Skip to content
Softfire

The Signal — World State Distribution

The Signal is the delivery layer that pushes Living World state from Strand nodes to connected game clients. It handles the full snapshot on session join, delta frames every tick thereafter, and reconnect recovery. The Signal is an infrastructure detail — your game code interacts with its outputs via IWorldStateQuery and WorldStateCache, not with The Signal directly.

Full snapshot on session join

When a client authenticates and is assigned to a Strand, the Strand immediately sends a full world-state snapshot for all zones the client is subscribed to. The snapshot includes:

  • Current population levels for all species in each zone
  • Current resource node levels
  • Current weather state and climate values
  • Current zone control (faction) data
  • Current world time

This snapshot is large compared to delta frames, but it is sent only once per session. After the snapshot is applied to the local WorldStateCache, the client transitions to receiving delta frames.

Delta frames

Each Pulse tick produces a delta frame: only the values that changed since the previous tick are included. A typical delta frame for a quiet zone might contain:

  • One or two population adjustments
  • Three or four resource level changes
  • A weather value update

Frames are compressed and signed. The Strand delivers frames to all subscribed clients over a persistent WebSocket connection. Frame delivery is ordered and acknowledged — a dropped frame triggers a range re-request, not a full re-snapshot.

Zone subscription

Clients subscribe to a subset of zones, not the entire world. The WorldStateSubscriptionService manages which zones a client receives state for:

var subscription = Services.Get<WorldStateSubscriptionService>();


// Subscribe to a zone when the player enters it
subscription.Subscribe(zoneId);


// Unsubscribe when the player leaves
subscription.Unsubscribe(zoneId);


// Check current subscriptions
IReadOnlySet<ZoneId> active = subscription.ActiveSubscriptions;

The engine automatically manages subscriptions when you use the built-in zone-transition system. You only need to manage subscriptions manually if you are building a custom zone system.

Zones outside the active subscription set do not send delta frames to the client. Subscribing to a new zone triggers a per-zone snapshot for that zone only — not a full world re-snapshot.

IWorldStateQuery

IWorldStateQuery is the synchronous read interface over the local WorldStateCache. All query methods return cached values — they do not make network calls. The cache is updated by The Signal in the background.

var worldState = Services.Get<IWorldStateQuery>();


// Population
PopulationSnapshot wolves = worldState.GetPopulation(zoneId, "wolf");


// Resource level
ResourceLevelSnapshot iron = worldState.GetResourceLevel(zoneId, "iron_ore");


// Weather
WeatherSnapshot weather = worldState.GetWeather(zoneId);


// Faction control
ZoneControlSnapshot control = worldState.GetZoneControl(zoneId);


// Diplomatic stance
DiplomaticStance stance = worldState.GetFactionStance("faction_a", "faction_b");


// Current world time
WorldTime time = worldState.GetCurrentTime(zoneId);

All queries are O(1) — they are dictionary lookups into the in-memory cache. There is no async overhead at the read site.

Subscribing to changes

React to state changes by subscribing to WorldStateCache.Changed:

var cache = Services.Get<WorldStateCache>();


cache.Changed += (sender, change) =>
{
    switch (change)
    {
        case PopulationChangedEvent pop:
            HandlePopulationChange(pop);
            break;


        case WeatherChangedEvent wx:
            HandleWeatherChange(wx);
            break;


        case ResourceLevelChangedEvent res:
            HandleResourceChange(res);
            break;


        case ZoneControlChangedEvent ctrl:
            HandleZoneControlChange(ctrl);
            break;
    }
};

The Changed event fires on the main game thread, synchronised with the Update loop. You do not need to dispatch to the main thread from a handler — it is already there.

Reconnect behaviour

If a client disconnects (network loss, suspend/resume, Strand failover) and then reconnects:

  1. The client presents its last known tick number to the Strand
  2. If the Strand has retained frames since that tick, it sends only the missing delta frames
  3. If the Strand no longer has the old frames (gap too large, Strand restarted), it sends a fresh per-zone snapshot

The maximum delta replay window is 5 minutes of real time. Gaps longer than this result in a fresh snapshot. From the game’s perspective, the cache is simply updated — there is no visible state discontinuity.

Performance characteristics

The Signal is designed to be invisible at the game code level:

  • Bandwidth — delta frames for a typical active zone average 1–4 KB per tick. A player subscribed to 3 zones at full tick rate receives approximately 10–40 KB/min from The Signal.
  • CPU — the Strand-side serialiser and the client-side deserialiser run on background threads. The main game thread is only touched when the Changed event fires.
  • Latency — delta frames are delivered within 100–300ms of the Pulse tick completing, depending on Strand region and network conditions. Living World state is not real-time — it is near-real-time. Do not use it for frame-accurate gameplay decisions.