创建新工程

2025-12-05 19:00:14 +08:00
commit ff4fa5fffd
227 changed files with 32804 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,195 @@
+# 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. 启动服务器
+
+```bash
+cd server
+yarn install          # 安装依赖
+yarn build           # 编译 TypeScript
+yarn start           # 启动服务器
+```
+
+开发模式（自动重载）：
+```bash
+yarn dev
+```
+
+### 3. 运行游戏
+
+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。