# Game Ui Sprite Sheet Splitter

> Splits a generated game UI sprite sheet or component board into individual transparent PNG elements, writes crop metadata, validates dimensions and alpha channels, and packages all PNG files into a ZIP archive. Use after component breakdown when users ask to cut a combined sprite sheet, isolate every button/icon/card/effect, export single elements, remove a solid background, or deliver a download…

- **Type:** Skill
- **Install:** `agentstack add skill-guiguiyan930-source-game-ui-design-workflow-game-ui-sprite-sheet-splitter`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [guiguiyan930-source](https://agentstack.voostack.com/s/guiguiyan930-source)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [guiguiyan930-source](https://github.com/guiguiyan930-source)
- **Source:** https://github.com/guiguiyan930-source/game-ui-design-workflow/tree/main/skills/game-ui-sprite-sheet-splitter

## Install

```sh
agentstack add skill-guiguiyan930-source-game-ui-design-workflow-game-ui-sprite-sheet-splitter
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 游戏 UI 雪碧图拆分与 PNG 打包

把组件拆解阶段生成的整张雪碧图进一步切成独立透明 PNG，并打包成可下载 ZIP。不要把“生成组件清单”误当成“已经完成像素级切图”。

## 前置条件

读取：

- 已批准的组件拆解结果
- `contracts/style-contract.yaml`
- `contracts/component-contract.yaml`
- `contracts/asset-manifest.yaml`
- `contracts/sprite-contract.yaml`（存在时）

输入雪碧图必须是实际存在的图片文件。若只有提示词或组件列表，先完成组件图生成。

最终单元素 PNG 必须去掉全部文字，包括标题、按钮文案、数字标签、占位文字、水印和说明编号。文字不是组件图形的一部分。

## 适用输入

- 透明背景雪碧图：优先按 Alpha 通道识别。
- 纯色或近似纯色背景：采样四周背景色并移除。
- 同一张图上的按钮、图标、卡片、装饰、特效和角色。

不适合：

- 元素互相遮挡或粘连严重的完整 UI 页面。
- 带复杂场景背景且元素没有间隔的合成图。
- 需要恢复被遮挡像素的素材。

遇到这些情况，应重新生成留有间距的组件雪碧图，而不是强行切割。

## 输入雪碧图规范

组件生图时优先要求：

- 所有元素完整、互不接触、四周留白。
- 统一纯色背景或透明背景。
- 不要文字、编号、水印和说明线。
- 阴影不要跨越到相邻组件。
- 相似状态按固定顺序排列，但不绘制网格线。
- 不要把一个组件拆散成多个远离的碎片。

## 自动拆分

执行：

```bash
python3 scripts/split_sprite_sheet.py  \
  --output-dir /assets/sprites//items \
  --zip /packages/-png.zip \
  --mode auto \
  --prefix 
```

默认行为：

1. 输入有透明通道时按 Alpha 检测。
2. 输入不透明时采样边缘背景色。
3. 合并距离较近的像素区域。
4. 过滤过小噪点。
5. 每个元素增加安全边距。
6. 导出独立透明 PNG。
7. 生成 `sprite-manifest.yaml`。
8. 生成包含 manifest 和全部 PNG 的 ZIP。

## 语义 mapping

自动序号不能作为最终资产名。准备按检测顺序排列的 YAML：

```yaml
items:
  - semantic_name: shop-buy-button-normal
    component_id: shop-buy-button
    category: button
    state: normal
    slice: {type: 9-slice, margins: [36, 36, 28, 28]}
```

执行时增加：

```bash
--mapping mappings/shop-components.yaml
```

工具会用 `semantic_name` 作为 PNG 文件名，并把组件 ID、分类、状态与 slice 写入 manifest。命名和切图方式分别遵循组件技能的语义命名规范与[切图规则](references/slice-rules.md)。

自动切割不会自动识别或修复文字。源雪碧图仍有文字时，先执行以下任一操作，再开始切割：

1. 优先重新生成无文字雪碧图。
2. 无法重生时，对文字区域做蒙版修复或内容填充，补回底板纹理。
3. 修复后重新检查，不能只把文字裁掉而留下透明洞、色块或残影。

不得把含文字的切片标记为批准。

## 参数调整

元素被拆得太碎：

```bash
--connect-gap 6
```

多个元素被粘成一张：

```bash
--connect-gap 0
```

背景残留：

```bash
--mode background --background-tolerance 16
```

浅色组件被误删：

```bash
--background-tolerance 8
```

小图标被过滤：

```bash
--min-area 16
```

需要更多裁切留白：

```bash
--padding 8
```

重新输出时显式使用 `--force`，不得静默覆盖已批准包。

## 项目契约

将结果写入 `contracts/sprite-contract.yaml`：

- 源雪碧图与源页面
- 检测模式和阈值
- 输出目录和 ZIP 路径
- 单元素 ID、路径、原图坐标、尺寸和透明状态
- 人工检查状态

在 `asset-manifest.yaml` 至少登记：

- 原始雪碧图：`kind: sprite-sheet`
- 最终压缩包：`kind: package`

单元素明细由 `sprite-contract.yaml` 管理，避免大型组件包让全局 manifest 失控。

## 人工验收

自动切图后逐项检查：

- 每个文件只包含一个完整元素。
- 元素没有被裁断。
- 相邻元素没有粘连。
- 阴影、发光和半透明边缘完整。
- 背景已透明，无白边、色边和脏点。
- 不含标题、按钮文案、数字标签、水印或文字残影。
- 文件名、坐标和尺寸与 manifest 一致。
- ZIP 可以解压，包含全部 PNG 和 manifest。

误切时先调整阈值重新生成；仍无法解决时，在 `sprite-contract.yaml` 记录人工裁切框，不要把错误结果标记为批准。

## 文件命名

```text
-001.png
-002.png
-003.png
...
-png.zip
```

确定组件语义后可重命名为：

```text
button-primary-default.png
nav-home-selected.png
currency-gold.png
effect-crescent-glow.png
```

重命名后同步更新 manifest，不能只改文件名。

## 完成定义

- 原始雪碧图可追踪
- 每个元素是独立透明 PNG
- 自动坐标和实际尺寸已记录
- 人工验收通过
- `review.text_free: true`
- ZIP 包存在且可解压
- 最终 PNG 使用语义名称并关联 component ID
- 项目严格校验通过
- `quickstart.md` 记录解压和使用方式

需要继续生成 Atlas 和引擎 JSON 时，调用 `game-ui-asset-pipeline`。

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [guiguiyan930-source](https://github.com/guiguiyan930-source)
- **Source:** [guiguiyan930-source/game-ui-design-workflow](https://github.com/guiguiyan930-source/game-ui-design-workflow)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-guiguiyan930-source-game-ui-design-workflow-game-ui-sprite-sheet-splitter
- Seller: https://agentstack.voostack.com/s/guiguiyan930-source
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.