# GameFrameX
[](LICENSE.md)
[](https://gameframex.doc.alianblank.com)
[](https://trendshift.io/repositories/20145)
[](https://discord.gg/VDWUjWMDw9)
[](https://github.com/GameFrameX/gameframex)
[](https://www.bilibili.com/video/BV1yrpeepEn7)
[](https://gitee.com/GameFrameX/gameframex)
All-in-One Solution for Indie Game Development · Empowering Indie Developers' Dreams
[Documentation](https://gameframex.doc.alianblank.com) · [Quick Start](#quick-start) · QQ Group: 467608841 / 233840761
**English** | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md)
## Project Overview
**An open-source toolbox that helps you take a game all the way "from idea → built → live and running."**
When you make a game, the really hard part usually isn't "drawing a character or coding a skill" — it's stitching all those pieces together:
- Where do player save files live? How do you read them back?
- In a multiplayer game, how does the server forward messages?
- Who manages items, levels, and progression data? What happens when a designer changes something?
- After launch, how do you read the data, manage players, and ship new versions?
All that heavy lifting is already done for you by GameFrameX — you just focus on the fun part: "is my game actually fun?"
### Features
| What you'd otherwise DIY | What GameFrameX hands you out of the box |
|---|---|
| Writing a multiplayer server from scratch | A ready-made high-performance server (written in .NET, built for many concurrent players) |
| Figuring out how to store data | Player data in MongoDB (fast), backend data in PostgreSQL (rock-solid) |
| Hand-carrying Excel configs into code | LuBan turns Excel into code and data in one click |
| Client and server "speaking the same language" | ProtoBuf unifies the protocol — change once, both sides sync |
| Flying blind after launch | A built-in admin web panel for reading data / managing players / pushing configs |
| Server deployment giving you a headache | One-click packaging and deployment with Docker |
> Plain and simple: **even a solo developer can build and run an online game like a small team would.**
**Who is it for:**
- Indie developers who want to make **online / multiplayer games** but are stuck on "how do I even do the server?"
- Small teams that want to quickly spin up a **game prototype** to validate an idea
- Learners who want to go through the full "client + server + backend" pipeline end-to-end
### Showcase
| Game | Channels | Live since |
|:---|:---|:---|
| 深夜的烧烤店 (Midnight BBQ) | [TapTap](https://www.taptap.cn/app/384964) | 2024-04-15 |
| 连续黑白 | Douyin, Kuaishou, Alipay, HarmonyOS, TapTap, iOS, etc. | 2024-11 |
> Shipped a game with GameFrameX? Open a PR or issue to add it to the list.
## Quick Start
**This repo IS the complete project**: git clone, Code → Download ZIP, or any mirror site — whatever way you download it, it runs as-is. No extra pulls needed.
Three steps (details in the [tutorial](#installation) below):
```shell
# 1. Start the local database (MongoDB, user admin / admin)
cd docker/mongo && docker compose up -d
# 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"
# 3. Open the Unity/ project with Unity 2019.4.40f1, load Assets/Scenes/Launcher.unity, press Play
```
If you see the login screen and can create a character into the main city, the full client↔server loop works.
Is the server up? Check the listening ports: `nc -z localhost 29100` (TCP) and `nc -z localhost 28080` (HTTP) — success means it's alive. (Port 29090 is the metrics port and is **off by default** — see the port table below.)
### Installation
Follow along — about 10–15 minutes (Unity first import included).
#### Step 1: Download the project
```shell
git clone https://github.com/GameFrameX/GameFrameX.git
cd GameFrameX
```
Don't want git? **Code → Download ZIP** on GitHub, or grab it from a mirror like [gitee](https://gitee.com/GameFrameX/GameFrameX) — same result.
#### Step 2: Install the prerequisites
| Install | Version | Where |
|---|---|---|
| **.NET SDK** | **10.0 or newer** | https://dotnet.microsoft.com/download |
| **Unity Editor** | **2019.4.40f1** (Unity Hub → Installs → Install Editor → Archive) | https://unity.com/download |
| **Docker Desktop** | any recent | https://www.docker.com/ |
> **Note**: .NET 10 is a hard requirement for the server and the table-generation tool — get this one right.
#### Step 3: Start the local database
```shell
cd docker/mongo
docker compose up -d
```
That's MongoDB: `mongodb://admin:admin@localhost:27017` (data lands in `docker/mongo/database/`).
> PostgreSQL (`docker/postgres/`) serves the Admin backend — this tutorial doesn't need it.
#### Step 4: Build & start the server
```shell
cd ../../Server
dotnet build
cd bin/app_debug
dotnet GameFrameX.Launcher.dll --DataBaseUrl="mongodb://admin:admin@localhost:27017/?authSource=admin"
```
**Why only one argument?** The defaults (see `Server/GameFrameX.Launcher/StartUp/AppStartUpGame.cs`) already open the full port set:
| Port | Purpose | Default |
|---|---|---|
| 29100 | TCP: long-lived game client connections | on |
| 28080 | HTTP: login and other APIs (`/game/api/...`) | on |
| 29110 | WebSocket | off — start with `--IsEnableWebSocket true` |
| 29090 | metrics / health | off — start with `--IsOpenTelemetryMetrics true --MetricsPort 29090` |
The only thing to override is `DataBaseUrl` — the default points at a public demo database; point it at the MongoDB you just started.
**Even simpler with an IDE**: open `Server/Server.slnx` with Rider / Visual Studio (`Server.sln` if `.slnx` isn't supported), set the startup project to `GameFrameX.Launcher`, **set Working directory to `Server/bin/app_debug`**, leave arguments empty — and change the `DataBaseUrl` default in `AppStartUpGame.cs` to your local connection string (that edits a file inside the aggregated repo, fine for local debugging — see the overwrite note below).
**Verify**: `nc -z localhost 29100 && nc -z localhost 28080` in a terminal — success means it's alive (or check the server log for `has been started` / `Now listening on`).
#### Step 5: Connect the Unity client
1. Open the `Unity/` folder with **2019.4.40f1** via Unity Hub (first open pulls Packages — needs internet, be patient)
2. Load the scene `Assets/Scenes/Launcher.unity`
3. Press **Play**
The client defaults to `127.0.0.1` (TCP 29100 / HTTP 28080), matching the server's default ports — no config changes needed. Seeing the login screen and creating a character into the main city means the tutorial is complete.
> Moving to another machine / a remote server? Change two spots: the TCP address in `Unity/Assets/Hotfix/UI/Logic/UILogin/UIPlayerList.cs` (`serverIp` / `serverPort`), and the HTTP address in `Unity/Assets/Hotfix/UI/Logic/UILogin/UILogin.cs` etc. (search for `127.0.0.1:28080`).
#### Prefer the LayaAir client?
Open `LayaBox/` with the LayaAir IDE; entry point `src/Main.ts`. Two gotchas: WebSocket is **off by default** — start the server with `--IsEnableWebSocket true` first (default WsPort 29110; `nettest.ts` defaults to `ws://127.0.0.1:21100`, which does NOT match — align them); the connect address lives in `LayaBox/src/gameframex/nettest.ts`; protocol generation uses `Protobuf/Proto2TsExport_LayaBox.sh`.
## Usage Examples
The downloaded snapshot **ships with all generated artifacts** (config code/data, protocol code — all in place), so it runs as-is. Only regenerate when you change a source file:
### After editing Excel configs (`Config/Excels/Tables/`)
| What you changed | Run | Output goes to |
|---|---|---|
| tables the server reads | `cd Config && sh gen-server-bin.sh` (Windows: double-click `gen-server-bin.bat`) | `Server/GameFrameX.Config/` |
| tables the client reads | `cd Config && sh gen-client-json.sh` | `Unity/Assets/` (code + data) |
> File naming matters: `letter-EnglishName-ChineseName.xlsx` (e.g. `D-ItemConfig-道具表-道具-1001.xlsx`); the first 4 rows in each sheet are the header (`##var` / `##type` / `##group` / description), data starts at row 5. Full rules in [GameFrameX.Config](https://github.com/GameFrameX/GameFrameX.Config).
### After editing the protocol (`Protobuf/*.proto`)
The export tool is not shipped in the repo — build it once (the aggregated layout already satisfies its output-path requirements):
```shell
cd Tools
dotnet build ProtoExport/ProtoExport.csproj -c Release # output lands in ../Protobuf/Tools/ automatically
cd ../Protobuf
sh Proto2CsExport_Server.sh # server protocol → Server/GameFrameX.Proto/
sh Proto2CsExport_Client.sh # client protocol → Unity/Assets/Hotfix/Proto/
```
> Protocol hard rules: proto3 only; `option module = 10;` is mandatory; messages must be named `Req
](https://www.linkedin.com/in/alianblank)
[](https://www.reddit.com/r/GameFrameX/)
[](https://x.com/alian_blank)
[](https://www.youtube.com/channel/UCD9QhSFJ5xZkn5NTSV-DVAw)
[](https://bsky.app/profile/alianblank.bsky.social)
[](https://www.bilibili.com/video/BV1yrpeepEn7)
[](https://gitee.com/GameFrameX/gameframex)
### Sponsor
[AITKPARTY](https://aitkparty.com/) is an AI LLM API relay/aggregation service built on the open-source New API project, giving developers one unified interface to major language models — no need to integrate each provider yourself.
### Contributors
