Mosaic Game / Mesh Server

这是一个基于 C++17 的游戏服务器示例项目，支持分布式大世界的无缝迁移功能，有一本配套的书籍来介绍当前项目的完整实现细节，书籍的电子版地址见于深入理解游戏服务端:从网络通信到无缝迁移。

当前仓库已经包含：

• 顶层 CMake 工程
• 服务端与客户端角色代码
• 数据导出与代码生成工具
• MongoDB / Redis 的示例配置
• Linux 下的批量启动脚本

1. 项目整体结构

仓库的核心目录可以按职责理解：

目录	作用
src/	顶层公共实现，和 include/ 一起组成 mosaic_game 主库
include/	顶层公共头文件，包含网络、路由、加密、HTTP、工具等模块
common/	通用业务组件与基础库，例如 db_logic、redis_logic、server_utility、entity_common、property、team_handler、group_handler
roles/	具体进程角色，分为 server/ 和 client/
tools/	独立工具程序，例如 export_xlsx、generate_rpc、http_gm_client
generator/	Python 封装脚本和生成配置，用于驱动 RPC、属性、调试命令、公式、表格导出等生成流程
data/	配置、导表结果、地图、调试配置、密钥、Excel 源数据
deploy/	安装输出目录，二进制在 deploy/bin/，启动脚本在 deploy/scripts/，Mongo 初始化脚本在 deploy/mongodb/
deps/	第三方依赖的拉取、编译和安装目录，packages/ 是默认 CMake 查找前缀
third_party/	以源码方式纳入构建的第三方代码，目前包含 RecastNavigation

1.1 服务角色

roles/server/ 下当前包含这些服务进程：

• mgr_server：管理与协调中心
• gate_server：网关入口
• service_server：业务服务节点
• space_server：场景 / 游戏逻辑节点
• map_server：地图相关服务
• db_server：MongoDB 持久化相关服务
• redis_server：Redis 读写与缓存相关服务

roles/client/ 下包含：

• basic_client：客户端基础库
• cli_client：命令行客户端可执行程序

1.2 构建产物

顶层 CMakeLists.txt 将安装前缀固定为 deploy/，因此执行 install 后，可执行文件会进入 deploy/bin/。

当前仓库里已经能看到的典型产物包括：

• 服务端：mgr_server、gate_server、service_server、space_server、map_server、db_server、redis_server
• 客户端：basic_client、cli_client
• 工具：export_xlsx、generate_rpc、http_gm_client
• 生成辅助：generate_property_sync

2. 依赖管理

项目依赖分成三类：系统依赖、通过 deps/install_deps.py 编译安装的依赖、以及少量 Python 运行依赖。

2.1 系统依赖

顶层 CMake 直接查找或依赖以下系统组件：

• CMake 3.12+
• C++17 编译器
• Boost >= 1.71.0（system、date_time）
• OpenSSL
• Threads
• LLVM / Clang 开发环境

Ubuntu 至少需要先安装这些基础包：

sudo apt install libssl-dev libboost-all-dev llvm clang libclang-dev

Windows 平台建议直接安装 LLVM 官方预编译版本：

1. 打开 LLVM Releases 页面：https://github.com/llvm/llvm-project/releases
2. 下载对应版本的 Windows 安装包，通常是类似 LLVM-x.y.z-win64.exe 的文件
3. 安装时勾选加入系统 PATH
4. 安装完成后确认 libclang.dll 位于 LLVM 安装目录的 bin/ 下，常见路径为：C:\Program Files\LLVM\bin\libclang.dll

如果后续需要运行仓库中的生成脚本，还需要把这个 libclang.dll 复制到：

deploy/bin/libclang.dll

如果你希望系统包直接满足更多依赖，也可以额外安装：

• nlohmann-json3-dev
• libfmt-dev
• libspdlog-dev
• libtinyxml2-dev
• redis-server

2.2 deps/install_deps.py 管理的依赖

仓库提供了 deps/install_deps.py，会把缺失的依赖拉到 deps/sources/，在 deps/builds/ 下构建，并安装到 deps/packages/。

脚本当前会处理这些依赖：

