Table of Contents

Class EventBuilder<T>

Namespace
Typhon.Engine
Assembly
Typhon.Engine.dll

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

T

The 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

selector Expression<Func<T, EntityId>>

Selects the entity field.

name string

The 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

selector Expression<Func<T, TField>>

Selects the field.

codec Codec

How the value travels.

name string

The wire name. null takes the field's own name.

Returns

EventBuilder<T>

This builder.

Type Parameters

TField

The 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

selector Expression<Func<T, TField>>

Selects the field.

Returns

EventBuilder<T>

This builder.

Type Parameters

TField

The 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

point Func<T, Vector3D>

Reads the event's world position. Called once per event, never per session.

radiusM double

When 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

point Func<T, Vector3D>

Reads the event's position in its realm. Called once per event, never per session.

realm Func<T, RealmId>

Reads the realm the point is in — an emitter has it cheaply from the cluster or entity it acts on (ClusterRef.Realm).

radiusM double

When 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

entities Expression<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

entity Expression<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

realm Func<T, RealmId>

Reads the realm the event is addressed to.

subtree bool

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