topfreegames/pitaya: a Go game server framework with clustering and client SDKs

What Pitaya solves, and who it is aimed at

Pitaya targets the server side of a multiplayer game that has outgrown a single process. The README describes it as a "simple, fast and lightweight game server framework with clustering support and client libraries for iOS, Android, Unity and others through the C SDK". The unit of work is a server process that accepts client sessions, routes messages to handlers, and can call other Pitaya processes over RPC. The clustering part is what separates it from a plain WebSocket library: a frontend connector can accept connections while a backend room server holds the game state, and the two communicate through the framework rather than through code you write.

The audience is narrow on purpose. You need Go on the server, because handlers are Go functions registered on a module and the repository's go.mod declares module github.com/topfreegames/pitaya/v3 with go 1.25.4. You also need to be comfortable running infrastructure: etcd is listed as optional and used for service discovery, NATS as optional and used for sending and receiving RPC, and Docker as optional for running both in containers. In practice, if you want the cluster example to work, those two services are not optional at all.

The client side is the other half of the pitch. libpitaya is a C SDK, and the README points to libpitaya-cluster for cluster-aware clients. That is how a Unity, iOS or Android game talks to the server without reimplementing the protocol. The README credits nano as the framework Pitaya is based on and pomelo for the distributed design and protocol inspiration, which tells you the architectural lineage without you having to read the code.

How the frontend connector and backend room talk to each other

The mechanism visible in the README is a two-role deployment. A connector frontend accepts client traffic; a room backend holds logic. The README's example runs both from the cluster_grpc example with two make targets, and states that after both are running "there should be 2 pitaya servers running, a frontend connector and a backend room".

Discovery and RPC are delegated. etcd handles service discovery, so a frontend can find a backend without hardcoded addresses. NATS carries RPC between servers. Both are declared as optional in the prerequisites, but the Makefile's run-chat-example target starts etcd and nats through docker compose before running the chat demo, so the repository's own examples treat them as required for anything distributed.

The transport layer is pluggable in the sense that the repository ships multiple protocol examples: examples/demo/cluster, examples/demo/cluster_protobuf, and a WebSocket chat demo. The go.mod requires google.golang.org/grpc, github.com/gorilla/websocket and github.com/golang/protobuf, so gRPC, WebSocket and protobuf are all first-class in the codebase rather than bolted on. The Makefile also builds a k6 extension from xk6-pitaya with the pkg directory, which means load testing against a Pitaya server is a supported path rather than something you write from scratch. Observability is wired in too: the Makefile has targets that set PITAYA_METRICS_PROMETHEUS_PORT, OTEL_SDK_DISABLED, OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_TRACES_SAMPLER, and a run-jaeger-aio target that brings up Jaeger and prints the UI address as http://localhost:16686. Prometheus, OpenTelemetry and Datadog are all in the dependency list.

Installing Pitaya and running your first cluster

The README gives a clone-and-setup path. Go 1.16 or newer is listed as a prerequisite, though go.mod now requires Go 1.25.4, so treat the go.mod value as the real floor. etcd, NATS and Docker are listed as optional, but the example below uses Docker for etcd.

First clone the repository and pull in its dependencies. The setup target also initializes git submodules, which matters because pitaya-protos is a submodule in the repository listing.

git clone https://github.com/topfreegames/pitaya.git
cd pitaya
make setup

Next start etcd. The README runs this from the examples/testing directory with docker compose, and notes that etcd may be run without Docker if you prefer.

cd ./examples/testing && docker compose up -d etcd

Now start the two servers from the cluster_grpc example. Run each target in its own shell, because both are long-running processes.

make run-cluster-grpc-example-connector
make run-cluster-grpc-example-room

With both up, the README says there should be two Pitaya servers running. To talk to the frontend, use pitaya-cli, the REPL client that lives in the pitaya-cli directory. The README shows connecting to localhost:3250 and sending a request to room.room.entry, with the response sv-> {"code":0,"result":"ok"}.

pitaya-cli
>>> connect localhost:3250
connected!
>>> request room.room.entry
>>> sv-> {"code":0,"result":"ok"}

If you would rather build the CLI from source, the Makefile has a build target that writes the binary to ./build/pitaya-cli. Tests run with make test, which the README says covers both unit and e2e suites.

Where Pitaya will frustrate you

