# 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) |
| � **配置扩环境** | [环境配置指南](SETUP.md) |
| � ***查看进度** | [项目状态](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。