Nakama Integration for Mobile Game: Server, Matchmaking, Leaderboards
You developed a mobile game in Unity? The server side is always the bottleneck. A custom backend in Go requires at least a month of development, and ready-made BaaS solutions like PlayFab or GameSparks hit the budget hard. Nakama (GitHub) is an open-source game server that fits into your infrastructure and covers key tasks: authentication, matchmaking, leaderboards, real-time matches, and data storage. We have integrated Nakama into more than 10 mobile games — from casual puzzles to competitive PvP shooters. We'll tell you how it works and why Nakama saves up to 40% on server-side costs compared to proprietary solutions.
What problems does Nakama solve?
Typical difficulties when developing the server side of a mobile game:
-
Authentication without third-party SDKs. Nakama supports device ID, email, social networks (Apple, Google, Facebook) via a single API. App Store Review Guidelines (Section 5.1) require token encryption — we use Keychain/Keystore for iOS and EncryptedSharedPreferences for Android. The refresh token updates automatically; the session is not lost on restart.
-
Matchmaking with filtering. Nakama uses Bleve-style search queries. You can filter players by skill, region, game mode. For example,
+properties.skill:>1200and+properties.region:eu. This is 3 times faster than a custom Go implementation. -
Authoritative matches for anti-cheat. In relayed matches, the server only forwards messages — any client can tamper with data. Authoritative matches in TypeScript validate moves on the server, eliminating cheating. Comparison:
| Feature | Relayed matches | Authoritative matches |
|---|---|---|
| Server logic | None | Yes (Lua/TypeScript) |
| Cheat protection | Low | High |
| Latency | Low (P2P) | Medium (server) |
| Development complexity | Low | Medium |
| Use case | Casual games | Competitive games |
How we implement Nakama: process and stack
Our stack: Nakama 3.x (server), Unity 2022 LTS (client), TypeScript (authoritative modules), Kubernetes (orchestration). Example case: Client wanted a real-time PvP shooter with anti-cheat. We deployed Nakama on 3 Kubernetes nodes, set up authoritative matches with action validation (checking speed, coordinates, damage), matchmaking by MMR and region. Result: ping <50 ms in Europe, zero cheating incidents in 3 months. Server infrastructure cost — 40% lower than PlayFab.
Process and timeline
| Stage | Duration | Result |
|---|---|---|
| Analysis | 1-2 days | Technical specification, infrastructure selection |
| Design | 2-3 days | Architecture, DB schema, API |
| Basic integration | 3-5 days | Authentication, storage, leaderboard |
| Matchmaking & real-time | 5-10 days | Authoritative matches, matchmaking, sockets |
| Testing | 3-5 days | Load testing, bug fixing |
| Deployment & documentation | 2-3 days | Deployment, manual, team training |
Total time: from 2 to 4 weeks depending on complexity. We'll evaluate your project in 1 day — contact us to discuss details.
Why choose Nakama over custom backend?
Nakama reduces MVP launch time by 60% compared to writing a server in Go or Node.js. You get ready-made modules: authentication, friends, groups, chats, leaderboards, matchmaking. Open-source license (Apache 2.0) — no vendor lock-in. For custom logic — TypeScript or Lua, without switching technology.
How does matchmaking work in Nakama?
The matchmaker uses the Bleve search engine. You set criteria: skill range, game mode, region. Example code:
var ticket = await client.AddMatchmakerAsync( session, query: "+properties.skill:>1200", minCount: 2, maxCount: 4, stringProperties: new Dictionary<string, string> { ["mode"] = "deathmatch" }, numericProperties: new Dictionary<string, double> { ["skill"] = 1500 } ); socket.ReceivedMatchmakerMatched += matched => { socket.JoinMatchAsync(matched.MatchId); }; When a matched event is received, the client joins the match. For authoritative matches, the server additionally validates the player composition.
Typical mistakes when integrating Nakama
- Storing the token in
PlayerPrefswithout encryption — violates App Store Review Guidelines. Use Keychain (iOS) or EncryptedSharedPreferences (Android). - No rate limiting on the server — players can spam requests. Configure Nginx or use Nakama's built-in rate limiter.
- Not using refresh token — session expires in an hour, player gets kicked out. Implement
client.SessionRefreshAsyncwith refresh token storage. - Ignoring load testing — Nakama handles up to 10k concurrent connections per node, but still needs testing with your specific scenarios.
What's included in the work
- Full cycle: analysis, design, implementation, testing, deployment.
- CI/CD setup for automatic deployment (GitHub Actions, Docker).
- API and administration documentation.
- Training your team on Nakama Console.
- 1 month support guarantee after launch.
Our experience — 5+ years of mobile game development, 15+ projects with Nakama. Get a cost estimate — we'll provide a proposal within a day. Contact us to evaluate your project — we'll show how Nakama speeds up your game launch.