Table of Contents

Class ProfileBuilder

Namespace
Typhon.Engine
Assembly
Typhon.Engine.dll

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

tileM double

The tile's edge, in metres: a whole number of replication cells.

rateHz double

How often the counts are refreshed, in hertz.

radiusM double

The tiles a session is sent: those within this distance of its sphere's anchor; 0 for every tile. A World profile'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

maxEdgeM double

The 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⌉ + 5 cells per axis, which counts against the window bound at Start (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

detection PushDetection

The 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

ticks int

1, 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

kind string

A kind declared with SubscriptionsRegistry.RealmKinds.

variant Action<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

count int

The 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

kinds string[]

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

radius double

The enter radius, in metres.

leave double

The leave radius, in metres — larger than radius. Zero: no band.

max double

The 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.