GameFrameX

All-in-One Solution for Indie Game Development · Empowering Indie Developers' Dreams

Documentation · Quick Start · QQ Group: 467608841 / 233840761

English | 简体中文 | 繁體中文 | 日本語 | 한국어

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

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

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 below):

# 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

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 — same result.

Step 2: Install the prerequisites

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

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

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:

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/)

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.

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):

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<Name> / Resp<Name> / Notify<Name>; field numbers must be < 800; no nested messages. Full rules in GameFrameX.Protobuf.

After editing UI (FairyGUI)

Open FairyGUIProject/Game.fairy with the FairyGUI editor (≥5.0), then File → Publish — make sure "generate code" is checked; output is written into Unity/Assets/ (UI assets + C# binding code) automatically.

Most common newbie issue: Unity reports missing classes after publishing → 9 times out of 10 the "generate code" checkbox wasn't ticked.

Common Pitfalls

Architecture

This is an aggregated release repo — the latest code of the 7 source repos below is synced daily into same-named folders. One download gets you every piece, and the folders are already in the right places (config generation and protocol export find each other via relative paths — don't rename or move them):

GameFrameX/                   # project root
├── Server/                   # game server (.NET 10, Actor model + hot-update)
├── Unity/                    # Unity client project (HybridCLR hot-update, YooAsset)
├── LayaBox/                  # LayaAir client project (alternative client)
├── Config/                   # LuBan config tables: edit Excel here, generate code for both ends
├── Protobuf/                 # protocol: edit .proto here, export code for every end
├── FairyGUIProject/          # UI editing project (open Game.fairy in the FairyGUI editor)
├── Tools/                    # helper tools (protocol-export CLI / GUI)
├── docker/                   # one-command local databases (mongo / postgres)
├── scripts/                  # aggregation sync scripts
└── README / LICENSE etc.

Warning: Editing Server/, Unity/, etc. inside THIS repo is pointless — the daily sync will overwrite your changes. To change code or send PRs, go to the corresponding source repo in the table above.

Repos NOT aggregated (take them as needed):

Platform Support

It supports the major engines — whichever you use, it fits:

Dependencies

Documentation & Resources

All sites serve the same content — use whichever opens for you.

• Main: https://gameframex.doc.alianblank.com
• Mirror 1: https://gameframex-docs.pages.dev
• Mirror 2: https://gameframex.doc.cloudflare.alianblank.com
• Mirror 3: https://gameframex.doc.vercel.alianblank.com

Community & Support

Sponsor

AITKPARTY 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

Blank

blankalian

bambom

PlayerYF

Pilipala

Star History

Changelog

See the GitHub Releases page.

License

See LICENSE.md.

All plugins come from the internet; pay for them yourself when used. If anything infringes your rights, email me and I'll remove it, thanks.

This project must not be used where local law forbids it. Technology is innocent; those who abuse it are not.