Monitoring a player session

Observe session state, diagnostics, and the event plane to operate a game confidently.

Once a player is connected you should be able to answer three questions at any time: Is the session valid? What is the SDK doing? Are events flowing?

1. Session state

Use the SDK-stated status machine rather than guessing from gameplay:

const status = box.getStatus();                 // { state: "authenticated", ... }
const sessionStatus = box.getSessionStatus();   // finer-grained session state
const context = box.getPlayerContext();          // tournamentId, matchId, participantId, slot

Signal to the player:

• session not yet open, pending validation, active, or expired,
• a match context that no longer matches the current UI.

2. Diagnostics

musterbox diagnostics health          # one-shot checks
musterbox diagnostics health --watch  # continuous
musterbox diagnostics generate        # support bundle during incidents
musterbox pipeline status             # outbound queue pressure
musterbox transport diagnose          # control-plane connectivity
musterbox web-socket diagnose         # event-plane connectivity

3. The event plane

Inbound session/wallet/status events are dispatched to your handlers:

box.addEventListener("event", (evt) => {
  switch (evt.data.type) {
    case "session": renderSession(evt.data); break;
    case "status":  renderStatus(evt.data);  break;
    case "wallet":  refreshWallet(evt.data); break;
  }
});

In Manual runtime mode, remember to call tick each frame — that is what dispatches events and polls the plane.

4. Recognizing anomalies

Symptom	Likely cause	Action
MBX-SDK-008 repeated	Refresh failing repeatedly	Re-authenticate the player
MBX-SDK-011	Outbound queue full	Reduce submit rate; check connectivity
pending forever on results	Opponent has not claimed	Wait; show “awaiting opponent”
Transport errors against production URL	Environment misconfigured	Check baseUrl/environment
NotAuthenticated mid-game	Session expired	Re-authenticate, never continue unauthenticated

Instrumentation summary

• Log sdk version + ABI in your diagnostics footer (1.0.0 / 1.2.0).
• Capture a diagnostic bundle before filing anything.
• Never log tokens, PINs, or the game key. SDK output is pre-redacted; your own logs should be too.

Next: Events & realtime.