2d-pixel-asset

通过 Gemini + Chrome 生成 2D 像素素材

通过 Chrome 浏览器自动化，使用 Google Gemini 网页界面生成像素风格游戏素材，然后进行后处理，使其达到精确的像素尺寸并带有透明背景。

前提条件

• 已安装并启用 Claude-in-Chrome 扩展的 Chrome 浏览器
• 用户已在 https://gemini.google.com 登录 Google 账号
• Chrome MCP 工具可用（mcp__claude-in-chrome__*）
• 已安装 Pillow 的 Python 3（用于后处理）
• 如需使用 ML 移除背景： pip install transformers torch torchvision + CUDA GPU
• 如需使用 Adobe Express 移除背景： 用户已登录 Adobe 账号

加载工具

使用任何 Chrome MCP 工具前，必须先通过 ToolSearch 加载该工具：

ToolSearch: "select:mcp__claude-in-chrome__tabs_context_mcp"
ToolSearch: "select:mcp__claude-in-chrome__tabs_create_mcp"
ToolSearch: "select:mcp__claude-in-chrome__navigate"
ToolSearch: "select:mcp__claude-in-chrome__computer"
ToolSearch: "select:mcp__claude-in-chrome__find"
ToolSearch: "select:mcp__claude-in-chrome__upload_image"

工具映射

操作	MCP 工具
获取标签页上下文	mcp__claude-in-chrome__tabs_context_mcp
创建新标签页	mcp__claude-in-chrome__tabs_create_mcp
跳转到 URL	mcp__claude-in-chrome__navigate
点击、输入、截屏、悬停、等待	mcp__claude-in-chrome__computer
按描述查找元素	mcp__claude-in-chrome__find
上传参考图/编辑图	mcp__claude-in-chrome__upload_image
读取页面内容	mcp__claude-in-chrome__read_page

CLI 参数

调用技能后，从用户输入中解析以下参数：

参数	默认值	说明
(位置参数)	--	主要提示词文本（所有非标志内容）
--size 32 或 --size 64x32	32	最终输出的目标像素尺寸
--output path/	./Assets/	输出目录
--name filename	根据提示词生成	输出文件名（不含扩展名）
`--model pro	flash`	pro
--ref path1.png path2.png ...	无	用于指定风格的参考图（最多 14 张）
--edit path.png	无	要编辑/修改的现有图片
--tile	false	生成可平铺纹理（不移除背景）
`--resolution 1k	2k	4k`
--no-process	false	跳过后处理，保留原始输出
`--bg-color magenta	green	white`
--ml	false	使用 BiRefNet ML 模型移除背景
--adobe	false	使用 Adobe Express 移除背景
--margin N	1	最终输出中精灵周围的透明边距（px）

工作流

纵横比处理

重要：Gemini 提示词中的纵横比必须与目标 --size 匹配。

构建提示词前，运行脚本以获取最匹配的 Gemini 纵横比：

python "path/to/2d-pixel-asset/scripts/process_asset.py" \
  --size {target_size} --suggest-ratio

此脚本会输出最接近的 Gemini 支持的纵横比（例如 3:2、16:9、4:3）。 在提示词中使用该比例，格式为 Aspect ratio {ratio}。

示例：

• --size 32 → 1:1
• --size 128x64 → 16:9
• --size 64x128 → 9:16
• --size 96x128 → 3:4
• --size 192x128 → 3:2

还要在提示词中添加：“主体必须居中，并从边缘到边缘填满整个画布，周围尽量少留空白。”

后处理完成后： 如果脚本输出有关纵横比不匹配的 WARNING，请告知用户，并提供以下选项：

1. 使用正确的纵横比提示词重新生成
2. 接受结果，并在较短轴方向保留透明填充

第 1 步：初始化浏览器会话

1. Call tabs_context_mcp to discover existing tabs
2. Call tabs_create_mcp to create a fresh tab
3. Navigate to https://gemini.google.com/app
4. Take a screenshot with computer to verify the page loaded

第 2 步：新建对话并启用图像生成

重要：Gemini 用户界面为德语。

1. Use find to locate "Neuer Chat" button, click it with computer
2. Take a screenshot to confirm new chat is open
3. Use find to locate "Tools" button, click it
4. Use find to locate "Bild erstellen" toggle/option, click it to enable
5. Take a screenshot to confirm image generation is enabled

第 3 步：选择模型

默认模型为 Pro。模型选择器显示在输入区域右下方附近，标注为“Schnell”。

If user specified --model pro (or no --model flag):
  1. Use find to locate the model dropdown showing "Schnell"
  2. Click it to open the model selector
  3. Select the option labeled with "Pro"
  4. Take a screenshot to confirm Pro is selected

