flame_texturepacker 5.1.1

A simple plugin for the Flame Engine to import spritesheets generated by the TexturePacker tool.

A flame plugin to import sprite sheets generated by Gdx Texture Packer and Code & Web Texture Packer

---

flame_texturepacker

TexturePacker is a tool to create efficient sprite sheets. This plugin allows you to import sprite sheets generated by Gdx Texture Packer and Code and Web Texture Packer into your Flame game.

Install from Pub

flutter pub add flame_texturepacker

Usage

Asset Storage

Drop generated atlas file and sprite sheet images into the assets/images/ and link the files in your pubspec.yaml file:

 assets:
   - assets/images/atlas_map.atlas
   - assets/images/sprite_sheet1.png

Import the plugin like this:

import 'package:flame_texturepacker/flame_texturepacker.dart';

Load the TextureAtlas passing the path of the sprite sheet atlas file:

final atlas = await TexturePackerAtlas.load('atlas_map.atlas');

Extension on Game

For convenience, there is also an extension on Game (and FlameGame) that allows you to load an atlas directly:

class MyGame extends FlameGame {
  @override
  Future<void> onLoad() async {
    final atlas = await atlasFromAssets('atlas_map.atlas');
    // ...
  }
}

Loading from a Package

To load an atlas from another Flutter package, use the package parameter:

final atlas = await TexturePackerAtlas.load(
  'atlas_map.atlas',
  package: 'my_assets_package',
);

Paths and Prefixes

By default, TexturePackerAtlas.load looks for files in assets/images/. This is controlled by the assetsPrefix parameter, which defaults to 'images'.

1. Default usage (relative to assets/images/)

// Path: assets/images/hero.atlas
final atlas = await TexturePackerAtlas.load('hero.atlas');

2. Custom prefix (relative to assets/)

// Path: assets/atlases/hero.atlas
final atlas = await TexturePackerAtlas.load(
  'hero.atlas',
  assetsPrefix: 'atlases',
);

3. Full path (stripping standard prefix)

If you provide a path that already includes the standard assets/ or images/ prefix, the library will automatically strip them to avoid duplication. This is particularly useful when working with full asset paths.

// Path: assets/images/mega_explosions.atlas
final atlas = await TexturePackerAtlas.load(
  'assets/images/mega_explosions.atlas',
  assetsPrefix: '',
);

4. Automatic Package Detection

If you provide a path that starts with packages/package_name/..., the library will automatically detect the package name and adjust the internal loading logic.

// Path: packages/my_assets_package/assets/images/heroes.atlas
final atlas = await TexturePackerAtlas.load('packages/my_assets_package/assets/images/heroes.atlas');

Whitelist Images

This is optional, but recommended to avoid loading every sprite from your texture pack into memory. Use a list of relative paths to load only the Sprites you need into memory.

final regions = await TexturePackerAtlas.loadAtlas('atlas_map.atlas');
final atlas = TexturePackerAtlas.fromAtlas(regions, whiteList: [
  'weapons/',
  'ships/',
  'explosions/'
]);

File Storage

If you are using file storage, grab your atlas file like this:

final documentsPath = (await getApplicationDocumentsDirectory()).path;
final atlas = await TexturePackerAtlas.load(
  '$documentsPath/atlas_map.atlas',
  fromStorage: true,
);

Get a list of sprites ordered by their index, you can use the list to generate an animation:

final spriteList = atlas.findSpritesByName('robot_walk');

final animation = SpriteAnimation.spriteList(
 spriteList,
 stepTime: 0.1,
 loop: true,
);

Or use the convenience method getAnimation:

final animation = atlas.getAnimation('robot_walk', stepTime: 0.1, loop: true);

If your atlas contains multiple animations, load it once and reuse it:

final atlas = await TexturePackerAtlas.load('atlas_map.atlas');

final walkAnim = atlas.getAnimation('robot_walk');
final runAnim  = atlas.getAnimation('robot_run');
final jumpAnim = atlas.getAnimation('robot_jump', loop: false);

Get individual sprites by name:

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

Supported Features

Feature	Supported
Allow Rotation	YES
Multiple Pages	YES
Use indices	YES
Strip whitespace X	YES
Strip whitespace Y	YES

Example

Full working example can be found in example folder.

Note: Sprites used in this example can be found OpenGameArt here.

Credits

Thanks to Jonas Fröber for the original implementation. Thanks to Gnarhard for the feature to load an atlas file from a device's storage, sprite whitelisting, and memory optimizations.