Ryuu/AetherOnline
Watch
1
0
Fork
You've already forked AetherOnline
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Page: client realtime authority store and frame projection
Pages
Authoring Debugging Home Operations Protocol Reference Runtime Systems abilities loadouts and progression ability rotation and combo planner active realtime session actor directory admin actions and internal auth animation workbench operator guide aoi snapshot replication app mode bootstrap and lifecycle architecture guardrails and module tree tests asset loading routing and vfs authored ui surface renderer authoring command bus and transaction history authoring reference registry contributor extension contract authoring reference registry authoritative audit event schema and projections authoritative world time calendar and environmental scheduler bake product registry build strategy and loadout optimizer campaign journey and progression simulator catalog source map and record routing character gameplay state json store character paperdoll assets character stats and equipment modifiers chat presence and social client local offline save and bootstrap cache client local user preferences and account sync client multiplayer connection flow and session cleanup client realtime authority store and frame projection client scene presentation and player preview client snapshot staging and repair receipts client ui focus and text input planning combat action resolution and mob ai semantics combat presentation cues and transient effects combat rewards and progression persistence content dependency graph and scenario playtests content migration and catalog refactors control agent api and remote service runner control panel config and secret persistence control panel service build invalidation and log normalization control panel service lifecycle and quality gates control plane allocation and zone transfer routing control plane and service ops control plane route policy and coordination api control service supervisor manifest and stale process recovery crafting recipes and service integration dependency aware content health deterministic combat balance lab developer workspace doctor and readiness report diagnostics provider input lanes and failure isolation dialogue quest localization handoff dialogue runtime state and choice authority duplicate realtime claim takeover durable retry and session cleanup durable work queue consumer contract dynamic world state and scene phasing editor authored content workspace manifest and cache editor event console and asset debug dashboards editor extension and contribution registries editor scene snapshot lane demand editor settings registry and workspace presets editor viewport and world tools editor workbench and dock encounter difficulty mutators and reward scaling encounter instance and wave director encounter lobby ready check and entry encounter mechanics and boss timelines encounter memory persistence encounter reward eligibility lockouts and pity enemy archetypes combat kits and encounters engine report log and recovery routing environment configuration reference external engine patterns and boundaries farming footstep surface audio materials forgejo wiki publishing and docs check game data catalog game data generated item family adapters game database schema readiness game server catalog load health and fallback policy game server reconciliation and transfer marker cleanup game server startup readiness and registration game transport endpoints and quic exposure gameplay action authority and command audit gameplay action replay ledger and idempotency gameplay authority replay fixtures and drift gates gameplay conditions effects and events gameplay system slice scaffold gameplay ui runtime and bevy sync generated artifact drift and repair generated artifact registry and quality gate integration glossary hotbar hud runtime projection and input in process zone transfer phase journal input profiles and keybinds interactive world map minimap and cartography internal auth and admin delegation chain inventory items and stack limit safety item authoring lifecycle and reference repairs json catalog hot reload batch and candidate revalidation legacy compatibility and migration register local player input control and reconciliation local playtest and standalone preview localization extraction and runtime catalog login account admin repository and cascades login database migrations and schema contracts login server auth sessions and character entry login session cache throttle and revocation loot table authoring and drop audits mob animation presentation events and projectile cues mob encounters and scene combat movement authority networking tick health and zone pressure npc ai schedules and deterministic behavior npc definition catalog npc schedules routines and contextual behavior npc services npc state memory and interactions pack export content gate party composition roles and synergy simulator passive traits and procs persistent interactive world objects placed light runtime budget and preview heatmap player appearance equipment persistence player economy authority player homesteads housing and property auctions player journal and codex player navigation tracking and world guidance player notification inbox authority and delivery player preview animation profile player preview debug gizmos and collision overlays player preview render cache and keyed entity lifecycle player preview weather masks and effect budget player snapshot assembly and durable row normalization post process volume blending and preview overlays project files import profiles and asset change impact public endpoint detection and upnp exposure quality gate jsonl events and panel failure summaries quest runtime projection and turn in authority quic reliable stream topology and negotiation realtime admission throttling and load shedding realtime bootstrap manifest and snapshot service realtime bootstrap wire sections and compression realtime client reconnect journal and command replay realtime datagram codecs and ingress policy realtime egress mailboxes and lane scheduling realtime ingress validation and failure policy realtime packet debug capture and triage realtime protocol registry realtime registry and wire contract realtime resume ledger record format realtime rollout policy and compatibility negotiation realtime runtime profile and transport adaptation realtime session activation hydration boundary realtime timebases tick ordering and clock ownership redis keyspace ttls and cleanup targets regions points of interest and exploration discovery relationship reputation gates and service deltas remote avatar replica binding and interpolation render surface guard and window safety runtime actor identity and authority contract runtime camera arrival and cutscene overrides runtime debug overlays and developer options runtime environment registry and startup config validation runtime path roots and packaged asset resolution runtime profiling tracy captures and budget gates runtime scene manifests and zone authoring runtime ui fonts and localized text presentation scenario sandbox and timeline inspector scene audio runtime routing scene command center and visual graph tools scene cutscene authoring scene documents scene layer schema depth and bands scene lighting post process and placed lights scene navigation and collision scene preview scenario replay cli scene runtime media weather and camera phases scene runtime schedule and frame budget scene trigger authority and reconciliation scene triggers scene validation and repairs service json rpc contracts service observability and metrics contract service registry heartbeats drain and shutdown session handoff and transfer shared content workspace shared test fixtures and fixture workspaces shared validation report schema source inventory and engine health standalone account realm and character flow standalone asset pack and preflight standalone loading pause death and recovery screens standalone shell flow and ui lifecycle standalone ui preview root and transient lifecycle starter character economy bootstrap status effects and combat modifiers story content loop text asset migration journals and atomic rollback tiled prefab import and placement tilemap asset import contracts tileset atlas preview surfaces trigger permissions targeting and action pipelines typed disconnect codes and transport advisories ui layout binding graph and editor workflow ui layout ui skins validation and bake validation errors validation provider registry and strict preflight vendor stock and shop economy authoring viewport spatial planning overlays vscode dev tasks and generated launch profiles workspace package roles and scoped quality profiles world entry smoke harness and soak telemetry world events and scenario director world gameplay assemblies world interactions and activity boards world mechanism and puzzle graphs world overlay gizmos and culling world travel waypoints and zone transitions xtask content gates and plans
1 client realtime authority store and frame projection
forgejo-actions edited this page 2026-07-15 12:43:13 +00:00
Table of contents

