# 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。