# F1游戏服务端

基于Go语言和Cherry框架构建的SLG（策略类）游戏服务器，采用分布式架构和Actor模型。

## 项目概述

F1游戏服务器是一个高性能、分布式的游戏服务端项目，核心玩法为地图沙盘系统。项目使用以下技术栈：

- **语言**: Go 1.24
- **框架**: Cherry（基于Actor模型的分布式框架）
- **通信**: Protocol Buffers + NATS集群
- **存储**: MongoDB（持久化） + Redis（缓存）
- **架构**: 分布式架构，支持多节点部署

### 开始

- `clone`本仓库，通过`bash`来执行初始化命令
- 安装`protoc` (v3.17.3) 和 `protoc-gen-go` (v1.27.1)
- 执行`make`查询相关指令，执行`make init`进行项目初始化
- 执行`make chmod`设置脚本权限

### 术语定义

- `node` 节点，每个服务进程都称为一个`节点`，通过`节点类型`进行归类
- `pid` 平台id
- `uid` 游戏内用户唯一id
- `playerID` 玩家id
- `openID` 第三方的用户唯一id

### 服务器架构图

(**项目使用基于nats集群的架构**)

[基于nats集群的架构](tool/docs/images/architecture-nats.jpg)
[架构图PNG](docs/architecture.png)

### 节点类型

- **game**: 游戏服节点，核心游戏逻辑和玩家会话，滚服部署
- **gate**: 游戏网关节点，WebSocket/HTTP网关，处理客户端连接，可多节点部署
- **center**: 游戏中心节点，账户管理和支付服务，单节点部署
- **master**: 节点发现服务，仅在NATS模式下使用，实现简易的发现服务功能
- **web**: web节点，主要处理对外的http业务
- **chat**: 聊天节点，处理游戏内聊天功能
- **map**: 地图节点，处理地图沙盘玩法（核心功能）
- **pay**: 支付节点，处理游戏支付相关业务
- **record**: 记录节点，处理游戏记录数据
- **ops**: 运维节点，提供运维相关接口

### 调试&启动

- 每个节点的启动都通过`nodes/main.go`的`run`命令进行
- 启动前先确认`etc/profile/`目录是否有您需要的profile配置
- **内部已部署整套`dev环境`，开发人员仅需启动`game节点`即可进行本地调试**

#### 启动参数示例

- `run -path=./etc/profile/su.json -node=master-1`  启动master类型的节点，环境为`dev`，节点id为`master-1`
- `run -path=./etc/profile/su.json -node=center-1`  启动center类型的节点，环境为`dev`，节点id为`center-1`
- `run -path=./etc/profile/su.json -node=gate-1`  启动gate类型的节点，环境为`dev`，节点id为`gate-1`
- `run -path=./etc/profile/su.json -node=gate-1`  启动gate类型的节点，环境为`dev`，节点id为`gate-1`
- `run -path=./etc/profile/su.json -node=web-1`     启动web类型的节点，环境为`dev`，节点id为`web-1`
- `run -path=./etc/profile/su.json -node=map-1`      启动map类型的节点，环境为`dev`，节点id为`map-1`
- `run -path=./etc/profile/su.json -node=3`         启动game类型的节点，环境为`dev`，节点id为`3`

#### 版本查看
- `run version` 或 `run v` 或 `run ver` 查看节点版本信息

### 调试&启动

- 每个节点的启动都通过`nodes/{xxx}/{xxx}.go`的`Run`函数进行
- 启动前先确认`etc/profile/`目录是否有您需要的profile配置
- **内部已部署整套`dev环境`，开发人员仅需启动`game节点`即可进行本地调试**

#### 启动参数示例

- `run -path=./etc/profile/ryansu.json -node=master-1`  启动master类型的节点，环境为`ryansu`，节点id为`master-1`
- `run -path=./etc/profile/ryansu.json -node=center-1`  启动center类型的节点，环境为`ryansu`，节点id为`center-1`
- `run -path=./etc/profile/ryansu.json -node=gate-1`  启动gate类型的节点，环境为`ryansu`，节点id为`gate-1`
- `run -path=./etc/profile/ryansu.json -node=web-1`     启动web类型的节点，环境为`ryansu`，节点id为`web-1`
- `run -path=./etc/profile/ryansu.json -node=1`         启动game类型的节点，环境为`ryansu`，节点id为`1`


