Avatar Motor

Optional game seam for DEEP validation of a client-authoritative avatar report. The Motor already applies a generic envelope (per-message rate limiting via Core's RateLimitOptions, a gross-delta / max-speed teleport reject, and finite-value checks); register an IAvatarMoveValidator to add game-specific rules on top — a per-state max step, a kill-plane floor, a jump/dash budget, a "you cannot be here in this game-state" test. It is consulted AFTER the built-in checks pass, and its veto drops the report. Optional ([InjectOptional]): most co-op games need nothing beyond the built-in envelope and register no validator. Its absence is the default — the piece stays fully functional and removable without it.

• bool Accept(long entityId, in Vec3 position, in Vec3 prevPosition, float dtMs)

  Returns true to accept the reported position for entityId, false to reject the whole report. prevPosition is the entity's previous authoritative position and dtMs the elapsed server milliseconds since the last accepted report (0 for the first report after spawn/teleport) — enough to bound a per-state step without the game tracking its own timing.

Optional game seam that decides which client may drive which server-spawned entity. Route B exists because the game has a bespoke controller the server cannot reproduce — which is equally true of its enemies, NPCs and host-driven props. Those are spawned server-side and have no owning session, so the game elects one client as the simulation host and that client relays their poses through the same MotorState report it already sends for its own avatar (MotorState.EntityId). The framework has no notion of a host — election is a game decision (lowest player entity id, the party leader, the lowest-latency peer, a lobby setting), and it changes at runtime when that client leaves. So the Motor asks: may THIS session move THAT entity, right now? Optional ([InjectOptional]) and closed by default: with no authority registered the server rejects every non-zero MotorState.EntityId, so a game that has not opted in behaves exactly as before. Registering one opens exactly the entities you approve — the Motor additionally refuses any target that is not server-spawned, so a relay can never touch another player's avatar even if this method wrongly returns true.

// The host (lowest player entity id) drives every server entity; nobody else drives any.
public sealed class HostRelayAuthority : IMotorRelayAuthority
{
    private readonly IHostElection _election; // the game's own, already needed for its AI
    public bool MayRelay(ISession session, long entityId) => _election.IsHost(session.ConnectionId);
}
// services.AddSingleton<IMotorRelayAuthority, HostRelayAuthority>();

• bool MayRelay(ISession session, long entityId)

  Returns true to let session report the authoritative pose of entityId — a server-spawned entity it does not own. Called on every relayed report (a hot path: keep it a lookup, not a scan), AFTER the Motor has confirmed the entity exists and is server-spawned, and BEFORE the built-in rate / gross-delta / IAvatarMoveValidator checks, which then apply to the relayed entity exactly as they do to an avatar. Returning false drops the report silently — the entity simply keeps its last authoritative pose, which is also what happens while a host election is in flight.

The ENTIRE per-game surface for server-authoritative motion: a pure, deterministic step the framework runs on BOTH tiers (server = authority, client = prediction). This IS the game's controller — gravity, jump, air-control, ground-snap, speed — expressed as portable math (no Physics.*, no Time.*, no engine calls), so the server can run it identically and prediction agrees. Contract:Step MUST be a pure function of its arguments — same state + input + dt + geometry ⇒ same result on both tiers. Any hidden state or non-determinism shows up as reconciliation correction. Gravity/jump constants live HERE, in the game — never in the framework (the Prime Directive). Portable only: a Unity-PhysX controller can't be re-run on the server; keep those on client-authoritative Motor. This serves a controller you can express as deterministic math.

• MotorSimState Step(in MotorSimState state, in MotorInput input, float dt, IMotorGeometry geometry)

  Advances state by input over dt seconds, resolving against geometry (ground + walls), and returns the new state.

OBSERVER-side game seam — the entire per-game surface for rendering a remote avatar. Each frame the Motor samples every tracked remote entity's interpolated pose off the server timeline and calls Apply with that pose and the latest opaque blob. The game resolves the entity id to its own avatar (e.g. via IWorldEntities/ICharacterFactory), writes the transform, and reads the blob to drive its animator/VFX/state — all presentation, 100% the game's. The framework never interprets the blob; it only moved the bytes. Optional ([InjectOptional]): a headless / diagnostics-only client binds no applier and the Motor still receives and buffers the streams, rendering nothing. Bind one on any client that shows remote avatars.

• void Apply(long entityId, in MotorPose pose, ReadOnlySpan<byte> blob, uint serverTimeMs)

  Renders entityId at an authoritative interpolated pose for this frame.

OWNER-side game seam — the entire per-game surface for reporting the local avatar. The Motor calls Sample once per send tick; the game returns its avatar's current world-space pose and packs whatever game state observers need (animation-state index, flags, jump/dash counters, a car's gear/rpm…) into the supplied blob span. The framework never reads those bytes — it relays them verbatim. Because the game supplies the pose, its OWN controller stays the single source of truth for local motion (Route B / 1:1 feel); the Motor never simulates or overrides it. Optional ([InjectOptional]): a spectator or observer-only client binds no source and simply never sends. Bind one on any client that owns a controllable avatar.

