Migrating from Nakama to Supercraft GSB: A 10-Step Checklist (2026)

Self-hosted Nakama (open-source from Heroic Labs) is a strong choice for studios with platform engineers who want full control over their backend. But the operational cost — 24/7 oncall, security patching, scaling decisions, Postgres ops — is real and persistent. This guide walks through migrating a live game from self-hosted Nakama to Supercraft Game Server Backend (GSB), the managed BaaS alternative, with zero downtime.

Before You Start: Is GSB the Right Replacement?

GSB replaces Nakama cleanly if your game uses Nakama primarily for: player auth, save sync, leaderboards, friends/groups, matchmaking, virtual currencies, inventory, and basic real-time features. GSB does not replace Nakama if you depend heavily on Nakama's real-time multiplayer relay (Nakama's authoritative-server runtime) or if you've forked Nakama for source-level customization.

Read the Nakama open-source vs managed comparison first if you're still in the decision phase.

The 10-Step Checklist

Step 1: Audit your Nakama usage

List every Nakama API call your client and server code makes today. Group by category: auth, storage objects, leaderboards, virtual currency, inventory, RPC functions, matchmaker, friends/groups, notifications. The list becomes your migration spec.

Pull a 30-day RPC-call report from your Nakama metrics. RPC calls below 1% of total volume can usually be dropped or deferred during migration.

Step 2: Map Nakama APIs to GSB equivalents

Nakama	GSB equivalent	Notes
Authenticate (email, custom, device, Steam, etc.)	POST /v1/auth/login (email + password) / /v1/auth/anonymous / /v1/auth/oauth	Direct mapping. GSB supports email + OAuth (Google, Apple, Steam) + anonymous-promote.
Storage Objects (write/read/delete)	Player JSON documents with patch semantics	Nakama's collection/key/value model maps to GSB's nested JSON documents. Plan your schema flattening.
Leaderboards / Tournaments	Leaderboards API with seasonal boards	Direct mapping. Tournaments map to seasonal leaderboards.
Friends / Groups	Friends API + Groups API	Direct mapping.
Matchmaker	GSB matchmaker	Map your Nakama matchmaker rule strings to GSB's queue config.
RPC functions (Lua, TypeScript, Go)	GSB cloud-functions endpoint	Rewrite required. GSB cloud-functions runtime differs from Nakama's; budget the most rewrite time here.
Virtual currency / Wallet	Currencies API with atomic transactions	Direct mapping.
Real-time multiplayer (Nakama relay)	Out of scope	If you use Nakama's authoritative-server relay, you'll need a separate networking solution (Mirror, Photon Fusion, Unity Netcode for GameObjects).
Notifications	GSB notifications endpoint	Direct mapping for in-game; push notifications via your existing FCM/APNS integration.

Step 3: Export your Nakama player data

Use Nakama's built-in export tool or query Postgres directly. Dump player accounts, storage objects, leaderboard records, virtual wallets, and inventory state.

Critical: capture Nakama user IDs alongside the data. You'll need to map Nakama IDs to GSB IDs in step 7.

Step 4: Set up your GSB project

Create a GSB project at gsb.supercraft.host/pricing (start on free tier for migration testing). Configure environments — typically dev, staging, prod. Generate API keys for each.

Step 5: Build the import script

Write a one-shot import script that iterates your Nakama export and creates equivalent GSB entities:

• For each Nakama user: create a GSB player with anonymous-promote auth, then merge in their email if present
• For each storage object: write to the matching GSB player document (nesting collection/key into a single JSON tree)
• For each leaderboard record: write to the matching GSB leaderboard
• For each wallet entry: write to GSB currencies
• For each inventory item: write to GSB inventory
• Write a mapping table: nakama_user_id → gsb_player_id

Test on staging first. Run import in batches of 1,000 players to monitor for errors.

Step 6: Rewrite RPC functions

This is the longest single step. Nakama RPCs (Lua, TypeScript, Go modules) don't translate 1:1 to GSB cloud-functions. For each RPC:

• Identify the trigger (player call, scheduled task, server-side validation)
• Map to GSB cloud function equivalent
• Rewrite the business logic; do NOT just port the code verbatim — runtime semantics differ
• Write tests; production data is the only audit you'll get

Step 7: Update your client SDK calls

Replace Nakama SDK calls in your game client with GSB SDK calls. Wrap each in a feature flag so you can toggle between Nakama and GSB during cutover.

Use the nakama_user_id → gsb_player_id mapping from step 5 so existing players see their progression seamlessly after the switch.

Step 8: Stage a parallel-write period

For 1-2 weeks before cutover, run both backends in parallel. Every player action writes to both Nakama (current source of truth) and GSB (shadow). This catches mapping bugs before they hit production.

Compare data integrity daily. If GSB diverges from Nakama by more than 0.1%, fix the import script and re-run.

Step 9: Cutover

Pick a low-traffic window (typically a weekday off-hour for your game's primary audience). Flip the feature flag from Nakama to GSB. Monitor for 4 hours minimum.

Keep Nakama running in read-only mode for 30 days as a rollback safety net. Most migrations don't need to roll back, but the buffer covers edge cases.

Step 10: Decommission Nakama

After 30 days of stable GSB-only operation:

• Shut down Nakama servers
• Drop Postgres database (after backing up)
• Cancel cloud hosting bills (EC2, GCE, Azure VMs)
• Archive import scripts and mapping tables (don't delete — audit trail)
• Remove Nakama SDKs from your client codebase in the next release

What You Stop Operating

This is the real win of the migration. Things you no longer worry about after moving to managed GSB:

• Postgres replication, backups, schema migrations, and ops
• Nakama version upgrades and breaking-change handling
• Security patches on your Nakama / Postgres / Linux stack
• Scaling decisions for player concurrency spikes
• 24/7 on-call rotation for backend incidents
• SSL certificate renewals on your Nakama public endpoint

Common Pitfalls

• RPC rewrites are 60% of the work. Plan timeline accordingly.
• Nakama collection/key/value storage doesn't map 1:1 to nested JSON. Plan schema flattening before importing.
• Don't migrate the real-time relay. If you depend on Nakama's authoritative-server relay, plan a separate networking solution before cutover.
• Don't skip the parallel-write period. Cutting over without it is the #1 source of post-migration data loss.

Cost Comparison After Migration

Studios moving from self-hosted Nakama to GSB typically replace ~$300-1,000/mo of cloud hosting + ops time with $19-99/mo of GSB subscription. The bigger savings is engineering time — no more on-call shifts, no more schema-migration anxiety, no more Nakama-version-upgrade sprints.

Bottom Line

Migrating from self-hosted Nakama to managed GSB is a tractable 1-3 week effort for most indie games. The biggest wins post-migration are eliminating ops overhead, predictable flat pricing, and the option to unify your backend with Supercraft dedicated-server hosting under one vendor. The biggest cost is rewriting RPC logic — plan for it. If your team uses Nakama specifically because they want source-level control, stay on Nakama; if they're maintaining it because they had to, GSB removes the maintenance burden.

Ready to start? Sign up for the GSB free tier and start with the parallel-write period in a staging environment. The GSB documentation covers the SDK quickstart for Unity, Unreal, and Godot.