Class ProfileBuilder
Declares a named set of observers — "player", "god", "spectator" — that a session is bound to as a whole.
public sealed class ProfileBuilder
- Inheritance
-
ProfileBuilder
- Inherited Members
Remarks
A profile exists so interest is a policy an application states once rather than a sequence of requests every connection has to get right. Switching a session's profile replaces its whole interest atomically and resets its view, which is the only honest way to do it: a half-switched session would be told about entities under one rule and forgotten about them under another.
Methods
Aggregate(double, double, double)
Per-cell counts per archetype, for a view too wide to send entities for: a strategic map, a far tier, a heat map.
public ObserverBuilder Aggregate(double tileM, double rateHz, double radiusM = 0)
Parameters
tileMdoubleThe tile's edge, in metres: a whole number of replication cells.
rateHzdoubleHow often the counts are refreshed, in hertz.
radiusMdoubleThe tiles a session is sent: those within this distance of its sphere's anchor; 0 for every tile. A
Worldprofile's aggregate covers every tile.
Returns
- ObserverBuilder
The observer's builder.
Remarks
A tier (09 § 5, § 8): declared beside the profile's one entity observer (World or Sphere), it sends the tiles' counts in AGG
blocks — never entity records — refreshed at most rateHz times a second, each time the tiles that changed. Every archetype it
counts must be one some profile replicates.
ClientRegion(double)
A convex ground footprint the client sends through the built-in ClientRegion command — a camera's view, clipped at the horizon.
public ObserverBuilder ClientRegion(double maxEdgeM)
Parameters
maxEdgeMdoubleThe widest the region's bounding box may be on any axis, in metres. A client asking for more is clamped about its centroid, not refused. It sizes every session's window,
⌈maxEdgeM / c⌉ + 5cells per axis, which counts against the window bound atStart(09 § 7).
Returns
- ObserverBuilder
The observer's builder.
Remarks
A session holds the entities whose visibility position lies in the region it last sent and whose cell it has been delivered; until it sends one it holds nothing. Near(int) caps what it holds, by whole cells nearest the region's centroid.
Detection(PushDetection)
Who says this profile's entities changed (ADR-067). Default Explicit: the application, by calling Replicate<TArchetype>(in ClusterRef<TArchetype>, int) after each replicated write.
public ProfileBuilder Detection(PushDetection detection)
Parameters
detectionPushDetectionThe mode. Automatic is refused unless AllowAutomaticPushDetection is set.
Returns
- ProfileBuilder
This builder.
Remarks
An entity is projected only when it is pushed — by the application, or by the engine for a spawn, a destroy, a WriteSpatial, a migration or a
client still extrapolating it — and a session learns about it from its own geometry rather than from a per-session known-set.
Every(int)
Serves this profile's sessions one tick in ticks, staggered by session; each frame carries everything since the session's last
one, replayed from the push log.
public ProfileBuilder Every(int ticks)
Parameters
ticksint1, 2 or 4.
Returns
- ProfileBuilder
This builder.
In(string, Action<ProfileBuilder>)
The profile's variant for realms of kind (12-realms § 1.4): in such a realm its sessions are served by the observers declared
here instead of the profile's own — one profile name for every scale, and a realm switch that changes the variant is still one reset.
public ProfileBuilder In(string kind, Action<ProfileBuilder> variant)
Parameters
kindstringA kind declared with
SubscriptionsRegistry.RealmKinds.variantAction<ProfileBuilder>Declares the variant's observers, as a profile's.
Returns
- ProfileBuilder
This builder.
MaxObservers(int)
Raises how many observers this profile may declare, for an application that admits sessions with a matching MaxObservers.
public ProfileBuilder MaxObservers(int count)
Parameters
countintThe profile's own ceiling, at least 1. Defaults to DefaultMaxObservers.
Returns
- ProfileBuilder
This builder.
Remarks
This ceiling is the declaration's, never a session's. A profile is declared once, at Start, and bound by whichever sessions ask for it;
the admission hook is what decides whether a given session may hold that many observers, and its number is the one that binds at run time. Capping the
declaration at the default limit instead — which is what this replaced — made a session admitted with a higher limit unable to ever bind a
profile that used it, because the profile could not be written in the first place.
NotIn(params string[])
Realms of these kinds serve this profile's sessions nothing (12-realms § 1.4): a session in one holds nothing positioned there — counted, never refused.
public ProfileBuilder NotIn(params string[] kinds)
Parameters
kindsstring[]Kinds declared with
SubscriptionsRegistry.RealmKinds.
Returns
- ProfileBuilder
This builder.
Sphere(double, double, double)
A radius around a point, an entity, or the session's controlled entity.
public ObserverBuilder Sphere(double radius, double leave = 0, double max = 0)
Parameters
radiusdoubleThe enter radius, in metres.
leavedoubleThe leave radius, in metres — larger than
radius. Zero: no band.maxdoubleThe largest radius a session of this profile can be given at run time through SetRadius(SessionId, double) — a player boarding an aircraft. Zero: the session's radius is fixed. The window is sized for it at
Start, so it counts against the window bound.
Returns
- ObserverBuilder
The observer's builder.
Remarks
The two radii are not a refinement: an entity hovering on one boundary would enter and leave every tick, and every re-entry costs a full enter record. Hysteresis is what makes the cost of jitter zero instead of unbounded.
The band is a bound, not per-entity memory (09 § 3): an entity whose true position is within radius is held, one past
leave is not, and between them it may be either. The profile's sessions test the midpoint R′ = (R + L) / 2 against a
position that moves only past half the band, so an entity oscillating by less than that never flaps.
World()
Everything, of the archetypes named with Of<TArchetype>(). For a tool, a viewer bot, or a world small enough that the whole of it is the interesting part. Cells are delivered in grid order behind one cursor, then every event of the tick.
public ObserverBuilder World()
Returns
- ObserverBuilder
The observer's builder.