If user specified --model flash or --flash:
  1. Keep "Schnell" (Flash) -- no action needed

第 4 步：上传参考图（如提供了 --ref）

1. For each reference image path:
   a. Use upload_image to upload the file
2. Maximum 14 reference images supported
3. Take a screenshot to verify uploads appear in the input area

第 5 步：上传要编辑的现有图片（如提供了 --edit）

1. Use upload_image to upload the specified image
2. The modification instructions will be included in the prompt
3. Take a screenshot to verify the image appears in the input area

第 6 步：构建并提交提示词

将用户的核心请求与像素艺术默认设置结合，构建提示词。

始终包含以下元素：

1. 分辨率指令： “以 {resolution} 分辨率生成”（默认 1K）
2. 像素艺术风格： “像素艺术精灵图、粗黑描边、无抗锯齿、清晰的像素边缘”
3. 背景处理（基于 --bg-color，默认洋红色）：
   • 对于背景为洋红色的精灵图：“孤立显示在纯色、平坦、均匀的洋红色背景上。必须使用十六进制颜色 #FF00FF（RGB 255, 0, 255）。整个背景必须为单一纯洋红色，绝不能有任何变化。整个图像采用平坦、均匀的光照。”
   • 对于背景为绿色的精灵图：“孤立显示在纯色、平坦、均匀的色度键绿色背景上。必须使用十六进制颜色 #00FF00（RGB 0, 255, 0）。整个背景必须为单一纯绿色，绝不能有任何变化。整个图像采用平坦、均匀的光照。”
   • 对于背景为白色的精灵图：“孤立显示在纯色、平坦、均匀的纯白色背景上。整个图像采用平坦、均匀的光照。”
   • 对于图块（--tile）：“无缝可平铺纹理，填满整个矩形画布”
4. 用户的核心提示词作为主体描述

提示词模板（精灵图——默认洋红色背景）：

Create a pixel art sprite of {user_prompt}. Pixel art style with thick black outlines,
no anti-aliasing, clean pixel edges. The subject must be centered and fill the entire
canvas from edge to edge with minimal empty space around it. Isolated on a solid, flat,
uniform magenta background. Use EXACTLY hex color #FF00FF (RGB 255, 0, 255). The entire
background must be a single pure magenta color with absolutely zero variation. Flat, even,
uniform lighting across the entire image. Generate in {resolution} resolution.
Aspect ratio {aspect_ratio}.

提示词模板（图块）：

Create a seamless tileable pixel art texture of {user_prompt}. Pixel art style with
no anti-aliasing, clean pixel edges. The texture must fill the entire rectangular canvas
with no borders or margins. Seamlessly tileable in all directions. Generate in {resolution}
resolution.

提示词模板（使用 --edit 的编辑模式）：

Modify this pixel art: {user_prompt}. Maintain the pixel art style with thick black
outlines, no anti-aliasing. Keep everything else exactly the same unless specified.
Generate in {resolution} resolution.

**参考：**请参阅 references/prompting-guide.md，了解详细的提示词构建策略、风格描述词和示例。

提交：

1. Use find to locate the prompt input field
2. Type the constructed prompt using computer action "type"
3. Press Enter to submit
4. Wait 10 seconds (computer wait action)
5. Wait another 10 seconds (computer wait action)
6. Take a screenshot to verify the image was generated

第 7 步：下载生成的图像

