# h5game-assistant

**Repository Path**: bzm121/h5game-assistant

## Basic Information

- **Project Name**: h5game-assistant
- **Description**: 狼人杀/谁是卧底 桌游辅助平台（Server+Client 同仓）：Node.js 后端 + Cocos Creator 客户端，WebSocket 实时同步
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-09-09
- **Last Updated**: 2026-10-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# h5game-assistant

> 狼人杀 / 谁是卧底 桌游辅助平台（**Server + Client** 同仓库，Monorepo 形态）

线下桌游（狼人杀、谁是卧底）经常需要一个"上帝视角"的工具来记录发言、统计票数、管理词库。本项目为此而做：主持人用一台平板或手机，玩家用各自手机扫码加入房间，所有数据实时同步到后端。

## 🧩 项目结构

```
h5game-assistant/
├── server/                  # 后端（Node.js + MySQL + WebSocket）
│   ├── app.js              # 入口
│   ├── configs/            # 业务配置
│   ├── models/             # 数据模型
│   ├── routes/             # HTTP 路由
│   ├── services/           # 业务服务层
│   ├── ws/                 # WebSocket 频道管理
│   ├── sql/                # 表结构与种子数据
│   ├── utils/              # 工具函数
│   ├── doc/                # 内部文档
│   └── h5game/             # 静态资源（前端构建产物）
└── client/                  # 前端（Cocos Creator）
    ├── assets/             # 场景与脚本
    │   ├── scene/          # 场景文件
    │   └── scripts/        # TS 脚本（Modal 弹窗等）
    ├── settings/           # 项目配置
    ├── profiles/           # 构建配置
    ├── package.json
    ├── tsconfig.json
    └── README.md
```

## ✨ 功能特性

### 服务端
- 🚀 **Node.js + 原生 WS**，无 Socket.IO 依赖
- 🗄️ **MySQL 持久化**，含房间、玩家、发言、投票、词库等表
- 🔐 **微信开放平台接入**（公众号 OAuth 登录）
- 👤 **管理员后台**（用户名密码登录）
- 🛌 **断线重连** + 心跳保活
- 📊 **实时数据推送**：发言、投票、上警、遗言等

### 客户端（Cocos Creator）
- 🎨 **原创 assets** — 全部 UI 资源自主绘制，拒绝通用素材
- 🪟 **Modal 弹窗组件**（`Modal.ts`）+ 灰色遮罩 + fade-in/fade-out 动效
- 📱 **多端适配** — 主持人端（平板）+ 玩家端（手机）双模式
- 🌐 **WS 实时通信** — 发言、票型、状态变更秒级同步

## 🚀 快速开始

### Server

```bash
cd server
cp .env.example .env
# 编辑 .env：DB_HOST/DB_USER/DB_PASSWORD/DB_NAME/WECHAT_APPID/...
npm install
node app.js
```

### Client

1. 用 **Cocos Creator 3.x** 打开 `client/` 目录
2. 配置 `server` 地址（在 `assets/scripts/Config.ts` 的 `BASE_URL`）
3. 构建 → 发布到 `server/h5game/`

## 🗄️ 数据库

- 表结构：`server/sql/h5game.sql`
- 默认含 13 张表（房间、玩家、发言、投票、词库等），见 `server/doc/`

## 🛠️ 技术栈

| 层 | 选型 |
|---|---|
| 后端 | Node.js 22（内置 `http` / `ws`）+ MySQL 8 |
| 实时通信 | 原生 WebSocket |
| 鉴权 | JWT + Session + 微信 OAuth |
| 前端 | Cocos Creator 3 + TypeScript |
| 部署 | PM2 + Nginx |

## 📜 许可证

## 📜 许可证 / License

本项目基于 **Apache License 2.0** 开源 — 详见 [LICENSE](LICENSE) 与 [NOTICE](NOTICE)。

Copyright 2026 白志明 (Bai Zhiming)