Add Ion Network Plugin design documentation (v1 & v2)

[jimbuck]

Summary

This PR adds comprehensive design documentation for the Ion Network Plugin, covering both the v1 foundation and v2 advanced features (client-side prediction, lag compensation, entity interpolation). The documentation establishes the architecture, abstractions, and integration patterns for networked gameplay in Ion.

Changes

• ion-network-plugin.md: Core design document covering three architectural options (Replicated World, Network Events, Hybrid) with detailed comparison. Recommends Option 3 (Hybrid) combining automatic component replication with explicit network events. Includes decisions on serialization (raw blitting), network identity (automatic assignment), authority model (server-authoritative with opt-in owner authority), and v1 scope.

• ion-network-prediction-lagcomp.md: Detailed v2 feature specification building on v1 foundation, covering:

  • Client-side prediction: Local input application with PredictionInputBuffer and [Predicted] attribute
  • Server reconciliation: Rollback and resimulation when predictions diverge from authoritative server state
  • Entity interpolation: Smooth rendering of remote entities between server snapshots using InterpolationBuffer
  • Server-side lag compensation: Rewind queries via GetComponentAtTick() and WithWorldAtTick() for fair hit detection
  • Complete middleware pipeline integration showing where each system runs in the frame lifecycle
  • Snapshot ring buffer as the shared foundation enabling all four features

Key Design Decisions

• Hybrid approach: Automatic [Networked] component replication for continuous state + explicit INetworkEventBus for discrete events (RPCs, commands, chat)
• Snapshot architecture: Ring buffer of past world states captured every tick, enabling rollback, prediction validation, and lag compensation without runtime overhead
• Unmanaged components: Leverages Ion's record struct constraint for zero-allocation serialization via MemoryMarshal.AsBytes()
• Transport abstraction: INetworkTransport interface with LiteNetLib as v1 implementation, Steam Networking as future option
• Authority model: Server-authoritative by default with per-component opt-in owner authority for client-predicted state
• Middleware integration: NetworkSystem registers into Ion's pipeline at [Init], [First], [FixedUpdate], and [Last] stages

Notable Details

• Prediction and lag compensation are fully architected in v1 (snapshot capture, tick counter, event bus) but feature implementations deferred to v2
• Visual smoothing strategy for reconciliation corrections (separate simulation vs render position with lerping)
• Extrapolation fallback for interpolation when server snapshots are late
• Anti-cheat safeguards for lag compensation (max rewind window, attacker advantage tradeoff)
• Memory cost example: 128 ticks × 1000 entities × 64 bytes ≈ 8 MB (configurable)

https://claude.ai/code/session_016AjVXfrXScZ9H4PuZ5WXAt

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch claude/ion-network-plugin-design-0f2Bb

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}