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

object

EventBuilder<T>

Inherited Members

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

Events are best effort, and that is a design statement rather than a limitation. They accumulate per skipped session up to a cap and then the oldest are dropped with a loss count. Anything that must never be lost 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.

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.

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.

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.