• void Sample(out MotorPose pose, Span<byte> blob, out int blobLength)

  Produces the current owner pose and writes the opaque game-state into blob.

Public facade / diagnostics seam for the Motor client loop. A game rarely needs this — the whole contract is the two SPIs (IAvatarStateSource / IAvatarStateApplier), plus the optional IRelayedAvatarStateSource on a simulation host — but it exposes lightweight counters an overlay or test can read.

• int RemoteEntityCount

  Number of remote entities currently being interpolated.

• bool IsReportingOwner

  True once the owner has sent at least one report this session (a local avatar is live).

• int RelayedEntityCount

  Number of server-spawned entities this client relayed on the last send tick (0 unless the game bound an IRelayedAvatarStateSource and this client is the elected simulation host) — the cheapest way for an overlay or a test to see whether relaying is actually live.

What the Motor client can tell you about remote playback quality, so "is the jitter fixed?" is a number rather than an impression. This exists because the absence of it cost real time: a game whose numeric harness had been lost saw three unrelated defects — proxy collision, snapshot arrival-time stamping, and an undersized jitter buffer — all present identically as "the jitter is back", which made genuine progress look circular. The framework owns the measurement now, so every game gets the separation for free. Every aggregate below describes the entities that actually STREAM — the ones that have received at least one Motor packet. The Motor opens a buffer for every non-self entity in the world, which in a game using authored level content is mostly props that will never send anything; averaging those in reports a delay no packet produced and a remote count two orders of magnitude off the number of players. See TrackedEntityCount for the other figure. Read-only and optional: implemented by the Motor client, consumed by the diagnostics overlay through [InjectOptional], so nothing depends on it being present.

• int RemoteEntityCount

  Remote entities that are actually streaming — buffered AND having received at least one snapshot. This is the number to compare against "how many other players are here".

• int TrackedEntityCount

  Remote entities the Motor holds a buffer for, streaming or not. Always at least RemoteEntityCount; the difference is the world's non-Motor entities (authored props, scenery), and a large one is normal, not a leak.

• MotorInterpolationMode InterpolationMode

  Whether the delay is measured per source or authored (see MotorInterpolationMode).

• float WorstDelaySeconds

  The largest interpolation delay any remote is currently rendered at, in seconds — the worst link in the session, which is the one a player complains about.

• float MeanDelaySeconds

  Mean interpolation delay across remotes, in seconds.

• float WorstJitterMs

  Largest smoothed arrival jitter across remotes, in milliseconds — WHY the worst delay is what it is.

• float WorstGapMs

  Largest recent arrival gap across remotes, in milliseconds. A gap far above one send interval is consecutive packet loss, which is invisible in the jitter figure alone.

• float WorstTransitMs

  Largest measured path-transit baseline across remotes, in milliseconds — how LATE snapshots arrive after their owner sampled them (the whole owner→server→here path), as opposed to how UNEVENLY (WorstJitterMs). This is the term that sets the SCALE of an adaptive delay; without it on display, a small WorstDelaySeconds is ambiguous between "correctly sized" and "ignoring latency" — precisely the confusion GAP-15 documents. Zero until the server timeline is in use (lateness needs a shared clock to measure).