1. Hover over the generated image using computer action "hover"
2. Look for the download button (arrow icon, top-right of image on hover)
3. Use find to locate the download button ("Bild in Originalgröße herunterladen")
4. Click the download button using the found ref
5. Wait 5 seconds for the download to complete
6. Find the downloaded file:
   ls -t ~/Downloads/*.png | head -5

第 8 步：后处理（移除背景 + 光栅化）

如果设置了 --no-process，则跳过此步骤。

选择背景移除策略

决策逻辑（按顺序执行）：

1. 如果有 --ml 标志：使用 BiRefNet ML 模型
2. 如果有 --adobe 标志：使用 Adobe Express（第 8b 步）
3. 如果有 --tile 标志：跳过背景移除（--no-remove-bg）
4. **默认：**使用 --bg-color 指定的色度键（默认：洋红色）

下载后，截取生成图像的屏幕截图并进行目视检查。如果尽管使用了洋红色提示词，背景看起来仍不干净（有渐变、阴影、混合颜色），可考虑对该图像改用 --ml。

8a：基于脚本移除背景（色度键或 ML）

# Default: Chroma key magenta
python "path/to/2d-pixel-asset/scripts/process_asset.py" \
  ~/Downloads/{downloaded_file}.png \
  --size {target_size} \
  --bg-color magenta \
  --output {output_path}/{filename}.png

# ML fallback (BiRefNet):
python "path/to/2d-pixel-asset/scripts/process_asset.py" \
  ~/Downloads/{downloaded_file}.png \
  --size {target_size} \
  --ml \
  --output {output_path}/{filename}.png

# Green chroma key:
python "path/to/2d-pixel-asset/scripts/process_asset.py" \
  ~/Downloads/{downloaded_file}.png \
  --size {target_size} \
  --bg-color green \
  --output {output_path}/{filename}.png

# Legacy white:
python "path/to/2d-pixel-asset/scripts/process_asset.py" \
  ~/Downloads/{downloaded_file}.png \
  --size {target_size} \
  --bg-color white \
  --output {output_path}/{filename}.png

• 默认 --size：32（生成 32x32 图像）。非正方形图像可使用：--size 64x32。
• 如果设置了 --tile：添加 --no-remove-bg 标志（图块会保留背景）。

8b：使用 Adobe Express 移除背景（如果有 --adobe 标志）

使用 Chrome 浏览器自动化，通过 Adobe Express 移除背景：

1. Create a new tab or reuse existing
2. Navigate to https://new.express.adobe.com/home/tools/remove-background
3. Take a screenshot to verify page loaded
4. Find the upload area / "Browse" button
5. Upload the downloaded Gemini image using upload_image
6. Wait 10-15 seconds for Adobe to process
7. Take a screenshot to verify background was removed
8. Find and click the download button
9. Wait 5 seconds for download
10. Find the downloaded file:
    ls -t ~/Downloads/*.png | head -5
11. Then run process_asset.py with --no-remove-bg to only crop and rasterize:
    python "path/to/2d-pixel-asset/scripts/process_asset.py" \
      ~/Downloads/{adobe_result}.png \
      --size {target_size} \
      --no-remove-bg \
      --output {output_path}/{filename}.png

第 9 步：移至最终位置

1. Ensure output directory exists: mkdir -p {output_dir}
2. If --no-process was set, move raw file:
   mv ~/Downloads/{file}.png {output_dir}/{name}.png
3. Report the final file path to the user

像素艺术提示词优化

优化用户提示词时，应用以下针对像素艺术的原则：

• **调色板：**建议使用有限调色板（“16 色调色板”、“NES 调色板”、“包含 8 种颜色的自然色调”）
• **透视：**指定视角（“俯视图”、“3/4 等距视图”、“横向卷轴侧视图”、“正面视图”）
• **动画帧：**对于精灵图集，除非用户要求动画，否则指定“单帧、静态姿势”
• **尺寸参考：**提及预期用途（“适用于 32x32 网格”、“用于 2D 平台游戏的角色精灵图”）
• **描边：**精灵图始终指定“粗黑描边”，图块可选
• **阴影：**使用“平涂”或“简单的双色调阴影”——避免渐变
• **正向描述：**描述要包含的内容，而不是排除的内容。使用“平坦、均匀的光照”，而不是“无阴影”

错误处理

• 页面无法加载： 重试导航，确认互联网连接正常
• 图像生成失败： 简化提示词，降低复杂度
• 下载按钮不可见： 使用 find 按引用定位“Bild in Originalgröße herunterladen”按钮
• 文件不在 Downloads 中： 再等待 5 秒，使用 ls -t ~/Downloads/*.png | head -5 检查
• 色度键处理后有残留： 对该图像切换到 --ml 标志
• ML 模型加载失败： 检查 torch/transformers 是否已安装，并确认 CUDA 可用
• Adobe Express 上传失败： 确认用户已登录 Adobe 账户
• 未找到模型选择器： 截取屏幕截图，查看输入区域附近是否有其他界面元素
• 未找到“Bild erstellen”： 尝试搜索“Bilderstellung”，或截取屏幕截图以确认正确的德语标签

重要说明

• 每次生成都要创建新的聊天，以避免先前提示词造成上下文污染
• Gemini 界面使用德语——所有按钮标签均为德语（Neuer Chat、Tools、Bild erstellen、Schnell）
• 每次使用前，都要通过 ToolSearch 加载 Chrome MCP 工具
• 生成的图像包含 C2PA Content Credentials 和 SynthID 水印
• 默认输出目录为相对于用户当前工作目录的 ./Assets/
• 默认背景颜色为洋红色（#FF00FF），可避免与常见游戏美术颜色冲突
• process_asset.py 脚本需要 Python 3 和 Pillow（pip install Pillow）
• 如需进行 ML 移除，请安装：pip install transformers torch torchvision
• BiRefNet 模型（约 1GB）首次使用时会下载到 HuggingFace 缓存中