调整readme
This commit is contained in:
moyin
345
SETUP.md
345
SETUP.md
@@ -1,132 +1,275 @@
|
||||
# 环境配置指南
|
||||
# AI Town Game - 开发与运行指南
|
||||
|
||||
## 环境要求
|
||||
|
||||
- **Godot 4.5.1+** - 游戏引擎
|
||||
- **Node.js 24.7.0+** - JavaScript 运行时
|
||||
- **Yarn 1.22.22+** - 包管理器
|
||||
- **Godot Engine**: 4.5.1 或更高版本
|
||||
- **Node.js**: 18+ (用于后端服务器)
|
||||
- **Git**: 用于版本控制
|
||||
|
||||
## 快速配置
|
||||
## 快速开始
|
||||
|
||||
### 1. 安装 Godot
|
||||
### 1. 克隆项目
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd ai_community
|
||||
```
|
||||
|
||||
1. 从 [Godot 官网](https://godotengine.org/download) 下载 Godot 4.5.1+
|
||||
2. 解压并运行 Godot 引擎
|
||||
### 2. 安装服务器依赖
|
||||
```bash
|
||||
cd server
|
||||
npm install
|
||||
```
|
||||
|
||||
### 2. 打开项目
|
||||
### 3. 配置环境变量
|
||||
```bash
|
||||
# 复制环境配置文件
|
||||
cp .env.example .env
|
||||
|
||||
1. 启动 Godot 引擎
|
||||
# 编辑 .env 文件，配置你的设置
|
||||
```
|
||||
|
||||
### 4. 启动开发服务器
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
服务器将在 `http://localhost:3000` 运行
|
||||
|
||||
### 5. 在 Godot 中打开项目
|
||||
|
||||
1. 打开 Godot Engine
|
||||
2. 点击 "导入"
|
||||
3. 浏览到项目目录，选择 `project.godot` 文件
|
||||
3. 选择项目目录中的 `project.godot` 文件
|
||||
4. 点击 "导入并编辑"
|
||||
|
||||
### 3. 安装服务器依赖
|
||||
### 6. 运行游戏
|
||||
|
||||
```bash
|
||||
cd server
|
||||
yarn install
|
||||
```
|
||||
|
||||
### 4. 启动开发环境
|
||||
|
||||
**启动服务器**：
|
||||
```bash
|
||||
cd server
|
||||
yarn dev
|
||||
```
|
||||
|
||||
**运行游戏**：
|
||||
在 Godot 编辑器中按 F5
|
||||
在 Godot 编辑器中：
|
||||
- 按 **F5** 运行游戏
|
||||
- 或点击右上角的 "播放" 按钮
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
ai_community/
|
||||
├── project.godot # Godot 项目配置
|
||||
├── scenes/ # 游戏场景
|
||||
├── scripts/ # GDScript 脚本
|
||||
├── assets/ # 游戏资源
|
||||
├── tests/ # 测试文件
|
||||
├── server/ # WebSocket 服务器
|
||||
│ ├── src/ # TypeScript 源码
|
||||
│ ├── data/ # 数据存储
|
||||
│ └── package.json # 服务器依赖
|
||||
└── .kiro/specs/ # 项目规范文档
|
||||
├── .godot/ # Godot 缓存（不提交）
|
||||
├── assets/ # 游戏资源
|
||||
│ ├── fonts/ # 字体文件
|
||||
│ ├── icon/ # 图标
|
||||
│ ├── sprites/ # 精灵图
|
||||
│ ├── tilesets/ # 瓦片集
|
||||
│ └── ui/ # UI 资源
|
||||
├── scenes/ # Godot 场景文件
|
||||
├── scripts/ # GDScript 脚本
|
||||
│ ├── ChineseFontLoader.gd # 中文字体加载器
|
||||
│ └── ... # 其他游戏脚本
|
||||
├── server/ # 后端服务器
|
||||
│ ├── src/ # 服务器源码
|
||||
│ └── admin/ # 管理界面
|
||||
├── tests/ # 测试文件
|
||||
├── nginx/ # Nginx 配置
|
||||
├── project.godot # Godot 项目配置
|
||||
├── export_presets.cfg # 导出预设
|
||||
└── README.md # 项目说明
|
||||
```
|
||||
|
||||
## 输入映射
|
||||
|
||||
项目已配置以下输入映射：
|
||||
|
||||
- **ui_left**: 左方向键 / A 键
|
||||
- **ui_right**: 右方向键 / D 键
|
||||
- **ui_up**: 上方向键 / W 键
|
||||
- **ui_down**: 下方向键 / S 键
|
||||
- **interact**: E 键
|
||||
|
||||
## 开发工作流
|
||||
|
||||
1. **启动服务器**: `cd server && yarn dev`
|
||||
2. **打开 Godot**: 导入并打开项目
|
||||
3. **编写代码**: 在 `scripts/` 目录创建 GDScript 文件
|
||||
4. **创建场景**: 在 `scenes/` 目录创建 .tscn 文件
|
||||
5. **测试**: 按 F5 运行游戏或 F6 运行当前场景
|
||||
6. **提交代码**: 使用 Git 提交更改
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q: 如何更改服务器端口？
|
||||
|
||||
A: 编辑 `server/src/server.ts`，修改端口号（默认 8080）
|
||||
|
||||
### Q: 如何添加新的依赖？
|
||||
|
||||
A: 在 `server/` 目录下运行：
|
||||
```bash
|
||||
yarn add <package-name>
|
||||
```
|
||||
|
||||
### Q: TypeScript 编译错误怎么办？
|
||||
|
||||
A: 运行以下命令检查错误：
|
||||
```bash
|
||||
cd server
|
||||
yarn build
|
||||
```
|
||||
|
||||
## 测试环境
|
||||
## 开发说明
|
||||
|
||||
### 运行测试
|
||||
|
||||
**所有测试**：
|
||||
1. 打开 `tests/RunAllTests.tscn`
|
||||
2. 按 F6 运行
|
||||
在 Godot 编辑器中：
|
||||
1. 打开测试场景（`tests/` 目录）
|
||||
2. 按 F6 运行当前场景
|
||||
3. 查看输出面板的测试结果
|
||||
|
||||
**游戏测试**：
|
||||
1. 打开 `scenes/TestGameplay.tscn`
|
||||
2. 按 F6 运行
|
||||
3. 使用 WASD 移动角色
|
||||
### 添加中文字体
|
||||
|
||||
### 预期结果
|
||||
如果游戏中文显示乱码：
|
||||
|
||||
- 所有单元测试通过
|
||||
- 角色可以在场景中移动
|
||||
- 相机跟随角色
|
||||
- 碰撞检测正常
|
||||
1. 将中文字体文件（如 `msyh.ttc`）放到 `assets/fonts/` 目录
|
||||
2. 在 Godot 中选中字体文件
|
||||
3. 在 Import 面板中：
|
||||
- **取消勾选** "Allow System Fallback"
|
||||
- 点击 "Reimport"
|
||||
4. `ChineseFontLoader.gd` 会自动加载字体
|
||||
|
||||
## 下一步
|
||||
### 导出 Web 版本
|
||||
|
||||
环境配置完成后，你可以：
|
||||
1. 在 Godot 中：**Project → Export**
|
||||
2. 选择 "Web" 预设
|
||||
3. 确保以下设置：
|
||||
- Variant → Thread Support: **禁用**
|
||||
- Variant → Extensions Support: **禁用**
|
||||
4. 点击 "Export Project"
|
||||
5. 选择输出目录（如 `web_assets/`）
|
||||
|
||||
1. **运行测试**: 确保所有功能正常
|
||||
2. **查看场景**: 打开 `scenes/DatawhaleOffice.tscn` 查看办公室
|
||||
3. **开始开发**: 参考 `.kiro/specs/godot-ai-town-game/tasks.md` 继续开发
|
||||
### 本地测试 Web 版本
|
||||
|
||||
## 资源链接
|
||||
```bash
|
||||
# 使用 Python 启动本地服务器
|
||||
cd web_assets
|
||||
python -m http.server 8000
|
||||
|
||||
- [Godot 官方文档](https://docs.godotengine.org/)
|
||||
- [GDScript 参考](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/index.html)
|
||||
- [WebSocket API](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
|
||||
- [TypeScript 文档](https://www.typescriptlang.org/docs/)
|
||||
# 或使用 Node.js
|
||||
npx http-server -p 8000
|
||||
```
|
||||
|
||||
配置完成！🚀
|
||||
然后在浏览器中访问 `http://localhost:8000`
|
||||
|
||||
## 部署
|
||||
|
||||
### 部署到服务器
|
||||
|
||||
1. **构建项目**
|
||||
```bash
|
||||
# 在 Godot 中导出 Web 版本到 web_assets/
|
||||
```
|
||||
|
||||
2. **部署服务器**
|
||||
```bash
|
||||
cd server
|
||||
npm run build
|
||||
npm start
|
||||
```
|
||||
|
||||
3. **配置 Nginx**
|
||||
```bash
|
||||
# 复制 nginx 配置
|
||||
sudo cp nginx/nginx.conf /etc/nginx/sites-available/ai-town
|
||||
sudo ln -s /etc/nginx/sites-available/ai-town /etc/nginx/sites-enabled/
|
||||
sudo nginx -t
|
||||
sudo systemctl reload nginx
|
||||
```
|
||||
|
||||
4. **使用 Docker（可选）**
|
||||
```bash
|
||||
docker-compose -f docker-compose.prod.yml up -d
|
||||
```
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 游戏中文显示乱码
|
||||
|
||||
**原因**：字体没有正确嵌入到 Web 导出中
|
||||
|
||||
**解决方法**：
|
||||
1. 确保 `assets/fonts/` 目录有中文字体文件
|
||||
2. 在 Godot 中选中字体文件
|
||||
3. Import 面板 → **取消勾选** "Allow System Fallback"
|
||||
4. 点击 "Reimport"
|
||||
5. 重新导出项目
|
||||
|
||||
### 服务器无法启动
|
||||
|
||||
**检查**：
|
||||
- 端口 3000 是否被占用
|
||||
- Node.js 版本是否 >= 18
|
||||
- `.env` 配置是否正确
|
||||
|
||||
**解决**：
|
||||
```bash
|
||||
# 检查端口
|
||||
netstat -ano | findstr :3000 # Windows
|
||||
lsof -i :3000 # Linux/Mac
|
||||
|
||||
# 检查 Node.js 版本
|
||||
node --version
|
||||
|
||||
# 重新安装依赖
|
||||
rm -rf node_modules
|
||||
npm install
|
||||
```
|
||||
|
||||
### Godot 项目无法打开
|
||||
|
||||
**解决**：
|
||||
1. 确认 Godot 版本 >= 4.5.1
|
||||
2. 删除 `.godot/` 目录
|
||||
3. 重新打开项目（会重新导入资源）
|
||||
|
||||
### Web 导出后无法运行
|
||||
|
||||
**检查**：
|
||||
- 是否使用 HTTP 服务器（不要直接打开 HTML 文件）
|
||||
- 浏览器控制台是否有错误（F12）
|
||||
- 是否禁用了 Thread Support
|
||||
|
||||
## 开发工作流
|
||||
|
||||
### 1. 创建新功能
|
||||
|
||||
```bash
|
||||
# 创建新分支
|
||||
git checkout -b feature/new-feature
|
||||
|
||||
# 开发...
|
||||
|
||||
# 提交
|
||||
git add .
|
||||
git commit -m "添加新功能"
|
||||
git push origin feature/new-feature
|
||||
```
|
||||
|
||||
### 2. 测试
|
||||
|
||||
- 在 Godot 编辑器中测试（F5）
|
||||
- 运行单元测试
|
||||
- 导出 Web 版本测试
|
||||
|
||||
### 3. 合并
|
||||
|
||||
```bash
|
||||
# 合并到主分支
|
||||
git checkout main
|
||||
git merge feature/new-feature
|
||||
git push origin main
|
||||
```
|
||||
|
||||
## 性能优化
|
||||
|
||||
### Godot 优化
|
||||
- 使用对象池减少内存分配
|
||||
- 优化碰撞检测
|
||||
- 使用 VisibilityNotifier 控制更新
|
||||
|
||||
### 服务器优化
|
||||
- 使用 Redis 缓存
|
||||
- 数据库查询优化
|
||||
- 启用 gzip 压缩
|
||||
|
||||
## 调试技巧
|
||||
|
||||
### Godot 调试
|
||||
```gdscript
|
||||
# 打印调试信息
|
||||
print("Debug:", variable)
|
||||
|
||||
# 断点调试
|
||||
# 在代码行号左侧点击设置断点
|
||||
# 按 F5 运行，程序会在断点处暂停
|
||||
```
|
||||
|
||||
### 服务器调试
|
||||
```bash
|
||||
# 查看日志
|
||||
npm run dev # 开发模式会显示详细日志
|
||||
|
||||
# 使用调试器
|
||||
node --inspect server/src/server.ts
|
||||
```
|
||||
|
||||
## 贡献指南
|
||||
|
||||
1. Fork 项目
|
||||
2. 创建功能分支
|
||||
3. 提交更改
|
||||
4. 推送到分支
|
||||
5. 创建 Pull Request
|
||||
|
||||
## 许可证
|
||||
|
||||
查看 LICENSE 文件了解详情。
|
||||
|
||||
## 联系方式
|
||||
|
||||
如有问题，请在 GitHub 上提交 Issue。
|
||||
|
||||
Reference in New Issue
Block a user