feat: TexturePacker atlas can be generated from device's file

.github/.cspell/people_usernames.txt

@@ -5,6 +5,7 @@ erayzesen # erayzesen.itch.io
 erickzanardo # github.com/erickzanardo 
 feroult # github.com/feroult 
 fröber # github.com/Brixto
+gnarhard # github.com/gnarhard
 Klingsbo # github.com/spydon
 luanpotter # github.com/luanpotter
 Lukas # github.com/spydon

.github/.cspell/words_dictionary.txt

@@ -34,4 +34,3 @@ tappable
 tappables
 toolset
 underutilize
-unrotated

packages/flame_texturepacker/README.md

@@ -33,6 +33,9 @@ flutter pub add flame_texturepacker
 
 ## Usage
 
+
+### Asset Storage
+
 Drop generated atlas file and sprite sheet images into the `assets/` and link the files in your
 `pubspec.yaml` file:
 
@@ -52,6 +55,16 @@ Load the TextureAtlas passing the path of the sprite sheet atlas file:
 final atlas = await fromAtlas('atlas_map.atlas');
 ```
 
+
+### File Storage
+
+If you are using file storage, grab your atlas file like this:
+
+```Dart
+final documentsPath = (await getApplicationDocumentsDirectory()).path;
+final atlas = await fromAtlas("${documentsPath}/atlas_map.atlas", fromStorage: true);
+```
+
 Get a list of sprites ordered by their index, you can use the list to generate an animation:
 
 ```Dart
@@ -80,10 +93,12 @@ Note: Sprites used in this example can be found OpenGameArt [here][4].
 ## Credits
 
 Thanks to [Jonas Fröber][5] for the original implementation.
+Thanks to [Gnarhard][6] for the feature to build the atlas file from a device's storage.
 
 [1]: https://www.codeandweb.com/texturepacker 'Code & Web Texture Packer'
 [2]: https://github.com/crashinvaders/gdx-texture-packer-gui 'Gdx Texture Packer'
 [3]: example/lib/main.dart 'Full working example'
 [4]: https://opengameart.org/content/toon-characters-1 'Robot sprite'
 [5]: https://github.com/Brixto
+[6]: https://github.com/gnarhard
 

packages/flame_texturepacker/lib/atlas/model/texture_packer_sprite.dart

@@ -1,9 +1,4 @@
-import 'dart:math';
-import 'dart:ui';
-
 import 'package:flame/components.dart';
-import 'package:flame/game.dart';
-import 'package:flame/rendering.dart';
 import 'package:flame_texturepacker/atlas/model/region.dart';
 
 /// {@template _texture_packer_sprite}
@@ -16,25 +11,17 @@ class TexturePackerSprite extends Sprite {
         index = region.index,
         offsetX = region.offsetX,
         offsetY = region.offsetY,
-        packedWidth = region.rotate ? region.height : region.width,
-        packedHeight = region.rotate ? region.width : region.height,
+        packedWidth = region.width,
+        packedHeight = region.height,
         originalWidth = region.originalWidth,
         originalHeight = region.originalHeight,
         rotate = region.rotate,
         degrees = region.degrees,
         super(
           region.page.texture,
           srcPosition: Vector2(region.left, region.top),
-          srcSize: Vector2(
-            region.rotate ? region.height : region.width,
-            region.rotate ? region.width : region.height,
-          ),
-        ) {
-    decorator = Transform2DDecorator(transform);
-    if (region.rotate) {
-      transform.angle = radians(90);
-    }
-  }
+          srcSize: Vector2(region.width, region.height),
+        );
 
   /// The number at the end of the original image file name, or -1 if none.
   ///