• bool TryGetRemote(long entityId, out float delaySeconds, out float jitterMs, out float worstGapMs, out int bufferedSnapshots)

  Per-entity readout, or false when that entity is not a buffered remote (it may be ours, host-driven by us, or gone). Unlike the aggregates this answers for a TRACKED entity, streaming or not — asked about a specific id the honest answer is its state, and a never-streamed one reports zero buffered snapshots, which is the tell.

• bool TryGetRemoteTransit(long entityId, out float transitMs)

  Per-entity path-transit baseline (see WorstTransitMs), or false when that entity is not a tracked remote. Additive rather than a fifth out-param on TryGetRemote, so no existing game readout has to change to keep compiling.

OWNER-side game seam for ServerAuth mode — the game's INPUT (not a pose). The framework calls this each send tick to build a MotorInput; the server integrates it (authority) and the client predicts with the same input. The counterpart of client-auth mode's IAvatarStateSource (which reports a finished pose). Bind on any client that owns a server-auth avatar.

• void Sample(out Vec3 move, out uint buttons, out Quat aim)

  Produces this tick's desired input: move direction, buttons (jump/dash/…), and aim.

The game's hook for "you are now here" — PHYS-10's client half. What a placement IS. Not a correction. A reconcile says "you were slightly wrong": the predictor snaps and REPLAYS the inputs still in flight, because those inputs really happened. A placement says "you are somewhere else now" — respawned, teleported into an instance, or thrown across the room by a falling wall — and replaying a run that happened somewhere else is the classic bug where a respawned player slides back across the map. The pending tail is discarded, not replayed. In ServerAuth this is a NOTIFICATION. The predictor has already been reset before this is called, so the avatar is where the server says. Implement it to cut the camera, flash the screen, stop a footstep loop, or nothing at all. In ClientAuth this is an INSTRUCTION, and the only one there is. The client owns the pose in that mode, so nothing else will move the avatar: a game that does not implement this cannot be respawned or thrown. That is the honest division — a bespoke controller is the game's, and the framework will not reach into it. Optional: resolved through [InjectOptional], and absent nothing is called.

• void OnPlaced(Vector3 position, Quaternion rotation, Vector3 velocity, byte reason)

  The server has placed this client's avatar.

HOST-side game seam — report poses for entities this client does not own. Route B exists because the game has a bespoke controller the server cannot reproduce, and that applies just as much to its enemies, NPCs and host-driven props: they are spawned server-side, have no owning session, and nobody but a client can say where they are. So the game elects ONE client as the simulation host, runs their controllers there, and the Motor relays their poses on exactly the path it already uses for the local avatar — no game message, no game-allocated wire id, no per-entity interpolation bookkeeping. This is a second, optional source alongside IAvatarStateSource (which stays unchanged and keeps reporting the local avatar): bind both on the host, only IAvatarStateSource on everyone else, or neither on a spectator. Sampling happens on the same send tick and under the same MotorOptions.SendRateHz and MaxStateBytes budgets — relaying introduces no new rate of its own. The server must agree. A relayed report is accepted only if the game also registered an IMotorRelayAuthority server-side that approves this session for that entity, and the entity is genuinely server-spawned. Report an id you are not authorised for and the report is simply dropped — which is also the harmless steady state while a host election is changing hands. Host echo is suppressed. The host is itself an observer of what it relays, so the server fans the resulting EntityMotorState back to it. The Motor DROPS those echoes for every id this source is currently relaying, so the host renders its own live simulation while every other client renders the interpolated relay. That is the same asymmetry a game already has between its local player (real controller) and remote proxies (interpolated), so no new one is introduced — and the moment an id leaves RelayedEntityIds (host migration, the entity stops being host-driven) the echoes are accepted again and it becomes an ordinary interpolated remote.

• IReadOnlyList<long> RelayedEntityIds

  The entities this client is currently driving, or an empty list / null when it is driving none (the normal state on every non-host). Read once per send tick and indexed, never retained, so returning a reused list is both allowed and preferred. Ids of 0 and the local avatar's own id are ignored — the local avatar belongs to IAvatarStateSource.

• bool TrySample(long entityId, out MotorPose pose, Span<byte> blob, out int blobLength)

  Produces the current pose + opaque game state of entityId, exactly as Sample does for the local avatar. Return false to skip this entity for this tick — the honest answer when it just died, despawned, or has not been created locally yet — and nothing is sent for it.