SpriteAtlas class

A parsed sprite atlas containing one or more SpriteAtlasPages plus a registry of named SpriteRegions and AtlasAnimationClips.

Loading

// Result is cached by AssetManager — repeated calls for the same path
// return the same atlas without re-parsing or re-uploading textures.
final atlas = await SpriteAtlas.fromAsset('assets/data/heroes.json');

Creating sprites

// Creates a Sprite already wired to the correct region on the atlas page.
// renderSize is set to sourceSize so trimmed sprites display correctly.
final sprite = atlas.createSprite('hero_idle_0',
    position: Offset(100, 200),
    scale: 2.0);
engine.rendering.add(sprite);

Animated sprites

final sprite = atlas.createSprite('hero_run_0', position: Offset(200, 300));
final anim   = atlas.createAnimation('run', sprite);
engine.animation.add(anim);

Runtime clip registration

Clips embedded in the atlas JSON (Aseprite frameTags) are available immediately. Additional / override clips can be registered in code:

atlas.registerClip(AtlasAnimationClip(
  name: 'attack_combo',
  frames: [
    AtlasFrame(regionName: 'hero_attack_0', duration: 0.05),
    AtlasFrame(regionName: 'hero_attack_1', duration: 0.08),
    AtlasFrame(regionName: 'hero_attack_2', duration: 0.12),
  ],
  loop: false,
));

Constructors

SpriteAtlas({required String name, required List<SpriteAtlasPage> pages, required Map<String, SpriteRegion> regions, Map<String, AtlasAnimationClip>? clips})

Properties

clipNames → Iterable<String>

Every clip name registered in this atlas (both parsed and runtime).

no setter

hashCode → int

The hash code for this object.

no setter, inherited

name → String

Human-readable name taken from atlas metadata (typically the image file name without extension).

final

pages → List<SpriteAtlasPage>

All texture pages, ordered by page index.

final

regionCount → int

Total number of sprite regions.

no setter

regionNames → Iterable<String>

Every region name packed in this atlas.

no setter

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

createAnimation(String clipName, Sprite sprite, {bool? loop, double speed = 1.0, VoidCallback? onComplete}) → AtlasSpriteAnimation

Create an AtlasSpriteAnimation that drives sprite through the named animation clip.

createSprite(String regionName, {Vector3? position, double rotation = 0.0, double scale = 1.0, int layer = 0, int zOrder = 0, bool flipX = false, bool flipY = false}) → Sprite

Create a Sprite backed by the named region on this atlas.

getClip(String name) → AtlasAnimationClip?

Returns the named clip, or null if it does not exist.

getRegion(String name) → SpriteRegion?

Returns the named region, or null if it does not exist in this atlas.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

registerClip(AtlasAnimationClip clip) → void

Register (or replace) an AtlasAnimationClip at runtime.

registerClips(Iterable<AtlasAnimationClip> clips) → void

Convenience: register multiple clips in a single call.

requireClip(String clipName) → AtlasAnimationClip

Returns the named clip.

requireRegion(String regionName) → SpriteRegion

Returns the named region.

toString() → String

A string representation of this object.

override

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Static Methods

fromAsset(String jsonPath) → Future<SpriteAtlas>

Load and parse a sprite atlas from a JSON asset file, returning a fully ready SpriteAtlas with all page textures decoded.