Disclosure: This article was generated with AI for the FrameSprite team, which has a commercial interest in FrameSprite. It received a separate AI editorial review against the cited sources. Executed synthetic fixtures are identified with their runtime and limits; no other editor, engine, production or performance test is implied.
Inspect the affected cel's z-index before moving the whole weapon layer. Aseprite can change a cel's drawing order for one frame while leaving the visible layer list in place. That is useful when equipment crosses the body, but an inherited value can also explain why one exported pose has an unexpected overlap.
Key Takeaways
- Cel z-index is a per-frame ordering property.
- Diagnose the source composition before changing a runtime sorting rule.
- Compare neighboring frames and export a reference before making broad edits.
Confirm that this is an ordering problem
Choose a frame where the weapon and body actually overlap. Hide and show the weapon to identify which pixels belong to it. Compare the same region in the previous and next frames. A missing cel, a shifted cel, and a translucent cel need different repairs from a stacking change.
If only opacity changes, inspect the single-frame cel-opacity diagnosis. If the flattened source frame is correct but the game combines separate parts incorrectly, follow the runtime equipment-occlusion handoff. The steps here target the native source composition.
The Cel.zIndex reference defines zero as the layer's normal position, positive values as moving the cel forward, and negative values as moving it backward. The documented range is -32768 through 32767. A cel's membership in a layer does not alone describe its final order.
Print the values without editing the source
Run a diagnostic script against a saved copy of the intended sprite. This reads the cels and prints their frame, layer name, and z-index:
local sprite = app.activeSprite
if not sprite then return end
for _, cel in ipairs(sprite.cels) do
print(cel.frameNumber, cel.layer.name, cel.zIndex)
end
Find the affected frame and compare its weapon value with adjacent frames. Frame numbers in the Cel API begin at one. Keep that distinction when comparing a zero-based external manifest.
If the value is intentional, document it. If it is accidental, change only the selected cel through the editor's available cel controls or an undoable script after recording its original value. Do not set every weapon cel to zero merely because one pose is wrong: a swing may legitimately pass behind the torso halfway through an action.
A bounded ordering example
The synthetic fixture has two flat layers: weapon at index zero with cel z-index two, and body at index one with cel z-index zero. Their distinct effective positions are two and one, so the illustrated order is body, then weapon.
The file-format specification's cel chunk and NOTE.5 describe z-index-aware ordering and tie handling. Our small arithmetic fixture deliberately avoids ties and nested groups. Sorting every production document only by layerIndex + zIndex would omit those cases.
The results record effectiveOrder: ["body", "weapon"], produced with Python 3.12.10/Pillow 13.0.0. The script and input reproduce that diagram. They do not execute the Lua example or Aseprite's renderer.
Verify the repaired sequence
Export the affected frame before and after the focused change using identical visibility, scale, and background settings. Check the overlap at native resolution, then play the neighboring poses in order. The weapon should cross at the intended animation phase without disappearing behind an unrelated layer.
Include the source frame number and an overlap reference in the delivery notes. Preserve action names and durations using the frame-tag export checklist. A correct still frame is insufficient if the delivered action selects different frames or timings.
Prepared by the FrameSprite Workflow Team. AI-assisted technical writing with a synthetic ordering illustration; no Aseprite GUI or runtime rendering was tested. Editorial method · Corrections.
Top comments (0)