AsepriteClipLoader Class
Loads AnimationClips from Aseprite JSON sprite-sheet exports.
Supports both JSON Array and JSON Hash data formats
(File → Export Sprite Sheet).
public class AsepriteClipLoaderInheritance System.Object → AsepriteClipLoader
Remarks¶
Each meta.frameTags entry becomes one AnimationClip named after the tag.
Frame durations are taken directly from the per-frame duration field (milliseconds).
Tag directions map as follows:
|
If the JSON has no frameTags (or an empty array), a single clip named after
defaultClipName is created from all frames.
Aseprite slice data (meta.slices) is mapped to SpriteFrame hit boxes.
Any slice whose name matches HitBoxSliceName (default "hitbox") is
stored as the primary HitBox. All other slices are stored as
additional named boxes via SetHitBox(string, Rectangle) using the slice name as the
key, so slices named "hurtbox", "head", etc. are preserved automatically.
The Aseprite per-slice pivot field, when present, is mapped to
Origin (normalised by the original canvas frame size from
sourceSize, so trimmed exports produce correct pivot positions).
When Aseprite's Trim export option is active, frames carry spriteSourceSize
(the sub-rect of the original canvas covered by trimmed pixels) and sourceSize
(the original untrimmed canvas size). The loader maps the trim offset to
DrawOffset so that trimmed sprites render at the correct canvas
position without any changes to the atlas frame rect.
The tag-level repeat field is mapped to RepeatCount
on Loop and PingPong clips.
The tag-level data field (Aseprite Tag User Data) is forwarded to
UserData as a string, unless UserData
has already been set by the direction logic (e.g. PingPongReverseTag).
The per-frame data field (Aseprite Frame User Data, set via
right-click → Frame Properties) is mapped to UserData as a
string. Frames without a data field, or with an empty string, leave
UserData as null.
| Fields | |
|---|---|
| PingPongReverseTag | Value placed in UserData for pingpong_reverse tags. |
| Properties | |
|---|---|
| HitBoxSliceName | Name of the Aseprite slice that is mapped to HitBox. Defaults to "hitbox". All other slices are still loaded as named boxes. |
| PivotSliceName | Name of the Aseprite slice whose pivot data is mapped to Origin. Defaults to "hitbox" (same slice as HitBoxSliceName), which matches the common Aseprite workflow of placing a pivot on the primary hitbox slice. Set to a different slice name when you use a dedicated pivot slice (e.g. "pivot"). When multiple slices carry pivot data for the same frame, only the slice matching this name is used; others are logged as warnings and ignored. |
| Methods | |
|---|---|
| ConfigureAnimator(SpriteAnimator, IReadOnlyList<AnimationClip>) | Adds all clips in clips to animator and applies direction hints stored in UserData. A clip with UserData == automatically toggles Reversed on enter/exit, scoped per (clip, animator) pair. Safe to call multiple times — callbacks are only subscribed once per pair. |
| Load(string, ITexture, string, string) | Synchronously loads all tagged animation clips from an Aseprite JSON export file. |
| Load(Stream, ITexture, string, string, string) | Synchronously loads all tagged animation clips from a System.IO.Stream containing Aseprite JSON. |
| Load(ReadOnlyMemory<byte>, ITexture, string, string, string) | Synchronous overload for LoadAsync(ReadOnlyMemory<byte>, ITexture, string, string, string, CancellationToken). Parses a UTF-8 encoded Aseprite JSON payload already in memory. |
| LoadAsync(string, ITexture, string, string, CancellationToken) | Loads all tagged animation clips from an Aseprite JSON export file. |
| LoadAsync(Stream, ITexture, string, string, string, CancellationToken) | Loads all tagged animation clips from a System.IO.Stream containing Aseprite JSON. |
| LoadAsync(ReadOnlyMemory<byte>, ITexture, string, string, string, CancellationToken) | Loads all tagged animation clips from a UTF-8 encoded Aseprite JSON payload in memory. |
| ParseJson(string, string, ITexture, string, string) | Parses Aseprite JSON directly from a string. |