OpenPixel-RPG 能将地球上任何地点转化为可交互像素风 JRPG 世界的 AI 驱动项目

📋 准备工作：核心依赖与 API 密钥

在开始前，请确保你的系统已安装 Node.js 和 Python 3，并准备好以下 API 密钥（这是让 AI 功能正常运行的关键）：

Google Maps API Key：用于地理编码和获取 3D Tiles 图像。
Google Gemini API Key：用于世界设计、图像生成和视觉审查等核心 AI 任务。
DashScope API Key：用于调用通义千问等模型（项目示例中用于 NPC 文本生成）。
（可选）Baidu Maps API Key：用于获取街道级场景参考，可增强生成效果。

🚀 部署步骤

整个过程分为五个主要阶段，请按顺序操作。

第一阶段：克隆项目并安装依赖

打开终端，克隆项目仓库并进入项目根目录：

1 2	git clone https://github.com/tensor2023/OpenPixel-RPG.git cd OpenPixel-RPG

进入核心前端与后端目录：
1
cd G_gen_pixel
安装 Node.js 前端依赖：
1
npm install
安装 Python 后端依赖：
1
pip install -r requirements.txt

第二阶段：配置环境变量

在 G_gen_pixel 目录下，复制示例环境变量文件：
1
cp .env.example .env

编辑 .env 文件，填入你准备好的所有 API 密钥：

# 示例 .env 内容
GOOGLE_MAPS_API_KEY=你的Google_Maps_API密钥
GEMINI_API_KEY=你的Gemini_API密钥
DASHSCOPE_API_KEY=你的DashScope_API密钥
BAIDU_MAP_AK=你的Baidu_Maps_API密钥（可选）

保存文件。

第三阶段：启动三个核心服务

这个项目需要同时运行三个服务。请为每个服务打开一个独立的终端窗口，并确保它们都在 OpenPixel-RPG/G_gen_pixel 目录下执行。

终端 1：启动 Vite 前端开发服务器（提供网页界面）
1
npm run dev
成功启动后，终端会显示本地访问地址，通常是 http://localhost:5173。
终端 2：启动主后端服务（处理模式 1 和 2 的核心逻辑）
1
python server.py
这个服务默认运行在 5001 端口，负责处理图像上传、NYC 地标探索等功能。
终端 3：启动全局地图后端服务（专门处理模式 3）
1
python global_server.py
这个服务运行在 5002 端口，负责模式 3（地球上任意地点）的 OSM 白盒和全球地图生成。

第四阶段：体验三种模式

打开浏览器，访问 http://localhost:5173，你就能看到项目界面。你可以按以下三种模式开始体验：

模式	操作步骤	核心流程
模式 1: 上传照片	1. 选择本地的照片 2. 设置“像素风格”提示词 3. 点击“生成像素地图” 4. 点击“生成 GeoPixel 游戏” 5. 点击“进入世界”	用户图片 → AI像素化 → 生成可玩的游戏世界
模式 2: NYC 地标	1. 点击“城市地图” 2. 输入曼哈顿地标名（如 Times Square） 3. 加载完成后，选择“快速模式” 4. 点击“生成 GeoPixel 游戏” 5. 点击“进入世界”	获取预生成的像素瓦片 → 构建交互地图
模式 3: 全球任意地点	1. 输入全球任意地址，点击“加载地图” 2. 在 3D 视图中微调区域，设置“像素风格” 3. 点击“生成全球地图”（自动运行三步流水线） 4. 点击“生成 WorldX 游戏” 5. 点击“进入世界”	OSM白盒(几何) + 3D Tiles(色彩) + AI风格迁移 → 生成像素地图 → 构建世界

第五阶段：游戏内交互与 NPC 生成

进入游戏世界后，你可以通过以下方式与 AI 生成的 NPC 互动：

走到 NPC 身边，按下键盘上的 Z 键 进行对话。
在游戏世界中，点击 “生成 NPC” 按钮，输入位置，系统将自动调用 AI 为该地点生成一个带有独特背景故事和性格的本地 NPC（生成过程约需 30 秒）。

⚠️ 故障排查与注意事项

端口占用：确保 5173、5001、5002 端口未被其他程序占用。
API 配额：AI 图像生成和 LLM 调用会消耗 API 额度，请注意你的使用量。
依赖问题：如果遇到 ModuleNotFoundError，请检查 Python 依赖是否完整安装。如果前端构建失败，可以尝试删除 node_modules 并重新执行 npm install。
模式 3 说明：此模式依赖 Google 3D Tiles 和 OSM 服务，网络状况可能影响加载速度和成功率。首次加载地图可能需要稍等片刻。
性能提示：本项目涉及 AI 图像生成和 3D 渲染，建议在性能较好的电脑上运行。