(#3861) fix example , improve example

Author: s1r1m1r1

packages/flame_texturepacker/README.md

@@ -56,12 +56,89 @@ 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');
 ```
 
 
-### Whitelist Images
+### 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');
+```
+
+
+### 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.
 
@@ -76,12 +153,14 @@ final atlas = TexturePackerAtlas.fromAtlas(regions, whiteList: [
 
 
 ### File Storage
-
 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 +175,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 +207,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,5 @@
 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_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,42 @@
+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,
+      );
+}