Sprite Atlas Slicer

全局协作约定

• 编码、审查、重构或修 bug 时，可显式触发 karpathy-guidelines：先说明假设和取舍，保持改动外科式，定义可验证成功标准。
• 汇报长日志、长文档、工具输出、agent 工作或调试证据时，可显式触发 reporting-discipline：先给结论、关键证据、风险和下一步，不默认粘贴大段原文。
• 常用触发语：use karpathy-guidelines and reporting-discipline，或“用 karpathy 打底，并按 reporting discipline 汇报”。

Overview

Use this skill to turn a transparent PNG atlas into separate game-ready PNG files. Prefer deterministic pixel slicing over imagegen for this step; generation is for making or editing art, while slicing should preserve the existing pixels.

Workflow

1. Confirm the input is a transparent PNG atlas. If the source has a flat chroma-key background, remove it first with the imagegen skill's chroma-key helper.
2. Run scripts/slice_sprite_atlas.py on the transparent atlas.
3. Inspect _preview_contact_sheet.png for obvious issues: adjacent fragments, missing text/icon pieces, over-cropped edges, or tiny noise sprites.
4. If auto slicing is imperfect, create or edit a boxes JSON and rerun with --boxes.
5. Deliver the output directory, manifest.json, _preview_contact_sheet.png, and zip archive if requested.

Quick Commands

Auto slice a well-spaced transparent atlas:

python scripts/slice_sprite_atlas.py \
  --input /path/to/atlas.png \
  --out-dir /path/to/slices \
  --zip /path/to/slices.zip

Use manual boxes when sprites sit too close together:

python scripts/slice_sprite_atlas.py \
  --input /path/to/atlas.png \
  --out-dir /path/to/slices \
  --boxes /path/to/boxes.json \
  --zip /path/to/slices.zip

The boxes file can be either a list or an object with an items list:

[
  { "name": "button_build", "box": [1005, 750, 1133, 897] },
  {
    "name": "aircraft_passenger_plane",
    "box": [620, 474, 953, 695],
    "clear": [[0, 0, 118, 92]],
    "keep_largest": false
  }
]

clear rectangles are local to the sprite box. Use keep_largest: true when a sprite has one main alpha component plus detached noise.

Defaults

• Alpha threshold: 8
• Output padding: 2px
• Auto grouping dilation: 8px
• Minimum component area: 100px
• Output names: 001_<name>.png

Adjust --dilate down when separate sprites merge together. Adjust it up when one sprite splits into pieces such as dashed outlines, text, or detached icon badges.

Validation

Before claiming completion, verify:

python scripts/slice_sprite_atlas.py --input /path/to/atlas.png --out-dir /tmp/slices --zip /tmp/slices.zip

Then inspect the preview and confirm every sprite PNG is RGBA and non-empty. The script writes a manifest with source boxes and output sizes for review.

Common Mistakes

• Do not call imagegen to cut an already generated atlas into individual files; it will redraw and drift.
• Do not crop by the black preview background. Crop from the alpha channel.
• Do not trust auto slicing when sprites touch or sit very close. Use --boxes for production assets.
• When a crop still contains neighboring fragments, add clear rectangles or keep_largest in the boxes JSON.
• Do not put outputs directly into a Cocos assets/ folder unless the user wants import metadata created.