Class EventBuilder<T>
Declares how a system's event queue reaches clients: which sessions hear an event, and what of it travels.
public sealed class EventBuilder<T> where T : unmanaged
Type Parameters
TThe event type.
- Inheritance
-
EventBuilder<T>
- Inherited Members
Remarks
Events are best effort unless declared Reliable(), and that is a design statement rather than a limitation. A session that misses more than the log holds is told how many it lost. Anything a client can learn again is state: a death is a mode change, not a message, and a client that missed the message still learns the creature is dead from its next record. What it can never learn again — a trade's outcome, the loot it was given — is a reliable event: delivered once and in order to every live session it is routed to, or the session is closed.
Routing costs are per event, not per session. RouteNear(Func<T, Vector3D>, double) buckets events by grid cell and each session collects the cells it overlaps, so a hundred sessions and a thousand events cost O(events + Σ cells) rather than their product.
Every public instance field of T travels, whether or not the declaration mentions it (01-model § 7).
Field<TField>(Expression<Func<T, TField>>, Codec, string) and Entity(Expression<Func<T, EntityId>>, string) OVERRIDE how one of them travels; Ignore<TField>(Expression<Func<T, TField>>) keeps one off the wire. A field
nobody mentions is not a field nobody wanted — it is usually one somebody forgot.
Methods
Broadcast()
Routes the event to every session. For a server-wide announcement, not for anything a session could be uninterested in.
public EventBuilder<T> Broadcast()
Returns
- EventBuilder<T>
This builder.
Entity(Expression<Func<T, EntityId>>, string)
An entity reference the event carries. It travels as a netId, so a client receives the identity it already knows rather than a server-side id it could not use.
public EventBuilder<T> Entity(Expression<Func<T, EntityId>> selector, string name = null)
Parameters
selectorExpression<Func<T, EntityId>>Selects the entity field.
namestringThe wire name. null takes the field's own name.
Returns
- EventBuilder<T>
This builder.
Remarks
An EntityId field travels as a netId by default, so this verb is what renames one or states the intent where it reads better; it is not what makes the reference travel.
Field<TField>(Expression<Func<T, TField>>, Codec, string)
A value the event carries.
public EventBuilder<T> Field<TField>(Expression<Func<T, TField>> selector, Codec codec, string name = null)
Parameters
selectorExpression<Func<T, TField>>Selects the field.
codecCodecHow the value travels.
namestringThe wire name. null takes the field's own name.
Returns
- EventBuilder<T>
This builder.
Type Parameters
TFieldThe field's type.
Remarks
It overrides the codec the field's CLR type defaults to; it is not what makes the field travel.
Exceptions
- InvalidOperationException
The selector names something that is not a public instance field of
T, or that field is already declared or ignored.
Ignore<TField>(Expression<Func<T, TField>>)
Keeps one of the event's fields off the wire: a server-side correlation id, a field only the routing reads.
public EventBuilder<T> Ignore<TField>(Expression<Func<T, TField>> selector)
Parameters
selectorExpression<Func<T, TField>>Selects the field.
Returns
- EventBuilder<T>
This builder.
Type Parameters
TFieldThe field's type.
Remarks
It takes a verb because silence must not mean "not replicated". Every other field travels by default, so an omission and a decision would otherwise look identical in the declaration and in review.
Exceptions
- InvalidOperationException
The selector names something that is not a public instance field of
T, or that field already carries a declaration.
Reliable()
Makes the event reliable (14 § 7, SUB-35): while a session lives it receives every one routed to it, once, in emission order — across skipped frames,
a RESET, and a burst larger than a frame, which goes over the next frames — and a session that cannot be kept so is closed with 1013. An emit
past ReliableEventBytes is refused: Emit<T>(in T) returns false.
public EventBuilder<T> Reliable()
Returns
- EventBuilder<T>
This builder.
Remarks
The route is the event's own, judged against the session's geometry when the event is delivered. Not carried across a resume: a resumed session is a new session, and the application re-sends what its client must learn.
RouteNear(Func<T, Vector3D>, double)
Routes the event to sessions whose interest contains the point it carries.
public EventBuilder<T> RouteNear(Func<T, Vector3D> point, double radiusM = 0)
Parameters
pointFunc<T, Vector3D>Reads the event's world position. Called once per event, never per session.
radiusMdoubleWhen above zero, only sessions whose viewpoint lies within this radius of the point hear it.
Returns
- EventBuilder<T>
This builder.
RouteNear(Func<T, Vector3D>, Func<T, RealmId>, double)
Routes the event to sessions of realm's realm whose interest contains the point it carries (12-realms § 3): the point is a place
in that realm, and a session of another realm never hears it, whatever its local coordinates.
public EventBuilder<T> RouteNear(Func<T, Vector3D> point, Func<T, RealmId> realm, double radiusM = 0)
Parameters
pointFunc<T, Vector3D>Reads the event's position in its realm. Called once per event, never per session.
realmFunc<T, RealmId>Reads the realm the point is in — an emitter has it cheaply from the cluster or entity it acts on (
ClusterRef.Realm).radiusMdoubleWhen above zero, only sessions whose viewpoint lies within this radius of the point hear it.
Returns
- EventBuilder<T>
This builder.
RouteToKnown(params Expression<Func<T, EntityId>>[])
Routes the event to every session that already knows any of the entities it names — the sessions for which the event means something, because they have the entity it is about.
public EventBuilder<T> RouteToKnown(params Expression<Func<T, EntityId>>[] entities)
Parameters
entitiesExpression<Func<T, EntityId>>[]Selects the entity fields to test.
Returns
- EventBuilder<T>
This builder.
RouteToOwner(Expression<Func<T, EntityId>>)
Routes the event to the session controlling the entity it names.
public EventBuilder<T> RouteToOwner(Expression<Func<T, EntityId>> entity)
Parameters
entityExpression<Func<T, EntityId>>Selects the entity field.
Returns
- EventBuilder<T>
This builder.
RouteToRealm(Func<T, RealmId>, bool)
Routes the event to every session in realm's realm — with subtree, also to every session in a realm below it
in the parent tree (Parent): a planet-wide message that reaches the players in its interiors (12-realms § 3). The parent
tree routes; it grants no visibility.
public EventBuilder<T> RouteToRealm(Func<T, RealmId> realm, bool subtree = false)
Parameters
realmFunc<T, RealmId>Reads the realm the event is addressed to.
subtreeboolWhether realms below it hear it too.
Returns
- EventBuilder<T>
This builder.
RouteToSession()
Routes the event to the one session the emitter names, with EmitTo<T>(SessionId, in T): a reply, a private notice.
public EventBuilder<T> RouteToSession()
Returns
- EventBuilder<T>
This builder.