Feat/407 multiplayer puzzle sessions

[mijinummi]

[FEAT] Multiplayer Puzzle Solving Sessions

Summary

Implements real-time multiplayer puzzle-solving sessions for the quest service, allowing multiple players to collaborate on the same puzzle with synchronized state, player presence tracking, session persistence, timeout handling, and partial solution tracking.

The implementation introduces a WebSocket-driven session architecture designed to keep puzzle state consistent across connected players while gracefully handling joins, leaves, disconnects, and session expiration.

What Changed

🎮 Multiplayer Session Architecture

Introduced a dedicated multiplayer session lifecycle for collaborative puzzle solving:

Create Session
      ↓
Join Players
      ↓
WebSocket Connections
      ↓
Shared Puzzle State
      ↓
Collaborative Updates
      ↓
Persist Session State
      ↓
Complete / Timeout

Sessions provide an isolated environment where multiple players can work on the same puzzle simultaneously.

⚡ Real-Time WebSocket Synchronization

• Added WebSocket-based multiplayer communication.
• Connected players receive state updates in real time.
• Puzzle actions are propagated to all active session participants.
• New players receive the current session state when joining.
• State updates are scoped to the appropriate multiplayer session.

👥 Player Join & Leave Management

Implemented player presence management for:

• Joining an active session.
• Leaving a session intentionally.
• Unexpected WebSocket disconnections.
• Reconnecting to an existing session where supported.
• Removing inactive players from active session state.

Player membership is kept synchronized with the session lifecycle.

🧩 Collaborative Puzzle Solving

Players can contribute to the same puzzle simultaneously.

The backend tracks collaborative actions and synchronizes relevant changes across the session:

Player A ─┐
Player B ─┼──► Shared Puzzle State ──► All Players
Player C ─┘

This allows participants to see progress made by other players without requiring manual refreshes.

💾 Session Persistence

Added persistent session state so multiplayer sessions are not dependent entirely on in-memory WebSocket state.

Persisted information includes the relevant session metadata, player participation, puzzle progress, and solution state required to recover or inspect a session.

⏱️ Timeout Handling

Added session timeout handling for inactive or abandoned sessions.

Expired sessions are detected and transitioned out of the active state rather than remaining indefinitely in the multiplayer session store.

This prevents stale sessions from consuming resources.

🧠 Partial Solution Tracking

The game engine now tracks partial progress toward a puzzle solution.

This allows collaborative sessions to maintain intermediate progress rather than treating the puzzle as only:

UNSOLVED → SOLVED

Instead, player contributions can progressively update the shared solution state until the puzzle is completed.

📊 Session Analytics

Added session-level analytics to provide visibility into multiplayer activity, including relevant participation and session lifecycle metrics.

This provides a foundation for measuring collaboration patterns, completion rates, player activity, and session performance.

Disconnect & Recovery Behaviour

The session handles unexpected player disconnections without terminating the entire puzzle session:

Player Disconnects
       ↓
Detect WebSocket closure
       ↓
Update player presence
       ↓
Preserve shared puzzle state
       ↓
Remaining players continue
       ↓
Player reconnects / session ends

A single player's connection failure therefore does not cause the shared puzzle state to be lost.

Performance & Scalability

The WebSocket architecture is designed to support multiplayer sessions with 10+ concurrent players while limiting state updates to the relevant session participants.

Session-scoped broadcasting avoids unnecessarily sending puzzle updates to unrelated connections.

Testing

Added comprehensive coverage for:

• Session creation.
• Session joining.
• Multiple players joining the same puzzle.
• WebSocket connection lifecycle.
• Real-time state synchronization.
• Collaborative puzzle actions.
• Player departure.
• Unexpected disconnection.
• Session persistence.
• Partial solution tracking.
• Session timeout and cleanup.
• Session completion.
• Multiplayer sessions with 10+ players.
• Session analytics.

Acceptance Criteria

• Multiplayer sessions can be created and managed.
• Players can join and leave active sessions.
• WebSocket connections provide real-time communication.
• Puzzle state synchronizes across connected players.
• Players can collaboratively solve puzzles.
• Partial solution progress is tracked.
• Session state is persisted.
• Disconnects are handled gracefully.
• Inactive sessions are terminated through timeout handling.
• Architecture supports 10+ concurrent players per session.
• Session analytics are available.
• Comprehensive tests cover the multiplayer lifecycle.

Result

The quest service now supports real-time collaborative puzzle-solving sessions, allowing multiple players to work together with synchronized state, resilient connection handling, persistent progress, session timeouts, and multiplayer analytics.

The implementation provides the foundation for scalable cooperative gameplay while ensuring that player disconnects do not compromise the shared puzzle session.

Closes #410
Closes #409
Closes #407
Closes #411

[drips-wave]

@mijinummi Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits