Nakama

Nakama is a production-ready, open-source game backend server built in Go, designed for teams building multiplayer, social, and real-time games. It provides a complete suite of backend primitives — authentication, distributed storage, realtime chat, matchmaking, leaderboards, tournaments, in-app purchase validation, and push notifications — all in a single deployable binary, eliminating the need to assemble these systems from scratch.

The server supports multiple protocols simultaneously: gRPC and REST for request/response workloads, and WebSockets or rUDP for realtime communication. An embedded console UI is accessible directly in the browser without separate installation, providing live inspection of player data, storage objects, runtime modules, and active multiplayer matches.

Nakama’s extensibility is a core design pillar. Developers can write custom server-side logic in Lua, TypeScript/JavaScript, or native Go — all three runtime environments run concurrently in the same server process. This lets teams prototype rapidly in Lua, use TypeScript for familiar tooling, or drop into Go for performance-critical code paths.

Compatible with PostgreSQL and CockroachDB, Nakama deploys to any cloud provider or on-premise infrastructure. A managed hosting option (Heroic Cloud) is available for teams that want production uptime, backups, and scaling handled for them. Official client SDKs cover Unity, Unreal, Godot, JavaScript, C#, Java, Swift, and Defold.

What You Get

• Multi-provider Authentication - Register and authenticate users via email/password, device ID, Apple Sign-In, Google, Facebook, Steam, GameCenter, or fully custom tokens — JWT sessions issued automatically.
• Distributed Object Storage - Store JSON game objects in named collections with per-record read/write permissions, version conflict detection, and cursor-based pagination for large datasets.
• Realtime Chat - Create 1-on-1, group, and global chat channels over WebSocket with message persistence, history retrieval, and real-time delivery — no polling required.
• Query-based Matchmaking - Players submit match tickets with numeric and string properties; the matchmaker evaluates them against configurable queries (rank range, region, skill tier) to form balanced sessions automatically.
• Party System - Players form temporary parties with a designated leader, share presence notifications, and transition as a group into multiplayer matches without losing party membership.
• Dynamic Leaderboards - Create unlimited leaderboards with configurable sort order, expiry windows for seasonal resets, and efficient rank lookups for both top players and the cohort surrounding a specific user.
• Tournaments and Leagues - Define competitive events with entry fees, score submission windows, and prize tiers; link multiple tournaments into multi-stage leagues for long-term player engagement.
• Server-side Purchase Validation - Validate Apple App Store, Google Play, Amazon Appstore, and Steam receipts server-side with idempotent transaction records to prevent double-claiming.
• Three-runtime Extension System - Write custom RPC functions, before/after hooks, and match logic in Lua scripts, TypeScript/JavaScript modules, or compiled Go plugins — all run concurrently in the same server process.
• Embedded Nakama Console - Browser-based admin UI bundled into the binary: inspect player accounts, explore storage, view Prometheus metrics, test APIs interactively, and inspect active realtime matches.
• Official Client SDKs - First-party libraries for Unity, Unreal Engine, Godot, JavaScript/TypeScript, C#/.NET, Java/Android, Swift/iOS, and Defold with full API coverage and documentation.
• PostgreSQL and CockroachDB Support - Uses standard Postgres wire protocol; run on a single PostgreSQL node for development or a CockroachDB cluster for distributed, highly available production deployments.

Common Use Cases

• Launching a competitive mobile battle game - A studio uses Nakama’s matchmaker with numeric skill-rating queries to form balanced 5v5 sessions, records match outcomes to leaderboards, and runs monthly tournaments that feed into a season-long league — all without writing custom backend systems.
• Adding social features to an existing game - A team integrates Nakama’s social graph and group chat into an already-shipped title to let players add friends, form guilds, and see friends’ leaderboard positions, using the REST API from their existing game client.
• Building a game economy with server-authoritative validation - An RPG developer uses Nakama’s storage for inventory management, Lua runtime hooks to validate trade transactions server-side before committing them to the database, and Apple/Google purchase validation to safely grant premium currency.
• Prototyping a realtime co-op game - An indie developer writes match loop logic in Lua to iterate quickly, uses WebSocket sessions for realtime state sync between players, and later migrates performance-critical match handlers to Go plugins without changing client code.
• Self-hosting a game backend on bare metal - A studio deploys Nakama as a Docker container alongside CockroachDB on their own servers, configures Prometheus metrics collection, and uses the embedded console to monitor player activity and debug storage issues in production.

Under The Hood