### 构建和发布

#### 常用命令
```bash
# 查看所有可用命令
make help

# 初始化项目（安装protoc-gen-go）
make init

# 构建完整项目（交互模式）
make build

# 非交互模式构建
make build <env> <update_excel> <publish>
# env: 1=dev, 2=test, 3=dev&test, 4=prod
# update_excel: y/Y/1 表示更新并导出Excel数据
# publish: y/Y/1 表示推送到发布仓库

# 仅构建源代码
make code

# 构建Excel数据文件
make excel

# 构建protobuf文件
make proto

# 清理构建产物
make clean

# 清理数据库
make clean_db
```

#### 仓库管理
```bash
# 更新外部仓库
make pull-excel    # 更新Excel配置
make pull-proto   # 更新protobuf定义
make pull-cherry  # 更新Cherry框架

# 设置脚本权限
make chmod
```

#### Excel数据管理
```bash
# 更新Excel仓库并转换为JSON
make pull-e        # 从f1/excel.git更新excel仓库
make e            # 转换xlsx文件到etc/data/并生成go文件到internal/data/
```

#### 测试命令
```bash
# 运行所有测试
go test ./...

# 运行特定测试文件
go test ./tool/test/slice/slice_test.go

# 运行测试并显示详细输出
go test -v ./path/to/test

# 运行单个测试函数
go test -run TestSpecificFunction ./path/to/test

# 运行基准测试
go test -bench=. ./path/to/test

# 运行测试并生成覆盖率报告
go test -cover ./path/to/package
```

### 版本发布
- 执行 `make build`，根据提示选择对应的版本发布。
- 详细的发布流程请参考 `docs/git-flow/` 目录下的git flow文档。

### 模块简介

#### excel

- 本目录为策划excel配表仓库
- 通过`make e`导表
- Excel数据导出到 `etc/data/` 目录

#### protocol

- 本目录为protobuf通信协议仓库，[通信协议包头](tool/docs/images/protocol.jpg)
- 协议文件位于 `internal/pb/` 目录，基于 `/f1/protocol.git` 仓库生成
- 生成逻辑详见`etc/script/build_proto.sh`脚本
- 使用 `make pull-p` 更新protocol.git仓库
- 使用 `make proto` 生成最终的协议文件
- protoc-gen-go v1.27.1
- protoc v3.17.3

#### nodes/center

- 游戏中心节点，单节点部署，用于处理帐号、支付相关公共业务
- 不做具体游戏内的业务

#### nodes/map

- 地图节点，处理地图沙盘玩法（核心功能）
- 包含AOI管理、寻路、联盟地图等功能
- 详细文档请参考 `nodes/map/README.md`

#### nodes/game

- 游戏服节点，滚服部署

#### nodes/gate

- 游戏网关节点，可多节点部署，根据负载情况进行多节点部署
- 可以给每个`区`设置一个网关地址。通过数据库`center.area.gate`字段进行设置
- 可以自行架设反向代理进行多个gate节点集群
- 可通过阿里/腾讯云的`SLB服务`进行多网关节负载部署

#### nodes/master

- 仅在`profile->cluster->discovery`模式为`nats`时使用该节点
- 实现简易的发现服务功能，单节点部署，用于同步/广播节点信息

#### nodes/web

- web节点主要处理对外的http业务

#### nodes/chat

- 聊天节点，处理游戏内聊天相关业务

#### nodes/pay

- 支付节点，处理游戏支付相关业务

#### nodes/record

- 记录节点，处理游戏记录数据相关业务

#### nodes/ops

- 运维节点，提供运维相关接口

#### nodes/match

- 匹配节点，处理游戏匹配相关业务

#### tool

