GameFrameX: a complete client and server project for online indie games

A repository that is a whole game, not a library

GameFrameX is presented as an open source toolbox that takes a game from idea to built to live and running, with Unity, Godot, Cocos and Laya clients and one .NET server behind them. The framing in the project overview is deliberate. It argues that the hard part of making a game is not drawing a character or coding a skill, but stitching the pieces together: where save files live, how a server forwards messages in a multiplayer game, who owns items, levels and progression data, and what happens after launch when you need to read data, manage players and ship new versions.

That is a claim about scope, and the repository layout backs it up. The top level contains Unity/ for the Unity client, Server/ for the .NET server, Tools/ for the table generation tooling, Config/, Protobuf/ for the shared protocol definitions, FairyGUIProject/ and LayaBox/ for the other client targets, docker/ for the database containers, and scripts/.

The Quick Start section makes the same point in one line: this repository is the complete project, and whether you clone it, download a ZIP or pull it from a mirror, it runs as-is with no extra pulls. There is no package to add, no plugin to wire in and no separate backend project to find.

The intended users are named explicitly. Indie developers who want to make online or multiplayer games but are stuck on how to do the server. Small teams that want to spin up a prototype to validate an idea. And learners who want to walk the full client, server and backend pipeline end to end. The primary language of the repository is JavaScript, the licence is AGPL-3.0, and the default branch is main.

Two databases with different jobs

The storage design splits player state from backend data, and the tutorial shows how those two are run separately.

The Quick Start step one is the local MongoDB:

# 1. Start the local database (MongoDB, user admin / admin)
cd docker/mongo && docker compose up -d

The connection string is mongodb://admin:admin@localhost:27017, and the data lands in docker/mongo/database/. Player data is described in the feature table as living in MongoDB, where reads are fast.

PostgreSQL is the other half, in docker/postgres/, and it serves the Admin backend. The tutorial explicitly says it does not need it, which is a useful signal about the shape of the project. If you are evaluating the stack, you can ignore the admin panel's database until you actually want the admin panel, and the quick verification of the client to server loop does not require it.

The reason for the split is workload. A game server writes and reads player state constantly, with a shape that changes as the game changes, while the admin backend is a conventional relational system holding configuration and operational records. MongoDB for the first and PostgreSQL for the second keeps the hot path out of the transactional store.

There is one configuration detail that deserves attention before you start anything. The default data source in the launcher points at a public demo database, and the README is explicit that the only thing you need to override is the DataBaseUrl so it points at the MongoDB you just started. If you skip that, you are pointed at somebody else's demo instance, and a demo server full of test data is not a place to develop a game.

LuBan for tables and ProtoBuf for the wire

Two pieces of the project address the two ways game data goes wrong: designer data that has to become code, and client and server that have to agree.

LuBan is the table generation tool. In the feature comparison it is described as turning Excel into code and data in one click, which solves the problem the project overview names, namely hand-carrying Excel configurations into code. A designer edits a spreadsheet, the generator produces the code and the data, and the change is versioned like any other change. The Tools/ directory in the repository is where that lives, and the .NET 10 requirement applies to the server and to the table generation tool together, which tells you they are built together.

ProtoBuf handles the other side. The feature table describes it as unifying the protocol so that a change made once keeps both sides in sync, and the Protobuf/ directory at the top level holds the shared definitions. That is a large part of why the client and server can be written in different languages: the contract is a schema, not a hand-written parser on each side.

The remaining pieces complete the operational story. A built-in admin web panel is listed for reading data, managing players and pushing configurations after launch. One-click packaging and deployment with Docker is listed for the server side. The admin panel is what turns the project from a demo into something you could run a live service on, and it is also the piece that needs PostgreSQL.

The Protobuf and LuBan combination is the part with the largest effect for a small team. It removes the two most common sources of client and server drift, and it does so with tools rather than process. The cost is that you have adopted two specific technologies on top of the .NET server, and the schema and the spreadsheet become the places where your game is actually defined.

Building and starting the server, and the port map

The server is a .NET solution, and the Quick Start gives the exact sequence:

# 2. Build & start the server (override only the DB connection; ports use defaults)
cd ../../Server && dotnet build
cd bin/app_debug
dotnet GameFrameX.Launcher.dll --DataBaseUrl="mongodb://admin:admin@localhost:27017/?authSource=admin"

The README explains why there is only one argument. The defaults, in Server/GameFrameX.Launcher/StartUp/AppStartUpGame.cs, already open the full port set, so the only value you have to change is the database connection.

The port table is worth reading before you debug anything. Port 29100 is TCP for long-lived game client connections and is on by default. Port 28080 is HTTP for login and other APIs under /game/api/... and is on by default. Port 29110 is WebSocket and is off, started with --IsEnableWebSocket true. Port 29090 is metrics and health and is off by default, started with --IsOpenTelemetryMetrics true and a MetricsPort value of 29090.

Checking that the server is alive is a one-liner, using nc to check the two default ports:

nc -z localhost 29100 && nc -z localhost 28080

The README also gives the log alternative, looking for has been started or Now listening on. That distinction between the TCP port and the HTTP port matters, because a client that cannot connect is often talking to the wrong one of the two.

