209 lines
5.6 KiB
Markdown
209 lines
5.6 KiB
Markdown
# AI Town Game - Godot 多人在线游戏
|
||
|
||
基于 Godot 4.x 引擎开发的 2D 多人在线 AI 小镇游戏，首个场景为 Datawhale 办公室。
|
||
|
||
## 项目特性
|
||
|
||
- 🎮 2D 多人在线游戏
|
||
- 🌐 网页版优先（HTML5 导出）
|
||
- 📱 预留移动端适配
|
||
- 💬 实时对话系统
|
||
- 🔄 角色在线/离线状态切换
|
||
- 🎨 Datawhale 品牌场景
|
||
|
||
## 技术栈
|
||
|
||
- **游戏引擎**: Godot 4.5.1
|
||
- **客户端语言**: GDScript
|
||
- **服务器**: Node.js + TypeScript + WebSocket
|
||
- **包管理**: Yarn
|
||
- **数据格式**: JSON
|
||
|
||
## 快速开始
|
||
|
||
### 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 办公室
|
||
│ └── TestGameplay.tscn # 测试场景
|
||
├── scripts/ # GDScript 脚本
|
||
├── assets/ # 游戏资源
|
||
├── tests/ # 测试文件
|
||
├── server/ # WebSocket 服务器
|
||
└── .kiro/specs/ # 项目规范文档
|
||
```
|
||
|
||
## 服务器 API
|
||
|
||
WebSocket 服务器监听端口: `8080`
|
||
|
||
### 消息格式
|
||
```json
|
||
{
|
||
"type": "message_type",
|
||
"data": {},
|
||
"timestamp": 1234567890
|
||
}
|
||
```
|
||
|
||
### 主要消息类型
|
||
- `auth_request` / `auth_response` - 身份验证
|
||
- `character_create` - 创建角色
|
||
- `character_move` - 角色移动
|
||
- `character_state` - 角色状态更新
|
||
- `dialogue_send` - 发送对话
|
||
- `world_state` - 世界状态同步
|
||
|
||
详细 API 文档请参考 `server/README.md`
|
||
|
||
## Web 导出
|
||
|
||
1. 在 Godot 中打开 "项目" -> "导出"
|
||
2. 添加 "HTML5" 导出预设
|
||
3. 配置导出选项
|
||
4. 点击 "导出项目"
|
||
|
||
## 开发指南
|
||
|
||
### 添加新场景
|
||
1. 在 `scenes/` 目录创建新场景
|
||
2. 使用 TileMap 绘制地图
|
||
3. 配置碰撞层
|
||
4. 在 WorldManager 中注册场景
|
||
|
||
### 代码风格
|
||
- 变量和函数使用 `snake_case`
|
||
- 类名使用 `PascalCase`
|
||
- 常量使用 `UPPER_CASE`
|
||
- 详细规范请参考 `CODING_STYLE.md`
|
||
|
||
## 故障排除
|
||
|
||
### 常见问题
|
||
|
||
**Q: 角色不显示或不移动？**
|
||
A: 确保游戏窗口是激活状态，检查控制台错误信息
|
||
|
||
**Q: 服务器连接失败？**
|
||
A: 确认服务器正在运行（`yarn dev`），检查端口 8080 是否被占用
|
||
|
||
**Q: 测试失败？**
|
||
A: 查看控制台详细错误信息，确保所有文件已保存
|
||
|
||
## 📚 完整文档
|
||
|
||
### 用户文档
|
||
- **[用户使用手册](USER_MANUAL.md)** - 完整的游戏使用指南
|
||
- **[快速测试指南](HOW_TO_TEST.md)** - 测试游戏功能
|
||
- **[环境配置指南](SETUP.md)** - 开发环境配置
|
||
|
||
### 开发文档
|
||
- **[开发者技术文档](DEVELOPER_GUIDE.md)** - 完整的技术文档和 API 参考
|
||
- **[代码风格指南](CODING_STYLE.md)** - 代码规范和最佳实践
|
||
- **[测试指南](tests/TEST_GUIDE.md)** - 测试框架和使用方法
|
||
- **[属性测试指南](tests/PROPERTY_TEST_GUIDE.md)** - 属性测试详解
|
||
|
||
### 运维文档
|
||
- **[部署和运维指南](DEPLOYMENT_GUIDE.md)** - 生产环境部署
|
||
- **[服务器文档](server/README.md)** - WebSocket 服务器详解
|
||
|
||
### 项目管理
|
||
- **[项目状态](PROJECT_STATUS.md)** - 当前开发状态
|
||
- **[演示指南](DEMO_GUIDE.md)** - 项目演示和展示
|
||
- **[项目规范](.kiro/specs/godot-ai-town-game/)** - 需求、设计和任务文档
|
||
|
||
## 🎯 快速导航
|
||
|
||
| 我想... | 查看文档 |
|
||
|---------|----------|
|
||
| 🎮 **玩游戏** | [用户使用手册](USER_MANUAL.md) |
|
||
| 🧪 **测试功能** | [快速测试指南](HOW_TO_TEST.md) |
|
||
| 💻 **开发扩展** | [开发者技术文档](DEVELOPER_GUIDE.md) |
|
||
| 🚀 **部署上线** | [部署和运维指南](DEPLOYMENT_GUIDE.md) |
|
||
| 📊 **项目演示** | [演示指南](DEMO_GUIDE.md) |
|
||
| 🔧 **配置环境** | [环境配置指南](SETUP.md) |
|
||
|
||
## 许可证
|
||
|
||
MIT License
|
||
|
||
## 联系方式
|
||
|
||
项目相关问题请提交 Issue。 |