Client Realtime Authority Store And Frame Projection

The client realtime state separates server-owned facts, local prediction, transport state, transient ingress events, and frame-safe read models. This keeps low-latency presentation possible without letting an optimistic UI value become authoritative gameplay state.

Ownership And Data Flow

RealtimeSessionState is the transport-thread shared state behind RealtimeSessionHandle. Its major ownership groups are:

  • transport: endpoint, session token, health, reconnect/transfer state, runtime profile, packet status, and telemetry;
  • world: authoritative local player baseline, AOI players and buckets, replica directory, snapshot staging, clock sync, environment, and cutscene sync;
  • authority: typed gameplay snapshots, authoritative event journal, and AuthoritySnapshotStore indexes and diagnostics;
  • prediction: movement reconciliation, pending gameplay predictions, last-sent state, and optimistic UI overlays;
  • ui_events: bounded or drain-once ingress such as chat, action results, combat events, rewards, and overlays;
  • outbound: client command queues and wakeup state.

Network reducers own writes to server-derived state. Gameplay and presentation systems consume projections or drain explicitly owned event queues. They must not manufacture authority by writing projected values back into authority.

Authoritative Snapshots And Store

RealtimeGameplayAuthoritySnapshots retains the typed snapshots used by consumers: stats, combat, inventory, currencies, equipment, quest, gameplay conditions, and farming tiles. Its AuthoritySnapshotStore adds indexed access and provenance:

  • per-domain revision and last applied event metadata;
  • stale-domain tracking;
  • inventory by item id, currency by id, equipment by slot, and quest by quest id;
  • gameplay-action results and denials by request id;
  • a projected index of pending predictions by request id.

Each authoritative packet is reduced through its packet-specific reducer. The reducer updates the typed snapshot, records an authoritative event and packet label, and applies the matching store domain. Snapshot-owned revisions, such as equipment or quest revision, are compared with the client event revision by taking the larger value.

The authoritative event revision is client-local ordering metadata, not a replacement for domain revisions. The journal is capped at 128 envelopes.

Optimistic Overlays

RealtimeOptimisticUiOverlay contains optional gameplay, appearance, inventory, stats, equipment, and equipped-tool values. Projection merges use the optimistic value first only for domains that define an overlay. The underlying authoritative snapshot and store remain unchanged.

For example, predicted loadout application can immediately project inventory, stats, equipment, and equipped tool while authority.inventory, authority.player_stats, authority.equipment, and their store revisions remain untouched. When matching authoritative snapshots arrive, reducers clear the relevant overlay before publishing the authoritative value.

Equipment projection deliberately exposes all three views:

  • equipment: merged value for normal presentation;
  • authoritative_equipment: latest server value;
  • optimistic_equipment: pending UI value, if any.

Gameplay-action results remove the pending prediction and reconcile request-specific overlay state. A result also records the gameplay-action domain and marks Prediction stale; downstream reconciliation and later snapshots establish the fresh view.

Frame Projection Data Flow

The per-frame path is:

stream/datagram ingress
  -> packet reducer or AOI staging window
  -> RealtimeSessionState authority/world/prediction
  -> flush at most one staged AOI snapshot for this render frame
  -> RealtimeFrameProjection
  -> scene authority, dialogue, gameplay UI, and other Bevy consumers

tick_multiplayer_ui_state polls the async job and transport, then flushes buffered AOI snapshots. publish_realtime_frame_projection_system runs afterward and replaces the Bevy resource only when its value changed.

RealtimeFrameProjection contains optional transport, world, and gameplay projections plus copied chat events. With no realtime handle it is empty. World projection merges optimistic local gameplay/appearance over the authoritative local player but leaves visible remote players authoritative. Gameplay projection merges only the supported optimistic domains and clones an AuthoritySnapshotStore augmented with the current pending-prediction journal.

The projection is a frame snapshot, not a mutation API. Destructive queues such as gameplay action results and combat rewards keep explicit owners and are not generalized into the copied frame resource.

Lifecycle And State Transitions

Session activation

Activation installs the session token, runtime profile, local authoritative player, environment, and transport state. A fresh activation clears prediction and AOI phase state. Resume activation retains only unacknowledged movement and gameplay predictions, advances the event revision to at least the resume revision, and still clears the old AOI baseline.

Normal authoritative update

The packet reducer updates a typed snapshot, records event provenance, refreshes the store domain, and clears a matching overlay where defined. The next frame projection exposes the merged result.

Transfer preparation

Transfer changes endpoint and token, marks transport Transferring, clears AOI/replica and snapshot-staging state, resets the last snapshot id, and clears pending trigger resolutions. Destination activation establishes the new local baseline.

Server disconnect

Disconnect clears prediction and replicated AOI phase state. Player combat and gameplay-condition snapshots are removed and their store domains marked stale. Other typed snapshots are not individually erased by this transition, so consumers must gate authority use on live transport/frame state. Full connection cleanup later drops the realtime handle.

Extending An Authoritative Domain

When adding a new server-owned client domain:

  1. Add the typed snapshot to the appropriate world/protocol contract and realtime authority aggregate.
  2. Add descriptor/dispatch metadata so the packet has a stable authoritative event kind and packet label.
  3. Implement one reducer that updates the typed value and records store provenance.
  4. Add an AuthoritySnapshotDomain and store index only when consumers need lookup, revision, stale, or incident diagnostics.
  5. Define whether prediction is allowed. If it is, add an overlay and explicit reconciliation/clear behavior; do not reuse the authoritative field for prediction.
  6. Add the projected value to RealtimeGameplayProjection or RealtimeWorldProjection and consume it from RealtimeFrameProjection in frame systems.
  7. Test authoritative application, optimistic non-mutation, reconciliation, disconnect/transfer behavior, and frame projection.

Rules And Invariants

  • Server packet reducers are the write boundary for authoritative client state.
  • An optimistic overlay may change presentation but must not advance an authority-domain revision or populate an authoritative index.
  • Authoritative arrival wins by clearing its matching overlay.
  • Frame consumers must check transport health before treating projected data as live authority.
  • AOI snapshots are monotonic by snapshot id and are limited to one staged application per render frame.
  • Pending predictions appear in the projected store without being inserted into the underlying authoritative store.
  • Event queues with one destructive consumer must be drained once and fanned out with Bevy messages when multiple readers need them.
  • Transfer and disconnect must clear old AOI replicas before a new world baseline is presented.

Validation And Debugging

Focused regression tests include:

cargo test -p aether realtime_session_state_builds_typed_world_and_gameplay_projections
cargo test -p aether predicted_loadout_projects_optimistic_view_without_authority_mutation
cargo test -p aether authority_snapshot_store_indexes_quests_and_pending_actions_by_request
cargo test -p aether gameplay_projection_projects_pending_predictions_from_journal
cargo test -p aether server_disconnect_transition_resets_prediction_authority_and_interest_phase_state

For a stale or wrong value, compare these layers in order:

  1. transport.last_server_packet and transport.last_message: did the expected reducer run?
  2. The typed field under authority: did decode and assignment succeed?
  3. domain_revision, last_applied_event, and stale_domains: did store provenance move?
  4. optimistic_ui: is a prediction intentionally masking the server value?
  5. RealtimeFrameProjection: was a changed projection published after polling and staged snapshot flush?
  6. The final consumer: is it using the frame projection or an unrelated local fallback?

A useful equipment diagnostic is to print merged, authoritative, and optimistic revisions together. If the merged value is wrong while the authoritative value is correct, inspect overlay clearing. If all are stale, inspect packet dispatch and reducer application. If session state is correct but the UI is stale, inspect frame resource change detection and the consumer's rebuild signature.

The client logs rejected gameplay actions with request id, request kind, predicted action, and server message. Expected range/contact denials are debug-level; other denials are warnings and are indexed in the authority store.

Related Pages