# game_server

Erlang/OTP 游戏服务端 umbrella 工程。项目按职责拆成多个 OTP app，并通过 `rebar3` profiles 组合出游戏服、登录服和压测/客户端模拟服。

## 项目概览

本仓库主要包含：

- `game_server`：核心游戏服，负责 TCP/HTTP 服务、角色与玩法逻辑、缓存、日志、定时任务、跨节点通信等。
- `login_server`：登录服，负责账号登录信息、区服信息、内部账号/IP 白名单、维护状态、合服相关入口等。
- `client_server`：压测/客户端模拟服务，用于连接登录服、游戏服并执行测试模块。
- `game_proto`：协议定义与 protobuf/gpb 生成配置。
- `game_config`：游戏配置表 Erlang 模块及二次加工生成逻辑。
- `base`：公共基础库，包含网络、HTTP、日志、计时器、进程、JSON、排行榜、工具函数等通用能力。

项目依赖 `ranch`、`cowboy`、`ibrowse`、`mysql_poolboy`、`jsx`、`gpb`、`recon`、`ms_cache`、`ms_tbllog` 等库，并使用多个本地 rebar3 插件生成缓存、协议、日志表、功能模块模板和配置加工代码。

## 目录结构

```text
.
+-- apps/
|   +-- base/           # 公共基础库
|   +-- game_config/    # 游戏配置与配置生成结果
|   +-- game_proto/     # proto 协议与生成结果
|   +-- game_server/    # 核心游戏服
|   +-- login_server/   # 登录服
|   +-- client_server/  # 压测/客户端模拟服
+-- config/             # 根 profile 使用的 sys/vm 配置模板
+-- shell/              # 开发、生成、SQL、发布、热更等脚本
+-- _checkouts/         # 本地依赖与 rebar3 插件
+-- rebar.config        # 根构建配置、profiles、release 配置
+-- rebar.config.script # shell/compile 时动态生成私有配置
```

## Rebar Profiles

根 `rebar.config` 定义了几个主要 profile：

| Profile | 说明 | 编译 app |
| --- | --- | --- |
| `game_server` | 游戏服 release/shell | `base`、`game_config`、`game_proto`、`game_server` |
| `login_server` | 登录服 release/shell | `base`、`login_server` |
| `client_server` | 压测/客户端模拟服 | `base`、`game_config`、`game_proto`、`client_server` |
| `config_check` | 配置表加工/校验 | `game_config` |

`rebar.config.script` 会在 `compile` 和 `shell` 时按本机 IP 尾段推导默认 `server_id`，并在 `config_priv/` 下生成私有运行配置，例如：

- `config_priv/sys_game_<server_id>.config`
- `config_priv/sys_login_<server_id>.config`
- `config_priv/sys_client_<server_id>.config`

这些私有配置会覆盖开发开关、GM 开关、数据库名、端口等运行参数。若 `config/` 模板更新后已有 `config_priv/` 文件较旧，脚本会提示手动同步或删除后重新生成。

## 快速开始

前置要求：

- Erlang/OTP
- rebar3
- MySQL 或项目配置中指定的数据库环境
- Windows 下建议使用 PowerShell/Cygwin；Linux 下可直接使用 shell 脚本

编译：

```bash
rebar3 as game_server compile
rebar3 as login_server compile
rebar3 as client_server compile
```

启动开发 shell：

```bash
rebar3 as game_server shell
rebar3 as login_server shell
rebar3 as client_server shell
```

指定多游戏服实例时，可在 profile 名后追加 `_<server_id>`：

```bash
rebar3 as game_server_901 shell
rebar3 as game_server_902 shell
```

动态 profile 会基于 `game_server` profile 复制配置，并把端口调整为：

- TCP：`18000 + server_id`
- HTTP：`19000 + server_id`

## 发布构建

生成 release：

```bash
rebar3 as game_server release
rebar3 as login_server release
rebar3 as client_server release
```

打包 release：

```bash
rebar3 as game_server tar
rebar3 as login_server tar
rebar3 as client_server tar
```

发布产物位于：

```text
_build/<profile>/rel/<profile>/
```

`relx` overlay 会把对应的 `sys.config`、`vm.args`、SQL 文件、定时任务配置等复制到 release 目录。

## 配置说明

根目录 `config/` 放置通用配置模板：

- `sys_game.config` / `vm_game.args`：游戏服运行配置
- `sys_login.config` / `vm_login.args`：登录服运行配置
- `sys_client.config` / `vm_client.args`：压测/客户端模拟服配置
- `cron_game.tab`：游戏服定时任务配置

常见关注项：

- 游戏服：`server_id`、`server_name`、`tcp_port`、`http_port`、`login_node`、`center_node`、开服时间、GM/开发/内网开关。
- 登录服：`server_env`、`login_node_port`、日志配置、缓存/数据库配置。
- 客户端模拟服：目标游戏服 `host/tcp_port`、登录服地址、测试模块列表。
- `ms_cache` / `ms_tbllog`：缓存与日志表落库配置。

注意：本地敏感参数不要写进 README。需要变更数据库、节点名、端口时，优先修改私有配置或部署环境配置。

## 自动生成内容

编译前会自动执行以下 provider hook：

