refactor: Update package support filed and handle more sprite index patterns

packages/flame_texturepacker/README.md

@@ -56,7 +56,96 @@ Import the plugin like this:
 Load the TextureAtlas passing the path of the sprite sheet atlas file:
 
 ```Dart
-final atlas = await atlasFromAssets('atlas_map.atlas');
+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:
+
+
+```dart
+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:
+
+```Dart
+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/`)
+
+
+```dart
+// Path: assets/images/hero.atlas
+final atlas = await TexturePackerAtlas.load('hero.atlas');
+```
+
+
+#### 2. Custom prefix (relative to `assets/`)
+
+
+```dart
+// 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.
+
+
+```dart
+// 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.
+
+```dart
+// Path: packages/my_assets_package/assets/images/heroes.atlas
+final atlas = await TexturePackerAtlas.load('packages/my_assets_package/assets/images/heroes.atlas');
 ```
 
 
@@ -81,7 +170,10 @@ If you are using file storage, grab your atlas file like this:
 
 ```Dart
 final documentsPath = (await getApplicationDocumentsDirectory()).path;
-final atlas = await atlasFromStorage('$documentsPath/atlas_map.atlas');
+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:
@@ -96,6 +188,22 @@ final animation = SpriteAnimation.spriteList(
 );
 ```
 
+Or use the convenience method `getAnimation`:
+
+```Dart
+final animation = atlas.getAnimation('robot_walk', stepTime: 0.1, loop: true);
+```
+
+If your atlas contains multiple animations, load it once and reuse it:
+
+```Dart
+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:
 
 ```Dart
@@ -112,8 +220,8 @@ final idleSprite = atlas.findSpriteByName('robot_idle')!;
 | Allow Rotation     | YES       |
 | Multiple Pages     | YES       |
 | Use indices        | YES       |
-| Strip whitespace X | NO        |
-| Strip whitespace Y | NO        |
+| Strip whitespace X | YES       |
+| Strip whitespace Y | YES       |
 
 
 ## Example

packages/flame_texturepacker/lib/flame_texturepacker.dart

@@ -1,43 +1,6 @@
 library flame_texturepacker;
 
-import 'package:flame/cache.dart';
-import 'package:flame/game.dart';
-import 'package:flame_texturepacker/src/texture_packer_atlas.dart';
-
+export 'package:flame_texturepacker/src/extension_on_game.dart';
 export 'package:flame_texturepacker/src/texture_packer_atlas.dart';
+export 'package:flame_texturepacker/src/texture_packer_parser.dart';
 export 'package:flame_texturepacker/src/texture_packer_sprite.dart';
-
-extension TexturepackerLoader on Game {
-  /// Loads the specified pack file from assets
-  /// Uses the parent directory of the pack file to find the page images.
-  Future<TexturePackerAtlas> atlasFromAssets(
-    String assetsPath, {
-    Images? images,
-    AssetsCache? assets,
-    bool useOriginalSize = true,
-    List<String> whiteList = const [],
-    String assetsPrefix = 'images',
-  }) async => TexturePackerAtlas.load(
-    assetsPath,
-    images: images ?? this.images,
-    assets: assets ?? this.assets,
-    useOriginalSize: useOriginalSize,
-    whiteList: whiteList,
-    assetsPrefix: assetsPrefix,
-  );
-
-  /// Loads the specified pack file from storage
-  /// Uses the parent directory of the pack file to find the page images.
-  Future<TexturePackerAtlas> atlasFromStorage(
-    String storagePath, {
-    Images? images,
-    bool useOriginalSize = true,
-    List<String> whiteList = const [],
-  }) async => TexturePackerAtlas.load(
-    storagePath,
-    fromStorage: true,
-    images: images ?? this.images,
-    useOriginalSize: useOriginalSize,
-    whiteList: whiteList,
-  );
-}

packages/flame_texturepacker/lib/src/extension_on_game.dart

@@ -0,0 +1,40 @@
+import 'package:flame/cache.dart';
+import 'package:flame/game.dart';
+import 'package:flame_texturepacker/flame_texturepacker.dart';
+
+extension TexturepackerLoader on Game {
+  /// Loads the specified pack file from assets
+  /// Uses the parent directory of the pack file to find the page images.
+  Future<TexturePackerAtlas> atlasFromAssets(
+    String assetsPath, {
+    Images? images,
+    AssetsCache? assets,
+    bool useOriginalSize = true,
+    List<String> whiteList = const [],
+    String assetsPrefix = 'images',
+    String? package,
+  }) => TexturePackerAtlas.load(
+    assetsPath,
+    images: images ?? this.images,
+    assets: assets ?? this.assets,
+    useOriginalSize: useOriginalSize,
+    whiteList: whiteList,
+    assetsPrefix: assetsPrefix,
+    package: package,
+  );
+
+  /// Loads the specified pack file from storage
+  /// Uses the parent directory of the pack file to find the page images.
+  Future<TexturePackerAtlas> atlasFromStorage(
+    String storagePath, {
+    Images? images,
+    bool useOriginalSize = true,
+    List<String> whiteList = const [],
+  }) => TexturePackerAtlas.load(
+    storagePath,
+    fromStorage: true,
+    images: images ?? this.images,
+    useOriginalSize: useOriginalSize,
+    whiteList: whiteList,
+  );
+}

packages/flame_texturepacker/lib/src/model/page.dart

@@ -2,11 +2,14 @@ import 'dart:ui';
 
 class Page {
   late String textureFile;
-  late Image texture;
+  Image? texture;
   late int width;
   late int height;
   late String format;
   late String minFilter;
   late String magFilter;
-  late String repeat;
+  String? repeat;
+
+  /// Returns true if the texture has been loaded.
+  bool get isLoaded => texture != null;
 }