Architecture Nakama implements a modular monolith pattern where each bounded context — authentication, storage, matchmaking, chat, leaderboards, runtime extensions — lives in a separate Go package but deploys as a single binary, avoiding microservice operational overhead while maintaining clear separation of concerns. The server initializes all subsystems through explicit constructor-based dependency injection, passing interfaces rather than concrete types for the database, logger, metrics, session registry, match registry, and runtime, ensuring substitutability and testability throughout. The gRPC and REST APIs are unified via Protocol Buffer contracts with grpc-gateway generating HTTP/JSON transcoding automatically from a single protobuf definition, eliminating divergence between API surfaces. Runtime extensibility is achieved through a Runtime interface that three independent engines — Lua via gopher-lua, JavaScript/TypeScript via Goja, and native Go plugins — must satisfy simultaneously, enabling game teams to choose their preferred language without switching servers. The matchmaker uses Bluge, an embedded full-text and numeric search engine, to index player tickets as documents and evaluate matching criteria as search queries, allowing arbitrarily complex matching rules to be expressed without code changes.

Tech Stack Nakama is written in Go (v1.26) and uses gRPC with Protocol Buffers as the primary RPC mechanism, with grpc-gateway providing automatic HTTP/REST transcoding so clients can use either protocol transparently. Primary data persistence relies on PostgreSQL and CockroachDB accessed via pgx/v5 with raw SQL queries and the standard database/sql interface. The three scripting runtimes are gopher-lua (a pure-Go Lua 5.1 VM), Goja (a pure-Go ECMAScript 5.1+ engine for TypeScript transpiled to JavaScript), and native Go shared-object plugins loaded at startup. Matchmaking leverages Bluge as an in-memory document search index for player ticket evaluation. Prometheus client is embedded for metrics export, Zap provides structured high-performance logging, and the entire server ships with an embedded console UI served over HTTP — all as a single binary containerized via Docker with official multi-service Compose configurations.

Code Quality Nakama maintains substantial test coverage with 22 test files across the server package covering API endpoints, storage, friend graphs, tournaments, wallets, leaderboard rank caches, and runtime environments for both Go and JavaScript engines. Tests construct real server instances against a live database rather than mocking subsystems, making them integration-level tests that validate actual behavior under realistic conditions. Error handling follows Go idioms consistently — errors propagate explicitly through return values with proper gRPC status codes attached, and structured Zap logging captures contextual error information throughout call paths. The codebase defines explicit typed interfaces for all major subsystems, and GitHub Actions CI runs golangci-lint static analysis alongside build and Docker publish pipelines on every change. The vendor directory is checked in, ensuring reproducible builds without network access.

What Makes It Unique Nakama’s most distinctive technical contribution is its concurrent multi-runtime extension system — a single server process that hosts Lua scripts, TypeScript modules, and compiled Go plugins simultaneously, all satisfying the same Runtime interface and callable from any client. The Bluge-powered matchmaker is particularly elegant: matching criteria are expressed as search query strings against a player property document index, enabling arbitrarily complex matching rules (rank windows, regional preference, skill brackets) to be configured without server code changes. The party system integrates directly with the match lifecycle so party members transition into multiplayer sessions as a group while preserving presence and leadership state. The embedded Nakama Console — a full React-based web UI compiled into the server binary — provides a live API explorer, storage browser, runtime module inspector, and match viewer accessible on port 7351 without any additional deployment, which is uncommon in open-source backend frameworks of this complexity.

Self-Hosting

Nakama is released under the Apache License 2.0, a permissive open-source license that grants broad rights with minimal restrictions. You can use, modify, and distribute Nakama — including in commercial products and services — without paying licensing fees or releasing your proprietary game code as open source. The only requirements are preserving copyright notices and the license text. There are no open-core limitations in the published source: all features visible in the repository, including the console UI, the full matchmaker, and all three runtime environments, are available to self-hosters without any license key or enterprise agreement.

Running Nakama yourself means accepting full responsibility for the operational stack. You need to provision and maintain at least one server for Nakama and a separate database node (PostgreSQL or a CockroachDB cluster for high availability). For production workloads, Heroic Labs recommends a minimum of an n1-standard-1 class VM for Nakama and follows CockroachDB’s own hardware guidelines for the database tier. You are responsible for database backups, schema migrations on upgrades (Nakama runs these automatically on startup but you must ensure they complete without downtime), horizontal scaling decisions, TLS certificate management, and log aggregation. The server is stateless across restarts for most features, but session and match state lives in memory, so rolling deploys require coordination to avoid dropping active players.

Compared to the managed Heroic Cloud option, self-hosting trades operational convenience for cost control and data sovereignty. Heroic Cloud handles replication, automated backups, multi-region failover, managed upgrades, and provides SLA-backed uptime guarantees and access to Heroic Labs support channels. Self-hosters get none of these guarantees by default and must build their own runbooks for incident response, capacity planning, and disaster recovery. For studios shipping to large player bases, the engineering time required to operate a reliable Nakama deployment at scale is a real cost that Heroic Cloud is designed to absorb.