• 开源库：nlohmann/json、fmt、spdlog、tinyxml2、miniz、magic_enum、cxxopts、hiredis、mongo-c-driver、mongo-cxx-driver
• 作者维护的库：aoi、any_container、behavior_tree、formula_tree、meta、property_sync、typed_string、xlsx_reader、typed_matrix、http_utils、chat、rank、match_maker、task_channel、distributed_space

建议在仓库根目录执行：

cd deps
python install_deps.py

脚本完成后会把依赖安装到 deps/packages/，顶层工程默认通过 CMAKE_PREFIX_PATH 从这里查找包。

2.3 Python 依赖

以下场景需要 Python 3：

• deploy/scripts/ 下的批量启动 / 停止脚本
• generator/script/ 下的代码生成脚本
• deploy/mongodb/create_index.py 初始化 MongoDB 索引

其中 create_index.py 依赖 pymongo：

python -m pip install pymongo

3. 编译方式

顶层 CMakeLists.txt 当前有这些关键设置：

• C++ 标准：C++17
• MSVC 下额外启用：/std:c++latest /utf-8
• 非 MSVC 下默认启用：-Wall -Wextra -Wno-unused-parameter
• WITH_ASAN 默认是 ON，非 MSVC 编译器会启用 AddressSanitizer
• CMAKE_INSTALL_PREFIX 固定为仓库内的 deploy/
• 开启了 CMAKE_UNITY_BUILD

第一次创建构建目录时，linux需要在代码顶层目录执行以下命令：

cmake -S . -B build  -DCMAKE_PREFIX_PATH="$(pwd)/deps/packages"

如果是windows，需要在代码顶层目录执行以下命令：

cmake -S . -B build -DCMAKE_PREFIX_PATH="$($PWD.Path)\deps\packages"

注意目前项目里有很多反射相关的代码需要在编译之前重新生成，所以执行完上面这个cmake初始化命令之后，还需要额外的操作来触发这些反射文件的生成。

进入build/tools/generate_rpc/目录，执行cmake --build ./ --target install，来生成generate_rpc这个二进制工具并安装到deploy/bin/目录下。

然后再进入generator/script/目录，执行两个代码生成指令:

1. 执行python ./rpc_gen.py all，来生成所有的RPC相关的代码。
2. 执行python ./property_gen.py all，来生成所有的属性同步相关的代码。

执行完成这两步之后，进入build目录，执行cmake ..，来重新配置项目，这样项目里就会包含那些自动生成的文件了。

然后再执行cmake --build ./ --target install --parallel，来生成其他所有的二进制文件，并安装所有的二进制文件到deploy/bin/目录下。

4. 运行与部署设置

4.1 默认配置文件

运行时主要使用这些配置：

• data/config/json_stub_test.json：服务拓扑、监听端口、密钥路径、部分数据目录
• data/config/db_config_test.json：MongoDB 连接配置
• data/config/redis_config_test.json：Redis 连接配置
• data/config/gate_servers.json：网关列表配置

其中 json_stub_test.json 默认定义了一套本地测试拓扑，包含：

• mgr_server
• redis_server_0
• db_server_0
• service_server_0
• gate_server_0
• gate_server_1
• space_server_0
• space_server_1
• map_server_0

4.2 数据目录约定

运行配置默认会引用这些数据：

• data/export/xlsx/：导表结果
• data/export/formula/：公式导出结果
• data/keys/：公私钥文件

如果修改启动目录或手动运行二进制，需要特别注意相对路径是否仍然成立。

4.3 MongoDB 设置

项目默认示例配置是：

• 数据库：mosaic_game
• 用户：test
• 密码：test
• 地址：127.0.0.1:27017

准备步骤通常是：

1. 安装并启动 MongoDB
2. 创建数据库用户，和 data/config/db_config_test.json 保持一致

这里推荐先创建一个管理员用户，用于管理数据库。

use admin
db.createUser({user:"mosaic_admin", pwd:"Mosaic@123456", roles:[{role:"userAdminAnyDatabase", db:"admin"}]})

然后修改/etc/mongod.conf 打开security部分 security authorization: enabled

然后再生成普通用户test，来管理我们服务器真正使用的数据库mosaic_game:

test> use admin
switched to db admin
admin> db.auth("mosaic_admin", "Mosaic@123456")
{ ok: 1 }
admin> use mosaic_game
switched to db mosaic_game
mesh_server> db.createUser({user:"test", pwd:"test", roles:[{role:"dbOwner", db:"mosaic_game"}]})
{ ok: 1 }

3. 进入 deploy/mongodb/ 执行索引初始化脚本

示例：

cd deploy/mongodb
python create_index.py

4.4 Redis 设置

项目默认示例配置是：

• 地址：127.0.0.1:6379
• 密码：test
• 超时：5

这个配置就比较简单了，修改 /etc/redis/redis.conf 打开 bind字段 设置为0.0.0.0 然后打开requirepass 设置为test 请确保 Redis 的认证信息与 data/config/redis_config_test.json 一致。

5. 启动方式

5.1 Linux 下批量启动服务

目前仓库自带的启动脚本只支持 Linux。默认脚本位置：deploy/scripts/。

启动服务端：

cd deploy/scripts
python3 run_servers.py

常用参数：

• -g：space_server 数量
• -s：service_server 数量
• -p：map_server 数量
• -b：db_server 数量
• -t：gate_server 数量
• -c：主配置文件，默认 ../../data/config/json_stub_test.json
• -m：Mongo 配置，默认 ../../data/config/db_config_test.json
• -r：Redis 配置，默认 ../../data/config/redis_config_test.json
• -d：数据目录，默认 ../../data/
• -l：日志目录，默认 ../logs/

脚本会按顺序启动：

1. mgr_server
2. redis_server
3. db_server
4. service_server
5. gate_server
6. space_server
7. map_server

日志默认写入 deploy/logs/。

5.2 Linux 下启动客户端

cd deploy/scripts
python3 run_clients.py

常用参数：

• -n：客户端数量
• -c：配置文件
• -d：数据目录
• -l：日志目录
• -p：起始 HTTP 端口，默认 8200
• -b：机器人配置，默认 idle

5.3 Linux 下停止服务

优先使用管理接口通知停服：

cd deploy/scripts
python3 stop_servers.py

如果需要强制结束进程：

cd deploy/scripts
python3 stop_servers.py -f

5.4 Windows 运行说明

deploy/scripts/run_servers.py、run_clients.py、stop_servers.py 当前都显式限制为 Linux 平台，Windows 下直接运行会退出。

因此在 Windows 上更适合这两种方式：

1. 通过 Visual Studio / VS Code 单独启动某个服务进程进行调试
2. 在 deploy/bin/ 中手动运行对应可执行文件，并显式传入配置路径、日志路径和数据路径

如果需要完善 Windows 一键启动能力，建议后续补一套 PowerShell 启动脚本。

6. 常用开发流程

6.1 第一次拉起项目

cd deps
python install_deps.py

cd ..
cmake -S . -B build -DCMAKE_PREFIX_PATH="$(pwd)/deps/packages"

# 先单独生成并安装 generate_rpc 工具
cd ./build/tools/generate_rpc/
cmake --build ./ --target install

# 回到顶层目录
cd ../..

# 生成 RPC / property 相关代码
cd generator/script
python ./rpc_gen.py all
python ./property_gen.py all

# 重新配置后再进行全量编译安装
cd ../..
cmake -S . -B build -DCMAKE_PREFIX_PATH="$(pwd)/deps/packages"
cmake --build build --parallel
cmake --build build --target install --parallel

然后：

1. 准备 MongoDB 和 Redis
2. 检查 data/config/*.json 中的连接信息
3. 执行 deploy/mongodb/create_index.py
4. 在 Linux 下通过 deploy/scripts/run_servers.py 启动整组服务

6.2 导表和代码生成

项目里存在两类生成流程：

• C++ 工具：export_xlsx、generate_rpc、generate_property_sync
• Python 封装：generator/script/xlsx_gen.py、rpc_gen.py、property_gen.py、debug_gen.py

这些生成步骤依赖已经编译出的工具程序，以及正确可用的 libclang.dll / libclang 环境。

如果有任何rpc相关代码的修改，都需要进入generator/script/目录执行python rpc_gen.py all。

对应的如果有任何的property相关代码的修改，都需要进入generator/script/目录执行python property_gen.py all。