suaveplan/packages/threejs/r3f/r3f-networking/README.md

@suaveplan/r3f-networking - R3F-tier multiplayer state synchronisation: interpolation, client-side prediction, snapshot diffing, server reconciliation FSM, React hooks + React-Three-Fiber components. Transport-agnostic — composes any @suaveplan/network Transport.

Summary

R3F-tier multiplayer state-synchronisation for React-Three-Fiber scenes. Composes any @suaveplan/network Transport (canonical: @suaveplan/network-transport-webrtc), @suaveplan/diff for snapshot deltas, @suaveplan/fsm for the reconciliation state machine, and @suaveplan/serialize for the wire codec.

Documentation tree

• server-authority — (no submodules)
  • server-authority — (no submodules)
• network-provider — (no submodules)
  • network-provider-context — Module-scope React.Context exported as a separate file so consumers can import the context object directly (`useConte…
  • network-provider — (no submodules)
• network-stats — (no submodules)
  • network-stats — (no submodules)
• networked-entity — (no submodules)
  • apply-networked-frame — Pure per-frame helper that writes a target EntityTransform into a Three.js group-shaped target. Local entities snap d…
  • networked-entity — (no submodules)
• interpolation — (no submodules)
  • interpolation — (no submodules)
• prediction — (no submodules)
  • prediction — (no submodules)
• reconciliation-fsm — (no submodules)
  • reconciliation-fsm — (no submodules)
• snapshot-diff — (no submodules)
  • snapshot-diff — (no submodules)
• state-buffer — (no submodules)
  • state-buffer — (no submodules)
• wire-codec — (no submodules)
  • wire-codec — (no submodules)
• errors — (no submodules)
  • errors — (no submodules)
• use-network-predict — (no submodules)
  • use-network-predict — (no submodules)
• use-network-sync — (no submodules)
  • use-network-sync — (no submodules)
• use-networked-entity — (no submodules)
  • use-networked-entity — (no submodules)
• observability — (no submodules)
  • observability — (no submodules)
• entity-sync — (no submodules)
  • entity-sync — (no submodules)
• interest-manager — (no submodules)
  • interest-manager — (no submodules)
• memory-transport — (no submodules)
  • memory-transport — (no submodules)
• network-helpers — (no submodules)
  • network-helpers — (no submodules)

- [server-authority](./src/authority/server-authority/server-authority.md) — _(no submodules)_- [network-provider](./src/components/network-provider/network-provider.md) — _(no submodules)_- [network-provider-context](./src/components/network-provider/network-provider-context.md) — Module-scope `React.Context` exported as a separate file so consumers can import the context object directly (`useConte…

• network-provider — (no submodules)- network-stats — (no submodules)- network-stats — (no submodules)- networked-entity — (no submodules)- apply-networked-frame — Pure per-frame helper that writes a target EntityTransform into a Three.js group-shaped target. Local entities snap d…
• networked-entity — (no submodules)- interpolation — (no submodules)- interpolation — (no submodules)- prediction — (no submodules)- prediction — (no submodules)- reconciliation-fsm — (no submodules)- reconciliation-fsm — (no submodules)- snapshot-diff — (no submodules)- snapshot-diff — (no submodules)- state-buffer — (no submodules)- state-buffer — (no submodules)- wire-codec — (no submodules)- wire-codec — (no submodules)- errors — (no submodules)- errors — (no submodules)- use-network-predict — (no submodules)- use-network-predict — (no submodules)- use-network-sync — (no submodules)- use-network-sync — (no submodules)- use-networked-entity — (no submodules)- use-networked-entity — (no submodules)- observability — (no submodules)- observability — (no submodules)- entity-sync — (no submodules)- entity-sync — (no submodules)- interest-manager — (no submodules)- interest-manager — (no submodules)- memory-transport — (no submodules)- memory-transport — (no submodules)- network-helpers — (no submodules)- network-helpers — (no submodules)- server-authority — (no submodules)- network-provider — (no submodules)- network-provider-context — Module-scope React.Context exported as a separate file so consumers can import the context object directly (`useConte…
• network-provider — (no submodules)- network-stats — (no submodules)- network-stats — (no submodules)- networked-entity — (no submodules)- apply-networked-frame — Pure per-frame helper that writes a target EntityTransform into a Three.js group-shaped target. Local entities snap d…
• networked-entity — (no submodules)- interpolation — (no submodules)- interpolation — (no submodules)- prediction — (no submodules)- prediction — (no submodules)- reconciliation-fsm — (no submodules)- reconciliation-fsm — (no submodules)- snapshot-diff — (no submodules)- snapshot-diff — (no submodules)- state-buffer — (no submodules)- state-buffer — (no submodules)- wire-codec — (no submodules)- wire-codec — (no submodules)- errors — (no submodules)- errors — (no submodules)- use-network-predict — (no submodules)- use-network-predict — (no submodules)- use-network-sync — (no submodules)- use-network-sync — (no submodules)- use-networked-entity — (no submodules)- use-networked-entity — (no submodules)- observability — (no submodules)- observability — (no submodules)- entity-sync — (no submodules)- entity-sync — (no submodules)- interest-manager — (no submodules)- interest-manager — (no submodules)- memory-transport — (no submodules)- memory-transport — (no submodules)- network-helpers — (no submodules)- network-helpers — (no submodules)- server-authority — (no submodules)- network-provider — (no submodules)- network-provider-context — Module-scope React.Context exported as a separate file so consumers can import the context object directly (`useConte…
• network-provider — (no submodules)- network-stats — (no submodules)- network-stats — (no submodules)- networked-entity — (no submodules)- apply-networked-frame — Pure per-frame helper that writes a target EntityTransform into a Three.js group-shaped target. Local entities snap d…
• networked-entity — (no submodules)- interpolation — (no submodules)- interpolation — (no submodules)- prediction — (no submodules)- prediction — (no submodules)- reconciliation-fsm — (no submodules)- reconciliation-fsm — (no submodules)- snapshot-diff — (no submodules)- snapshot-diff — (no submodules)- state-buffer — (no submodules)- state-buffer — (no submodules)- wire-codec — (no submodules)- wire-codec — (no submodules)- errors — (no submodules)- errors — (no submodules)- use-network-predict — (no submodules)- use-network-predict — (no submodules)- use-network-sync — (no submodules)- use-network-sync — (no submodules)- use-networked-entity — (no submodules)- use-networked-entity — (no submodules)- observability — (no submodules)- observability — (no submodules)- entity-sync — (no submodules)- entity-sync — (no submodules)- interest-manager — (no submodules)- interest-manager — (no submodules)- memory-transport — (no submodules)- memory-transport — (no submodules)- network-helpers — (no submodules)- network-helpers — (no submodules)- server-authority — (no submodules)- network-provider — (no submodules) - network-provider-context — Module-scope React.Context exported as a separate file so consumers can import the context object directly (`useConte…
• network-provider — (no submodules)- network-stats — (no submodules) - network-stats — (no submodules)- networked-entity — (no submodules) - apply-networked-frame — Pure per-frame helper that writes a target EntityTransform into a Three.js group-shaped target. Local entities snap d…
• networked-entity — (no submodules)- interpolation — (no submodules) - interpolation — (no submodules)- prediction — (no submodules) - prediction — (no submodules)- reconciliation-fsm — (no submodules) - reconciliation-fsm — (no submodules)- snapshot-diff — (no submodules) - snapshot-diff — (no submodules)- state-buffer — (no submodules) - state-buffer — (no submodules)- wire-codec — (no submodules) - wire-codec — (no submodules)- errors — (no submodules) - errors — (no submodules)- use-network-predict — (no submodules) - use-network-predict — (no submodules)- use-network-sync — (no submodules) - use-network-sync — (no submodules)- use-networked-entity — (no submodules) - use-networked-entity — (no submodules)- observability — (no submodules) - observability — (no submodules)- entity-sync — (no submodules) - entity-sync — (no submodules)- interest-manager — (no submodules) - interest-manager — (no submodules)- memory-transport — (no submodules) - memory-transport — (no submodules)- network-helpers — (no submodules) - network-helpers — (no submodules)

What this package owns

• Interpolation — frame-loop smoothing of remote-peer transforms (core/interpolation).
• Client-side prediction — local input applied immediately, reconciled against authoritative snapshots (core/prediction).
• Reconciliation FSM — synchronized → diverged → resyncing state machine driven by divergence magnitude (core/reconciliation-fsm).
• Snapshot diffing — RFC-6902 JSON Patch between authoritative snapshots via @suaveplan/diff (core/snapshot-diff).
• Wire codec — Zod-validated frame encode/decode via @suaveplan/serialize (core/wire-codec).
• Entity sync + interest management (sync/entity-sync, sync/interest-manager).
• Server authority with anti-cheat hooks (authority/server-authority).
• In-memory transport — deterministic real Transport implementation for integration tests (transport/memory-transport).
• React hooks — useNetworkSync, useNetworkedEntity, useNetworkPredict.
• R3F components — <NetworkProvider>, <NetworkedEntity>, <NetworkStats>.

Observability

OTel meter @suaveplan/r3f-networking. Histograms r3f_net.snapshot_dispatch_ms and r3f_net.prediction_divergence; counters r3f_net.snapshots_total{outcome} and r3f_net.peer_events_total{event}.

Error registry

defineCodes("R3F_NET", […]) — 8 codes: SNAPSHOT_OUT_OF_ORDER, PEER_DROPPED, PREDICTION_DIVERGED, INVALID_OPTIONS, INVALID_SNAPSHOT, DISPOSED, TRANSPORT_FAILED, ABORTED.

License

MIT