RegionPublisher

The worker's side of interest management: which gateways hear about each region, and the grouping that lets one serialization serve all of them.

Class in namespace Nebula · Packages/com.1by3.nebula/Runtime/Interest/RegionPublisher.cs

public sealed class RegionPublisher

The worker's side of interest management: which gateways hear about each region, and the grouping that lets one serialization serve all of them.

Every region carries a subscriber mask, one bit per gateway link. Once a tick the publisher groups the regions that share a mask, so a batch is written once and sent to each gateway in the mask: with G gateways the work is O(entities + batches × subscribers) instead of O(entities × gateways). Nothing here remembers what a gateway already knows — a worker's memory must not grow with the number of gateways — so the only per-gateway state is the region set itself.

Fields

MaxGateways

public const int MaxGateways = 64;

Bits in a mask. A mesh with more gateway links than this falls back to per-region sends for the rest.

Properties

LinkedMask

public ulong LinkedMask { get; }

Bit per gateway link currently registered.

SubscribedRegions

public int SubscribedRegions { get; }

Regions at least one gateway subscribes.

Groups

public IReadOnlyList<Group> Groups { get; }

Groups produced by the last BuildGroups<T>.

FilteredEntities

public long FilteredEntities { get; }

Entities in subscribed regions in the last rebuild: what is actually sent.

TotalEntities

public long TotalEntities { get; }

Entities the worker holds in regions at all: what would be sent without interest management.

Methods

Bit

public static ulong Bit(int gatewayBit);

AddGateway

public void AddGateway(int gatewayBit, RegionSubscriptionReceiver receiver);

RemoveGateway

public void RemoveGateway(int gatewayBit);

Drop a gateway link: its bit leaves every region it held.

ApplyChanges

public void ApplyChanges(int gatewayBit, RegionSubscriptionReceiver receiver);

Fold a committed subscription change into the region masks. Call it from the receiver's change callback: the journal it exposes is exactly the work to do, so the cost follows the change and not the size of the set.

public void Subscribe(int gatewayBit, ulong region);

Unsubscribe

public void Unsubscribe(int gatewayBit, ulong region);

MaskOf

public ulong MaskOf(ulong region);

Which gateways want a region (0 = nobody, so nothing in it is sent anywhere).

SpawnBits

public ulong SpawnBits(ulong from, ulong to);

An entity moved from region from to to: these gateways have not heard of it and need a spawn.

ForgetBits

public ulong ForgetBits(ulong from, ulong to);

The counterpart: these gateways subscribed the old region only, and are told to forget it.

WideMask

public ulong WideMask(in InterestGrid grid, double x, double y, double z, double radius);
public ulong WideMask(in InterestGrid grid, ulong instanceId, double x, double y, double z, double radius);

Which gateways a wide entity (one whose own radius exceeds a region scan) reaches: the ones with a focus region within its radius. Matched at the evaluation rate, not per tick.

WideMaskSalted

public ulong WideMaskSalted(in InterestGrid grid, ulong salt, double x, double y, double z, double radius);

WideMask for an entity whose region space is given by its salt (RegionKeys.SaltOf): a scope, or a physics frame with regions of its own inside one. Only foci of the same space come out near it.

ExplicitMask

public ulong ExplicitMask(ulong netId);

Which gateways explicitly subscribed an entity by id (a policy extra, or one they own).

BuildGroups

public void BuildGroups<T>(InterestIndex<T> index);

Group this tick's subscribed regions by mask. Allocation free after the first few ticks: the region lists are pooled and reused. Iterate Groups, write one batch per group, and send it to every gateway in Group.Mask.