# xechat-game-server

**Repository Path**: xechat/xechat-game-server

## Basic Information

- **Project Name**: xechat-game-server
- **Description**: 统一后台游戏管理
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-21
- **Last Updated**: 2026-10-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

---
AIGC:
    Label: "1"
    ContentProducer: 001191440300708461136T1XGW3
    ProduceID: 71dfd8187db27d1ff1c323fdb6b34ebf_1545954f9d4a11f19155525400826444
    ReservedCode1: y4VK5zYHK99Lqn7k/nIuIYMj2s1zJX1CncGuUXAzN0QvOh17HlcOMMJ/2z8VNpaNRJ9HJW4SaHRjg8vFTUCTQQsOofLjbzz80CxaS0/fFINbWN3YDNZgjhk5LPUEsjJwxdz7Pwx+LvxL3a3iMlFxdISpWKe/iL2TQfLTzpWkTfFrb2fFZ7Tz/OD2k/8=
    ContentPropagator: 001191440300708461136T1XGW3
    PropagateID: 71dfd8187db27d1ff1c323fdb6b34ebf_1545954f9d4a11f19155525400826444
    ReservedCode2: y4VK5zYHK99Lqn7k/nIuIYMj2s1zJX1CncGuUXAzN0QvOh17HlcOMMJ/2z8VNpaNRJ9HJW4SaHRjg8vFTUCTQQsOofLjbzz80CxaS0/fFINbWN3YDNZgjhk5LPUEsjJwxdz7Pwx+LvxL3a3iMlFxdISpWKe/iL2TQfLTzpWkTfFrb2fFZ7Tz/OD2k/8=
---

# XEChat Game Server

xechat 游戏平台的**游戏服务端骨架与第三方接入文档**。平台提供统一玩家通道（hub，唯一对外端口 9100）+ 游戏 SPI + 加载器 + 斗地主参考实现；第三方开发者按本文档即可独立开发游戏服务端与前端，并上架 xemanager 游戏大厅。

