feat: Expose useAtlas on Flame Tiled (#2852)

Flame Tiled uses SpriteBatch under the hood to render its tiles. That API has a flag called useAtlas that when false allows rendering to be done through drawImageRects instead of drawAtlas.

There were not way to set that through Flame Tiled though. This PR exposes that as an option for the developer.

packages/flame_tiled/lib/src/renderable_tile_map.dart

@@ -211,6 +211,7 @@ class RenderableTiledMap {
     Images? images,
     AssetBundle? bundle,
     bool Function(Tileset)? tsxPackingFilter,
+    bool useAtlas = true,
   }) async {
     final contents =
         await (bundle ?? Flame.bundle).loadString('$prefix$fileName');
@@ -225,6 +226,7 @@ class RenderableTiledMap {
       images: images,
       bundle: bundle,
       tsxPackingFilter: tsxPackingFilter,
+      useAtlas: useAtlas,
     );
   }
 
@@ -244,6 +246,7 @@ class RenderableTiledMap {
     Images? images,
     AssetBundle? bundle,
     bool Function(Tileset)? tsxPackingFilter,
+    bool useAtlas = true,
   }) async {
     final map = await TiledMap.fromString(
       contents,
@@ -259,6 +262,7 @@ class RenderableTiledMap {
       images: images,
       bundle: bundle,
       tsxPackingFilter: tsxPackingFilter,
+      useAtlas: useAtlas,
     );
   }
 
@@ -275,6 +279,7 @@ class RenderableTiledMap {
     Images? images,
     AssetBundle? bundle,
     bool Function(Tileset)? tsxPackingFilter,
+    bool useAtlas = true,
   }) async {
     // We're not going to load animation frames that are never referenced; but
     // we do supply the common cache for all layers in this map, and maintain
@@ -298,6 +303,7 @@ class RenderableTiledMap {
         maxY: atlasMaxY,
         images: images,
         tsxPackingFilter: tsxPackingFilter,
+        useAtlas: useAtlas,
       ),
       ignoreFlip: ignoreFlip,
       images: images,

packages/flame_tiled/lib/src/tile_atlas.dart

@@ -35,7 +35,14 @@ class TiledAtlas {
     required this.atlas,
     required this.offsets,
     required this.key,
-  }) : batch = atlas == null ? null : SpriteBatch(atlas, imageKey: key);
+    bool useAtlas = true,
+  }) : batch = atlas == null
+            ? null
+            : SpriteBatch(
+                atlas,
+                imageKey: key,
+                useAtlas: useAtlas,
+              );
 
   /// Returns whether or not this atlas contains [source].
   bool contains(String? source) => offsets.containsKey(source);
@@ -99,6 +106,7 @@ class TiledAtlas {
     double? maxY,
     Images? images,
     bool Function(Tileset)? tsxPackingFilter,
+    bool useAtlas = true,
   }) async {
     final tilesetImageList = _onlyTileImages(
       map,
@@ -133,6 +141,7 @@ class TiledAtlas {
         atlas: null,
         offsets: {},
         key: 'atlas{empty}',
+        useAtlas: useAtlas,
       );
     }
 

packages/flame_tiled/lib/src/tiled_component.dart

@@ -98,6 +98,11 @@ class TiledComponent<T extends FlameGame> extends PositionComponent
   /// A custom [atlasMaxX] and [atlasMaxY] can be provided in case you want to
   /// change the max size of [TiledAtlas] that [TiledComponent] creates
   /// internally.
+  ///
+  /// TiledComponent uses Flame's `SpriteBatch` to render the map. Which under
+  /// the hood uses `Canvas.drawAtlas` calls to render the tiles. This behavior
+  /// can be changed by setting `useAtlas` to `false`. This will make the map
+  /// be rendered with `Canvas.drawImageRect` calls instead.
   static Future<TiledComponent> load(
     String fileName,
     Vector2 destTileSize, {
@@ -109,6 +114,7 @@ class TiledComponent<T extends FlameGame> extends PositionComponent
     AssetBundle? bundle,
     Images? images,
     bool Function(Tileset)? tsxPackingFilter,
+    bool useAtlas = true,
   }) async {
     return TiledComponent(
       await RenderableTiledMap.fromFile(
@@ -121,6 +127,7 @@ class TiledComponent<T extends FlameGame> extends PositionComponent
         bundle: bundle,
         images: images,
         tsxPackingFilter: tsxPackingFilter,
+        useAtlas: useAtlas,
       ),
       priority: priority,
     );