Struct SessionRequest
Steers one session from inside a system: its profile, its observers, what it controls, its budget, and whether it stays.
public readonly ref struct SessionRequest
- Inherited Members
Remarks
These are requests, not writes. Systems run in parallel over their own entities, and several of them may decide something about the same session in the same tick. Each call appends a record to the calling worker's own segment — no lock, no shared cursor, no false sharing — and the engine applies every segment single-threaded at the start of the session pass. Last writer wins per field, in a fixed order (worker index, then record order), so the result is deterministic rather than whichever thread happened to be quicker.
A ref struct on purpose. It borrows the worker's segment for the duration of one statement; it cannot be stored on a field, captured or passed to another thread, which is the compiler enforcing the per-worker discipline instead of documentation asking for it.
What applies. Profile(string), Control(EntityId), Follow(EntityId), SetBudget(int), SetSources(string, params long[]) and Kick(ushort, string) take effect. Observe(ObserverDeclaration, int) and Unobserve(int) throw here, at the call site, naming the phase that builds them — the shape is complete now so that an application written against it never has to be revisited when the verb it wanted starts working.
A refusal is thrown where the caller is, not a tick later. Recording an unsupported verb and refusing it when the session pass runs puts the exception on the engine's own stack, with nothing left naming the system that asked for it — and the system's own tick has already finished, so a debugger stopped on the throw cannot show what led to it. Kick(ushort, string) has always validated its close code at the call site for the same reason.
Properties
Session
The session these requests are about.
public SessionId Session { get; }
Property Value
Methods
Control(EntityId)
Binds the session to an entity it controls: owner fields and the SELF block follow that entity, and a profile's bound sphere follows it too.
public SessionRequest Control(EntityId entity)
Parameters
Returns
- SessionRequest
This request, so several may be chained.
Follow(EntityId)
Points the session's viewpoint — its centre and its realm — at an entity it does not control.
public SessionRequest Follow(EntityId entity)
Parameters
Returns
- SessionRequest
This request, so several may be chained.
Remarks
Following is not controlling, and that is the whole point of the verb (12-realms § 2.2 Q5). Control(EntityId) makes the session that
entity's: it receives the entity's SELF block and its owner fields, which are its private data. Follow(EntityId) gives the session the
entity's position and realm and nothing else — what a spectator, a GM camera or a replay viewer needs, and what an application that reached for
Control(EntityId) instead has been quietly sending to whoever was watching.
It overrides the profile's own anchor rather than requiring one: a profile declared AroundControlled() or Bind(e) follows this
entity while it is set, and a profile with no anchor at all gains one. On a World or ClientRegion observer, whose geometry is not a
point, it supplies the realm alone (12-realms § 1.5) — which is how a god camera keeps its own hull and still goes through the door behind the player
it is watching.
A followed entity that goes away behaves as a bound one does (09 § 6): the session keeps the last position and realm it was read at and the engine counts a lost follow, until the application follows something else or places the session itself. Where its subject went is the application's business, not something the engine should guess.
Kick(ushort, string)
Ends the session.
public SessionRequest Kick(ushort code, string reason = null)
Parameters
codeushortThe close code, in the application range
4100-4999.reasonstringWhy, at most KickReasonMaxBytes bytes once encoded; longer reasons are truncated on the wire.
Returns
- SessionRequest
This request, so several may be chained.
Exceptions
- ArgumentOutOfRangeException
codeis outside4100-4999. Every lower code already means something specific to every client — 1002 framing, 1013 overload, 4003 admission — so borrowing one makes an application's decision read as an engine fault and changes whether SDKs reconnect.
Observe(ObserverDeclaration, int)
Puts an observer in one of the session's observer slots, replacing whatever was there.
public SessionRequest Observe(ObserverDeclaration observer, int slot)
Parameters
observerObserverDeclarationThe region of interest.
slotintWhich of the session's observer slots it occupies.
Returns
- SessionRequest
This request, so several may be chained.
Remarks
The shape is final; the verb arrives in Phase 2, with the observer shapes that need it.
Exceptions
- NotSupportedException
Always, until Phase 2 builds per-session observers.
Profile(string)
Binds the session to a declared interest profile.
public SessionRequest Profile(string name)
Parameters
namestringThe profile's name, as
subs.Profile(name, ...)declared it.
Returns
- SessionRequest
This request, so several may be chained.
SetBudget(int)
Sets the session's outbound byte budget.
public SessionRequest SetBudget(int bytesPerSecond)
Parameters
bytesPerSecondintThe budget. Zero removes it; the frame ceiling and the enter budget still apply.
Returns
- SessionRequest
This request, so several may be chained.
Remarks
A Sphere session over its budget is degraded by LOD level (09 § 10): every distance band's period doubles per level, a profile with no band gets one
beyond half its radius, and the enter budget halves. Records are deferred and never dropped, so a small number slows a view down rather than
corrupting it. The level rises after a second over the budget and falls after three under 70 % of it. A World or ClientRegion session has no LOD
level, so the budget does not act on it: a ClientRegion's is its profile's near budget (Near, 09 § 7), counted in entities.
SetSources(string, params long[])
Replaces the keys the server chooses for the session in an explicit group set (14 § 4, P14): diffed against what it chose before, idempotent, applied at the next session pass. The keys the session's client asked for itself are untouched; a key either chose is held, filled and completed.
public SessionRequest SetSources(string set, params long[] keys)
Parameters
setstringAn explicit group set's name, as
subs.Groups(name, g => g.Explicit(...))declared it.keyslong[]The full list; empty gives back every key the server chose. Never 0, which names no group.
Returns
- SessionRequest
This request, so several may be chained.
Remarks
A session holds at most MaxGroupsPerSession keys of a set, its client's and the server's together: keys past it are not added, and counted.
SetVisibility(uint)
Sets which entities with a visibility mask the session sees (14 § 6, P18): one whose mask is 0, or shares a bit with mask. Default 0:
public entities only.
public SessionRequest SetVisibility(uint mask)
Parameters
maskuintThe session's tag mask.
Returns
- SessionRequest
This request, so several may be chained.
Remarks
A change is a RESET of the session's view (P20): every entity it should hold is delivered again under the new mask. Rare by design — a GM
mode, a team change — since a sweep of everything delivered would cost more than the refill. An entity's own mask changing is cheap instead: a leave
or an enter for the sessions it stops or starts being visible to.
Unobserve(int)
Empties one of the session's observer slots.
public SessionRequest Unobserve(int slot)
Parameters
slotintWhich slot.
Returns
- SessionRequest
This request, so several may be chained.
Remarks
The shape is final; the verb arrives in Phase 2, with Observe(ObserverDeclaration, int).
Exceptions
- NotSupportedException
Always, until Phase 2 builds per-session observers.