> **注意**：原 `game-gateway` 模块已并入 hub（[xechat-forward-match-lobby](https://gitee.com/xechat/xechat-forward-match-lobby) 的 9100 玩家通道，包名 `cn.xeblog.gameGateway`），本仓内**已不存在 `game-gateway/` 目录**。网关的部署与启停请见该仓库与 [部署步骤](https://gitee.com/xechat/xechat-doc)。

## 快速开始

```bash
# 1. 打包
mvn -q package

# 2. 生成 RSA 密钥对（首次）并启动 hub（塘通道 9527 + 玩家通道 9100 同进程）
#    密钥对生成与测试票据签发用 GatewayMain 入口：
java -cp xechat-forward-match-lobby-*.jar cn.xeblog.gameGateway.GatewayMain keygen
java -cp xechat-forward-match-lobby-*.jar cn.xeblog.gameGateway.GatewayMain ticket
#    启动 hub（玩家通道端口由 application.yml 的 gateway.port 决定，默认 9100）：
java -jar xechat-forward-match-lobby-*.jar

# 3. 启动 launcher 加载游戏服务端
#    ⚠️ LauncherMain 不解析任何命令行参数，配置只读 jar 同级 launcher.yml；
#    先把业务 jar 放进 launcher.yml 的 server-path 目录（默认 ./servers），再启动：
java -jar game-launcher/target/game-launcher-0.1.0.jar

# 4. 玩家连接（可用任意 ws 客户端，如 wscat）
wscat -c "ws://127.0.0.1:9100/ws/player?gameId=doudizhu&ticket=<TICKET>&roomId=r1"
```

> `keygen` / `ticket` 的参数不走命令行，读 hub 的 `application.yml` 中 `gateway.keygen.*` / `gateway.ticket.*`；票据线上由 xemanager 用 RSA 私钥签发。

## 模块说明

| 模块 | 职责 | 产物 |
| --- | --- | --- |
| `game-api` | SPI 接口与公共帧（无第三方依赖），游戏作者依赖此包 | 依赖 jar |
| `game-launcher` | 游戏加载器：URLClassLoader + ServiceLoader 加载业务 jar 并注册玩家通道 | 可执行 fat jar |
| `game-doudizhu` | 斗地主参考实现：状态机 + 房主开局/结束 + AI 补位 | 业务 jar |
| `web` | 斗地主前端（Vite+Vue3）：免登录、WS 对接、ARGB 主题 | 静态站点 |

> 统一玩家通道（9100）由 hub 提供，不在本仓；`frontend-sdk/` 为前端注入用的 match-lobby SDK。

## 核心概念（30 秒速览）

- **玩家通道唯一端口 9100**（hub 提供）：`/ws/server?gameId=&token=` 游戏注册；`/ws/player?gameId=&ticket=&roomId=` 玩家连接；只做路由/转发，不碰业务。
- **游戏服务端**：实现 `XechatGameServer` SPI（或继承 `AbstractGameRoomServer` 获得公共房间能力），注册到 `META-INF/services`，打成 jar 交给 launcher 加载。
- **房主控制**：满员进 `READY`，房主 `start`/`end_game` 控制开局与结束；**满员 10s 未开局自动兜底**（`game_start.auto=true`）。
- **邀请拦截**：已在房间/游戏中的玩家不可被邀请（`invite` / `invite_accept` 双重校验）。
- **前端免登录**：复用游戏大厅 `dld.lesscoding.net` 同域 `satoken`，`POST /xeManager/game/ticket` 换票据后连 WS。

## 文档导航（第三方开发者入口）

| 文档 | 内容 |
| --- | --- |
| [docs/architecture.md](docs/architecture.md) | 平台整体架构图、模块职责、与 xemanager/xechat-web 的接入关系、端口与服务一览 |
| [docs/game-server-dev.md](docs/game-server-dev.md) | **游戏服务端开发指南**：SPI、AbstractGameRoomServer 基类、META-INF/services、打包、launcher 配置（`launcher.yml`） |
| [docs/protocol.md](docs/protocol.md) | **通信协议全量**：ticket 算法、WS 接入、房间命令、业务透传、全部下行帧与上行 PlayerCommand |
| [docs/doudizhu-example.md](docs/doudizhu-example.md) | 斗地主参考实现说明：状态机、房主控制、10s 自动开局、AI 补位、牌型 |
| [docs/frontend-dev.md](docs/frontend-dev.md) | 前端开发指南：项目结构、免登录、/game/ticket 与 /game/players、WS 参数、ARGB+全局透明度主题 |
| [docs/deploy.md](docs/deploy.md) | 部署与上架流程：xemanager 登记、jar 放置 server-path、nohup 启动、日志落盘、自动发布 |
| [docs/troubleshooting.md](docs/troubleshooting.md) | 端到端联调步骤与常见问题（FAQ） |

> 建议阅读顺序：architecture → game-server-dev → protocol → doudizhu-example → frontend-dev → deploy。

## 关键文件速查

```
game-api/src/main/java/cn/xeblog/game/api/
├── XechatGameServer.java        # SPI 接口（gameId / onStart / onPlayerJoin / onPlayerMessage / onPlayerLeave / onTick）
├── AbstractGameRoomServer.java  # 公共房间基类（WAITING/READY/ENDED、满员自动开局、start/end_game）
├── GameRoom.java                # 房间接口（roomId/ownerId/status/autoStartAt/playerCount/maxPlayers/lock/broadcast）
├── PlayerSession.java           # 玩家会话（userId/roomId/send/broadcast）
├── GameContext.java             # 启动上下文（gameId/gatewayUrl/getParameter）
└── frame/                       # 公共帧（err/game_start/game_over/invite/room_closed...）

game-launcher/src/main/java/cn/xeblog/game/launcher/
├── LauncherMain.java            # 启动入口（--game / --config）
└── ...                          # URLClassLoader + ServiceLoader 加载、GatewayClient 注册

game-doudizhu/src/main/java/cn/xeblog/game/doudizhu/
├── DouDiZhuServer.java          # 参考实现（状态机/房主控制/AI）
├── ai/AiPlayer.java             # AI 内存会话
└── frame/ + model/              # 斗地主业务帧与牌型模型
```

> 玩家通道（9100 入口 `GatewayServer`、`RoomManager`、`RsaKeyGen`、`TicketUtil`）已随网关并入 hub，
> 现位于 [xechat-forward-match-lobby](https://gitee.com/xechat/xechat-forward-match-lobby) 的
> `src/main/java/cn/xeblog/gameGateway/`，不在本仓。

## 打包产物

| 模块 | 产物 | 类型 |
| --- | --- | --- |
| game-api | game-api-0.1.0.jar | 依赖 jar |
| game-launcher | game-launcher-0.1.0.jar | 可执行 fat jar |
| game-doudizhu | game-doudizhu-0.1.0.jar | 业务 jar（薄 jar） |
| frontend-sdk | xechat-lobby(.min).js | 前端注入 SDK（IIFE） |

## 环境要求

- JDK 17+
- Maven 3.6+
- Node.js 16+（仅 web/ 需要）
*（内容由AI生成，仅供参考）*