Flutter Flame: Sprite Animation Tutorial (Sprite Sheets Explained)

In the last Flutter Flame tutorial, we moved a plain RectangleComponent around the screen so we could focus on the game loop without worrying about art assets. Real games need actual characters, though, and that means sprite sheets. This tutorial covers loading a sprite sheet, slicing it into animation frames with Flame’s own SpriteSheet class, and switching between an idle animation and a run animation at runtime.

What You Need Before Starting

You need a sprite sheet where every frame is the same pixel size, laid out in a grid (rows and columns). If you do not have one yet, Kenney.nl gives away hundreds of CC0 (public domain) sprite sheets that work well for learning. Grab any character sheet, note its frame width and height in pixels (you will need the exact numbers), and drop the PNG into your Flutter project’s assets/images/ folder. Make sure pubspec.yaml lists that folder under flutter: assets:, or Flame will not find it at runtime.

Step 1: Load the Sprite Sheet Image

Flame caches images through the game’s own images loader, not through Flutter’s AssetImage. Inside a component’s onLoad(), calling await images.load('filename.png') loads the file from assets/images/ and returns a decoded dart:ui Image:

class Player extends SpriteAnimationGroupComponent<PlayerState>
    with HasGameReference {
  @override
  Future<void> onLoad() async {
    final image = await game.images.load('player_sheet.png');
    // next: slice it into frames
  }
}

enum PlayerState { idle, run }

A beginner mistake here is calling images.load() before the game widget has actually mounted (for example, in a constructor). It has to run inside onLoad(), which Flame guarantees runs after the component is attached to a loaded game.

Step 2: Slice the Sheet with Flame’s SpriteSheet Class

Flame’s SpriteSheet class turns one big image into addressable rows and columns of frames, as long as every frame is the same size. You give it the decoded image and the pixel size of a single frame via srcSize:

final spriteSheet = SpriteSheet(
  image: image,
  srcSize: Vector2(32, 32), // width, height of ONE frame, in pixels
);

This is the single most common place beginners get stuck: srcSize has to match the sheet’s actual frame dimensions exactly. If your sheet is 256×128 with 8 columns and 4 rows, each frame is 32×32, so srcSize is Vector2(32, 32), not the size you want to render the character at on screen. Getting this wrong does not throw an error; it just slices the sheet at the wrong boundaries and every animation frame looks subtly broken or shows parts of neighboring frames.

Step 3: Build an Idle and a Run Animation

SpriteSheet.createAnimation() reads across one row of the sheet and turns it into a SpriteAnimation. It takes a row index, a stepTime (seconds per frame), and an optional to parameter that stops the animation before the end of the row if that row has unused trailing frames:

final idleAnimation = spriteSheet.createAnimation(
  row: 0,
  stepTime: 0.2,
  to: 4, // row 0 has 4 real idle frames
);

final runAnimation = spriteSheet.createAnimation(
  row: 1,
  stepTime: 0.1,
  to: 6, // row 1 has 6 real run frames
);

Lower stepTime values play faster. A run cycle usually wants a smaller stepTime than an idle cycle, since a character’s legs move faster while running than its chest moves while idly breathing.

Step 4: Switch Animations at Runtime with SpriteAnimationGroupComponent

A plain SpriteAnimationComponent only ever plays one animation. To swap between idle and running, use SpriteAnimationGroupComponent<T> instead: it holds a map of states to animations, plus a current property you reassign whenever the active state should change.

class Player extends SpriteAnimationGroupComponent<PlayerState>
    with HasGameReference, KeyboardHandler {
  @override
  Future<void> onLoad() async {
    final image = await game.images.load('player_sheet.png');
    final spriteSheet = SpriteSheet(image: image, srcSize: Vector2(32, 32));

    animations = {
      PlayerState.idle: spriteSheet.createAnimation(row: 0, stepTime: 0.2, to: 4),
      PlayerState.run: spriteSheet.createAnimation(row: 1, stepTime: 0.1, to: 6),
    };

    current = PlayerState.idle;
    size = Vector2(32, 32);
    anchor = Anchor.center;
  }

  @override
  bool onKeyEvent(KeyEvent event, Set<LogicalKeyboardKey> keysPressed) {
    final isMoving = keysPressed.contains(LogicalKeyboardKey.arrowLeft) ||
        keysPressed.contains(LogicalKeyboardKey.arrowRight);

    current = isMoving ? PlayerState.run : PlayerState.idle;
    return true;
  }
}

enum PlayerState { idle, run }

Reassigning current does not restart the animation from scratch each frame; Flame only resets the animation ticker when the value actually changes. You can set it every frame in onKeyEvent or update() without worrying about the run cycle stuttering back to frame zero on every keypress.

Step 5: Flip the Sprite for Left and Right Movement

Most sprite sheets only face one direction. Rather than drawing a second mirrored sheet, call flipHorizontallyAroundCenter(), a method every PositionComponent (including SpriteAnimationGroupComponent) inherits, whenever the character changes direction:

bool _facingRight = true;

void _faceDirection(bool movingRight) {
  if (movingRight != _facingRight) {
    flipHorizontallyAroundCenter();
    _facingRight = movingRight;
  }
}

Guard it with a boolean like this. Calling flipHorizontallyAroundCenter() every single frame while already facing the right way will flip the sprite back and forth on alternating frames, since each call toggles the flip rather than setting it to a fixed state.

Common mistakes beginners make with sprite sheet animation

  • Wrong srcSize. If frames look sliced wrong or show slivers of the next frame, double-check the sheet’s actual frame pixel dimensions, not the size you want the sprite rendered at on screen.
  • Forgetting the pubspec.yaml assets entry. Flame’s images.load() throws a clear “Unable to load asset” error at runtime if the image is not declared under flutter: assets: in pubspec.yaml.
  • Calling flipHorizontallyAroundCenter() every frame unconditionally. Always gate it behind a direction check, or the sprite flickers between flipped and unflipped on consecutive frames.
  • Mismatched row lengths. If a row has fewer real frames than the sheet’s column count (for example, padding frames at the end), always pass to: so the animation does not play the empty padding frames as part of the loop.

Frequently asked questions

Do I need a separate sprite sheet for left and right facing?

No. flipHorizontallyAroundCenter() mirrors whatever sheet you already have, so one sheet covers both directions as long as the character design is symmetric enough to look right mirrored.

Why does SpriteSheet need srcSize instead of just figuring out the grid automatically?

Sprite sheets have no embedded metadata about where one frame ends and the next begins; it is just one flat image. srcSize is how you tell Flame the grid, and it is the one value you cannot get wrong.

Can I use this same approach for a Kotlin/Jetpack Compose game instead of Flutter?

The sprite sheet concept is identical, but the Dart API shown here is Flame-specific. For the Android/Kotlin side of this content pillar, see the upcoming Game Development Guide for the Compose Canvas track.

This is the second article in the Flutter Flame track. For the full roadmap, including collision detection and a game-over state that build directly on the Player class above, see the Game Development Guide.