README.md · Admin/ts-gameframework

# TSGF是什么（ts-gameframework）

* **开源** 的 **游戏联机** 全栈式解决方案：`服务端自行部署` 或使用 `官方平台服务器` + 游戏客户端对接 `tsgf-sdk`
* **黑盒式** 实现游戏联机：客户端对接SDK，不用关心通信和同步逻辑 （模式参考腾讯的 `MGOBE` ）
* **全分布式的**的集群架构设计：可随在线用户增加而横向拓展服务器集群
* **自定义服务端逻辑**：拓展自己的同步逻辑和各种交互逻辑

# 1. 启动、部署服务端

## 1.1. `./servers/` 目录下执行 `npm install` （执行过一次即可）

## 1.2. 多种方式启动（任选其一）
* a) 开发环境最简启动

* 在 `./servers/` 目录执行 `npm run dev`

（端口：7100，7101，7102，7801，7901 如果被占用将导致启动失败！）

* b) 手动、分布式部署（生产环境时使用）

* `./servers/` 目录下执行 `npm run build`，然后复制出下列目录和文件：

deploy/
        dist/
        node_modules/ （不用此目录，则用 npm i 初始化）
        package.json
        tsgf.server.config.json

* 进阶：将 `tsgf.server.config.json` 文件复制多份，每份修改为一种服务的一个实例（[配置参考](#tsgfserverconfigjson配置参考)），如下目录结构

servers/
            deploy/
            dist/
            node_modules/
            package.json
            tsgf.hallServer.config.json
            tsgf.gameServerCluster.config.json
            tsgf.matchServerCluster.config.json
            tsgf.gameServer01.config.json
            tsgf.matchServer01.config.json
            tsgf.demoServer.config.json
  
  * 修改每个配置文件中的 **runServer** 节点，确定每个配置文件都要启动哪些服务实例
  * 通过启动参数控制当前进程（实例）使用哪个配置文件，如 `node dist/index.js -tsgfConfigFile="../tsgf.hallServer.config.json"`
  * 部署为系统服务
     - windows部署，提供了快捷部署服务方式，右键管理员运行 `deploy/install_runasAdmin.cmd` 即可（需修改其中的服务信息）
     - linux部署，可以使用 `pm2`

* **微信小程序需注意**，因微信平台要求访问的域名是固定的，所以就需要让游戏服务器走统一的反向代理。游戏服务器的地址使用url参数形式进行区分，由反向代理组件实现代理规则（如nginx）。比如：游戏服务器地址配置为：`wss://game.a.com/?srv=n1&port=p` (`game.a.com` 为 nginx 服务器地址)，nginx是支持根据url参数定义代理规则，实际地址是：`ws://n1.game.a.com:p/`，然后 `n1.game.a.com` 解析为内网IP, 指向游戏服务器

# 2. 客户端使用

## tsgf-sdk
核心客户端SDK包, 可不直接引用

## tsgf-sdk-browser
客户端是浏览器环境时引用
## tsgf-sdk-miniapp
客户端是小程序环境时引用

## tsgf-dev-demo-client
demoServer 的客户端封装

## 客户端示例

- [客户端示例合集](https://gitee.com/fengssy/tsgf-demos)

## 版本要求

* tsgf-sdk 1.0.2 要求 tsgf-servers>=1.2.2
* tsgf-sdk 1.3.0 要求 tsgf-servers>=1.3.0

## 应用

* 为 `TSGF开放平台` 的应用，一个开发者可以有多个应用，一般一个应用对应一个游戏，目前平台仅开放体验应用（限制流量），应用标识：`default`， 密钥：`FDGWPRET345-809RGKFER43SKGF`
* 应用自己的用户体系需要对接到 `TSGF` 的玩家体系，`openId` 为应用自己用户的唯一标识，通过服务端授权获得 `TSGF` 的玩家ID以及认证令牌（playerId, playerToken），用于 `tsgf-sdk` 的连接使用。

## 实现自己的应用web服务端

* 即 `demoServer` 的角色。主要负责将应用自己的用户体系对接到 `TSGF` 的玩家体系
* 推荐实现方案:
  * 应用的用户登录后，在应用的web服务器上请求 `TSGF` 大厅的服务端认证接口，获得玩家认证信息（playerId/playerToken等）
  
    *可参考 `src/demoServer/api/ApiPlayerAuth.ts`*
  * 由应用将玩家认证信息返回到客户端，用于客户端的所有需要认证的api

## 匹配功能说明

* 匹配组，只有在相同组才能匹配到一起，决定是否在同一个匹配组的因素有：匹配自定义类型，匹配器标识，maxPlayers，队伍相关配置
* 创建房间时，`ICreateRoomPara.isPrivate` 决定当前房间人不满时是否允许参与匹配（需配置 `ICreateRoomPara.matcherKey）`
* `matcherKey`：匹配器标识定义，不同匹配器的匹配请求之间不会互通。（内置匹配器标识 `MatcherKeys`)
* `matcherParams`：匹配器参数，根据不同的匹配器使用对应的类（请看 `MatcherKeys` 的注释）
* 内置匹配器参数的字段：`resultsContinueRoomJoinUsMatch` 控制匹配成功是创建一个新房间时, 如果人未满，是否允许继续匹配满

## 帧同步设计要求

* 输入操作分离：与“我”无关的逻辑实现

*其实只要是帧同步游戏，就需要做到上面说的设计*

# 3. 设计说明

## 结构介绍

### 服务器结构图

![拓扑图](https://fengssy.gitee.io/zgame/Games/TSGF/ServerStructure.png?v=1.1.1)

### 玩家使用时序图

![时序图](https://fengssy.gitee.io/zgame/Games/TSGF/SequenceDiagram.png?v=1.1.0)

* **应用** 一个开发者可以有多个应用，一般一个应用对应一个游戏。目前统一使用 **default** 应用标识

* **应用web服务器**  为开发者自己实现用户体系的站点，用于将开发者的用户体系对接到 **TSGF** 的玩家体系

* **大厅服务器** 为 HTTP 服务，可使用常规 web 集群方案进行部署，提供如玩家认证、创建房间、查询房间、匹配操作、分配游戏服务器等功能

* **游戏集群管理服务** 为 websocket 服务，用来管理`游戏服务器`的服务，只能部署一个实例

* **游戏服务器** 为 websocket 服务，可以部署多台（横向拓展），部署实例的数量随着在线玩家数量增加而增加。需要能连接到`游戏集群管理服务`，但实例之间并不进行通讯

* **匹配集群管理服务** 为 websocket 服务，用来管理`匹配服务器`的服务，只能部署一个实例

* **匹配服务器** 为 websocket 服务，可以部署多台（横向拓展），部署实例的数量随着应用增加而增加（单应用场景，只需要部署一个实例即可）。需要能连接到`匹配集群管理服务`，但实例之间并不进行通讯。

* 使用 [TSRPC](https://tsrpc.cn/) 作为通讯框架

*并用 `TSRPC` 框架自带的代码生成/同步模块，导致 `client` 目录名以及相对路径的固定（乱改可能会导致出错）*

## 自定义服务端逻辑

* 匹配器
    
    - 新建类，建议存放在 `src/shared/tsgfServer/match/`
    - 实现接口 `src/shared/tsgfServer/match/IMatcher.ts` （可参考同目录下的 `MatcherBaseMelee.ts`）
    - 修改代码 `src/shared/matchServer/BaseMatchServer.ts->onAssignTask` ，加入本匹配器类的实例

## tsgf.server.config.json配置参考

* 本配置使用 `jsonschema` 规范约束，因此在 `vscode` 中修改时有智能提示
* `redisConfig`: 配置连接 `redis` 的信息（运行中修改配置文件时，服务实例会自动重新读取配置） 注意！**redis** 的认证模式不支持用户名为空的情况
* `connString`: 配置连接各个数据库的字符串
  * `appDb`: 配置连接到应用库的连接字符串
* `hallServer`: 配置大厅服务
  * `port`: 侦听的端口
* `gameServerCluster`: 配置游戏集群管理服务
  * `port`: 侦听的端口
  * `nodeList`: 本集群下的所有管理节点（运行中修改配置文件时，服务实例会自动重新读取配置）
    * `clusterNodeId`: 节点ID, 集群内唯一
    * `clusterKey`: 本节点连接集群的密钥
* `matchServerCluster`: 配置匹配集群管理服务
  * `port`: 侦听的端口
  * `nodeList`: 本集群下的所有管理节点（运行中修改配置文件时，服务实例会自动重新读取配置）
    * `clusterNodeId`: 节点ID, 集群内唯一
    * `clusterKey`: 本节点连接集群的密钥
* `gameServer`: 游戏服务（运行中修改配置文件时，服务实例会自动重新读取配置）
  * `clusterWSUrl`: 游戏集群管理服务的连接地址，如 `ws://tsgf-servers:7101/`
  * `clusterNodeId`: 游戏集群中的节点id，需要和游戏集群管理服务的配置 `gameServerCluster.nodeList[].clusterNodeId` 一致
  * `clusterKey`: 游戏集群中的密钥，需要和游戏集群管理服务的配置 `gameServerCluster.nodeList[].clusterKey` 一致
  * `serverName`: 本游戏服务实例的名称，仅用于显示
  * `serverWSUrl`: 客户端连接本服务的地址，如 `ws://127.0.0.1:7801/`
  * `extendData`: 可自定义拓展信息，any类型
  * `listenPort`: 侦听的端口（修改本配置需要重启服务实例）
* `matchServer`: 匹配服务
  * `clusterWSUrl`: 集群管理服务的连接地址，如 `ws://tsgf-servers:7102/`
  * `clusterNodeId`: 集群中的节点id，需要和集群管理服务的配置 `matchServerCluster.nodeList[].clusterNodeId` 一致
  * `clusterKey`: 集群中的密钥，需要和集群管理服务的配置 `matchServerCluster.nodeList[].clusterKey` 一致
  * `serverName`: 本服务实例的名称，仅用于显示
* `demoServer`: 模拟应用自己的WEB服务器，用于将应用自己的用户去映射到玩家，获得玩家的认证信息，以连接到 `TSGF` 的服务
* `runServer`: string[] 决定当前实例启动时运行哪些服务

# 4. 交流群

## QQ群
![QQ群](https://fengssy.gitee.io/zgame/Games/TSGF/TSGF_QQGroupQRCode.png?v=1.1.1)

# 5. 引用

[TSRPC](https://tsrpc.cn/)

Pomu Rainpuff [Nijisanji EN](https://skfb.ly/orVQ7) by scuffward is licensed under [Creative Commons Attribution](http://creativecommons.org/licenses/by/4.0/).

Admin/ts-gameframework

简介

发行版

贡献者

近期动态

Admin/ts-gameframework .gitee-modal { width: 500px !important; }

简介

发行版

贡献者

近期动态

搜索帮助

Admin/ts-gameframework