If you prefer an IDE, the README describes opening Server/Server.slnx with Rider or Visual Studio, using Server.sln if the newer solution format is not supported, setting the startup project to GameFrameX.Launcher and the working directory to Server/bin/app_debug, leaving the arguments empty, and changing the DataBaseUrl default in AppStartUpGame.cs. The working directory matters because that is where the built output and its configuration are resolved from.

Four client targets and the Unity version they assume

The client side of the repository covers four engines, which is unusual for a project of this kind and is the strongest argument for it. Unity/ holds the Unity client, LayaBox/ the Laya client, FairyGUIProject/ the FairyGUI project, and the description names Godot and Cocos as well.

The Quick Start closes with the client step, which is specific about the editor version:

# 3. Open the Unity/ project with Unity 2019.4.40f1, load Assets/Scenes/Launcher.unity, press Play

The installation table confirms it: Unity Editor 2019.4.40f1, installed through the Unity Hub by choosing Install Editor and then Archive. The.NET SDK requirement is 10.0 or newer, and Docker Desktop is any recent version.

The verification is human rather than technical. If you see the login screen and can create a character into the main city, the full client to server loop works. That is a good acceptance test to adopt, because it exercises the login API, the character creation path, the data write to MongoDB and the network transport in one action.

There is a caveat about the Unity version that is easy to miss. 2019.4 is an old LTS branch, and the project pins it exactly, right down to the patch release. The.NET 10 requirement is called a hard requirement for the server and the table generation tool, with the note to get this one right. A team on a current Unity version, or one that cannot run a 2019 editor, has to decide whether to upgrade the client project, and the README excerpt does not document that path. The multi-engine claim is about the repository containing the clients, not about every engine being equally current.

Where GameFrameX is the wrong tool

The first case is the one the project itself defines. It is not a library and it is not a service you integrate. If you have an existing game with its own networking, its own data layer and its own deployment, then adopting GameFrameX means replacing those, not extending them. The value is in the completeness, and the completeness is exactly what makes it a poor fit for an established codebase.

The second case is teams that do not want to operate MongoDB, PostgreSQL and Docker. The local tutorial starts two database containers and the server, and the described production path adds an admin panel and a deployment story on top. A team without someone willing to own that is signing up for infrastructure work.

The third case is licence and distribution. The project is AGPL-3.0 with a LICENSE.md file at the root. For an indie game distributed as a product rather than hosted as a service, the network clause of the AGPL is a question that needs legal review, and this article does not interpret it. What matters is that the answer is not automatically the same as for a permissive licence, and you should settle it before building on the code.

The fourth is the release story. The repository has no GitHub releases, and the version you get is whatever you clone from the main branch. Combined with a pinned Unity editor and a hard .NET 10 requirement, that means you are tracking a moving target with a moving dependency set, and there is no changelog-style release to diff against when something breaks.

One more practical observation. The project is clearly developed with a Chinese-speaking community in mind, with QQ groups listed, Chinese and Japanese and Korean README translations, and a Gitee mirror alongside GitHub. That is a good sign for the community, and it is also a signal about where documentation and support are densest, which is worth weighing if your team does not read Chinese.

Shipped games, community channels and what is missing

The table of shipped games lists two built with the project, one live on TapTap since 2024-04-15 and one listed across Douyin, Kuaishou, Alipay, HarmonyOS, TapTap and iOS since 2024-11, and the project invites others to open a pull request or issue to add theirs. Two shipped titles is not a large body of evidence, but it is evidence that the pipeline reaches a store release rather than only a local build.

The distribution channels in the README are worth knowing about. There is a documentation site, a Discord server, a Bilibili video, a Gitee mirror alongside the GitHub repository, and a Trendshift badge. The multi-language READMEs cover Simplified Chinese, Traditional Chinese, Japanese and Korean.

The top-level entries also include AGENTS.md and CLAUDE.md, files aimed at coding agents, alongside the multi-language READMEs and the scripts/ directory. That is a small signal about the project's working style, and it is also the only documentation of the agent workflow in the repository listing.

What the repository listing does not show is a test suite, a contribution guide, a changelog, or a release pipeline. The absence of those in the top level is worth noting for an adopter, because the documentation site, the source and the community chat become the places where the answers live, and the answers are not versioned alongside the code.

The last push to the repository was on 2026-10-19, four days before this review, so the project is moving. Whether it is moving fast enough to keep a Unity 2019 client and four engine integrations in step with a.NET 10 server is the open question, and the only way to answer it is to look at the commit history before you commit to the stack.

Editorial conclusion

Adopt GameFrameX if you are a solo developer or a small team that wants a working online game loop, with a server, a data pipeline and a client in one repository, and you can work with the fixed choices it makes. Do not adopt it if you need a library you can drop into an existing game, if you cannot run MongoDB, PostgreSQL and Docker locally, or if the pinned toolchain is a problem, because the tutorial assumes Unity 2019.4.40f1 and .NET 10. Verify first that the client runtime you want is the one you will maintain, that the AGPL-3.0 terms suit your distribution model, and that you read the default configuration before starting the server, since the default data source points at a public demo database and the last push was on 2026-10-19 with no GitHub releases published.

Frequently asked questions

Official sources

1. GameFrameX/GameFrameX on GitHub
2. Issues
3. License: AGPL-3.0
4. Project website
5. README