datawhale/whale-town
1
1
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: datawhale:fe82d8f267889de33acb3527888c9daca8f65508
Branches Tags
datawhale:main
...
compare: datawhale:main
Branches Tags
datawhale:main

2 Commits
fe82d8f267 ... main

Author SHA1 Message Date
moyin
4f5e546245 Merge branch 'main' of https://gitea.xinghangee.icu/datawhale/whale-town 2025-12-06 17:36:31 +08:00
moyin
419d2939f6 调整readme 2025-12-06 17:33:14 +08:00
5 changed files with 693 additions and 32 deletions
Expand all files Collapse all files

0
.kiro/specs/multi-client-sync-fix/design.md Normal file
View File

92
.kiro/specs/multi-client-sync-fix/requirements.md Normal file
View File

@@ -0,0 +1,92 @@
# 需求文档
## 简介
本文档规定了修复 AI Town 游戏中多客户端同步问题的需求。目前，当多个 Web 客户端同时连接时，存在严重的同步问题：新角色的外观无法正确显示，新创建的角色看不到已存在的角色，角色之间无法相互交流。
## 术语表
- **客户端（Client）**: 运行游戏的 Web 浏览器实例
- **角色（Character）**: 游戏世界中由玩家控制的实体
- **服务器（Server）**: 管理游戏状态的 WebSocket 服务器
- **世界状态（World State）**: 游戏中所有角色及其属性的完整状态
- **角色外观（Character Appearance）**: 视觉属性，包括身体颜色、头部颜色和精灵信息
- **角色状态消息（Character State Message）**: 包含角色信息的网络消息，包括 ID、名称、位置、在线状态和外观数据
- **世界状态消息（World State Message）**: 包含所有角色及其状态的完整列表的网络消息
- **广播（Broadcast）**: 向除发送者外的所有已连接客户端发送消息
## 需求
### 需求 1
**用户故事：** 作为玩家，我希望在其他角色加入游戏时看到他们的正确外观，以便我可以在视觉上区分不同的玩家。
#### 验收标准
1. WHEN 创建新角色时 THEN 服务器 SHALL 向所有已连接的客户端广播包含外观数据的完整角色状态
2. WHEN 客户端接收到角色状态消息时 THEN 客户端 SHALL 提取外观数据并应用到角色精灵上
3. WHEN 角色在世界中生成时 THEN 客户端 SHALL 使用外观数据中的正确身体颜色和头部颜色渲染角色
4. WHEN 角色状态消息中缺少外观数据时 THEN 客户端 SHALL 使用默认外观值
5. WHILE 角色在世界中可见时 THEN 客户端 SHALL 始终保持角色的外观属性一致
### 需求 2
**用户故事：** 作为加入游戏的新玩家，我希望看到世界中所有现有的角色，以便我可以与已经在线的其他玩家互动。
#### 验收标准
1. WHEN 客户端成功认证时 THEN 服务器 SHALL 发送包含所有在线角色的世界状态消息
2. WHEN 客户端接收到世界状态消息时 THEN 客户端 SHALL 生成或更新消息中列出的所有角色
3. WHEN 从世界状态生成角色时 THEN 客户端 SHALL 包含完整的角色数据（包括外观）
4. WHEN 角色已在本地存在时 THEN 客户端 SHALL 更新现有角色而不是创建重复角色
5. WHILE 处理世界状态时 THEN 客户端 SHALL 从远程角色生成中排除玩家自己的角色
### 需求 3
**用户故事：** 作为玩家，我希望向其他玩家发送消息并接收他们的消息，以便我可以在游戏世界中进行交流和互动。
#### 验收标准
1. WHEN 玩家发送对话消息时 THEN 服务器 SHALL 向所有已连接的客户端广播该消息
2. WHEN 客户端接收到对话消息时 THEN 客户端 SHALL 在适当的 UI 元素中显示该消息
3. WHEN 显示对话消息时 THEN 客户端 SHALL 显示发送者的角色名称
4. WHEN 消息发送给特定角色时 THEN 服务器 SHALL 仅将消息传递给该角色的客户端
5. WHILE 对话系统处于活动状态时 THEN 客户端 SHALL 为每个对话维护消息历史记录
### 需求 4
**用户故事：** 作为开发者，我希望服务器在所有状态消息中包含完整的角色数据，以便客户端拥有正确渲染角色所需的所有信息。
#### 验收标准
1. WHEN 创建角色状态消息时 THEN 服务器 SHALL 包含 id、name、position、isOnline 和 appearance 字段
2. WHEN 广播角色状态时 THEN 服务器 SHALL 序列化完整的角色对象（包括嵌套的外观数据）
3. WHEN 角色外观发生变化时 THEN 服务器 SHALL 向所有客户端广播更新的外观
4. WHEN 从磁盘加载角色时 THEN 服务器 SHALL 保留所有外观数据
5. WHILE 维护角色状态时 THEN 服务器 SHALL 确保外观数据在保存和加载操作中的完整性
### 需求 5
**用户故事：** 作为玩家，我希望角色同步在多个客户端之间可靠工作，以便所有玩家的游戏状态保持一致。
#### 验收标准
1. WHEN 角色移动时 THEN 服务器 SHALL 向所有其他客户端广播位置更新
2. WHEN 角色上线时 THEN 服务器 SHALL 向所有客户端广播在线状态
3. WHEN 角色下线时 THEN 服务器 SHALL 向所有客户端广播离线状态
4. WHEN 接收到角色状态更新时 THEN 客户端 SHALL 仅将更新应用于远程角色而不是玩家自己的角色
5. WHILE 多个客户端连接时 THEN 服务器 SHALL 在所有客户端之间维护一致的状态
### 需求 6
**用户故事：** 作为开发者，我希望所有新的同步功能与现有系统逻辑完美融合，以便系统保持稳定且不引入新的错误。
#### 验收标准
1. WHEN 实现新的同步逻辑时 THEN 系统 SHALL 保持与现有网络管理器的兼容性
2. WHEN 修改角色状态广播时 THEN 系统 SHALL 保持与现有 MessageProtocol 的消息格式一致性
3. WHEN 更新世界管理器时 THEN 系统 SHALL 保持与现有角色生成和移除逻辑的兼容性
4. WHEN 处理角色外观数据时 THEN 系统 SHALL 保持与现有 CharacterData 和 CharacterController 的数据结构一致性
5. WHEN 添加新的消息处理逻辑时 THEN 系统 SHALL 不破坏现有的安全验证、速率限制和错误处理机制
6. WHEN 修改客户端同步逻辑时 THEN 系统 SHALL 保持与现有游戏状态管理器的状态转换逻辑一致性
7. WHILE 实现多客户端同步时 THEN 系统 SHALL 确保不与现有的单客户端功能（如玩家移动、对话系统）产生冲突

