Class ObserverBuilder
Declares one observer: what region it covers and which archetypes it reaches through.
public sealed class ObserverBuilder
- Inheritance
-
ObserverBuilder
- Inherited Members
Remarks
Every shape ships: World, Sphere and ClientRegion as a profile's one entity observer, Aggregate as the tier beside it (09 § 5). The far tier of Far(double, double) is the Aggregate's, and refused.
An observer reaches an archetype only if that archetype is spatially indexed. Data with no position — a market, a leaderboard, a player's own inventory — is not something an observer can be pointed at; it travels as a source or as owner fields.
Methods
AroundControlled()
Follows whatever entity the session controls, with no request from the application.
public ObserverBuilder AroundControlled()
Returns
- ObserverBuilder
This builder.
At(Vector3D)
Places a sphere at a fixed world position.
public ObserverBuilder At(Vector3D position)
Parameters
positionVector3DThe centre, in world space.
Returns
- ObserverBuilder
This builder.
Remarks
It takes a position rather than a pair of horizontal coordinates on purpose: which two axes are "the ground" is the application's convention, not the engine's, and a two-argument overload silently drops the third for anyone whose world is oriented the other way.
Bands(Action<BandBuilder>)
Declares a Sphere's distance bands (09 § 9): beyond a fraction of the radius, an entity's updates are sent every N ticks.
public ObserverBuilder Bands(Action<BandBuilder> bands)
Parameters
bandsAction<BandBuilder>The bands, innermost first —
b => b.Every(2, beyond: 0.5).Every(4, beyond: 0.75).
Returns
- ObserverBuilder
This builder.
Exceptions
- InvalidOperationException
The observer is not a Sphere, or its bands were already declared.
Bind(EntityId)
Binds a sphere to an entity, so the region follows it.
public ObserverBuilder Bind(EntityId entity)
Parameters
entityEntityIdThe entity to follow.
Returns
- ObserverBuilder
This builder.
Far(double, double)
Adds a far tier: per-cell counts per archetype beyond the near tier, at a bounded rate.
public ObserverBuilder Far(double tileM, double maxHz)
Parameters
tileMdoubleThe aggregation tile's edge, in metres.
maxHzdoubleHow often the far tier may be refreshed, in hertz.
Returns
- ObserverBuilder
This builder.
Fill(int)
The most full enter records this observer's fill may take in one frame, in place of EnterBudgetPerFrame — and so its sessions' owed-enter cap, four of them (SUB-36). The frame's byte allowance, half a frame, paces the fill whatever the count.
public ObserverBuilder Fill(int entersPerFrame)
Parameters
entersPerFrameintThe enters a frame's fill may take.
Returns
- ObserverBuilder
This builder.
Remarks
For a view that holds a world, not a neighbourhood. The engine's budget is the granularity at which a player's view fills smoothly; a World
observer over a planet of 80 000 entities fills at that pace in over a hundred frames — about ten seconds at 10 Hz. Ten times the budget fills it in
about a second, each frame still within half its limit. int.MaxValue lifts the count altogether: the fill is then paced by the frame's bytes
alone — what an operator's spectator wants, and what a population of players does not.
Groups(string)
Holds the keys of an explicit or a shared group set (14 § 4): the ones the session's client asked for and the application allowed, or the server chose — or the set's one key, from the session's first frame. No reach: these keys are not met by geometry.
public ObserverBuilder Groups(string set)
Parameters
setstringThe group set's name.
Returns
- ObserverBuilder
This builder.
Groups(string, double)
Holds the groups of set whose region this observer meets: within reachM of the region's extent — its nearest
point, zero inside it (14 § 3.3, P6). A region set only, on a Sphere.
public ObserverBuilder Groups(string set, double reachM)
Parameters
setstringA group set declared with Groups(string, Action<GroupSetBuilder>).
reachMdoubleThe reach, metres, at least 0: "which sets I belong to", declared apart from what the sphere sees.
Returns
- ObserverBuilder
This builder.
Near(int)
A ClientRegion's near budget (09 § 7): its cells are delivered nearest the region's centroid first while the entities they hold, counted over the
observer's archetypes, stay within budget; the cells beyond are not held — a profile's Aggregate covers them. Cells, never single
entities, are what the budget delivers and takes back, with a deadband: taken back when the count passes 1.1 × budget, more delivered only after it
has stayed under 0.9 × budget for a second.
public ObserverBuilder Near(int budget)
Parameters
budgetintThe entity count the region's delivered cells may hold.
Returns
- ObserverBuilder
This builder.
Remarks
A Sphere's budget is its session's byte budget (SetBudget); Start refuses a near budget on any other shape.
Of<TArchetype>()
Adds an archetype this observer reaches. One observer over several archetypes is what lets the engine walk a cell once for many of them.
public ObserverBuilder Of<TArchetype>() where TArchetype : Archetype<TArchetype>
Returns
- ObserverBuilder
This builder.
Type Parameters
TArchetypeThe archetype.