🚀 Game Sync - State Replication & Synchronization

[jordyfontoura]

Description

We need to implement the core game synchronization system for Multibonk.
The goal is to keep all players’ game states in sync while maintaining a smooth and responsive experience, even under network latency.

This system should be based on:

• State Replication: the host periodically sends authoritative snapshots of the game state.
• Client-Side Prediction: clients immediately apply their own inputs locally to reduce perceived latency.
• Rollback & Reconciliation: when a snapshot arrives, clients correct any divergence from the authoritative state.

This will allow the game to run smoothly in a P2P environment, even with variable latency.

Scope

• Create a GameSyncManager (or similar) module to handle:
  • Local state updates and input queueing.
  • Periodic state snapshots from host to peers.
  • Rollback & reconciliation when the authoritative state differs.
• Integrate with the existing NetworkManager messaging system:
  • Messages for input events.
  • Messages for state snapshots.
• Tick-based simulation:
  • Define a fixed tick rate for simulation (e.g., 60 FPS or 30 TPS).
  • Each input and snapshot should be associated with a tick number.
• Implement prediction logic:
  • Clients apply inputs immediately.
  • Correct state when receiving authoritative updates (rewind & replay queued inputs).
• Logging and debugging tools for sync issues (tick mismatch, large corrections).

---

Acceptance Criteria (Updated)

Phase 1 (Advanced Player Sync)

• Player movement appears smooth with interpolation
• Local player has no input lag (prediction implemented)
• Network updates are bandwidth-optimized
• Position updates < 10 bytes per player

Phase 2 (Game Entity Sync)

• All enemies visible to all players
• Boss fights synchronized (health, phases, attacks)
• Items can be picked up (first player gets it)
• Chests and shrines work in multiplayer

Phase 3 (Combat & Progression)

• Damage dealt by any player is visible to all
• Player deaths are synchronized
• Level progression syncs correctly
• No duplicate experience/rewards

Phase 4 (Advanced Features)

• Desync detection alerts players
• Debug overlay shows network stats
• Tick-based simulation implemented
• Unit tests for rollback/prediction

---

Definition of Done

• All Phase 1-3 features implemented and tested
• Documentation updated with sync architecture
• Performance benchmarks meet targets:
  • < 100ms perceived latency
  • < 50 KB/s bandwidth per player
  • Stable 60 FPS with 4+ players
• No critical desyncs in normal gameplay

---

Additional Notes

• Start with a simple state (player position, velocity) before expanding to complex game entities.
• Consider exposing debug tools (e.g., /sync-stats UI overlay showing latency & corrections).