299
DEVELOPER_GUIDE.md Normal file
View File

@@ -0,0 +1,299 @@
# 开发者技术文档
## 项目架构
### 客户端架构
```
Main (Node)
├─ NetworkManager (Node) - 网络连接管理
├─ GameStateManager (Node) - 游戏状态管理
├─ UILayer (CanvasLayer) - UI 层
│ ├─ LoginScreen (Control) - 登录界面
│ ├─ CharacterCreation (Control) - 角色创建界面
│ ├─ HUD (Control) - 游戏内 UI
│ └─ DialogueBox (Control) - 对话框
└─ GameWorld (Node2D) - 游戏世界
├─ TileMap (TileMap) - 场景地图
├─ Characters (Node2D) - 角色容器
│ ├─ PlayerCharacter (CharacterBody2D) - 本地玩家
│ └─ RemoteCharacter (CharacterBody2D) - 其他角色
└─ Camera (Camera2D) - 摄像机
```
### 服务器架构
```
WebSocket Server (Node.js + TypeScript)
├─ ConnectionManager - 管理客户端连接
├─ AuthenticationService - 身份验证
├─ CharacterManager - 角色管理
├─ WorldState - 世界状态管理
├─ MessageRouter - 消息路由
├─ AdminAPI - 管理接口
├─ BackupManager - 备份管理
├─ LogManager - 日志管理
└─ HealthChecker - 健康检查
```
## 核心系统
### 网络管理器 (NetworkManager)
**职责**: 管理客户端与服务器的 WebSocket 连接
**主要方法**:
```gdscript
func connect_to_server(url: String) -> void
func disconnect_from_server() -> void
func send_message(message: Dictionary) -> void
func is_connected() -> bool
```
**信号**:
- `connected_to_server()` - 连接成功
- `disconnected_from_server()` - 断开连接
- `connection_error(error: String)` - 连接错误
- `message_received(message: Dictionary)` - 收到消息
### 角色控制器 (CharacterController)
**职责**: 处理角色的移动、动画和状态
**主要属性**:
```gdscript
var character_id: String
var character_name: String
var is_online: bool
var move_speed: float = 200.0
```
**主要方法**:
```gdscript
func move_to(direction: Vector2) -> void
func set_position_smooth(target_pos: Vector2) -> void
func play_animation(anim_name: String) -> void
func set_online_status(online: bool) -> void
```
### 对话系统 (DialogueSystem)
**职责**: 管理角色之间的对话交互
**主要方法**:
```gdscript
func start_dialogue(target_character_id: String) -> void
func send_message(message: String) -> void
func end_dialogue() -> void
func show_bubble(character_id: String, message: String, duration: float) -> void
```
**信号**:
- `dialogue_started(character_id: String)`
- `dialogue_ended()`
- `message_received(sender: String, message: String)`
## 数据模型
### 角色数据
```gdscript
{
"id": "unique_character_id",
"name": "角色名称",
"owner_id": "player_account_id",
"position": {
"x": 100.0,
"y": 200.0
},
"is_online": true,
"appearance": {
"head_color": "#F5DEB3",
"body_color": "#4169E1",
"foot_color": "#8B4513"
},
"created_at": 1234567890,
"last_seen": 1234567890
}
```
### 消息协议
所有消息使用 JSON 格式：
```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` - 私聊消息
## 扩展功能
### 角色外观自定义
**组件**:
- `CharacterCustomization.gd` - 外观自定义管理
- `CharacterPersonalization.gd` - 个性化设置
- `CharacterProfile.gd` - 角色档案
**外观数据结构**:
```gdscript
{
"head_color": "#F5DEB3",
"body_color": "#4169E1",
"foot_color": "#8B4513",
"created_at": 1234567890,
"version": "1.0"
}
```
### 社交系统
**组件**:
- `FriendSystem.gd` - 好友管理
- `PrivateChatSystem.gd` - 私聊功能
- `RelationshipNetwork.gd` - 关系网络
- `SocialManager.gd` - 社交管理器
### 安全系统
**组件**:
- `SecurityManager.gd` - 安全管理
- `RateLimiter.gd` - 速率限制
- `DialogueFilter.gd` - 对话过滤
**速率限制配置**:
```gdscript
{
"max_requests": 10,
"time_window": 60.0, # 秒
"cooldown": 5.0 # 秒
}
```
## 添加新功能
### 1. 创建规格文档
在 `.kiro/specs/` 创建新目录：
```
.kiro/specs/your-feature/
├── requirements.md # 需求和验收标准
├── design.md # 架构和设计
└── tasks.md # 实施计划
```
### 2. 实现功能
创建必要的脚本和场景：
```
scripts/YourFeature.gd
scenes/YourFeature.tscn
```
### 3. 编写测试
创建测试文件：
```
tests/test_your_feature.gd
```
### 4. 集成到主系统
在 `Main.gd` 或相关管理器中集成新功能。
## 代码规范
### 命名约定
- 变量和函数: `snake_case`
- 类名: `PascalCase`
- 常量: `UPPER_CASE`
- 私有变量: `_leading_underscore`
### 注释规范
```gdscript
## 类文档注释
## 描述类的用途和职责
class_name MyClass
## 函数文档注释
## 参数:
## - param1: 参数描述
## 返回: 返回值描述
func my_function(param1: String) -> int:
# 行内注释
return 0
```
### 信号定义
```gdscript
## 当某事件发生时触发
signal event_happened(data: Dictionary)
```
## 性能优化
### 对象池
使用对象池减少内存分配：
```gdscript
var object_pool: Array = []
func get_object():
if object_pool.is_empty():
return create_new_object()
return object_pool.pop_back()
func return_object(obj):
object_pool.append(obj)
```
### 网络优化
- 使用消息批处理
- 实现状态差异同步
- 减少不必要的网络请求
### 渲染优化
- 使用视锥剔除
- 优化碰撞检测
- 减少节点数量
## 调试技巧
### 打印调试
```gdscript
print("Debug:", variable)
print_debug("Stack trace")
```
### 断点调试
在代码行号左侧点击设置断点，按 F5 运行调试模式。
### 性能分析
使用 Godot 内置的性能监视器：
```gdscript
Performance.get_monitor(Performance.TIME_FPS)
Performance.get_monitor(Performance.MEMORY_STATIC)
```
## 服务器 API
详细的服务器 API 文档请参考 [server/README.md](server/README.md)
## 相关文档
- [项目状态](PROJECT_STATUS.md) - 当前开发状态
- [测试指南](HOW_TO_TEST.md) - 测试方法
- [环境配置](SETUP.md) - 开发环境配置
- [主游戏规格](.kiro/specs/godot-ai-town-game/) - 核心系统规格
- [角色自定义规格](.kiro/specs/character-appearance-customization/) - 外观系统规格