@@ -80,53 +67,5 @@ class TexturePackerSprite extends Sprite {
   final int degrees;
 
   /// The [degrees] field (angle) represented as radians.
-  double get angle => degrees * (pi / 180);
-
-  late final Decorator decorator;
-  final Transform2D transform = Transform2D();
-
-  // Used to avoid the creation of new Vector2 objects in render.
-  static final _tmpRenderPosition = Vector2.zero();
-  static final _tmpRenderSize = Vector2.zero();
-
-  @override
-  void render(
-    Canvas canvas, {
-    Vector2? position,
-    Vector2? size,
-    Anchor anchor = Anchor.topLeft,
-    Paint? overridePaint,
-  }) {
-    if (position != null) {
-      _tmpRenderPosition.setFrom(position);
-    } else {
-      _tmpRenderPosition.setZero();
-    }
-
-    // If the sprite is rotated on the sprite sheet un-rotate it and adjust the
-    // size.
-    final unrotatedAnchor = rotate ? Anchor.bottomLeft : anchor;
-
-    final tempSize = size ?? srcSize;
-    final tempWidth = rotate ? tempSize.y : tempSize.x;
-    final tempHeight = rotate ? tempSize.x : tempSize.y;
-
-    _tmpRenderSize.setValues(tempWidth, tempHeight);
-
-    _tmpRenderPosition.setValues(
-      _tmpRenderPosition.x - (unrotatedAnchor.x * _tmpRenderSize.x),
-      _tmpRenderPosition.y - (unrotatedAnchor.y * _tmpRenderSize.y),
-    );
-
-    decorator.applyChain(
-      (applyCanvas) => super.render(
-        applyCanvas,
-        position: _tmpRenderPosition,
-        size: _tmpRenderSize,
-        anchor: anchor,
-        overridePaint: overridePaint,
-      ),
-      canvas,
-    );
-  }
+  double get angle => radians(degrees.toDouble());
 }

packages/flame_texturepacker/lib/atlas/texture_packer_atlas.dart

@@ -1,13 +1,15 @@
 library flame_texturepacker;
 
 import 'dart:convert';
+import 'dart:io';
 
 import 'package:collection/collection.dart';
 import 'package:flame/cache.dart';
 import 'package:flame/flame.dart';
 import 'package:flame_texturepacker/atlas/model/page.dart';
 import 'package:flame_texturepacker/atlas/model/region.dart';
 import 'package:flame_texturepacker/atlas/model/texture_packer_sprite.dart';
+import 'package:flutter/painting.dart';
 
 final _images = Images(prefix: 'assets/');
 
