flame_texturepacker

flame_texturepacker is a bridge package that allows you to load sprite sheets generated by CodeAndWeb’s TexturePacker into your Flame game.

A sprite sheet (or texture atlas) is a larger image that packs many smaller sprites together. This reduces the number of separate textures a game must load, which lowers overhead and can improve loading speed and rendering performance.

Installation

Add flame_texturepacker to your project:

flutter pub add flame_texturepacker

Then import it in your Dart code:

import 'package:flame_texturepacker/flame_texturepacker.dart';

Usage

Loading from Assets

First, add your .atlas data file and sprite sheet images to your assets directory and reference them in your pubspec.yaml:

flutter:
  assets:
    - assets/images/atlas_map.atlas
    - assets/images/sprite_sheet1.png
    - assets/images/sprite_sheet2.png
    - assets/images/sprite_sheet3.png

Then load the atlas in your game:

class MyGame extends FlameGame {
  @override
  Future<void> onLoad() async {
    // Load the texture atlas
    final atlas = await atlasFromAssets('atlas_map.atlas');
    
    // Use the atlas to get sprites
    final sprite = atlas.findSpriteByName('robot_jump')!;
    add(SpriteComponent(sprite: sprite));
  }
}

TexturePackerAtlas

The TexturePackerAtlas class is the main interface for working with texture atlases. It provides several methods to query and retrieve sprites.

Finding Sprites

Find a single sprite by name:

final jumpSprite = atlas.findSpriteByName('robot_jump')!;
final fallSprite = atlas.findSpriteByName('robot_fall')!;

Find a sprite by name and index:

final sprite = atlas.findSpriteByNameIndex('robot_walk', 0);

Find all sprites with the same name:

This is particularly useful for creating animations from indexed sprites:

// Get all sprites with the name 'robot_walk'
// (e.g., robot_walk_0, robot_walk_1, etc.)
final walkingSprites = atlas.findSpritesByName('robot_walk');

// Create an animation from the sprite list
final walkingAnimation = SpriteAnimation.spriteList(
  walkingSprites,
  stepTime: 0.1,
  loop: true,
);

add(SpriteAnimationComponent(animation: walkingAnimation));

Advanced Options

Whitelist Filtering

To optimize memory usage, you can specify a whitelist of sprite names to load. Only sprites whose names contain any of the whitelist strings will be loaded:

final atlas = await TexturePackerAtlas.load(
  'atlas_map.atlas',
  whiteList: [ 'robot_walk' ]
);

This is particularly useful for large atlases where you only need a subset of sprites.

Original Size vs Packed Size

TexturePacker can trim transparent pixels from sprites to save space. By default, flame_texturepacker uses the original (untrimmed) size. You can change this behavior:

final atlas = await TexturePackerAtlas.load(
  'atlas_map.atlas',
  useOriginalSize: false, // Use the trimmed/packed size instead
);

Custom Asset Prefix

If your .atlas data file is not stored in the default images directory:

final atlas = await atlasFromAssets(
  'atlas_map.atlas',
  assetsPrefix: 'custom_path',
);

Full Example

A complete working example can be found in the flame_texturepacker example or in this tutorial from CodeAndWeb.