The documentation gap is the first real cost. The README's Contributing section is literally "#TODO", and there is no upgrade guide. The module path in go.mod is github.com/topfreegames/pitaya/v3 while the README's install instructions and the GitHub URLs it links still point at the unversioned repository. Anyone moving from v2 to v3 has to work out the import path change themselves. The repository does carry a go.work and go.work.sum at the top level, which suggests a multi-module workspace, but nothing in the README explains how that interacts with a downstream project that imports Pitaya as a dependency.

The operational surface is the second cost. etcd and NATS are described as optional, but clustering is the headline feature and both are needed for it. That means you are running and monitoring two additional distributed systems alongside your game servers. For a small team shipping a single-region game, that is a lot of moving parts to accept before you have written a line of game logic.

The third issue is language lock-in on the server. Handlers are Go. If your team is a Node.js or C# shop, Pitaya does not meet you where you are; the C SDK is a client, not a server runtime. The framework also does not appear to provide a managed hosting story. There is no homepage listed for the project, and the README points to self-hosted dependencies throughout.

Finally, the demo and example coverage is uneven. The chat demo is described as roughly 100 lines and adapted from nano's example. The cluster examples are the ones the README actually walks through. Anything beyond that, such as matchmaking, persistence or account systems, is not covered by the README at all.

Pitaya compared with Colyseus and Nakama

The closest alternatives differ mainly in where the server logic lives and who operates the infrastructure. Colyseus is a JavaScript and TypeScript framework: you write room logic in TypeScript, and the project provides its own matchmaking and state synchronization model. Pitaya asks for Go instead, and it does not ship an opinionated room-state replication layer; the room backend is whatever you write, with NATS carrying RPC to it. If your team is already in TypeScript, Colyseus removes an entire language from your stack that Pitaya adds.

Nakama takes the opposite approach from Pitaya on the server side. It is a batteries-included game backend with accounts, storage, leaderboards and matchmaking as built-in services, and you extend it with server-side hooks rather than building the services yourself. Pitaya gives you the transport, the clustering and the client SDKs, and leaves accounts, persistence and matchmaking to you. That is a deliberate trade: more control over the server, more code to write.

The distinction that matters most is the client story. Pitaya's reach into iOS, Android and Unity runs through a C SDK, which is unusual and useful if you have native clients that are not JavaScript. Colyseus and Nakama both have JavaScript clients as their primary path. If your game is Unity plus Go services, Pitaya's combination is hard to match; if your game is a browser title, the C SDK buys you nothing.

Maintenance, releases and the MIT licence

The repository is not archived, and the last push was on 2026-09-14. Recent tagged releases are v2.11.24 on 2026-06-18, v2.11.23 on 2026-06-09 and v2.11.22 on 2026-05-05. Note the gap between the v2.11.x tags and the v3 module path in go.mod: the tags in the release list do not line up with the version in the module declaration, and the README does not explain the relationship. Before you pin a version, check which import path corresponds to which tag.

Upgrade cost is hard to estimate from the README alone. The dependency list is long and includes etcd v3.5.11, NATS server v2.12.2, gRPC v1.64.1, OpenTelemetry v1.28.0 and Prometheus client v1.16.0. Each of those moves on its own schedule, and a Pitaya upgrade may drag several of them forward at once. The Makefile's setup-ci target installs goveralls at a pinned version, which is a small signal that CI tooling is pinned deliberately.

The licence is MIT, declared in the README badge and in the LICENSE file at the repository root. MIT is permissive: it allows commercial use, modification and redistribution with the copyright notice and licence text retained. That is a plain statement of what the licence says, not legal advice. If you are embedding Pitaya in a product with unusual distribution terms, have counsel read the LICENSE file rather than relying on the badge. The README also gives a security contact, [email protected], for vulnerability reports.

Editorial conclusion

Adopt Pitaya if your team writes Go, your game needs a frontend/backend split across processes, and you are willing to operate etcd and NATS. Do not adopt it if you need a managed backend, a non-Go server language, or a framework with a documented upgrade path between major versions; the README has no migration guide, so verify the v2 to v3 module path change and the go.work layout yourself before committing. The first thing to check is whether the examples/demo/cluster example still starts against your etcd and NATS versions, because that is the only end-to-end path the README describes.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. topfreegames/pitaya on GitHub