@@ -19,8 +21,20 @@ class TexturePackerAtlas {
 
   /// Loads all the sprites from the atlas that resides on the [path] and
   /// returns a new [TexturePackerAtlas].
-  static Future<TexturePackerAtlas> load(String path) async {
-    final atlasData = await _load(path);
+  /// If [fromStorage] is true, the atlas will be loaded from the device's
+  /// storage instead of the assets folder.
+  static Future<TexturePackerAtlas> load(
+    String path, {
+    bool fromStorage = false,
+  }) async {
+    final _TextureAtlasData atlasData;
+
+    if (fromStorage) {
+      atlasData = await _fromStorage(path);
+    } else {
+      atlasData = await _fromAssets(path);
+    }
+
     return TexturePackerAtlas(
       atlasData.regions.map(TexturePackerSprite.new).toList(),
     );
@@ -51,27 +65,65 @@ class TexturePackerAtlas {
   }
 }
 
-Future<_TextureAtlasData> _load(String path) async {
+/// Loads images from the assets folder.
+/// Uses the [path] to find the image directory.
+Future<_TextureAtlasData> _fromAssets(String path) async {
+  try {
+    return await _parse(path, fromStorage: false);
+  } on Exception catch (e) {
+    throw Exception('Error loading $path from assets: $e');
+  }
+}
+
+/// Loads images from the device's storage.
+/// Uses the [path] to find the image directory.
+Future<_TextureAtlasData> _fromStorage(String path) async {
+  try {
+    return await _parse(path, fromStorage: true);
+  } on Exception catch (e) {
+    throw Exception('Error loading $path from storage: $e');
+  }
+}
+
+/// Parses the atlas file and loads the images.
+/// Uses the [path] to find the image directory.
+/// Atlas will be loaded from the device's storage if [fromStorage] is true.
+/// Otherwise, it will be loaded from the assets folder.
+/// Returns a [_TextureAtlasData] containing the pages and regions.
+Future<_TextureAtlasData> _parse(
+  String path, {
+  required bool fromStorage,
+}) async {
   final pages = <Page>[];
   final regions = <Region>[];
-  final fileAsString = await Flame.assets.readFile(path);
+  final String fileAsString;
+
+  if (fromStorage) {
+    fileAsString = await File(path).readAsString();
+  } else {
+    fileAsString = await Flame.assets.readFile(path);
+  }
 
   final iterator = LineSplitter.split(fileAsString).iterator;
   var line = iterator.moveNextAndGet();
   var hasIndexes = false;
+
   while (true) {
     if (line == null) {
       break;
     }
+
     if (line.isEmpty) {
       line = iterator.moveNextAndGet();
     }
 
     Page? page;
+
     while (true) {
       if (line == null) {
         break;
       }
+
       if (line.isEmpty) {
         page = null;
         line = iterator.moveNextAndGet();
@@ -80,7 +132,21 @@ Future<_TextureAtlasData> _load(String path) async {
         page.textureFile = line;
         final parentPath = (path.split('/')..removeLast()).join('/');
         final texturePath = '$parentPath/$line';
-        page.texture = await _images.load(texturePath);
+
+        if (fromStorage) {
+          try {
+            final textureFile = File(texturePath);
+            final bytes = await textureFile.readAsBytes();
+            final decodedBytes = await decodeImageFromList(bytes);
+            Flame.images.add(texturePath, decodedBytes);
+            page.texture = Flame.images.fromCache(texturePath);
+          } on Exception catch (e) {
+            throw Exception('Could not add storage file to Flame cache. $e');
+          }
+        } else {
+          page.texture = await _images.load(texturePath);
+        }
+
         while (true) {
           line = iterator.moveNextAndGet();
           if (line == null) {
@@ -142,16 +208,19 @@ Future<_TextureAtlasData> _load(String path) async {
               region.originalHeight = double.parse(entry[4]);
             case 'rotate':
               final value = entry[1];
+
               if (value == 'true') {
                 region.degrees = 90;
               } else if (value == 'false') {
                 region.degrees = 0;
               } else {
                 region.degrees = int.parse(value);
               }
+
               region.rotate = region.degrees == 90;
             case 'index':
               region.index = int.parse(entry[1]);
+
               if (region.index != -1) {
                 hasIndexes = true;
               }
@@ -161,10 +230,12 @@ Future<_TextureAtlasData> _load(String path) async {
           region.originalWidth = region.width;
           region.originalHeight = region.height;
         }
+
         regions.add(region);
       }
     }
   }
+
   if (hasIndexes) {
     regions.sort((region1, region2) {
       var i1 = region1.index;
@@ -178,28 +249,37 @@ Future<_TextureAtlasData> _load(String path) async {
       return i1 - i2;
     });
   }
+
   return (pages: pages, regions: regions);
 }
 
-({int count, List<String> entry}) _readEntry(String inputLine) {
-  final line = inputLine.trim();
-  if (line.isEmpty) {
+({int count, List<String> entry}) _readEntry(String line) {
+  final trimmedLine = line.trim();
+
+  if (trimmedLine.isEmpty) {
     return (count: 0, entry: []);
   }
-  final colonIndex = line.indexOf(':');
+
+  final colonIndex = trimmedLine.indexOf(':');
+
   if (colonIndex == -1) {
     return (count: 0, entry: []);
   }
+
   final entry = <String>[];
-  entry.add(line.substring(0, colonIndex).trim());
+  entry.add(trimmedLine.substring(0, colonIndex).trim());
+
   for (var i = 1, lastMatch = colonIndex + 1;; i++) {
-    final commaIndex = line.indexOf(',', lastMatch);
+    final commaIndex = trimmedLine.indexOf(',', lastMatch);
+
     if (commaIndex == -1) {
-      entry.add(line.substring(lastMatch).trim());
+      entry.add(trimmedLine.substring(lastMatch).trim());
       return (count: i, entry: entry);
     }
-    entry.add(line.substring(lastMatch, commaIndex).trim());
+
+    entry.add(trimmedLine.substring(lastMatch, commaIndex).trim());
     lastMatch = commaIndex + 1;
+
     if (i == 4) {
       return (count: 4, entry: entry);
     }
@@ -213,6 +293,7 @@ extension _IteratorExtension on Iterator<String> {
     if (moveNext()) {
       return current;
     }
+
     return null;
   }
 }

packages/flame_texturepacker/lib/flame_texturepacker.dart

@@ -6,8 +6,11 @@ import 'package:flame_texturepacker/atlas/texture_packer_atlas.dart';
 export 'package:flame_texturepacker/atlas/model/texture_packer_sprite.dart';
 
 extension TexturepackerLoader on Game {
-  /// Loads the specified pack file, using the parent directory of the pack file
-  /// to find the page images.
-  Future<TexturePackerAtlas> fromAtlas(String assetsPath) async =>
-      TexturePackerAtlas.load(assetsPath);
+  /// Loads the specified pack file.
+  /// Uses the parent directory of the pack file to find the page images.
+  Future<TexturePackerAtlas> fromAtlas(
+    String assetsPath, {
+    bool fromStorage = false,
+  }) async =>
+      TexturePackerAtlas.load(assetsPath, fromStorage: fromStorage);
 }