whale-town/SETUP.md

AI Town Game - 开发与运行指南

环境要求

• Godot Engine: 4.5.1 或更高版本
• Node.js: 18+ (用于后端服务器)
• Git: 用于版本控制

快速开始

1. 克隆项目

git clone <repository-url>
cd ai_community

2. 安装服务器依赖

cd server
npm install

3. 配置环境变量

# 复制环境配置文件
cp .env.example .env

# 编辑 .env 文件，配置你的设置

4. 启动开发服务器

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 版本

# 使用 Python 启动本地服务器
cd web_assets
python -m http.server 8000

# 或使用 Node.js
npx http-server -p 8000

然后在浏览器中访问 http://localhost:8000

部署

部署到服务器

1. 构建项目

   # 在 Godot 中导出 Web 版本到 web_assets/
   

2. 部署服务器

   cd server
   npm run build
   npm start
   

3. 配置 Nginx

   # 复制 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（可选）

   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 配置是否正确

解决：

# 检查端口
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. 创建新功能

# 创建新分支
git checkout -b feature/new-feature

# 开发...

# 提交
git add .
git commit -m "添加新功能"
git push origin feature/new-feature

2. 测试

• 在 Godot 编辑器中测试（F5）
• 运行单元测试
• 导出 Web 版本测试

3. 合并

# 合并到主分支
git checkout main
git merge feature/new-feature
git push origin main

性能优化

Godot 优化

• 使用对象池减少内存分配
• 优化碰撞检测
• 使用 VisibilityNotifier 控制更新

服务器优化

• 使用 Redis 缓存
• 数据库查询优化
• 启用 gzip 压缩

调试技巧

Godot 调试

# 打印调试信息
print("Debug:", variable)

# 断点调试
# 在代码行号左侧点击设置断点
# 按 F5 运行，程序会在断点处暂停

服务器调试

# 查看日志
npm run dev  # 开发模式会显示详细日志

# 使用调试器
node --inspect server/src/server.ts

贡献指南

1. Fork 项目
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

许可证

查看 LICENSE 文件了解详情。

联系方式

如有问题，请在 GitHub 上提交 Issue。