Skip to content

Nakama client session recovery

Current verified configuration

Tank Game uses the pristine official Nakama Unreal plugin at version 2.11.5 as a project plugin. No local Nakama source patch is part of the maintained integration.

Version 2.11.5 supplies the request-lifetime behavior needed by UE 5.8. HTTP completion paths use weak client references and treat requests that complete after their client is released as cancelled. This owns the low-level safety boundary that prevents late callbacks during End PIE from dereferencing a destroyed UNakamaClient.

After UNakamaConnectionSubsystem creates the client, it deliberately applies:

Client->bAutoRefreshSession = false;
Client->bEnableRetries = false;

The plugin therefore owns request construction, transport, parsing, safe completion, and cancellation. It does not own Tank Game's refresh schedule or recovery policy.

Project-owned recovery contract

UNakamaConnectionSubsystem is the single coordinator for the complete client session lifecycle. It owns:

  • proactive access-token refresh before expiry;
  • refresh-token expiry detection and fallback to custom authentication;
  • association with the current EOS account and EOS session generation;
  • rejection of callbacks from superseded generations and attempts;
  • Nakama realtime connection and reconnection;
  • account retrieval after authentication;
  • backend readiness, unavailable, connecting, and blocked states;
  • permanent authentication rejection and fail-closed behavior;
  • retry scheduling, jitter, and backoff;
  • cancellation and generation invalidation during shutdown.

Successful refresh is fed back through the coordinator before it resumes the remaining account/realtime readiness sequence. Transient failures use the project recovery schedule. Rejected or expired refresh credentials abandon the session and return to the EOS-bound custom-authentication path.

Why plugin automatic refresh remains disabled

Nakama 2.11.5 can pre-emptively refresh a session when an authenticated HTTP request is submitted within its refresh window. That behavior is useful for a client whose only requirement is keeping individual HTTP calls authenticated, but it is not a replacement for Tank Game's lifecycle coordinator:

  • it is demand-driven by HTTP calls rather than the project's proactive readiness schedule;
  • it does not reconnect or validate the realtime client;
  • it does not manage EOS identity generation changes;
  • it does not drive Tank Game backend readiness and blocked states;
  • it does not perform the project's reauthentication and account-retrieval sequence;
  • it bypasses the project's generation-aware callback and retry policy.

Enabling it alongside the coordinator would create two refresh owners and allow an ordinary RPC to mutate the shared session while a recovery attempt is in flight. Removing the coordinator would discard the non-HTTP responsibilities above. Keep bAutoRefreshSession disabled unless all of those responsibilities are moved to a replacement state machine.

Why plugin automatic retries remain disabled

Nakama 2.11.5 can retry transient HTTP 500, 502, 503, and 504 responses. Tank Game disables this because its House RPC surface includes state-changing and potentially non-idempotent operations. An invisible plugin retry can repeat a House open, join, leave, close, freeze, or selection mutation independently of the state machine that owns its result.

Retries must remain explicit at the project operation boundary unless the corresponding backend RPC has a verified idempotency key and the owning state machine treats repeated completion safely.

Shutdown behavior

End PIE and GameInstance teardown may release the Nakama client while an HTTP request, including best-effort house_close, is still completing. Project callbacks must continue to reject work once shutdown begins. Nakama 2.11.5 owns the lower-level guarantee that a late transport completion does not access a released client.

Do not restore the temporary Nakama 2.11.0 source patch. Upgrade the official plugin when future request-lifetime or engine compatibility fixes are required, then revalidate this ownership boundary.

Verification gates

Changes to the plugin version or recovery ownership require all of the following:

  1. Build NakamaUnreal and NakamaBlueprints against the current AngelScript engine.
  2. Build the complete Metal_terraEditor target.
  3. Run MetalTerra.Nakama.Recovery.RejectsOutOfOrderCallbacks.
  4. Compile project Blueprints and compare failures with the accepted baseline.
  5. Exercise EOS login, Nakama authentication, account retrieval, realtime connection, representative House RPCs, session expiry/refresh, and realtime recovery.
  6. Start and end PIE with an in-flight best-effort House close and confirm that teardown produces no crash or late project callback.

The engine migration context is recorded in the UE AngelScript 5.8 upgrade.