400 lines
12 KiB
Markdown
400 lines
12 KiB
Markdown
# Zombie Crisis 3 - 项目技术文档
|
||
|
||
## 1. 项目概述
|
||
|
||
Zombie Crisis 3 是一款多人在线僵尸射击游戏，采用客户端-服务器架构，支持最多 4 名玩家同时游戏。
|
||
|
||
### 1.1 技术栈
|
||
|
||
| 层级 | 技术 | 说明 |
|
||
|------|------|------|
|
||
| 后端 | Java + Maven | 游戏逻辑服务器 |
|
||
| 前端 | JavaScript + Vite | Web 客户端 |
|
||
| 渲染 | Three.js | 3D 图形渲染 |
|
||
| 通信 | WebSocket | 实时双向通信 |
|
||
| 协议 | JSON | 消息序列化 |
|
||
|
||
### 1.2 项目结构
|
||
|
||
```
|
||
zp1/
|
||
├── backend/ # Java 游戏服务器
|
||
│ ├── pom.xml # Maven 配置
|
||
│ └── src/main/java/com/zombie/game/
|
||
│ ├── GameServerMain.java # 程序入口
|
||
│ ├── model/ # 数据模型
|
||
│ │ ├── GameWorld.java # 游戏世界主类
|
||
│ │ ├── GameMap.java # 地图与流向场
|
||
│ │ ├── Zombie.java # 僵尸实体
|
||
│ │ ├── Player.java # 玩家实体
|
||
│ │ ├── Bullet.java # 子弹实体
|
||
│ │ ├── Loot.java # 掉落物
|
||
│ │ ├── Room.java # 游戏房间
|
||
│ │ └── Constants.java # 常量定义
|
||
│ └── server/
|
||
│ ├── GameWebSocketServer.java # WebSocket 服务器
|
||
│ └── GameLoop.java # 游戏循环
|
||
│
|
||
├── frontend/ # JavaScript 客户端
|
||
│ ├── package.json
|
||
│ ├── vite.config.js
|
||
│ ├── index.html
|
||
│ └── src/
|
||
│ ├── main.js # 应用入口
|
||
│ ├── game/
|
||
│ │ ├── engine.js # 游戏引擎
|
||
│ │ └── scene.js # Three.js 场景
|
||
│ ├── network/
|
||
│ │ └── client.js # WebSocket 客户端
|
||
│ ├── ui/
|
||
│ │ ├── lobby.js # 大厅界面
|
||
│ │ ├── hud.js # 游戏 HUD
|
||
│ │ └── settings.js # 设置界面
|
||
│ └── utils/
|
||
│ ├── constants.js # 前端常量
|
||
│ ├── input.js # 输入管理
|
||
│ └── grid.js # 网格工具
|
||
│
|
||
└── FLOW_FIELD_NAVIGATION.md # 流向场寻路文档
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 系统架构
|
||
|
||
### 2.1 整体架构图
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 客户端 │
|
||
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
||
│ │ LobbyUI │ │ HUD │ │ Scene │ │ Network │ │
|
||
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
|
||
│ └────────────┴────────────┴────────────┘ │
|
||
│ │ │
|
||
│ ┌─────┴─────┐ │
|
||
│ │GameEngine │ │
|
||
│ └─────┬─────┘ │
|
||
└──────────────────────────┼──────────────────────────────────┘
|
||
│ WebSocket (ws://:8080)
|
||
│
|
||
┌──────────────────────────┼──────────────────────────────────┐
|
||
│ │ 服务器 │
|
||
│ ┌─────┴─────┐ │
|
||
│ │GameWebSocketServer│ │
|
||
│ └─────┬─────┘ │
|
||
│ ┌──────────────────┼──────────────────┐ │
|
||
│ ┌────┴────┐ ┌─────┴─────┐ ┌────┴────┐ │
|
||
│ │ Room │ │ GameLoop │ │ GameWorld│ │
|
||
│ │ Manager │ │ (30 TPS) │ │ │ │
|
||
│ └─────────┘ └─────┬─────┘ └────┬────┘ │
|
||
│ │ │ │
|
||
│ ┌─────┴─────────────────┴─────┐ │
|
||
│ │ Model Entities │ │
|
||
│ │ Player | Zombie | Bullet │ │
|
||
│ └──────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 2.2 游戏循环
|
||
|
||
服务器以固定 30 TPS (Tick Per Second) 运行游戏逻辑：
|
||
|
||
```
|
||
每帧 (约33ms):
|
||
1. updateFlowField() - 更新流向场
|
||
2. updateZombies() - 更新所有僵尸
|
||
3. updateBullets() - 更新所有子弹
|
||
4. updateZombieBullets() - 更新僵尸子弹
|
||
5. checkBulletCollisions()- 子弹碰撞检测
|
||
6. checkZombieAttacks() - 僵尸攻击检测
|
||
7. checkLootCollection() - 拾取物收集
|
||
8. broadcastGameState() - 广播游戏状态
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 核心模块详解
|
||
|
||
### 3.1 GameWorld
|
||
|
||
游戏世界主类，管理所有游戏实体和逻辑。
|
||
|
||
**主要职责**:
|
||
- 管理玩家、僵尸、子弹、掉落物集合
|
||
- 每帧调用所有实体的更新方法
|
||
- 处理实体间的碰撞检测
|
||
- 生成僵尸和管理难度
|
||
|
||
**关键方法**:
|
||
```java
|
||
public void update(float dt)
|
||
private void updateFlowField() // 更新流向场
|
||
private void updateZombies(float dt) // 更新僵尸
|
||
private void updateBullets(float dt) // 更新子弹
|
||
private void checkBulletCollisions() // 子弹碰撞
|
||
private void checkZombieAttacks() // 僵尸攻击
|
||
private void fireWeapon(Player, aimX, aimY) // 武器射击
|
||
```
|
||
|
||
### 3.2 GameMap
|
||
|
||
地图类，包含 32×32 格子地图和流向场寻路系统。
|
||
|
||
**流向场算法优势**:
|
||
- 一次计算，所有僵尸共享
|
||
- 自动适应多个玩家目标
|
||
- O(m) 复杂度，m=地图格子数
|
||
|
||
### 3.3 Zombie
|
||
|
||
僵尸实体，采用流向场移动 + 碰撞解决机制。
|
||
|
||
**移动系统**:
|
||
1. 查询流向场获取移动方向
|
||
2. 选择目标网格中心
|
||
3. 检查格子预留/占用
|
||
4. 移动并处理碰撞分离
|
||
|
||
### 3.4 Player
|
||
|
||
玩家实体，支持客户端预测和服务器校验。
|
||
|
||
**输入处理**:
|
||
```java
|
||
applyMovement(dx, dy, map) // 移动
|
||
setAngle(aimX, aimY) // 瞄准方向
|
||
fireWeapon(player, aimX, aimY) // 射击
|
||
```
|
||
|
||
### 3.5 Bullet
|
||
|
||
子弹实体，支持两种模式：
|
||
|
||
| 模式 | 武器 | 特点 |
|
||
|------|------|------|
|
||
| 弹道 | 手枪/机枪/霰弹枪 | 直线飞行，有射程限制 |
|
||
| 抛物线 | 手雷 | 弧线弹道，触地爆炸 |
|
||
|
||
### 3.6 Room
|
||
|
||
游戏房间，管理玩家列表和游戏状态。
|
||
|
||
**房间状态**:
|
||
- 等待中：玩家加入、准备
|
||
- 游戏中：所有玩家加载游戏
|
||
- 结束：所有玩家离开或游戏结束
|
||
|
||
---
|
||
|
||
## 4. 通信协议
|
||
|
||
### 4.1 消息格式
|
||
|
||
所有消息使用 JSON 格式：
|
||
```json
|
||
{
|
||
"type": "MESSAGE_TYPE",
|
||
"data": { ... }
|
||
}
|
||
```
|
||
|
||
### 4.2 消息类型
|
||
|
||
#### 客户端 → 服务器
|
||
|
||
| 消息类型 | 说明 | 数据 |
|
||
|---------|------|------|
|
||
| `create_room` | 创建房间 | `{playerName}` |
|
||
| `join_room` | 加入房间 | `{roomId, playerName}` |
|
||
| `leave_room` | 离开房间 | - |
|
||
| `ready` | 准备状态切换 | - |
|
||
| `start_game` | 开始游戏 | - |
|
||
| `player_input` | 玩家输入 | `{dx, dy, aimX, aimY, firing, weaponIndex, seq}` |
|
||
|
||
#### 服务器 → 客户端
|
||
|
||
| 消息类型 | 说明 | 数据 |
|
||
|---------|------|------|
|
||
| `room_list` | 房间列表 | `{rooms: [{id, hostName, playerCount}]}` |
|
||
| `room_state` | 房间状态 | `{roomId, hostId, players: [...]}` |
|
||
| `game_started` | 游戏开始 | `{playerId, mapData, players: [...]}` |
|
||
| `game_state` | 游戏状态 | `{players, zombies, bullets, ...}` |
|
||
| `error` | 错误消息 | `{message}` |
|
||
|
||
### 4.3 游戏状态同步
|
||
|
||
每帧广播的游戏状态包含：
|
||
```java
|
||
{
|
||
"players": [{id, x, y, angle, health, weaponIndex}],
|
||
"zombies": [{id, x, y, angle, health, isElite}],
|
||
"bullets": [{id, x, y, z, angle, weapon, ownerId}],
|
||
"zombieBullets": [...],
|
||
"loots": [{id, x, y, type}],
|
||
"explosions": [{x, y, radius}],
|
||
"removedBullets": [id1, id2, ...],
|
||
"gameTime": 120.5,
|
||
"waveNumber": 3,
|
||
"score": 1250
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 武器系统
|
||
|
||
### 5.1 武器配置
|
||
|
||
| 武器 | 伤害 | 射速 | 弹药 | 特点 |
|
||
|------|------|------|------|------|
|
||
| 手枪 | 50 | 400ms | ∞ | 单发，精准 |
|
||
| 机枪 | 15 | 100ms | 100 | 自动，略微散布 |
|
||
| 霰弹枪 | 20×6 | 800ms | 20 | 6发弹丸，高散布 |
|
||
| 手雷 | 120 | 1500ms | 10 | 可蓄力，范围伤害 |
|
||
|
||
### 5.2 手雷机制
|
||
|
||
- **蓄力**：长按射击键蓄力（最多2秒）
|
||
- **射程**：蓄力0-100%对应3-15格距离
|
||
- **弹道**：抛物线飞行
|
||
- **爆炸**：范围3格伤害
|
||
|
||
---
|
||
|
||
## 6. 僵尸系统
|
||
|
||
### 6.1 僵尸类型
|
||
|
||
| 类型 | 生命值 | 速度 | 特殊能力 |
|
||
|------|--------|------|----------|
|
||
| 普通 | 100+ | 2.0+ | 近战攻击 |
|
||
| 精英 | 800 | 1.5 | 远程射击 |
|
||
|
||
### 6.2 精英僵尸攻击
|
||
|
||
- **攻击范围**：8格
|
||
- **攻击间隔**：2秒
|
||
- **子弹伤害**：30
|
||
- **子弹速度**：6
|
||
|
||
### 6.3 难度递增
|
||
|
||
每30秒波次增加：
|
||
- 僵尸生命值 +20
|
||
- 僵尸速度 +0.1
|
||
- 生成间隔 -0.3秒（最低0.8秒）
|
||
|
||
---
|
||
|
||
## 7. 前端渲染
|
||
|
||
### 7.1 Three.js 场景
|
||
|
||
**摄像机**:
|
||
- 透视摄像机，45度FOV
|
||
- 偏移量 (0, 25, 18)
|
||
- 平滑跟随玩家
|
||
|
||
**光照**:
|
||
- 环境光：0x404060
|
||
- 方向光：0xffeedd（带阴影）
|
||
- 点光源：0xff4400
|
||
|
||
### 7.2 实体模型
|
||
|
||
| 实体 | 几何体 | 颜色 |
|
||
|------|--------|------|
|
||
| 玩家 | 圆柱体+球头 | 蓝/红/绿/黄 |
|
||
| 普通僵尸 | 圆柱体+球头 | 0x446633 |
|
||
| 精英僵尸 | 同上+发光球 | 0x882222 |
|
||
| 墙体 | 立方体 | 0x555577 |
|
||
|
||
### 7.3 特效系统
|
||
|
||
- **爆炸**：白色闪光 + 多层球体 + 碎片
|
||
- **枪口火焰**：黄色球体 + 光点
|
||
- **击中效果**：红色球体 + 火花粒子
|
||
- **掉落物**：旋转立方体
|
||
|
||
---
|
||
|
||
## 8. 客户端预测
|
||
|
||
### 8.1 预测机制
|
||
|
||
1. 客户端发送输入（含序列号）
|
||
2. 客户端立即本地预测执行
|
||
3. 服务器执行并返回 `lastProcessedSeq`
|
||
4. 客户端回滚并重放未确认输入
|
||
|
||
### 8.2 输入结构
|
||
|
||
```javascript
|
||
{
|
||
dx: -1~1, // 移动方向 X
|
||
dy: -1~1, // 移动方向 Y
|
||
aimX: worldX, // 瞄准位置 X
|
||
aimY: worldY, // 瞄准位置 Y
|
||
firing: boolean, // 是否射击
|
||
weaponIndex: 0-3, // 武器索引
|
||
grenadeCharge: 0-1, // 手雷蓄力
|
||
grenadeReleased: boolean,
|
||
seq: number // 序列号
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 常量配置
|
||
|
||
### 9.1 服务器常量 (Java)
|
||
|
||
```java
|
||
GRID_SIZE = 32 // 地图尺寸
|
||
PLAYER_SIZE = 0.8f // 玩家碰撞半径
|
||
ZOMBIE_SIZE = 0.8f // 僵尸碰撞半径
|
||
PLAYER_SPEED = 5.0f // 玩家移动速度
|
||
ZOMBIE_BASE_SPEED = 2.0f // 僵尸基础速度
|
||
TICK_RATE = 30 // 服务器Tick率
|
||
```
|
||
|
||
### 9.2 客户端常量 (JavaScript)
|
||
|
||
与服务器保持一致的定义在 `constants.js`。
|
||
|
||
---
|
||
|
||
## 10. 启动与部署
|
||
|
||
### 10.1 服务器启动
|
||
|
||
```bash
|
||
cd backend
|
||
mvn package
|
||
java -jar target/zombie-crisis-server-1.0.0.jar [port]
|
||
# 默认端口 8080
|
||
```
|
||
|
||
### 10.2 客户端启动
|
||
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
npm run dev
|
||
# 访问 http://localhost:5173
|
||
```
|
||
|
||
### 10.3 依赖版本
|
||
|
||
- **Java**: 17+
|
||
- **Maven**: 3.6+
|
||
- **Node.js**: 16+
|
||
- **Three.js**: (通过 npm)
|
||
|
||
---
|
||
|
||
## 11. 相关文档
|
||
|
||
- [流向场寻路系统技术文档](./FLOW_FIELD_NAVIGATION.md) - 僵尸AI寻路详细说明
|