--- name: aseprite description: "Parse Aseprite files (.ase/.aseprite) — layers, cels, tags, slices, palettes, tilesets — into JSON, durations and bounds for engines and tools." --- # Aseprite Inference An `.ase`/`.aseprite` file is a structured timeline of layered pixel (or tilemap) cels. Read and verify the file rather than hard-coding expectations; output what you know _and_ what you assumed. **Before inferring, ask:** - Authoring intent (tags/slices/user data) or render intent (visible pixels/bounds/ordering)? - Do you need pixels (decompress cel images), or is structure-only (layers/timing/tags) enough? - Is the sprite RGBA / Grayscale / Indexed / Tilemap — and does that change transparency/bounds logic? **Core principles** 1. **Chunk-driven:** skip unknown chunks by `chunk_size`, don't crash. 2. **Per-frame timing:** `header.speed` is deprecated; each frame has its own duration (fallback to speed only when a frame duration is 0). 3. **Separate decode modes:** fast metadata pass first; pixel/tile decode only when needed. ## Quick Start Turn a file into JSON — needs nothing but `node`: ```bash # This skill's directory. Claude Code substitutes CLAUDE_SKILL_DIR (project, global # or plugin install); other agents fall back to wherever `vg init` put it. SKILL="${CLAUDE_SKILL_DIR}" [ -d "$SKILL" ] || for d in .agents/skills .claude/skills ~/.agents/skills ~/.claude/skills; do [ -d "$d/aseprite" ] && SKILL=$d/aseprite && break done ``` ```bash node $SKILL/scripts/aseprite-inspect.mjs path/to/sprite.aseprite --json ``` Opt into pixel-derived inference (e.g. tight bounds): ```bash node $SKILL/scripts/aseprite-inspect.mjs path/to/sprite.aseprite --json --decode-cels ``` Add `--pretty` to indent the JSON. Decoding is capped by `--max-decompress-mib` (default 64), so a hostile file can't make it allocate. ## What You Can Infer Reliably Structure-only: frame count + per-frame durations + total timeline; layer hierarchy (child levels), blend modes, opacities, flags, optional UUIDs; per-frame/per-layer cel placement, linked cels, z-index, opacity; tags (ranges + direction/repeat); slices (frame-keyed rects, optional 9-slice + pivot); tilesets/tilemaps (tile dims, count, masks with ID + flips); palettes + transparency index; user data on layers/cels/tags/tilesets. With `--decode-cels`: tight per-cel/frame bounds (non-transparent extents), empty-frame detection, sprite-sheet packing hints. ## Common Workflows ### 1) Build engine metadata (JSON) Inspect structure-only, add `--decode-cels` if you need tight bounds. Emit `frames[]`, `layers[]`, `tags[]`, `slices[]`, normalized `frameMs[]`. For deterministic render order use z-index rules (cel header) + layer ordering. For character grounding, emit authoring anchors (slice/pivot/user-data) but validate final foot placement against exported PNG alpha bounds (via `asset-pipeline`) before locking runtime offsets. ### 2) Debug "why is this invisible?" Check layer visibility + opacity; whether a cel is **linked** to another frame; for indexed sprites, the transparent index + background-layer semantics. ### 3) Convert slices to hitboxes/anchors Use slice keys per frame for runtime hitboxes. Use pivot when present; otherwise infer (e.g. slice center) and record it as a fallback. ## Exporting for Phaser `aseprite -b` → `spritesheet.png` + `spritesheet.json`, then `this.load.aseprite(key, png, json)` + `this.anims.createFromAseprite(key)`. The rules that keep it correct: - **Hide editor-only layers with a Lua script, not `--ignore-layer`** — the CLI flag silently no-ops on some files. Match the usual suspects: `bg`, `BG`, `Background`, `Text`, `Reflection`, `Layer 1`. Recipe in `references/inference-recipes.md` §9. - **Frame 0 is often a blank guide spacer.** Check `--decode-cels` empty-frame detection and drop it from the tag range or the export, or every clip starts with a hole. - **`--format json-array`, `--sheet-type packed` or `rows`, NO `--trim`.** `createFromAseprite` looks frames up by index (`frames[i.toString()]`), which only the array layout gives; trim moves the feet per frame, so bottom-anchored origins drift. Keep the canvas fixed. - **Build anims from the exported per-frame `duration`s** — `createFromAseprite` does this; hand-rolled anims must pass `frames: [{ key, frame, duration }]` with no `frameRate`. - **Never pass `duration` to `play()`** — freezes on frame 1. Retime with `sprite.anims.timeScale`. Depth in the `phaser` skill, `references/spritesheets-and-textures.md`. ## Anti-Patterns - **"speed" is authoritative** — it's deprecated; frame duration is the timeline. Apply the speed fallback only when a frame duration is 0. - **Palette always exists / always 256 entries** — parse palette chunks when present; indexed sprites still need transparency-index handling. - **Hard-failing on unknown chunks** — skip by chunk size; store a summary for debugging. - **Decompressing everything by default** — decode only what you need; cap large sprites. - **Treating indexed pixels as RGBA** — they're palette indices; transparency is by transparent index (header). Only map to RGBA once you've parsed a palette (and record missing-palette cases). - **Ignoring linked cels** — you'll lose frames or infer empty bounds. Resolve links in a post-pass before pixel/bounds inference. - **Assuming UI grouping equals render grouping** — group compositing depends on header flags + blend/opacity validity. Treat groups as structural unless building a renderer. - **Conflating authoring vs render intent** — tags/slices/user data describe intent, pixels describe appearance; they can disagree. Output both, don't "correct" one with the other unless asked. ## References & Scripts - `scripts/aseprite-inspect.mjs` — binary parser + JSON; optional cel/tile decode - `references/aseprite-format-cheatsheet.md` — chunk map + gotchas - `references/inference-recipes.md` — how to compute bounds/timing/order safely