Agent Sprite Forge

在独立游戏开发中，美术资产的制作往往是最耗时的一环。Agent Sprite Forge 是一个基于 Codex 的开源技能集，它能够将你的自然语言需求直接转化为可用于游戏的 2D 精灵（Sprites）、分层地图 以及完整的 Godot 工程场景。

这不是简单的图片生成，而是一套完整的“规划-生成-后处理-工程化”流水线。由 AI 代理规划资产类型，Codex 负责生图，本地 Python 处理器完成去背、切格、碰撞检测等确定性任务，最终输出透明 PNG、GIF 动画、道具包以及包含碰撞体、触发区和调试玩家的 Godot 4.5 场景。

核心工作流：为什么选择 Codex？

Agent Sprite Forge 之所以首选 Codex 作为核心，是因为 Codex 内置了图像生成能力，使得整个流程可以在同一个代理会话内闭环完成：

1. 统一规划：由同一个 AI 代理决定资产类型、动画形式、地图管道和布局策略。
2. 无缝生图：无需调用外部图像 API，Codex 直接生成原始精灵表、道具包或地图底图。
3. 本地后处理：本地 Python 脚本负责去背、切格、对齐和质量控制（QC），确保输出的像素级精度。
4. 工程化输出：根据需要构建包含碰撞、区域、道具放置和元数据的 Godot 场景。

这种设计避免了多服务拼接带来的复杂性，让“人管方向，AI 干活”的理念在游戏开发中落地。

两大核心技能

该仓库目前提供了两个主要技能，分别针对角色/道具资产和地图场景：

1. skills/generate2dsprite：精灵与特效生成器

专注于生成并后期处理单个或批量化的游戏资产。

• 支持资产类型：
  • 生物与角色：玩家、NPC、怪物及其进化线。
  • 战斗要素：施法动作、弹丸、冲击/爆炸效果。
  • 特效表（FX Sheets）：标准化的帧动画序列。
  • 资源包（Bundles）：如 unit_bundle、spell_bundle、combat_bundle。
• 智能参考继承：
  • 支持依附参考图生成精灵变体、动画序列或进化形态。
  • 遵循“先上图，后生成”规则：用户上传或刚生成的图片会自动进入上下文，确保角色身份、风格和布局的一致性。

2. skills/generate2dmap：分层地图与 Godot 工程导出

这是该工具的亮点所在。它不仅能生成一张扁平的地图图片，更能输出可在 Godot 中直接编辑的工程文件。

🎨 三种美术风格管道

• clean_hd（默认）：高精度、干净的高清手绘风格，适合现代 2D 游戏。
• pixel_inspired：柔和像素感，保留细节但不过度粗糙。
• retro_pixel：复古像素艺术，仅在用户明确要求时启用。

🛠️ Godot 4.5 工程输出详解

当使用 $generate2dmap 时，你将获得一个结构清晰的 Godot 场景，包含：

• 可调整的 TileMapLayer：
  • 分层管理：地面、水体/桥梁、装饰物、遇怪草丛、障碍物。
• 分离式道具（YSorted_SeparateProps）：
  • 独立的 Sprite2D 节点，支持 Y 轴排序，确保遮挡关系正确。
• 交互区域（Area2D）：
  • 遇怪草丛：内置遭遇表，用于随机战斗触发。
  • 出口区：用于场景切换或路线转场。
• 物理碰撞（StaticBody2D）：
  • 自动为外围边界、草坪边缘、断崖和支柱底座添加碰撞阻挡器。
• 调试环境：
  • 内置 CharacterBody2D 调试玩家和相机，打开场景即可立即试玩和测试碰撞。

🔄 智能道具处理

• 道具包生成：小型环境物品可批量生成为 2×2、3×3 或 4×4 的道具包。
• 自动去背与切割：如果生成图中有洋红背景，本地处理器会自动进行软磨砂色键清理、除溢色，并切出透明道具。
• 按需调用：只有当地图管道需要可重用的透明道具时，才会调用 generate2dsprite 进行精细化处理；简单地图则维持单张烘焙图像以节省资源。

技术架构：代理规划 + 确定性执行

Agent Sprite Forge 的设计理念非常清晰：AI 负责创意判断，代码负责稳定执行。

• AI 代理（Codex）决定：
  • 资产类型、行动类型、捆绑方式。
  • 图纸布局、帧计数、对齐策略。
  • 是否保留分离效应。
• Python 本地处理器执行：
  • 依赖库：Pillow, numpy。
  • 任务：洋红背景去背、精确切格、主体 BBox 探测、缩放、透明 PNG/GIF 输出。
  • 特点：不负责创意，只负责像素级的确定性处理，确保每次输出的格式和规格一致。

快速安装指南

前置要求

• Git
• Python 3.x
• Codex 环境

选项 1：Windows PowerShell

# 1. 克隆仓库
git clone https://github.com/0x0funky/agent-sprite-forge.git
cd .\agent-sprite-forge

# 2. 安装依赖
python -m pip install -r .\requirements.txt

# 3. 创建技能目录并复制文件
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codex\skills" | Out-Null
Copy-Item -Recurse -Force `
  ".\skills\*" `
  "$env:USERPROFILE\.codex\skills\"

选项 2：macOS / Linux

# 1. 克隆仓库
git clone https://github.com/0x0funky/agent-sprite-forge.git
cd ./agent-sprite-forge

# 2. 安装依赖
python3 -m pip install -r ./requirements.txt

# 3. 创建技能目录并复制文件
mkdir -p ~/.codex/skills
cp -R ./skills/* ~/.codex/skills/

注意：安装完成后，建议重新启动一个新的 Codex 会话，以确保技能被正确加载。