- 工具目录，包含各种开发工具
  - `client-cli`: 客户端命令行工具，用于测试
  - `cleandb`: 数据库清理工具
  - `proto-route`: 协议路由工具
  - `test`: 各种测试工具

#### 数据库

- 通过`gorm`的migrator功能管理数据库结构

### 部署
- TODO (生产环境部署手册)

### QA

#### 1. 文本格式设置
- clone代码前修改git的`Auto Crlf convert`参数。AutoCrlf:false, SafeCrlf:false
- 修改Goland，找到`Settings -> Editor -> Code Style -> Line Separator`修改为`Unix and Macos`

#### 2. 代码编写事项
- XxxID 字段 ID 要大小如`HeroID`不能是小写如`Heroid`或者`HeroId`
- 方法的接收体名称统一使用 p ，这样看到 p.xxx 就知道是当前方法的主体
- 所有的 int 类型统一使用 int32 或者 int64
- 使用GORM进行数据库操作和映射管理
- 遵循Actor模型进行并发操作
- 详细代码风格指南请参考 `AGENTS.md`

#### 3. linux开发环境配置
- 安装`go` https://go.dev/doc/install
- 安装`protoc`  https://github.com/protocolbuffers/protobuf/releases
- 执行`make`或`make help` 查看相关脚本指令
- 执行`make chmod` 设置相关脚本的权限
- 执行`make init` 初始化相关组件

## 项目结构

```
f1-server/
├── nodes/              # 各个节点目录
│   ├── center/         # 中心节点
│   ├── game/           # 游戏节点
│   ├── gate/           # 网关节点
│   ├── master/         # 主节点
│   ├── web/            # Web节点
│   ├── chat/           # 聊天节点
│   ├── map/            # 地图节点（核心功能）
│   ├── pay/            # 支付节点
│   ├── record/         # 记录节点
│   ├── match/          # 匹配节点
│   └── ops/            # 运维节点
├── internal/           # 内部共享代码
│   ├── actor_remote/   # 远程调用
│   ├── component/      # 组件
│   ├── pb/             # 协议文件（自动生成）
│   ├── types/          # 自定义类型
│   └── ...
├── etc/                # 配置文件
│   ├── profile/        # 环境配置
│   ├── data/           # Excel数据（JSON）
│   └── script/         # 脚本文件
├── tool/               # 工具目录
├── docs/               # 文档目录
└── AGENTS.md           # AI代理开发指南
```

## 核心功能

### 地图沙盘系统（nodes/map）

地图沙盘是本项目的核心功能模块，包含以下特性：

- **AOI（Area of Interest）系统**: 分层管理不同类型的地图对象
- **寻路系统**: 支持大地图分区域、分层寻路的A星算法
- **行军系统**: 支持多种行军状态（空闲、停留、撤退、占领、采集、驻守、攻城等）
- **碰撞系统**: 处理行军对象之间的碰撞和战斗逻辑
- **城战系统**: 支持攻城大营、宣战、集结等城战玩法
- **联盟地图**: 支持联盟在地图上的业务逻辑

详细文档请参考 `nodes/map/README.md`。

## 技术特性

- **Actor模型**: 基于Cherry框架的Actor模型，实现高并发处理
- **分布式架构**: 支持多节点部署，可横向扩展
- **NATS集群**: 节点间通过NATS进行通信
- **Protocol Buffers**: 高效的消息序列化
- **MongoDB + Redis**: 持久化存储和高速缓存

## 开发文档

- 开发规范和指南：请参考 `AGENTS.md`
- Git工作流：请参考 `docs/git-flow/`
- 架构文档：请参考 `docs/` 目录

## 快速开始

1. 克隆仓库并初始化：
```bash
git clone <repository-url>
cd f1-server
make init
```

2. 设置脚本权限：
```bash
make chmod
```

3. 更新外部仓库：
```bash
make pull-excel
make pull-proto
```

4. 构建项目：
```bash
make build
```

5. 启动节点：
```bash
run -path=./etc/profile/dev.json -node=10002
```

## 贡献指南

请参考 `docs/git-flow/` 目录下的git flow文档了解开发流程。

## 许可证

[请在此处添加许可证信息]