flutter_spritesheet_animation #

Lightweight spritesheet animation widget for Flutter. Supports grid-based and JSON atlas (TexturePacker, Aseprite) spritesheets with named animations, playback modes, and an external controller.

Zero external dependencies - uses only the Flutter SDK.

Features #

• Grid-based spritesheet animation (uniform frame grid)
• JSON atlas animation (TexturePacker hash/array, Aseprite)
• Named animations via frameTags
• Playback modes: forward, reverse, pingPong
• External controller for programmatic control
• Per-frame duration support from atlas data
• Pre-computed frame rects for optimal rendering
• Configurable FPS, looping, blend mode, box fit

Installation #

dependencies:
  flutter_spritesheet_animation: ^1.0.0

Usage #

Grid Mode #

For spritesheets with frames arranged in a uniform grid:

SpriteAnimation.grid(
  image: AssetImage('assets/explosion.png'),
  columns: 8,
  rows: 4,
  frameCount: 30,  // optional, defaults to columns * rows
  fps: 24,
  width: 128,
  height: 128,
)

Atlas Mode #

For spritesheets defined by a JSON atlas (TexturePacker or Aseprite export):

// Load atlas from asset
final atlas = await SpriteAtlas.fromAsset('assets/character.json');

SpriteAnimation.atlas(
  image: AssetImage('assets/character.png'),
  atlas: atlas,
  animation: 'idle',  // named animation from frameTags
  width: 128,
  height: 128,
)

Controller #

Use SpriteAnimationController for programmatic playback control:

final controller = SpriteAnimationController(
  fps: 24,
  mode: PlayMode.pingPong,
  loop: true,
  autoPlay: false,
);

// In your widget tree
SpriteAnimation.grid(
  image: AssetImage('assets/explosion.png'),
  columns: 8,
  rows: 4,
  controller: controller,
)

// Control playback
controller.play();
controller.pause();
controller.stop();
controller.goToFrame(5);

// Change settings at runtime
controller.fps = 30;
controller.mode = PlayMode.reverse;
controller.loop = false;

// Switch named animations (atlas mode)
controller.setAnimation('walk', atlas: atlas);

// Read state
controller.isPlaying;    // bool
controller.currentFrame; // int
controller.totalFrames;  // int
controller.animationName; // String?

// Don't forget to dispose when using externally
controller.dispose();

Precaching #

Pre-cache spritesheet images to eliminate loading flash:

// Single image
await SpriteAnimation.precache(
  const AssetImage('assets/explosion.png'),
  context,
);

// Multiple images in parallel
await SpriteAnimation.precacheAll([
  const AssetImage('assets/idle.png'),
  const AssetImage('assets/walk.png'),
  const AssetImage('assets/attack.png'),
], context);

Callbacks #

SpriteAnimation.grid(
  image: AssetImage('assets/explosion.png'),
  columns: 8,
  rows: 4,
  loop: false,
  onFrame: (frame) => print('Frame: $frame'),
  onComplete: () => print('Animation finished'),
)

Atlas JSON Formats #

TexturePacker (hash):

{
  "frames": {
    "idle_0.png": {
      "frame": { "x": 0, "y": 0, "w": 64, "h": 64 },
      "rotated": false,
      "trimmed": false,
      "spriteSourceSize": { "x": 0, "y": 0, "w": 64, "h": 64 },
      "sourceSize": { "w": 64, "h": 64 }
    }
  },
  "meta": {
    "size": { "w": 256, "h": 256 },
    "frameTags": [
      { "name": "idle", "from": 0, "to": 3 },
      { "name": "walk", "from": 4, "to": 9 }
    ]
  }
}

Aseprite (array):

{
  "frames": [
    {
      "filename": "idle_0.png",
      "frame": { "x": 0, "y": 0, "w": 64, "h": 64 },
      "duration": 100
    }
  ],
  "meta": {
    "frameTags": [
      { "name": "idle", "from": 0, "to": 3 }
    ]
  }
}

Both formats are auto-detected.

Performance #

Optimized for smooth 60fps animation rendering:

• Zero widget rebuilds: Uses CustomPainter(repaint: controller) — frame changes repaint only the paint layer, skipping build() entirely
• Zero-allocation tick loop: Raw microsecond arithmetic instead of Duration objects in the hot path
• Pre-computed frame rects: Grid source rectangles are calculated once at load time, not during paint
• Reusable Paint object: Single Paint instance reused across frames, avoiding per-frame allocations
• Accumulator-based timing: Frame advancement uses a time accumulator for accurate frame pacing
• Image precaching: precache() / precacheAll() to eliminate loading flash
• Multiple instances: Each widget runs independently with its own controller, ticker, and paint layer
• No external dependencies: Zero overhead from third-party packages

API Reference #

SpriteAnimation #

SpriteAnimationController #

SpriteAtlas #

License #

MIT