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;
// trimmed and rotated frames are drawn where and how they belong.
final sprite = atlas.createSprite('hero_idle_0',
    position: Offset(100, 200),
    scale: 2.0);
engine.rendering.add(sprite);

Animated sprites

An entity plays a clip with a SpriteAnimationComponent, which the SpriteAnimationSystem advances:

entity.addComponent(SpriteAnimationComponent(
  atlasPath: 'assets/data/heroes.json',
  clip: 'run',
));

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, Map<String, dynamic>? userData}): An atlas named name over pages, with regions by name and starting with clips (none when null; more can be registered). regions, clips and userData (empty when null) are copied; pages is kept as given. Parsers make these.

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 setterinherited
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 setterinherited
userData → Map<String, dynamic>: What the authoring tool stored beyond the standard format — the meta.just block of an Aseprite-style export: per-clip loop flags and frame events. Empty for a file that has none.
final

Methods

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 — an AtlasRegionSprite.
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, {required AssetManager assets}) → Future<SpriteAtlas>: Load and parse a sprite atlas from a JSON asset file, returning a fully ready SpriteAtlas with all page textures decoded.
fromJson(Map<String, dynamic> json, {String basePath = '', String? jsonPath, required Future<Image> loadImage(String imagePath)}) → Future<SpriteAtlas>: Builds an atlas from already-decoded json, fetching each page's image through loadImage instead of the asset bundle — for a tool that reads files the bundle does not hold yet, or a test that has no bundle. basePath is the JSON file's directory, with its trailing slash; jsonPath lets a legacy grid sheet find the image beside it.