Class SubscriptionsRegistry
The declaration surface for engine-owned replication: the projections clients may see, the profiles that decide what each session watches, the commands clients may send, the events they hear and the metrics they are told about.
public sealed class SubscriptionsRegistry
- Inheritance
-
SubscriptionsRegistry
- Inherited Members
Remarks
Reached through Subscriptions, and configured before Start(). Replication rides the tick, so
it belongs to the runtime rather than to DatabaseEngine; and everything here is compiled once at Start, which is why the registry
freezes there and refuses a late declaration instead of quietly not applying it.
Declaring costs nothing at run time. The registry holds names, codecs and policy; it has no per-tick presence at all. What the tick sees is the compiled plan the projection compiler builds from it, in which every name has already become an offset.
Malformed declarations are refused where they are written. A duplicate wire name, a ninth change group, a 256th archetype, a 64-bit source with no
explicit narrowing and a metric under the reserved typhon. prefix all throw from the call that declared them. What cannot be judged from one
declaration — an observer shape or a source that a later phase builds — is refused at Start, with the phase named.
Constructors
SubscriptionsRegistry(SubscriptionsOptions)
Creates a registry over the given options.
public SubscriptionsRegistry(SubscriptionsOptions options = null)
Parameters
optionsSubscriptionsOptionsThe operator's replication options. null takes the defaults.
Remarks
The runtime builds its own from Subscriptions and exposes it as Subscriptions; that is the one the engine reads. Constructing one directly is for a test, or for an application that assembles its declarations somewhere other than beside its host.
Properties
Archetypes
The archetype projections, in declaration order.
public IReadOnlyList<ArchetypeProjection> Archetypes { get; }
Property Value
Commands
The command types, in declaration order.
public IReadOnlyList<CommandDeclaration> Commands { get; }
Property Value
DeclaredRealmKinds
The realm kinds declared with RealmKinds(params string[]); the default kind "" is implicit.
public IReadOnlyList<string> DeclaredRealmKinds { get; }
Property Value
Events
The replicated events, in declaration order.
public IReadOnlyList<EventDeclaration> Events { get; }
Property Value
GroupSets
The group sets declared with Groups(string, Action<GroupSetBuilder>), in ordinal name order — the catalog's: a set's index is its number on the wire.
public IReadOnlyList<GroupSetDeclaration> GroupSets { get; }
Property Value
IsFrozen
Whether Start has compiled these declarations. A frozen registry refuses every further declaration.
public bool IsFrozen { get; }
Property Value
Metrics
The application's metrics, in declaration order. The built-ins are not listed here: the engine owns them.
public IReadOnlyList<MetricDeclaration> Metrics { get; }
Property Value
Options
The operator's replication options.
public SubscriptionsOptions Options { get; }
Property Value
Profiles
The interest profiles, in declaration order.
public IReadOnlyList<ProfileDeclaration> Profiles { get; }
Property Value
Sessions
Session kinds, admission and the tick-visible session lifecycle.
public SubscriptionsSessions Sessions { get; }
Property Value
Methods
Archetype<TArchetype>()
Declares an archetype from its replication attributes (design/Subscriptions/11 § 5): [Replicated] on the archetype, [Motion] or
[Position] on a Comp<T> field, [Replicate], [OnEnter], [Owner], [Fraction], [Heading] on its
components' fields. The source generator compiles them into the builder calls Archetype<TArchetype>(Action<ArchetypeProjectionBuilder>)
would take; calling that overload instead replaces the attributes entirely, which is how a deployment overrides them.
public SubscriptionsRegistry Archetype<TArchetype>() where TArchetype : Archetype<TArchetype>, IReplicatedArchetype
Returns
- SubscriptionsRegistry
This registry.
Type Parameters
TArchetypeA
[Replicated]archetype: the generator implements IReplicatedArchetype on it, so an archetype without the attribute — or an assembly the generator does not run in — does not compile here.
Archetype<TArchetype>(Action<ArchetypeProjectionBuilder>)
Declares what clients may see of an archetype.
public SubscriptionsRegistry Archetype<TArchetype>(Action<ArchetypeProjectionBuilder> configure) where TArchetype : Archetype<TArchetype>
Parameters
configureAction<ArchetypeProjectionBuilder>Declares its position, fields and owner section.
Returns
- SubscriptionsRegistry
This registry.
Type Parameters
TArchetypeThe archetype.
Command<T>(Action<CommandBuilder<T>>)
Declares a command type clients may send.
public SubscriptionsRegistry Command<T>(Action<CommandBuilder<T>> configure) where T : unmanaged
Parameters
configureAction<CommandBuilder<T>>Declares delivery, rate, roles and pre-check.
Returns
- SubscriptionsRegistry
This registry.
Type Parameters
TThe command type: an unmanaged struct.
Event<T>(Action<EventBuilder<T>>)
Declares an event type clients receive, and how it is routed. Systems send one with Emit<T>(in T).
public SubscriptionsRegistry Event<T>(Action<EventBuilder<T>> configure) where T : unmanaged
Parameters
configureAction<EventBuilder<T>>Declares routing and fields.
Returns
- SubscriptionsRegistry
This registry.
Type Parameters
TThe event type: an unmanaged, blittable struct.
Remarks
Emitted, not drained (09 § 11, Q3). An event a client sees is emitted explicitly, as state is pushed (ADR-067): an application that also applies its events keeps its own EventQueue<T> for the simulation and emits what clients should see.
Groups(string, Action<GroupSetBuilder>)
Declares a group set (14 § 3): a family of groups, each a key its members carry in an indexed field, held by a session while its selector names the key — for a region set, while the session's observer meets the region's extent (Groups(string, double)).
public SubscriptionsRegistry Groups(string name, Action<GroupSetBuilder> configure)
Parameters
namestringThe set's name, as profiles and the catalog name it.
configureAction<GroupSetBuilder>Declares the selector and the members.
Returns
- SubscriptionsRegistry
This registry.
Metric(string, string, Codec, Func<double>, MetricKind, string[])
Declares an application metric, carried to sessions that asked for statistics.
public SubscriptionsRegistry Metric(string name, string unit, Codec codec, Func<double> source, MetricKind kind = MetricKind.Gauge, string[] labels = null)
Parameters
namestringThe metric's name. The
typhon.prefix is reserved for the engine's own.unitstringIts unit, as a client displays it —
ms,count,B/s.codecCodecHow the value travels. Encoders saturate: no NaN and no infinity reach the wire.
sourceFunc<double>Reads the current value, once per emission — not once per session.
kindMetricKindGauge or counter.
labelsstring[]The label set, for a metric that contributes one value per label rather than one value.
Returns
- SubscriptionsRegistry
This registry.
Metric(string, string, Codec, string[], MetricValuesSource, MetricKind)
Declares a labelled application metric (09 § 15, D5): one value per label, all read by one call per emission — not one per label, not one per session.
public SubscriptionsRegistry Metric(string name, string unit, Codec codec, string[] labels, MetricValuesSource source, MetricKind kind = MetricKind.Gauge)
Parameters
namestringThe metric's name. The
typhon.prefix is reserved for the engine's own.unitstringIts unit.
codecCodecHow each value travels.
labelsstring[]The labels, at least one, distinct: the order the values are written in.
sourceMetricValuesSourceFills the values, one per label in
labels' order; a value it leaves unwritten is zero.kindMetricKindGauge or counter.
Returns
- SubscriptionsRegistry
This registry.
Profile(string, Action<ProfileBuilder>)
Declares a named set of observers a session can be bound to.
public SubscriptionsRegistry Profile(string name, Action<ProfileBuilder> configure)
Parameters
namestringThe profile's name.
configureAction<ProfileBuilder>Declares its observers.
Returns
- SubscriptionsRegistry
This registry.
RealmKinds(params string[])
Declares the kinds a realm may carry (12-realms § 1.4) — planet, interior, space — which a profile's variants are chosen by
(In(string, Action<ProfileBuilder>)). The default kind "" always exists; the catalog lists them in canonical order.
public SubscriptionsRegistry RealmKinds(params string[] kinds)
Parameters
kindsstring[]Distinct, non-empty names.
Returns
- SubscriptionsRegistry
This registry.
SessionMetric(string, string, Codec, Func<SessionId, double>, MetricKind)
Declares a per-session application metric (09 § 15, D5): a value for each session that asked for statistics, read once per such session per emission — a second, on the tick every block is sent.
public SubscriptionsRegistry SessionMetric(string name, string unit, Codec codec, Func<SessionId, double> source, MetricKind kind = MetricKind.Gauge)
Parameters
namestringThe metric's name. The
typhon.prefix is reserved for the engine's own.unitstringIts unit.
codecCodecHow the value travels.
sourceFunc<SessionId, double>Reads the session's value. It runs on a frame worker, concurrently for different sessions: it must not write shared state.
kindMetricKindGauge or counter.
Returns
- SubscriptionsRegistry
This registry.
Static<TArchetype>(Action<ArchetypeProjectionBuilder>)
Declares an archetype whose replicated state never changes: its record is sent once, on enter, and never updated.
public SubscriptionsRegistry Static<TArchetype>(Action<ArchetypeProjectionBuilder> configure) where TArchetype : Archetype<TArchetype>
Parameters
configureAction<ArchetypeProjectionBuilder>Declares its position and fields.
Returns
- SubscriptionsRegistry
This registry.
Type Parameters
TArchetypeThe archetype.
Remarks
This is not an optimization hint the engine may ignore. A static archetype has no change groups and no per-entity comparison at all, so a world of scenery costs the projection pass nothing per tick — which is the difference between replicating a landscape and replicating a simulation.