12 KiB
12 KiB
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 压缩包，解压后包含两个可执行文件：
- 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 办公室
│ ├── 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
消息格式
{
"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 导出和部署
快速导出
- 在 Godot 中打开 "项目" → "导出"
- 添加 "Web" 导出预设
- 配置导出选项（线程支持、资源嵌入等）
- 导出到
web_build/目录
本地测试
cd web_build
python -m http.server 8000
访问 http://localhost:8000 测试游戏
生产部署
项目已配置 Docker + Nginx 部署方案：
- 构建 Web 版本：在 Godot 中导出到
web_assets/ - 启动服务器：
cd server yarn build yarn start - 使用 Docker：
docker-compose -f docker-compose.prod.yml up -d
nginx 配置已针对 Godot Web 优化（CORS 头部、MIME 类型、缓存策略等），配置文件位于 nginx/nginx.conf
项目规格系统
本项目采用规范化的开发流程，使用 Spec 文档系统管理需求、设计和实施：
📋 规格文档结构
每个功能模块包含三个核心文档：
-
requirements.md - 需求文档
- 用户故事和验收标准
- 明确的功能需求定义
- 可验证的验收条件
-
design.md - 设计文档
- 系统架构和组件设计
- 数据模型和接口定义
- 正确性属性（Property-Based Testing）
- 错误处理和测试策略
-
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必须唯一
- 数据序列化往返：序列化后反序列化应得到等价对象
- 碰撞检测：角色不能穿过障碍物
开发指南
添加新场景
- 在
scenes/目录创建新场景 - 使用 TileMap 绘制地图
- 配置碰撞层
- 在 WorldManager 中注册场景
添加新功能
- 在
.kiro/specs/创建新的规格目录 - 编写 requirements.md（需求和验收标准）
- 编写 design.md（架构和正确性属性）
- 编写 tasks.md（实施计划）
- 实现功能并编写属性测试
代码风格
- 变量和函数使用
snake_case - 类名使用
PascalCase - 常量使用
UPPER_CASE - 私有变量使用
_leading_underscore - 详细规范请参考 开发者技术文档
故障排除
常见问题
Q: 角色不显示或不移动？ A: 确保游戏窗口是激活状态，检查控制台错误信息
Q: 服务器连接失败？
A: 确认服务器正在运行（yarn dev），检查端口 8080 是否被占用
Q: 测试失败？ A: 查看控制台详细错误信息，确保所有文件已保存
📚 完整文档
核心文档
项目规范
🎯 快速导航
| 我想... | 查看文档 |
|---|---|
| 🧪 测试功能 | 快速测试指南 |
| 💻 开发扩展 | 开发者技术文档 |
| <EFBFBD> 配置扩环境 | 环境配置指南 |
| <EFBFBD> *查看进度 | 项目状态 |
| 🖥️ 服务器 API | 服务器文档 |
| 📋 了解需求 | 主游戏需求 |
| 🏗️ 查看架构 | 系统设计文档 |
| ✅ 追踪任务 | 任务列表 |
| 🎨 角色自定义 | 外观自定义规格 |
许可证
MIT License
联系方式
项目相关问题请提交 Issue。