107
HOW_TO_TEST.md Normal file
View File

@@ -0,0 +1,107 @@
# 快速测试指南
## 快速开始
### 方法 1: 快速测试场景（推荐）
1. 在 Godot 编辑器中打开 `scenes/TestGameplay.tscn`
2. 按 **F6** 运行当前场景
3. 使用 **WASD** 或方向键移动角色
**预期结果**：
- ✅ 看到 Datawhale 办公室场景
- ✅ 角色可以自由移动
- ✅ 相机跟随角色
- ✅ 角色被墙壁和家具阻挡
### 方法 2: 完整游戏测试
1. 确保服务器正在运行：
```bash
cd server
yarn dev
```
2. 在 Godot 编辑器中按 **F5** 运行主场景
3. 输入用户名并创建角色
4. 测试移动、对话等功能
## 运行测试套件
### 属性测试
1. 在 Godot 编辑器中打开 `tests/RunPropertyTests.gd`
2. 按 **F6** 运行
3. 查看控制台输出
**测试覆盖**：
- 键盘输入响应
- 服务器同步
- 在线/离线角色显示
- 错误显示
- 重连机制
### 单元测试
运行特定测试文件：
1. 打开 `tests/test_*.gd` 文件
2. 按 **F6** 运行
3. 查看测试结果
**可用测试**：
- `test_character_controller.gd` - 角色控制器测试
- `test_character_data.gd` - 角色数据测试
- `test_input_handler.gd` - 输入处理测试
- `test_game_state_manager.gd` - 状态管理测试
- `test_message_protocol.gd` - 消息协议测试
- `test_security_manager.gd` - 安全管理测试
- `test_rate_limiter.gd` - 速率限制测试
## 测试功能
### 角色移动
- 使用 WASD 或方向键
- 角色应该平滑移动
- 不能穿过墙壁和障碍物
### 相机控制（调试模式）
- **移动相机**: WASD 或方向键
- **缩放**: 鼠标滚轮
- **重置**: R 键
### 网络功能
- 创建角色
- 查看其他在线角色
- 角色状态同步
### 对话系统
- 接近其他角色
- 按 E 键交互
- 发送消息
## 常见问题
**Q: 测试失败怎么办？**
A: 查看控制台详细错误信息，确保所有文件已保存
**Q: 服务器连接失败？**
A: 确认服务器正在运行（`yarn dev`），检查端口 8080 是否被占用
**Q: 角色不显示？**
A: 确保游戏窗口是激活状态，检查控制台错误信息
## 性能测试
### 帧率测试
- 目标: 30+ FPS
- 查看 Godot 编辑器右上角的 FPS 显示
### 网络延迟
- 目标: 操作响应 < 200ms
- 观察角色移动的流畅度
## 下一步
- 查看 [项目状态](PROJECT_STATUS.md) 了解已完成功能
- 查看 [SETUP.md](SETUP.md) 了解开发环境配置
- 查看 [server/README.md](server/README.md) 了解服务器 API