```erlang
protobuf compile
cache compile
cfg_modify gen
user_default compile
```

主要生成物包括：

- `apps/game_proto/src/auto_gen/`：由 `apps/game_proto/proto/*.proto` 生成的 Erlang 协议模块。
- `apps/game_proto/include/`：协议头文件。
- `apps/game_config/src/auto_gen/`：由 `game_cfg` 与 `modify` 加工后的配置模块。
- `apps/*/src/auto_gen/cache/` 与 `include/auto_gen/cache/`：由 `cache/*.table` 生成的缓存访问模块和头文件。
- `apps/game_server/src/auto_gen/user_default/`：shell 辅助函数。

常用生成命令也可以通过 `shell/gen.sh` 中的函数执行：

```bash
rebar3 protobuf compile
rebar3 cache compile
rebar3 tbllog compile
rebar3 cfg_modify gen
rebar3 gen_mod compile -m <module_name>
```

## 核心运行流程

### game_server

`game_server_app:start/2` 的启动流程大致为：

1. 初始化 logger 与应用环境。
2. 启动 `game_server_sup`。
3. 初始化动态 ETS、协议 NIF 缓存、T 后台日志服务和 `ms_cache`。
4. 启动热更新 reloader、事件服务、业务进程树。
5. 游戏服类型为 `game_server` 时启动 crontab、HTTP、TCP。
6. 启动监控服务，注册热更新回调，执行开服后的修复/刷新逻辑。

HTTP 路由来自 `fnapi_handler`、`tblapi_handler`、`rccapi_handler`、`api_handler`。TCP 监听由 `ms_network:start_tcp/5` 启动，鉴权模块为 `login_mod`。

### login_server

`login_server_app:start/2` 的启动流程大致为：

1. 初始化 logger 与应用环境。
2. 启动 `login_server_sup`。
3. 启动 `ms_cache`。
4. 启动登录服 HTTP 服务。
5. 启动登录服业务进程。
6. 启动热更新 reloader。

登录服提供 SDK/API 路由、区服信息、账号登录记录、内部白名单、全服维护、推荐服、合服等管理能力。

### client_server

`client_server` 是轻量测试/压测服务。配置中指定目标游戏服、登录服和测试模块，启动后通过相关测试模块执行连接与业务验证。

## 数据库与 SQL

SQL 文件按服务放置：

- `apps/game_server/sql/`：游戏库、日志库初始化/合服/升级 SQL。
- `apps/login_server/sql/`：登录库初始化/合服 SQL。

缓存表定义位于：

- `apps/game_server/cache/*.table`
- `apps/login_server/cache/*.table`

日志表定义位于：

- `apps/game_server/tbllog/*.table`

修改 `.table` 后需要重新执行对应生成与编译流程。

## 开发约定

- 新增游戏功能模块时，优先参考 `apps/game_server/templates/mod/`，或使用 `rebar3 gen_mod compile -m <module_name>` 生成模板。
- 业务模块通常按 `<module>_mod`、`<module>_lib`、`<module>_data`、`<module>_check`、`<module>_network`、`<module>_log` 拆分。
- 协议变更放在 `apps/game_proto/proto/`，生成后再更新对应 network/mod 处理逻辑。
- 配置表变更放在 `apps/game_config/src/game_cfg/`，需要二次加工时在 `apps/game_config/src/modify/` 增加对应模块。
- 缓存结构变更优先修改 `.table`，由插件生成 record、访问模块和 SQL/prepare 列表。

## 运维脚本

`shell/` 下提供若干辅助脚本：

- `dev.sh`：开发工具主入口，会加载 `config.sh` 以及生成、SQL、服务、SVN 相关脚本。
- `gen.sh`：生成协议、缓存、日志表、功能模板等。
- `sql.sh`：数据库相关操作。
- `srv.sh`：本地/内网服务启停相关操作。
- `server.sh`：发布、重启、热更、全量包/升级包生成。

这些脚本包含环境路径、账号、部署目录等强环境绑定参数，使用前应先检查 `shell/config.sh` 和脚本头部配置。

## 常见命令

```bash
# 清理
rebar3 clean

# 编译游戏服
rebar3 as game_server compile

# 启动游戏服 shell
rebar3 as game_server shell

# 启动指定 server_id 的游戏服 shell
rebar3 as game_server_901 shell

# 编译登录服
rebar3 as login_server compile

# 启动登录服 shell
rebar3 as login_server shell

# 配置检查
rebar3 as config_check compile

# 生成 release
rebar3 as game_server release

# 打 tar 包
rebar3 as game_server tar
```

## 排查建议

- 启动失败先看 `log/error.log`、`log/info.log`、`log/http_info.log`。
- 如果私有配置与模板不一致，删除对应 `config_priv/sys_*_<server_id>.config` 后重新执行 compile/shell 生成。
- 如果协议或配置表模块缺失，先执行 `rebar3 clean` 后重新 `rebar3 as <profile> compile`。
- 如果数据库连接失败，检查 `ms_cache`、`ms_tbllog` 配置以及目标数据库是否已执行初始化 SQL。
- 如果端口冲突，检查 `server_id` 推导值和 `tcp_port/http_port` 是否与其他实例重复。