Class MotionBuilder

Namespace

Typhon.Engine

Assembly

Typhon.Engine.dll

Configures how an archetype's position travels: how wrong a client's extrapolation may get before a new motion segment is sent, what counts as a teleport, and how long a moving entity may go without a refresh.

public sealed class MotionBuilder

Inheritance

object

MotionBuilder

Inherited Members

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

None of this reaches the catalog. Tolerance, teleport speed and segment age are server policy: they decide when the engine emits a segment, and a client that received the segment needs none of them to extrapolate from it. What the catalog does carry is the velocity codec whose width Teleport(double) sizes — the one place this policy becomes a wire fact.

Every value is per archetype, because a spaceship and a walking NPC do not deserve the same: a tolerance tight enough for a duel is wasted bandwidth on a cargo hauler, and a teleport threshold that suits the hauler would interpolate a duelist across the arena.

Methods

IgnoreTickDilation()

Sizes the velocity codec for the nominal tick period only, ignoring the runtime's overload time dilation.

public MotionBuilder IgnoreTickDilation()

Returns

MotionBuilder

This builder.

Remarks

Under overload the engine ticks less often and each tick covers more time, so a displacement-per-tick codec has to be wide enough for the slowest rate the runtime may fall back to — up to 2.5 bits more than the nominal rate needs, on every segment, forever, for a state the server should rarely be in. An archetype whose movement is bounded per tick rather than per second — something that steps a fixed distance — pays that for nothing, and says so here. The cost of being wrong is a clamped velocity on a dilated tick, not a decode error.

MaxAge(double)

How long a moving entity may keep the same segment before the engine refreshes it, in seconds. Default 5 s. A stationary entity never gets one: nothing drifts when the velocity is zero, so a heartbeat would be pure cost.

public MotionBuilder MaxAge(double seconds)

Parameters

seconds double

The maximum segment age, above zero.

Returns

MotionBuilder

This builder.

Teleport(double)

The speed above which a step is a discontinuity rather than movement: the client cuts its extrapolation and jumps, and the segment's epoch advances.

public MotionBuilder Teleport(double maxSpeedMps)

Parameters

maxSpeedMps double

The fastest legitimate speed, in metres per second.

Returns

MotionBuilder

This builder.

Remarks

Give it a margin — about 1.5× the fastest thing that legitimately moves. A mover travelling at exactly the threshold rounds over it on some ticks and not others, so the client sees a smooth run punctuated by jumps for no reason the simulation would recognise.

It also sizes the velocity codec: the widest displacement one tick can carry is this speed times the tick period times the runtime's largest allowed tick multiplier, rounded up to 8, 16, 24 or 32 bits. A generous threshold therefore costs a little bandwidth on every segment, which is the honest trade — the alternative is a fixed width that is either wasteful or wrong.

Tolerance(double)

The extrapolation error, in metres, at which the engine gives the client a new segment. Default 5 cm.

public MotionBuilder Tolerance(double metres)

Parameters

metres double

The error budget, above zero.

Returns

MotionBuilder

This builder.

Remarks

It buys bandwidth directly: doubling it roughly halves the segments a curving entity produces, at the cost of a client that is up to twice as wrong between them. It cannot go below the position codec's own quantum — the client could not represent the difference.

VelocityFrom<TComponent, TField>(Comp<TComponent>, Expression<Func<TComponent, TField>>)

Takes the velocity from a field the simulation already maintains instead of measuring it, for a simulation that does not move its entities every tick and whose measured displacement would therefore read as a stop-start stutter.

public MotionBuilder VelocityFrom<TComponent, TField>(Comp<TComponent> component, Expression<Func<TComponent, TField>> selector) where TComponent : unmanaged

Parameters

component Comp<TComponent>

The component handle.

selector Expression<Func<TComponent, TField>>

Selects the velocity field.

Returns

MotionBuilder

This builder.

Type Parameters

TComponent

The component holding the velocity.

TField

The velocity field's type.