Class SubscriptionsCommands
What an application system reads commands through, and answers them with.
public sealed class SubscriptionsCommands : ISessionRequests
- Inheritance
-
SubscriptionsCommands
- Implements
- Inherited Members
Remarks
Everything here describes exactly one tick. The Engine-Pre drain fills the buffers before the application's track runs, so a command is visible for the tick it was drained into and for no other — never zero ticks, never two (SUB-08). A system that wants a command to outlive its tick copies it into state, which is what state is for.
Semantic validation belongs to the caller. What reaches here has passed the wire's own checks, the declaration's role list, its rate limit and its stateless pre-check. Range against the current world, cooldowns and ownership are the system's, because the state they must agree with is the system's (01-model § 7).
Fields
SleepingClusters
Clusters asleep across every replicated archetype, refreshed by each read of ProjectionBlocks. A diagnostic.
public int SleepingClusters
Field Value
Properties
EnterFlow
ENTER and LEAVE records published since start.
public (long Entered, long Left) EnterFlow { get; }
Property Value
Remarks
Enters far above leaves is a view still filling. Enters and leaves in step, at a rate far above what the world actually spawns and moves, is the same entities crossing the observers' boundary and crossing back.
EntriesMigrated
Replication entries carried from one cluster to another since start, summed over every archetype.
public long EntriesMigrated { get; }
Property Value
EpochEnter
Mean microseconds a subscriptions chunk spends entering its epoch, and how many chunks were measured.
public (double MeanUs, long Chunks) EpochEnter { get; }
Property Value
FrameBalance
The frame stage's effective worker count and parallel efficiency; zero unless phase timing is on.
public (double Effective, double Efficiency, long Ticks) FrameBalance { get; }
Property Value
FramePhases
The frame stage's phases, in ms of CPU summed over workers since start. All zero unless phase timing was enabled.
public (double Gather, double Sort, double Encode, double Publish) FramePhases { get; }
Property Value
FramePrologueMs
The frame stage's single-threaded prologue, per tick, in ms.
public (double Prologue, double Sweep, double Prepare) FramePrologueMs { get; }
Property Value
FrameSpan
The frame stage's span against the busy time inside it, and the concurrency the two imply.
public (double SpanMs, double BusyMs, double Concurrency, double StartSpreadMs) FrameSpan { get; }
Property Value
IdentityFlow
Network identities minted, released and reused since start.
public (long Minted, long Released, long Reused) IdentityFlow { get; }
Property Value
Remarks
Every archetype shares one allocator, so the first non-null state answers for all of them.
OpenSessions
Every session that is open right now, for an application that has to touch all of them — placing their observers, most of it.
public OpenSessionView OpenSessions { get; }
Property Value
ProjectBlocksMs
The projection's blocks, read and encoded, per tick, in ms of CPU summed over workers: ProjectPrologueMs' busy time less the claiming and the waits, the denominator ProjectWalkMs is a share of. Zero unless phase timing is on.
public double ProjectBlocksMs { get; }
Property Value
ProjectPrologueMs
The projection stage's serial blocks step per tick, split into the push-set preparation, the parked-entry drain and the push marks, and its parallel busy time per tick, in ms. Zero unless phase timing is on.
public (double Prepare, double Drain, double Mark, double Busy) ProjectPrologueMs { get; }
Property Value
ProjectWalkMs
The projection's column walk — every scalar field of every pushed slot read and coded, references resolved, clamps noted — per tick, in ms of thread time summed over workers. An upper bound on what a vectorized walk could cut (13 § 4.1): the resolution and the clamp notes stay scalar. Zero unless phase timing is on.
public double ProjectWalkMs { get; }
Property Value
ProjectionBlocks
Blocks the projection pass read, and blocks it declined because their cluster was dormant, since start.
public (long Projected, long Dormant) ProjectionBlocks { get; }
Property Value
Remarks
The second number is zero unless the application enabled cluster dormancy, which is what makes the pair readable: a projection cost that did not move means one thing if nothing was declined and the opposite if most of it was.
SendPath
The send path, measured while phase timing is on — see SendPump.SendPath.
public (double WakeMsPerPublish, double WokenPerPublish, double QueueDelayUs, double SendUs, long SendsSync, long SendsAsync) SendPath { get; }
Property Value
- (double WakeMsPerPublish, double WokenPerPublish, double QueueDelayUs, double SendUs, long SendsSync, long SendsAsync)
SendTotals
Frames and bytes handed to links since start.
public (long Frames, long Bytes) SendTotals { get; }
Property Value
SessionEvents
This tick's session lifecycle events — Opened, Closed — delivered in Engine-Pre, so a system reacts to one with an ordinary transaction in
the same tick.
public ReadOnlySpan<SessionEvent> SessionEvents { get; }
Property Value
Methods
Commands<T>()
This tick's commands of one type.
public CommandBatch<T> Commands<T>() where T : unmanaged
Returns
- CommandBatch<T>
The batch, empty when nothing arrived.
Type Parameters
TThe command's struct, as the application declared it.
Exceptions
- InvalidOperationException
Twas never declared as a command type.
ControlledOf(SessionId)
The entity a session is anchored to, or Null when its realm and viewpoint are the application's to set.
public EntityId ControlledOf(SessionId session)
Parameters
sessionSessionIdThe session.
Returns
- EntityId
The controlled entity, as
Session(s).Control(entity)last set it.
Remarks
Tick-thread only, as the rest of this type is: it reads the session row without the gate, because the controlled entity is written only on the tick.
EmitTo<T>(SessionId, in T)
Sends an event to one session: an event type declared with RouteToSession() (09 § 11). To a session that is closed or unknown, it reaches nobody.
public bool EmitTo<T>(SessionId session, in T evt) where T : unmanaged
Parameters
sessionSessionIdThe session.
evtTThe event; copied.
Returns
- bool
false only for a reliable event refused for want of room, as Emit<T>(in T).
Type Parameters
TA type declared with Event<T>(Action<EventBuilder<T>>) and routed to a session.
Exceptions
- InvalidOperationException
Tis not a declared event routed to a session.
Emit<T>(in T)
Sends an event to the clients its declaration routes it to (09 § 11). Encoded once, after this tick's projection, and the same bytes reach every session it matches; a session that misses frames receives it with its next one while the event log holds the tick, and is told how many it lost after.
public bool Emit<T>(in T evt) where T : unmanaged
Parameters
evtTThe event; copied.
Returns
- bool
false only for a reliable event refused for want of room (ReliableEventBytes): it reaches nobody, and the emitter is the one who must act on that. true otherwise.
Type Parameters
TA type declared with Event<T>(Action<EventBuilder<T>>).
Remarks
Each worker records into its own buffer; call it on the thread the ctx was handed to. A view kept past its tick or shared with other threads
stays correct — each buffer is gated — but its events land in another worker's order. A tick's events travel in worker order, then call order, which
is not the order the systems ran in across workers.
An EntityId field travels as the entity's netId — 0, "unknown", for an entity the client could not know. A session bound to no profile hears broadcasts and its own EmitTo<T>(SessionId, in T), in frames of events alone; the routes that need a view never reach it.
Exceptions
- InvalidOperationException
Tis not a declared event.
Enter(SessionId, RealmId)
Puts a session in realm with no viewpoint (12-realms § 2.2): what a World, ClientRegion or Aggregate-only session needs; a Sphere sees
nothing there until placed. Applied this tick, as Place(SessionId, RealmId, Vector3D), with the same refusals.
public bool Enter(SessionId session, RealmId realm)
Parameters
Returns
Follow(SessionId, EntityId)
Points a session's viewpoint at an entity it does not control, or releases it — this tick, as Place(SessionId, RealmId, Vector3D) and Enter(SessionId, RealmId) apply this tick.
public bool Follow(SessionId session, EntityId entity)
Parameters
sessionSessionIdThe session.
entityEntityIdThe entity to follow, or Null to release and give the profile's own anchor back.
Returns
Remarks
Why this exists beside Session(s).Follow(entity), which does the same thing a tick later. The staged form is right for a system deciding
something about a session it is looking at, and it is the only form available from a parallel system. But a follow is also the thing an application has
to UNDO before it may move a session itself, and a release that lands next tick makes "stop following this player and put the camera on planet 0"
impossible to express in one tick: the Leave(SessionId) in the same tick still sees the follow and throws. That is the same two-phase trap
TryEnter(SessionId, RealmId) was added to close, met from the other side — so the release is available immediately, from the tick, like every other verb on
this type.
Following is not controlling: the session is given the entity's position and realm and none of its owner data. See
SessionRequest.Follow for the whole argument.
FollowedOf(SessionId)
The entity a session's viewpoint follows, or Null — Session(s).Follow(entity), 12-realms § 2.2 Q5.
public EntityId FollowedOf(SessionId session)
Parameters
sessionSessionIdThe session.
Returns
- EntityId
The followed entity.
Remarks
Not the same question as ControlledOf(SessionId), which is why both exist. A session that follows an entity is centred on it and is in its
realm; a session that controls one is also served its SELF block and its owner fields. An application with a spectator mode wants the first and
must not have the second, so it asks this one. Tick-thread only, as the rest of this type is.
IsAnchored(SessionId)
Whether a session's realm is an entity's rather than the application's — the condition Enter(SessionId, RealmId), Place(SessionId, RealmId, Vector3D) and Leave(SessionId) raise on.
public bool IsAnchored(SessionId session)
Parameters
sessionSessionIdThe session.
Returns
- bool
true when the session follows an entity at run time (
Session(s).Follow), or when its applied profile isAroundControlledor bound to an entity.
Remarks
A query, not a guard. It reports the profile the engine has APPLIED, and a profile requested through Session(s).Profile(name) is applied
by the next tick's prologue — so between asking and acting the answer can change, and the failure is a throw on the tick thread. Use it to decide what
to draw, offer or log; use TryEnter(SessionId, RealmId) and TryPlace(SessionId, RealmId, Vector3D) to act.
A run-time Follow counts, whatever the profile declared. It is the same condition for the same reason: the engine is moving the session's
realm every tick from the followed entity, so an application moving it too would be the second writer of one field that 12-realms § 1.3 forbids. A
Follow on an otherwise unanchored profile — a god camera tracking a player's realm while keeping its own hull — anchors it exactly as
AroundControlled does, and releasing it with Null gives it back.
Leave(SessionId)
Takes a session out of every realm (12-realms § 1.6): its client is told with a RESET carrying REALM(NONE), and it hears only the events
addressed to it. Applied this tick.
public bool Leave(SessionId session)
Parameters
sessionSessionIdThe session.
Returns
Exceptions
- InvalidOperationException
The session's profile follows an entity, whose realm is its own.
Place(SessionId, RealmId, Vector3D)
Places a session in realm, looking from position, for THIS tick (R4.3, 12-realms § 2.2). A realm change is one
RESET frame carrying the new realm's REALM block, published this tick or retried until it is (SUB-29).
public bool Place(SessionId session, RealmId realm, Vector3D position)
Parameters
sessionSessionIdThe session.
realmRealmIdA registered realm, not closing.
positionVector3DWhere it is looking from, in the realm's space.
Returns
Exceptions
- ArgumentException
The realm is not registered, or is None — use Leave(SessionId).
- InvalidOperationException
The realm is closing, or the session's profile follows an entity — its realm is that entity's, and two writers of one field is a bug.
Place(SessionId, Vector3D)
Places a session's spatial observers for THIS tick.
public bool Place(SessionId session, Vector3D position)
Parameters
Returns
Remarks
It applies now, unlike everything on Session(SessionId). A profile, a budget or the entity a session controls are configuration, and the request log stages them so they take effect from a known boundary. A viewpoint is not configuration — it is this tick's position — and a tick of latency on it means every session resolves its interest around where it was rather than where it is.
Call it from an application system, once per session per tick, before the replication track runs. A session with a Sphere observer that
has never been placed sees nothing at all: an unplaced session is nowhere, not at the origin, because a default position is a legal world position and
silently giving everyone a sphere around it is worse than giving them nothing.
Exceptions
- InvalidOperationException
The engine holds several realms and the session is in none: say which, with Place(SessionId, RealmId, Vector3D) (12-realms § 1.3).
RealmOf(SessionId)
The realm a session's client holds: the realm of its last published RESET (12-realms § 2.2), None before its first and
while it is in none.
public RealmId RealmOf(SessionId session)
Parameters
sessionSessionIdThe session.
Returns
- RealmId
The committed realm.
Reject(SessionId, ushort, byte)
Answers a session's command by sequence number.
public bool Reject(SessionId session, ushort seq, byte reasonCode)
Parameters
sessionSessionIdWhose command it was.
sequshortIts sequence number.
reasonCodebyteAn AckReasons code.
Returns
Reject<T>(in ClientCommand<T>, byte)
Answers a command with a rejection, which reaches the client as an ACK record.
public bool Reject<T>(in ClientCommand<T> command, byte reasonCode) where T : unmanaged
Parameters
commandClientCommand<T>The command being refused.
reasonCodebyteAn AckReasons code; 128-255 are the application's own.
Returns
Type Parameters
TThe command's struct.
Remarks
A command that is simply not applied sends nothing — the client learns only that its seq was consumed. Rejecting is for telling it WHY, and it
costs a record in the next frame, so it is a decision rather than a default.
Replicate(in EntityRefMut)
Replicate<TArchetype>(in ClusterRef<TArchetype>, int) for an entity reached by id rather than by walking its cluster — the target of a
command, resolved with TryResolve(SessionId, uint, out EntityId) and opened with OpenMut.
public void Replicate(in EntityRefMut entity)
Parameters
entityEntityRefMutThe entity the system wrote.
Remarks
The same mark, in the same per-cluster word: one interlocked OR, duplicates free. Call it after the write, as with the cluster form; a no-op for an archetype no profile observes.
Replicate<TArchetype>(in ClusterRef<TArchetype>, int)
Tells the engine that the entity in slot of cluster changed something a client sees (ADR-067: replication is
explicit).
public void Replicate<TArchetype>(in ClusterRef<TArchetype> cluster, int slot) where TArchetype : class
Parameters
clusterClusterRef<TArchetype>The cluster the system is iterating.
slotintThe entity's slot.
Type Parameters
TArchetype
Remarks
A mark, not a send. One interlocked OR into a per-cluster bitmap the fence already drains; duplicates are free. After the fence the entity is encoded once, compared against what was last encoded (so a spurious push costs an encode and no wire), and fanned out to the sessions around it.
The contract is the developer's. A change that is never pushed is never sent. Spawns, destroys and WriteSpatial moves are pushed by the
engine; a component written through GetSpan or EntityRefMut is not. A no-op for an archetype no push profile observes.
Replicate<TArchetype>(in ClusterRef<TArchetype>, ulong)
Replicate<TArchetype>(in ClusterRef<TArchetype>, int) for a set of slots of one cluster.
public void Replicate<TArchetype>(in ClusterRef<TArchetype> cluster, ulong slots) where TArchetype : class
Parameters
clusterClusterRef<TArchetype>The cluster.
slotsulongThe slots, as a mask.
Type Parameters
TArchetype
Session(SessionId)
Asks something of a session: the profile it is bound to, the observers it carries, the entity it controls, its budget, or a kick.
public SessionRequest Session(SessionId session)
Parameters
sessionSessionIdThe session.
Returns
- SessionRequest
A builder whose calls are recorded and applied by the next tick's prologue.
Remarks
This is how a session gets a profile, and without one it receives nothing: interest is gathered per profile, so a session bound to none is not
in any tick's session set. The natural place to call it is the SessionEvents loop, on the Opened event.
Nothing happens immediately. A session row belongs to the tick (SUB-05); the calls are appended to this view's segment and applied
single-threaded at the start of the next tick, in the order they were made, before interest is gathered. A system reaches its own segment through
ctx.Subscriptions, which is what makes this safe from any system on any worker (SUB-39).
SessionKindOf(SessionId)
The kind a session named in its HELLO, or null when it is gone.
public string SessionKindOf(SessionId session)
Parameters
sessionSessionIdThe session.
Returns
- string
The kind.
SetRadius(SessionId, double)
Changes a session's Sphere radius from this tick on, within the range its profile declares — Sphere(r, max: m) (09 § 4).
public bool SetRadius(SessionId session, double radius)
Parameters
sessionSessionIdThe session.
radiusdoubleThe radius, in metres: between the profile's own (its band's midpoint when it declares a leave radius) and its declared maximum. 0 returns to the profile's own.
Returns
Remarks
A player boarding an aircraft. The change is geometry like an anchor move: the next frame sweeps the shell between the two radii — enters when it grows, leaves when it shrinks — with no reset, so the client keeps everything it already holds.
It applies now, like Place(SessionId, Vector3D), and holds until the session's profile changes, which returns it to the new profile's own radius. It is checked against the profile applied NOW: a profile requested through Session(SessionId) is applied by the next tick's prologue, so a radius for that profile is set from the next tick on.
The radius is the one sessions test — the band's midpoint (R + L) / 2 when the profile declares a leave radius — the same space as
max:.
Exceptions
- InvalidOperationException
No profile is applied to the session yet, or its profile is not a Sphere.
- ArgumentOutOfRangeException
The radius is outside the profile's declared range.
TryEnter(SessionId, RealmId)
Enter(SessionId, RealmId), answering false where it would raise for something that can change under the caller.
public bool TryEnter(SessionId session, RealmId realm)
Parameters
Returns
- bool
false when the session is closing or gone, when it follows an entity, or when the realm is gone or closing; otherwise true and the session is in it from this tick.
Remarks
It exists because the alternative cannot be written correctly by an application. A session whose profile follows an entity may not be moved explicitly — the entity decides its realm — and Enter(SessionId, RealmId) raises on one. But whether a session is anchored is decided by Typhon.Engine.Internals.ViewpointSource, which is internal, and a profile requested on one tick is applied by the NEXT tick's prologue: so an application that asks first and acts second is asking about a state that changes between the two, and the wrong answer is an exception on the tick thread. That is not hypothetical — it is the defect the SWG demo's spectator control shipped with, reachable by pressing Stop and picking a realm inside one tick.
So the test and the act are one call. IsAnchored(SessionId) answers the same question and cannot promise this, which is why it is documented as a query rather than as a guard.
What it does NOT swallow. None and a realm declaring no Replication still raise: neither can change under a caller — one is a misuse of the API and the other is fixed when the realm is registered — and answering false for them would turn a bug in the application into a session that quietly never arrives.
TryGetLastSeq(SessionId, out ushort)
The highest sequence number drained into a tick for a session, which is what SELF.lastSeq reports.
public bool TryGetLastSeq(SessionId session, out ushort lastSeq)
Parameters
Returns
Remarks
Every sequence at or below it was applied, rejected or coalesced away, which is exactly what a client's prediction reconciliation needs (03-wire-protocol § 12 W31).
TryNetIdOf(SessionId, EntityId, out uint)
The netId a session's client knows an entity by — the inverse of TryResolve(SessionId, uint, out EntityId).
public bool TryNetIdOf(SessionId session, EntityId entity, out uint netId)
Parameters
sessionSessionIdThe session whose view the identity is for.
entityEntityIdThe entity to name.
netIduintThe identity, or
0when that session cannot name it.
Returns
Remarks
What it is for: naming an entity the application chose to a client that can see it. Everything else in this surface goes the other way — a client names something and the server resolves it. An operator tool, a GM command, a tutorial that points at a quest giver, or a test that wants to drive a command at a specific entity all start from the entity and need the number.
Session-scoped although the identity is engine-wide, and that is a deliberate narrowing. One allocator issues netIds across
every replicated archetype, so an unscoped version would be a line shorter and a trap: handing a client an identity it was never
shown lets it name something outside its view, which is what SUB-26 exists to prevent and what TryResolve(SessionId, uint, out EntityId)
enforces in the other direction. Scoped, the worst a caller can do is be told no.
Same cost and same contract as TryResolve(SessionId, uint, out EntityId): an EntityMap probe and a geometric test against the session's COMMITTED geometry — what its last published frame carried — so call it for the entities an application names, not per entity per tick. From a system or between ticks, never while the fence is open: it reads state the projection and the frame stage write inside the fence window, and a foreign thread the window overlaps gets an InvalidOperationException, as TryResolve(SessionId, uint, out EntityId) does. An answer is good until the next frame is published — after a teleport's RESET, the entity may not be held again until the refill delivers it.
Exceptions
- InvalidOperationException
Called from a thread outside the fence while the fence window was open during the call.
TryPlace(SessionId, RealmId, Vector3D)
Place(SessionId, RealmId, Vector3D), answering false where it would raise for something that can change under the caller. See TryEnter(SessionId, RealmId) for why.
public bool TryPlace(SessionId session, RealmId realm, Vector3D position)
Parameters
sessionSessionIdThe session.
realmRealmIdA realm. Need not still be registered, or open.
positionVector3DWhere it is looking from, in the realm's space.
Returns
TryResolve(SessionId, uint, out EntityId)
Resolves an entity reference a client sent — a netId on the wire — back to the entity it names, if the session holds it (SUB-26).
public bool TryResolve(SessionId session, uint netId, out EntityId entity)
Parameters
sessionSessionIdThe session that sent the reference.
netIduintThe network identity, as the command carried it.
entityEntityIdThe entity.
Returns
- bool
false when nothing live holds that identity, the session is gone, or the session does not hold the entity: it is neither the session's controlled entity nor inside the geometry its client was last told about.
Remarks
A client can only name what it was shown (01 § 7). What a session holds is geometric (SUB-16), so this is the geometric test against the session's committed geometry — the anchor, radius and delivered cells of its last published frame, or its committed hull, or its World cursor — on the entity's v̂. An entity that left the view this tick is still accepted: the client saw it when it sent the command. One that it learned of only from an event (an attacker beyond its view) is refused — events inform, they do not grant reach.
An unknown identity is not an error. A client may name an entity that has since left, or one it was never shown; the answer is "no", and the system decides what that means. Treating it as malformed input would let one stale reference close a connection.
Costs an EntityMap probe through freshly opened chunk accessors and a geometric test, ≈ 1–2 µs: call it for the commands that name entities, not per entity per tick. It is committed-state accurate: a session served every few ticks (a rate class, overload) is judged against its last published frame, while the entity's v̂ is this tick's — near the edge the two can disagree by the motion of those ticks.
A teleport empties what the session holds, for as long as its refill takes. A re-anchor beyond one replication cell is a RESET: the client drops its whole view, and the new one is delivered nearest cell first under the enter budget, over one frame or several. An entity it held before the move is refused from the RESET frame on, and one of the new view from when its cell is delivered and its enter sent — the same answer the client's own store gives, so a command can only name what is on its screen.
From a system, or between ticks — never while the fence is open (EW-01's readers clause). The fence and the subscriptions track it holds the window across rewrite the committed view field by field with no protocol a reader could follow; a read they overlap would mix two frames, and an off-tick poller hits that window (#1494). A foreign thread that calls this while the window is open gets an InvalidOperationException instead of an answer; one whose read a whole fence ran during reads again (up to three times), so a call between ticks is answered. The check is a relaxed load at each end of the call. An off-tick caller still marshals the read onto the tick: it cannot know whether a fence is about to open.
Exceptions
- InvalidOperationException
Called from a thread outside the fence while the fence window was open during the call.
TryResolveAny(SessionId, uint, out EntityId)
Resolves a netId to the live entity that holds it, whatever the session holds — for tools that are not clients (an admin console, a replay).
A client's command goes through TryResolve(SessionId, uint, out EntityId), which refuses what its client was never shown.
public bool TryResolveAny(SessionId session, uint netId, out EntityId entity)
Parameters
sessionSessionIdThe session that sent the reference.
netIduintThe network identity.
entityEntityIdThe entity.
Returns
Remarks
A tool is not exempt from the threading contract: from a system or between ticks, never while the fence is open — the netId binding and the replica it reads are rewritten inside the fence window, and a foreign thread the window overlaps gets an InvalidOperationException, as TryResolve(SessionId, uint, out EntityId) does.
Exceptions
- InvalidOperationException
Called from a thread outside the fence while the fence window was open during the call.