game-ui-sprite-sheet-splitter

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

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

前置条件

读取：

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

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

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

适用输入

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

不适合：

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

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

输入雪碧图规范

组件生图时优先要求：

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

自动拆分

执行：

python3 scripts/split_sprite_sheet.py <source.png> \
  --output-dir <project>/assets/sprites/<pack-id>/items \
  --zip <project>/packages/<pack-id>-png.zip \
  --mode auto \
  --prefix <pack-id>

默认行为：

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

语义 mapping

自动序号不能作为最终资产名。准备按检测顺序排列的 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]}

执行时增加：

--mapping mappings/shop-components.yaml

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

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

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

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

参数调整

元素被拆得太碎：

--connect-gap 6

多个元素被粘成一张：

--connect-gap 0

背景残留：

--mode background --background-tolerance 16

浅色组件被误删：

--background-tolerance 8

小图标被过滤：

--min-area 16

需要更多裁切留白：

--padding 8

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

项目契约

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