datawhale/whale-town

Fork 0

Files

moyin 9e0b559c05 完善文档

2025-12-05 19:04:50 +08:00

5.6 KiB

Raw Permalink Blame History

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 压缩包，解压后包含两个可执行文件：

Godot_v4.5.1-stable_win64.exe - Godot 引擎主程序（图形界面版本）
Godot_v4.5.1-stable_win64_console.exe - 控制台版本（用于命令行操作和调试）

使用步骤：

解压 Godot_v4.5.1-stable_win64.exe.zip
双击运行 Godot_v4.5.1-stable_win64.exe（主程序）
在 Godot 项目管理器中点击"导入"
选择本项目根目录（包含 project.godot 文件的目录）
点击"导入并编辑"即可开始开发和测试

3. 启动服务器

cd server
yarn install          # 安装依赖
yarn build           # 编译 TypeScript
yarn start           # 启动服务器

开发模式（自动重载）：

yarn dev

4. 运行游戏

启动 Godot 引擎
点击 "导入"，选择项目根目录的 project.godot 文件
点击 "导入并编辑"
在 Godot 编辑器中按 F5 或点击 "运行项目" 按钮

测试游戏

快速测试（推荐）

在 Godot 编辑器中打开 scenes/TestGameplay.tscn
按 F6 运行场景
使用 WASD 或方向键移动角色

预期结果：

看到 Datawhale 办公室场景
角色可以自由移动
相机跟随角色
角色被墙壁和家具阻挡

运行测试套件

在 Godot 编辑器中打开 tests/RunAllTests.tscn
按 F6 运行
查看控制台输出，所有测试应该显示 ✅ 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

消息格式

{
  "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 导出

在 Godot 中打开 "项目" -> "导出"
添加 "HTML5" 导出预设
配置导出选项
点击 "导出项目"

开发指南

添加新场景

在 scenes/ 目录创建新场景
使用 TileMap 绘制地图
配置碰撞层
在 WorldManager 中注册场景

代码风格

变量和函数使用 snake_case
类名使用 PascalCase
常量使用 UPPER_CASE
详细规范请参考 CODING_STYLE.md

故障排除

常见问题

Q: 角色不显示或不移动？ A: 确保游戏窗口是激活状态，检查控制台错误信息

Q: 服务器连接失败？ A: 确认服务器正在运行（yarn dev），检查端口 8080 是否被占用

Q: 测试失败？ A: 查看控制台详细错误信息，确保所有文件已保存

📚 完整文档

用户文档

用户使用手册 - 完整的游戏使用指南
快速测试指南 - 测试游戏功能
环境配置指南 - 开发环境配置

开发文档

开发者技术文档 - 完整的技术文档和 API 参考
代码风格指南 - 代码规范和最佳实践
测试指南 - 测试框架和使用方法
属性测试指南 - 属性测试详解

运维文档

部署和运维指南 - 生产环境部署
服务器文档 - WebSocket 服务器详解

项目管理

项目状态 - 当前开发状态
演示指南 - 项目演示和展示
项目规范 - 需求、设计和任务文档

🎯 快速导航

我想...	查看文档
🎮 玩游戏	用户使用手册
🧪 测试功能	快速测试指南
💻 开发扩展	开发者技术文档
🚀 部署上线	部署和运维指南
📊 项目演示	演示指南
🔧 配置环境	环境配置指南

许可证

MIT License

联系方式

项目相关问题请提交 Issue。

5.6 KiB Raw Permalink Blame History Unescape Escape