# ts-gameframework **Repository Path**: code_one/ts-gameframework ## Basic Information - **Project Name**: ts-gameframework - **Description**: typescript游戏联机对战解决方案 - **Primary Language**: TypeScript - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 113 - **Created**: 2023-02-08 - **Last Updated**: 2023-02-08 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 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/).