227
README.md
View File

@@ -7,17 +7,40 @@
- 🎮 2D 多人在线游戏
- 🌐 网页版优先（HTML5 导出）
- 📱 预留移动端适配
- 💬 实时对话系统
- 💬 实时对话系统（支持表情、群聊、历史记录）
- 🔄 角色在线/离线状态切换
- 🎨 Datawhale 品牌场景
- 👤 角色外观自定义系统
- 🤝 社交功能（好友系统、私聊、关系网络）
- 📊 数据分析和性能监控
- 🔒 安全防护（输入验证、速率限制）
## 技术栈
### 客户端
- **游戏引擎**: Godot 4.5.1
- **客户端语言**: GDScript
- **服务器**: Node.js + TypeScript + WebSocket
- **包管理**: Yarn
- **数据格式**: JSON
- **编程语言**: 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
## 快速开始
@@ -102,14 +125,88 @@ ai_community/
├── 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`
@@ -125,11 +222,13 @@ WebSocket 服务器监听端口: `8080`
### 主要消息类型
- `auth_request` / `auth_response` - 身份验证
- `character_create` - 创建角色
- `character_create` - 创建角色（支持外观数据）
- `character_move` - 角色移动
- `character_state` - 角色状态更新
- `dialogue_send` - 发送对话
- `world_state` - 世界状态同步
- `friend_request` - 好友请求
- `private_message` - 私聊消息
详细 API 文档请参考 `server/README.md`
@@ -153,10 +252,70 @@ python -m http.server 8000
### 生产部署
项目已配置 Docker + Nginx 部署方案，nginx 配置已针对 Godot Web 优化（包含 CORS 头部、MIME 类型、缓存策略等）。
项目已配置 Docker + Nginx 部署方案：
详细的导出配置、部署步骤、性能优化和问题排查，请参考：
**[Web 部署完整指南](WEB_DEPLOYMENT_GUIDE.md)**
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必须唯一
- 数据序列化往返：序列化后反序列化应得到等价对象
- 碰撞检测：角色不能穿过障碍物
## 开发指南
@@ -166,11 +325,19 @@ python -m http.server 8000
3. 配置碰撞层
4. 在 WorldManager 中注册场景
### 添加新功能
1. 在 `.kiro/specs/` 创建新的规格目录
2. 编写 requirements.md（需求和验收标准）
3. 编写 design.md（架构和正确性属性）
4. 编写 tasks.md（实施计划）
5. 实现功能并编写属性测试
### 代码风格
- 变量和函数使用 `snake_case`
- 类名使用 `PascalCase`
- 常量使用 `UPPER_CASE`
- 详细规范请参考 `CODING_STYLE.md`
- 私有变量使用 `_leading_underscore`
- 详细规范请参考 [开发者技术文档](DEVELOPER_GUIDE.md)
## 故障排除
@@ -187,39 +354,35 @@ A: 查看控制台详细错误信息，确保所有文件已保存
## 📚 完整文档
### 用户文档
- **[用户使用手册](USER_MANUAL.md)** - 完整的游戏使用指南
### 核心文档
- **[快速测试指南](HOW_TO_TEST.md)** - 测试游戏功能
- **[开发者技术文档](DEVELOPER_GUIDE.md)** - 技术架构和 API 参考
- **[环境配置指南](SETUP.md)** - 开发环境配置
### 开发文档
- **[开发者技术文档](DEVELOPER_GUIDE.md)** - 完整的技术文档和 API 参考
- **[代码风格指南](CODING_STYLE.md)** - 代码规范和最佳实践
- **[测试指南](tests/TEST_GUIDE.md)** - 测试框架和使用方法
- **[属性测试指南](tests/PROPERTY_TEST_GUIDE.md)** - 属性测试详解
### 运维文档
- **[部署和运维指南](DEPLOYMENT_GUIDE.md)** - 生产环境部署
- **[项目状态](PROJECT_STATUS.md)** - 当前开发状态
- **[服务器文档](server/README.md)** - WebSocket 服务器详解
### 项目管理
- **[项目状态](PROJECT_STATUS.md)** - 当前开发状态
- **[演示指南](DEMO_GUIDE.md)** - 项目演示和展示
- **[项目规范](.kiro/specs/godot-ai-town-game/)** - 需求、设计和任务文档
### 项目规范
- **[主游戏规格](.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设计和数据模型
## 🎯 快速导航
| 我想... | 查看文档 |
|---------|----------|
| 🎮 **玩游戏** | [用户使用手册](USER_MANUAL.md) |
| 🧪 **测试功能** | [快速测试指南](HOW_TO_TEST.md) |
| 💻 **开发扩展** | [开发者技术文档](DEVELOPER_GUIDE.md) |
| 🚀 **部署上线** | [部署和运维指南](DEPLOYMENT_GUIDE.md) |
| 🖥️ **服务器部署** | [服务器部署完整指南](SERVER_DEPLOYMENT_GUIDE.md) |
| 🌐 **Web 部署** | [Web 部署完整指南](WEB_DEPLOYMENT_GUIDE.md) |
| ✅ **部署检查清单** | [部署检查清单](DEPLOYMENT_CHECKLIST.md) |
| 📊 **项目演示** | [演示指南](DEMO_GUIDE.md) |
| 🔧 **配置环境** | [环境配置指南](SETUP.md) |
| <EFBFBD> **配置扩环境** | [环境配置指南](SETUP.md) |
| <EFBFBD> ***查看进度** | [项目状态](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/) |
## 许可证