# 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。