276 lines
5.5 KiB
Markdown
276 lines
5.5 KiB
Markdown
# AI Town Game - 开发与运行指南
|
||
|
||
## 环境要求
|
||
|
||
- **Godot Engine**: 4.5.1 或更高版本
|
||
- **Node.js**: 18+ (用于后端服务器)
|
||
- **Git**: 用于版本控制
|
||
|
||
## 快速开始
|
||
|
||
### 1. 克隆项目
|
||
```bash
|
||
git clone <repository-url>
|
||
cd ai_community
|
||
```
|
||
|
||
### 2. 安装服务器依赖
|
||
```bash
|
||
cd server
|
||
npm install
|
||
```
|
||
|
||
### 3. 配置环境变量
|
||
```bash
|
||
# 复制环境配置文件
|
||
cp .env.example .env
|
||
|
||
# 编辑 .env 文件，配置你的设置
|
||
```
|
||
|
||
### 4. 启动开发服务器
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
服务器将在 `http://localhost:3000` 运行
|
||
|
||
### 5. 在 Godot 中打开项目
|
||
|
||
1. 打开 Godot Engine
|
||
2. 点击 "导入"
|
||
3. 选择项目目录中的 `project.godot` 文件
|
||
4. 点击 "导入并编辑"
|
||
|
||
### 6. 运行游戏
|
||
|
||
在 Godot 编辑器中：
|
||
- 按 **F5** 运行游戏
|
||
- 或点击右上角的 "播放" 按钮
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
ai_community/
|
||
├── .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 # 项目说明
|
||
```
|
||
|
||
## 开发说明
|
||
|
||
### 运行测试
|
||
|
||
在 Godot 编辑器中：
|
||
1. 打开测试场景（`tests/` 目录）
|
||
2. 按 F6 运行当前场景
|
||
3. 查看输出面板的测试结果
|
||
|
||
### 添加中文字体
|
||
|
||
如果游戏中文显示乱码：
|
||
|
||
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/`）
|
||
|
||
### 本地测试 Web 版本
|
||
|
||
```bash
|
||
# 使用 Python 启动本地服务器
|
||
cd web_assets
|
||
python -m http.server 8000
|
||
|
||
# 或使用 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。
|