Table of Contents

Struct SessionRequest

Namespace
Typhon.Engine
Assembly
Typhon.Engine.dll

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

SessionId

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

entity EntityId

The entity, or Null to release.

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

entity EntityId

The entity to follow, or Null to go back to the profile's own anchor.

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

code ushort

The close code, in the application range 4100-4999.

reason string

Why, at most KickReasonMaxBytes bytes once encoded; longer reasons are truncated on the wire.

Returns

SessionRequest

This request, so several may be chained.

Exceptions

ArgumentOutOfRangeException

code is outside 4100-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

observer ObserverDeclaration

The region of interest.

slot int

Which 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

name string

The 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

bytesPerSecond int

The 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

set string

An explicit group set's name, as subs.Groups(name, g => g.Explicit(...)) declared it.

keys long[]

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

mask uint

The 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

slot int

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