Migrate from Nakama: Gap Matrix & Cutover Plan

Nakama and Crux overlap on several backend primitives, but they make different architectural bets. Nakama can be self-hosted and extended with code running inside the backend. Crux is a managed fixed-scope API: custom game logic runs in your authoritative game server or another service. That difference determines migration size more than the number of API endpoints.

Migration gap matrix

Nakama capability	Crux path	Migration class
Authentication / accounts	Guest and email player auth plus persistent player records	Semantic migration. Provider identities and existing credentials need an account-link/re-auth strategy; do not assume password material can be copied.
Storage collections / objects	Player documents and project documents	Schema transform. Collection/key/permission semantics do not map 1:1 to keyed JSON documents.
Leaderboards / tournaments	Leaderboards with reset schedules	Partial mapping. Recreate board/reset semantics explicitly; do not assume Nakama tournament behavior is identical.
Wallet / inventory	Currencies, virtual items, balances and inventory adjustments	Schema transform. Rebuild catalogue keys and verify every balance/item invariant after import.
Friends / blocks	Friends, requests and blocks	Partial mapping. Validate relationship state and IDs during import.
Groups / clans / chat	No equivalent player group/chat service	External or stay on Nakama. Move this feature to another service before cutover.
Matchmaker	Crux matchmaking queues	Rewrite rules. Treat queue/filter behavior as a new contract, not a string translation.
Realtime / authoritative matches	Out of scope as a netcode engine	External. Keep or choose a realtime networking/server solution before migrating this dependency.
Server runtime RPCs / hooks	Your game server/service + Crux APIs/webhooks	Code move. Crux webhooks cover event-driven callbacks; synchronous client RPCs need an endpoint you operate.
Player notifications	No general player-notification primitive	External. Keep your push/in-game notification service.
Dedicated-server registry	Server registration, heartbeat and discovery APIs	Native but different schema. Rebuild registration/health metadata around the Crux contract.

1. Inventory what you actually use

List runtime modules, hooks/RPCs, authentication providers, storage collections, leaderboards/tournaments, wallet/inventory data, friends, groups, chat, matchmaker rules, realtime matches and operational tooling. A feature that exists in Nakama but your game never calls is not migration work.

2. Classify each dependency

Mark every row as native, semantic rewrite, or external. Do this before writing import code. If a critical feature lands in “external” and you have no replacement, stop the migration plan there.

3. Design account continuity before data import

Player data is useless if returning users cannot reach the same account. Preserve the Nakama user ID as migration metadata, build an explicit Nakama-ID → Crux-player-ID mapping, and decide how each authentication provider will re-link or re-authenticate. Do not promise transparent password migration unless the source credential format and target auth flow actually support it.

4. Export through a reproducible path

Use the Nakama APIs and/or your database access to produce a versioned export with user IDs, storage records, leaderboard state, economy state and relationship data you intend to migrate. Keep the export immutable so a failed import can be reproduced and audited.

5. Transform schemas explicitly

Nakama storage collections and Crux documents have different shapes and permission models. Write deterministic transforms, not ad-hoc “copy JSON” code. The same rule applies to economy catalogue keys, leaderboard reset behavior and social relationship states.

6. Rehome runtime code

Nakama’s server runtime is the biggest architectural gap. Move authoritative game logic to the dedicated game server or a backend service you operate. Event reactions can subscribe to Crux signed webhooks such as stat.updated and achievement.unlocked; synchronous RPC-style calls still need your own request/response endpoint.

7. Prove one low-risk path end-to-end

Before touching authentication or currency, migrate a non-critical document or leaderboard into a staging Crux project. Run it from the real engine/server code, verify reads/writes and observe the external-connection signal in the dashboard. This tells you whether the new operational model actually feels better before the risky work starts.

8. Shadow and reconcile where dual writes are safe

For mutable data that can safely be written to both systems, shadow writes during a staging or limited-production period and compare invariants: record counts, versions, balances, ranking entries and relationship edges. Do not invent a universal acceptable divergence percentage; define invariants per data class.

9. Cut over by capability, not by DNS alone

Use feature flags or versioned client/server releases so individual backend capabilities can move independently. Keep a rollback path until the new source of truth has passed your own correctness checks and enough production traffic has exercised it.

10. Archive before decommissioning

Only remove Nakama infrastructure after the rollback window and retention requirements are satisfied. Preserve database/export backups, ID mappings, import logs and the final migration code according to your retention policy. A successful cutover is not a reason to destroy the audit trail.

When not to migrate

If a large share of your product depends on Nakama runtime modules, chat/groups, its realtime engine, self-hosting, or direct source-level control, the operational cost may be buying exactly the flexibility you need. In that case, improving your Nakama deployment—or moving the same architecture to Heroic Cloud—can be lower risk than decomposing those capabilities across several services.

Bottom line

A Nakama-to-Crux migration is attractive when the problem is operating a backend platform you barely customize. It is unattractive when Nakama itself is where substantial game logic and realtime/social behavior lives. Use the gap matrix first; only write the importer after the architecture still makes sense.