393 lines
12 KiB
Markdown
393 lines
12 KiB
Markdown
# AI Town Game - Godot 多人在线游戏
|
||
|
||
基于 Godot 4.x 引擎开发的 2D 多人在线 AI 小镇游戏，首个场景为 Datawhale 办公室。
|
||
|
||
## 项目特性
|
||
|
||
- 🎮 2D 多人在线游戏
|
||
- 🌐 网页版优先（HTML5 导出）
|
||
- 📱 预留移动端适配
|
||
- 💬 实时对话系统（支持表情、群聊、历史记录）
|
||
- 🔄 角色在线/离线状态切换
|
||
- 🎨 Datawhale 品牌场景
|
||
- 👤 角色外观自定义系统
|
||
- 🤝 社交功能（好友系统、私聊、关系网络）
|
||
- 📊 数据分析和性能监控
|
||
- 🔒 安全防护（输入验证、速率限制）
|
||
|
||
## 技术栈
|
||
|
||
### 客户端
|
||
- **游戏引擎**: Godot 4.5.1
|
||
- **编程语言**: GDScript
|
||
- **UI框架**: Godot Control 节点系统
|
||
- **动画系统**: Tween + AnimationPlayer
|
||
- **测试框架**: GUT (Godot Unit Test) + 自定义属性测试
|
||
|
||
### 服务器
|
||
- **运行时**: Node.js 24.7.0+
|
||
- **编程语言**: TypeScript
|
||
- **网络协议**: WebSocket (ws 库)
|
||
- **包管理**: Yarn 1.22.22+
|
||
- **数据存储**: JSON 文件系统
|
||
|
||
### 开发工具
|
||
- **版本控制**: Git
|
||
- **部署**: Docker + Nginx
|
||
- **监控**: 自定义健康检查和日志系统
|
||
- **备份**: 自动备份管理器
|
||
|
||
### 数据格式
|
||
- **消息协议**: JSON
|
||
- **角色数据**: Dictionary (GDScript) / Object (TypeScript)
|
||
- **配置文件**: JSON / YAML
|
||
|
||
## 快速开始
|
||
|
||
### 1. 环境要求
|
||
|
||
- Godot 4.5.1+
|
||
- Node.js 24.7.0+
|
||
- Yarn 1.22.22+
|
||
|
||
### 2. 安装 Godot 引擎
|
||
|
||
项目根目录包含 `Godot_v4.5.1-stable_win64.exe.zip` 压缩包，解压后包含两个可执行文件：
|
||
|
||
1. **Godot_v4.5.1-stable_win64.exe** - Godot 引擎主程序（图形界面版本）
|
||
2. **Godot_v4.5.1-stable_win64_console.exe** - 控制台版本（用于命令行操作和调试）
|
||
|
||
**使用步骤**：
|
||
1. 解压 `Godot_v4.5.1-stable_win64.exe.zip`
|
||
2. 双击运行 `Godot_v4.5.1-stable_win64.exe`（主程序）
|
||
3. 在 Godot 项目管理器中点击"导入"
|
||
4. 选择本项目根目录（包含 `project.godot` 文件的目录）
|
||
5. 点击"导入并编辑"即可开始开发和测试
|
||
|
||
### 3. 启动服务器
|
||
|
||
```bash
|
||
cd server
|
||
yarn install # 安装依赖
|
||
yarn build # 编译 TypeScript
|
||
yarn start # 启动服务器
|
||
```
|
||
|
||
开发模式（自动重载）：
|
||
```bash
|
||
yarn dev
|
||
```
|
||
|
||
### 4. 运行游戏
|
||
|
||
1. 启动 Godot 引擎
|
||
2. 点击 "导入"，选择项目根目录的 `project.godot` 文件
|
||
3. 点击 "导入并编辑"
|
||
4. 在 Godot 编辑器中按 F5 或点击 "运行项目" 按钮
|
||
|
||
## 测试游戏
|
||
|
||
### 快速测试（推荐）
|
||
|
||
1. 在 Godot 编辑器中打开 `scenes/TestGameplay.tscn`
|
||
2. 按 **F6** 运行场景
|
||
3. 使用 **WASD** 或方向键移动角色
|
||
|
||
**预期结果**：
|
||
- 看到 Datawhale 办公室场景
|
||
- 角色可以自由移动
|
||
- 相机跟随角色
|
||
- 角色被墙壁和家具阻挡
|
||
|
||
### 运行测试套件
|
||
|
||
1. 在 Godot 编辑器中打开 `tests/RunAllTests.tscn`
|
||
2. 按 **F6** 运行
|
||
3. 查看控制台输出，所有测试应该显示 ✅ PASSED
|
||
|
||
## 游戏控制
|
||
|
||
### 基础控制
|
||
- **移动**: WASD 或方向键
|
||
- **交互**: E 键
|
||
- **退出**: ESC 键
|
||
|
||
### 相机控制（调试模式）
|
||
- **移动相机**: WASD 或方向键
|
||
- **缩放**: 鼠标滚轮
|
||
- **重置**: R 键
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
ai_community/
|
||
├── project.godot # Godot 项目配置
|
||
├── scenes/ # 游戏场景
|
||
│ ├── Main.tscn # 主场景
|
||
│ ├── DatawhaleOffice.tscn # Datawhale 办公室
|
||
│ ├── PlayerCharacter.tscn # 玩家角色
|
||
│ ├── RemoteCharacter.tscn # 远程角色
|
||
│ ├── ErrorNotification.tscn # 错误通知
|
||
│ └── TestGameplay.tscn # 测试场景
|
||
├── scripts/ # GDScript 脚本
|
||
│ ├── 核心系统/
|
||
│ │ ├── Main.gd # 主控制器
|
||
│ │ ├── NetworkManager.gd # 网络管理
|
||
│ │ ├── GameStateManager.gd # 状态管理
|
||
│ │ └── WorldManager.gd # 世界管理
|
||
│ ├── 角色系统/
|
||
│ │ ├── CharacterController.gd # 角色控制
|
||
│ │ ├── CharacterCustomization.gd # 外观自定义
|
||
│ │ ├── CharacterPersonalization.gd # 个性化
|
||
│ │ └── CharacterProfile.gd # 角色档案
|
||
│ ├── 对话系统/
|
||
│ │ ├── DialogueSystem.gd # 对话管理
|
||
│ │ ├── GroupDialogueManager.gd # 群聊
|
||
│ │ ├── PrivateChatSystem.gd # 私聊
|
||
│ │ └── EmojiManager.gd # 表情管理
|
||
│ ├── 社交系统/
|
||
│ │ ├── FriendSystem.gd # 好友系统
|
||
│ │ ├── RelationshipNetwork.gd # 关系网络
|
||
│ │ └── SocialManager.gd # 社交管理
|
||
│ └── 安全与监控/
|
||
│ ├── SecurityManager.gd # 安全管理
|
||
│ ├── RateLimiter.gd # 速率限制
|
||
│ └── PerformanceMonitor.gd # 性能监控
|
||
├── assets/ # 游戏资源
|
||
│ ├── fonts/ # 字体文件
|
||
│ ├── sprites/ # 精灵图
|
||
│ ├── tilesets/ # 瓦片集
|
||
│ └── ui/ # UI 资源
|
||
├── tests/ # 测试文件
|
||
│ ├── RunPropertyTests.gd # 属性测试运行器
|
||
│ └── test_*.gd # 各类测试
|
||
├── server/ # WebSocket 服务器
|
||
│ ├── src/ # 服务器源码
|
||
│ │ ├── server.ts # 主服务器
|
||
│ │ ├── api/ # API 接口
|
||
│ │ ├── backup/ # 备份管理
|
||
│ │ ├── logging/ # 日志系统
|
||
│ │ └── monitoring/ # 监控系统
|
||
│ └── admin/ # 管理界面
|
||
└── .kiro/specs/ # 项目规范文档
|
||
├── godot-ai-town-game/ # 主游戏规格
|
||
└── character-appearance-customization/ # 角色自定义规格
|
||
```
|
||
|
||
## 核心功能
|
||
|
||
### 🎨 角色外观自定义
|
||
- 头部、身体、脚部颜色自定义
|
||
- 预设颜色方案和自定义颜色选择器
|
||
- 实时预览和平滑动画效果
|
||
- 随机生成和重置功能
|
||
|
||
### 💬 增强对话系统
|
||
- 对话历史记录管理
|
||
- 表情符号支持
|
||
- 群组对话功能
|
||
- 对话过滤和审核机制
|
||
|
||
### 🤝 社交功能
|
||
- 好友系统（添加、删除、列表管理）
|
||
- 私聊功能（一对一消息）
|
||
- 角色关系网络（关系强度追踪）
|
||
- 社区活动和事件系统
|
||
|
||
### 🔒 安全防护
|
||
- 输入验证和过滤
|
||
- 速率限制（防止滥用）
|
||
- 会话管理和超时机制
|
||
- 数据传输安全性
|
||
|
||
### 📊 监控与分析
|
||
- 用户行为数据收集
|
||
- 游戏统计和分析
|
||
- 性能监控和报警
|
||
- 服务器健康检查
|
||
- 自动备份和日志管理
|
||
|
||
## 服务器 API
|
||
|
||
WebSocket 服务器监听端口: `8080`
|
||
|
||
### 消息格式
|
||
```json
|
||
{
|
||
"type": "message_type",
|
||
"data": {},
|
||
"timestamp": 1234567890
|
||
}
|
||
```
|
||
|
||
### 主要消息类型
|
||
- `auth_request` / `auth_response` - 身份验证
|
||
- `character_create` - 创建角色（支持外观数据）
|
||
- `character_move` - 角色移动
|
||
- `character_state` - 角色状态更新
|
||
- `dialogue_send` - 发送对话
|
||
- `world_state` - 世界状态同步
|
||
- `friend_request` - 好友请求
|
||
- `private_message` - 私聊消息
|
||
|
||
详细 API 文档请参考 `server/README.md`
|
||
|
||
## Web 导出和部署
|
||
|
||
### 快速导出
|
||
|
||
1. 在 Godot 中打开 "项目" → "导出"
|
||
2. 添加 "Web" 导出预设
|
||
3. 配置导出选项（线程支持、资源嵌入等）
|
||
4. 导出到 `web_build/` 目录
|
||
|
||
### 本地测试
|
||
|
||
```bash
|
||
cd web_build
|
||
python -m http.server 8000
|
||
```
|
||
|
||
访问 http://localhost:8000 测试游戏
|
||
|
||
### 生产部署
|
||
|
||
项目已配置 Docker + Nginx 部署方案：
|
||
|
||
1. **构建 Web 版本**：在 Godot 中导出到 `web_assets/`
|
||
2. **启动服务器**：
|
||
```bash
|
||
cd server
|
||
yarn build
|
||
yarn start
|
||
```
|
||
3. **使用 Docker**：
|
||
```bash
|
||
docker-compose -f docker-compose.prod.yml up -d
|
||
```
|
||
|
||
nginx 配置已针对 Godot Web 优化（CORS 头部、MIME 类型、缓存策略等），配置文件位于 `nginx/nginx.conf`
|
||
|
||
## 项目规格系统
|
||
|
||
本项目采用规范化的开发流程，使用 Spec 文档系统管理需求、设计和实施：
|
||
|
||
### 📋 规格文档结构
|
||
|
||
每个功能模块包含三个核心文档：
|
||
|
||
1. **requirements.md** - 需求文档
|
||
- 用户故事和验收标准
|
||
- 明确的功能需求定义
|
||
- 可验证的验收条件
|
||
|
||
2. **design.md** - 设计文档
|
||
- 系统架构和组件设计
|
||
- 数据模型和接口定义
|
||
- 正确性属性（Property-Based Testing）
|
||
- 错误处理和测试策略
|
||
|
||
3. **tasks.md** - 任务文档
|
||
- 详细的实施计划
|
||
- 任务分解和依赖关系
|
||
- 进度追踪和完成状态
|
||
|
||
### 🎯 当前规格模块
|
||
|
||
#### 主游戏系统 (.kiro/specs/godot-ai-town-game/)
|
||
- **12个核心需求**：角色创建、移动、对话、场景、网络等
|
||
- **30个正确性属性**：确保系统行为的可验证性
|
||
- **23个主要任务组**：涵盖从初始化到最终交付的完整流程
|
||
|
||
#### 角色外观自定义 (.kiro/specs/character-appearance-customization/)
|
||
- **8个功能需求**：默认外观、自定义界面、颜色调整等
|
||
- **18个正确性属性**：保证自定义系统的正确性
|
||
- **模块化设计**：易于扩展和维护
|
||
|
||
### ✅ 正确性属性测试
|
||
|
||
项目使用属性基础测试（Property-Based Testing）确保系统正确性：
|
||
|
||
- **测试覆盖**：48个正确性属性（30个主游戏 + 18个角色自定义）
|
||
- **测试迭代**：每个属性至少100次随机测试
|
||
- **测试标注**：`# Feature: [feature-name], Property X: [description]`
|
||
|
||
示例属性：
|
||
- 角色创建唯一性：任意两个角色的ID必须唯一
|
||
- 数据序列化往返：序列化后反序列化应得到等价对象
|
||
- 碰撞检测：角色不能穿过障碍物
|
||
|
||
## 开发指南
|
||
|
||
### 添加新场景
|
||
1. 在 `scenes/` 目录创建新场景
|
||
2. 使用 TileMap 绘制地图
|
||
3. 配置碰撞层
|
||
4. 在 WorldManager 中注册场景
|
||
|
||
### 添加新功能
|
||
1. 在 `.kiro/specs/` 创建新的规格目录
|
||
2. 编写 requirements.md（需求和验收标准）
|
||
3. 编写 design.md（架构和正确性属性）
|
||
4. 编写 tasks.md（实施计划）
|
||
5. 实现功能并编写属性测试
|
||
|
||
### 代码风格
|
||
- 变量和函数使用 `snake_case`
|
||
- 类名使用 `PascalCase`
|
||
- 常量使用 `UPPER_CASE`
|
||
- 私有变量使用 `_leading_underscore`
|
||
- 详细规范请参考 [开发者技术文档](DEVELOPER_GUIDE.md)
|
||
|
||
## 故障排除
|
||
|
||
### 常见问题
|
||
|
||
**Q: 角色不显示或不移动？**
|
||
A: 确保游戏窗口是激活状态，检查控制台错误信息
|
||
|
||
**Q: 服务器连接失败？**
|
||
A: 确认服务器正在运行（`yarn dev`），检查端口 8080 是否被占用
|
||
|
||
**Q: 测试失败？**
|
||
A: 查看控制台详细错误信息，确保所有文件已保存
|
||
|
||
## 📚 完整文档
|
||
|
||
### 核心文档
|
||
- **[快速测试指南](HOW_TO_TEST.md)** - 测试游戏功能
|
||
- **[开发者技术文档](DEVELOPER_GUIDE.md)** - 技术架构和 API 参考
|
||
- **[环境配置指南](SETUP.md)** - 开发环境配置
|
||
- **[项目状态](PROJECT_STATUS.md)** - 当前开发状态
|
||
- **[服务器文档](server/README.md)** - WebSocket 服务器详解
|
||
|
||
### 项目规范
|
||
- **[主游戏规格](.kiro/specs/godot-ai-town-game/)** - 核心游戏系统的需求、设计和任务
|
||
- [需求文档](.kiro/specs/godot-ai-town-game/requirements.md) - 12个核心需求，30个正确性属性
|
||
- [设计文档](.kiro/specs/godot-ai-town-game/design.md) - 架构设计和技术方案
|
||
- [任务文档](.kiro/specs/godot-ai-town-game/tasks.md) - 实施计划和进度追踪
|
||
- **[角色外观自定义规格](.kiro/specs/character-appearance-customization/)** - 角色个性化系统
|
||
- [需求文档](.kiro/specs/character-appearance-customization/requirements.md) - 8个功能需求，18个正确性属性
|
||
- [设计文档](.kiro/specs/character-appearance-customization/design.md) - UI设计和数据模型
|
||
|
||
## 🎯 快速导航
|
||
|
||
| 我想... | 查看文档 |
|
||
|---------|----------|
|
||
| 🧪 **测试功能** | [快速测试指南](HOW_TO_TEST.md) |
|
||
| 💻 **开发扩展** | [开发者技术文档](DEVELOPER_GUIDE.md) |
|
||
| <20> **配置扩环境** | [环境配置指南](SETUP.md) |
|
||
| <20> ***查看进度** | [项目状态](PROJECT_STATUS.md) |
|
||
| 🖥️ **服务器 API** | [服务器文档](server/README.md) |
|
||
| 📋 **了解需求** | [主游戏需求](.kiro/specs/godot-ai-town-game/requirements.md) |
|
||
| 🏗️ **查看架构** | [系统设计文档](.kiro/specs/godot-ai-town-game/design.md) |
|
||
| ✅ **追踪任务** | [任务列表](.kiro/specs/godot-ai-town-game/tasks.md) |
|
||
| 🎨 **角色自定义** | [外观自定义规格](.kiro/specs/character-appearance-customization/) |
|
||
|
||
## 许可证
|
||
|
||
MIT License
|
||
|
||
## 联系方式
|
||
|
||
项目相关问题请提交 Issue。 |