feat: Added prefix parameter to TiledComponent.load to specify assets…

… folder for tiled maps (#2651)

Added prefix parameter to TiledComponent.load for allowing tiled maps files in different assets folder structures. It still defaults to assets/tiles. I created this PR because I discovered it when I wanted to add a tiled map in a different folder structure. I also saw this issue #2641. And though lets add it.

packages/flame_tiled/lib/src/flame_tsx_provider.dart

@@ -35,12 +35,13 @@ class FlameTsxProvider implements TsxProvider {
 
   /// Parses a file returning a [FlameTsxProvider].
   ///
-  /// NOTE: this method looks for files under the path "assets/tiles/".
+  /// {@macro renderable_tile_prefix_path}
   static Future<FlameTsxProvider> parse(
     String key, [
     AssetBundle? bundle,
+    String prefix = 'assets/tiles/',
   ]) async {
-    final data = await (bundle ?? Flame.bundle).loadString('assets/tiles/$key');
+    final data = await (bundle ?? Flame.bundle).loadString('$prefix$key');
     return FlameTsxProvider._(data, key);
   }
 }

packages/flame_tiled/lib/src/renderable_tile_map.dart

@@ -192,7 +192,10 @@ class RenderableTiledMap {
 
   /// Parses a file returning a [RenderableTiledMap].
   ///
-  /// NOTE: this method looks for files under the path "assets/tiles/".
+  /// {@template renderable_tile_prefix_path}
+  /// This method looks for files under the path "assets/tiles/" by default.
+  /// This can be changed by providing a different path to [prefix].
+  /// {@endtemplate}
   ///
   /// {@template renderable_tile_map_factory}
   /// By default, [FlameTileLayer] renders flipped tiles if they exist.
@@ -201,15 +204,17 @@ class RenderableTiledMap {
   static Future<RenderableTiledMap> fromFile(
     String fileName,
     Vector2 destTileSize, {
+    String prefix = 'assets/tiles/',
     CameraComponent? camera,
     bool? ignoreFlip,
     Images? images,
     AssetBundle? bundle,
   }) async {
-    final contents = await Flame.bundle.loadString('assets/tiles/$fileName');
+    final contents = await Flame.bundle.loadString('$prefix$fileName');
     return fromString(
       contents,
       destTileSize,
+      prefix: prefix,
       camera: camera,
       ignoreFlip: ignoreFlip,
       images: images,
@@ -219,18 +224,21 @@ class RenderableTiledMap {
 
   /// Parses a string returning a [RenderableTiledMap].
   ///
+  /// {@macro renderable_tile_prefix_path}
+  ///
   /// {@macro renderable_tile_map_factory}
   static Future<RenderableTiledMap> fromString(
     String contents,
     Vector2 destTileSize, {
+    String prefix = 'assets/tiles/',
     CameraComponent? camera,
     bool? ignoreFlip,
     Images? images,
     AssetBundle? bundle,
   }) async {
     final map = await TiledMap.fromString(
       contents,
-      (key) => FlameTsxProvider.parse(key, bundle),
+      (key) => FlameTsxProvider.parse(key, bundle, prefix),
     );
     return fromTiledMap(
       map,

packages/flame_tiled/lib/src/tiled_component.dart

@@ -87,11 +87,14 @@ class TiledComponent<T extends FlameGame> extends PositionComponent
 
   /// Loads a [TiledComponent] from a file.
   ///
+  /// {@macro renderable_tile_prefix_path}
+  ///
   /// By default, [RenderableTiledMap] renders flipped tiles if they exist.
   /// You can disable it by passing [ignoreFlip] as `true`.
   static Future<TiledComponent> load(
     String fileName,
     Vector2 destTileSize, {
+    String prefix = 'assets/tiles/',
     int? priority,
     bool? ignoreFlip,
   }) async {
@@ -100,6 +103,7 @@ class TiledComponent<T extends FlameGame> extends PositionComponent
         fileName,
         destTileSize,
         ignoreFlip: ignoreFlip,
+        prefix: prefix,
       ),
       priority: priority,
     );

packages/flame_tiled/test/assets/tiles_custom_path/external_tileset_custom_path.tsx

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<tileset version="1.2" tiledversion="2018.11.29" name="level1" tilewidth="16" tileheight="16" tilecount="136" columns="17">
+<image source="../images/map-level1.png" width="272" height="128"/>
+  <tile id="64">
+   <properties>
+    <property name="type" value="sky"/>
+   </properties>
+  </tile>
+  <tile id="65">
+   <properties>
+    <property name="type" value="xpto"/>
+   </properties>
+  </tile>
+</tileset>

packages/flame_tiled/test/tiled_test.dart

@@ -31,7 +31,7 @@ void main() {
     setUp(() async {
       Flame.bundle = TestAssetBundle(
         imageNames: ['map-level1.png', 'image1.png'],
-        stringNames: ['map.tmx'],
+        stringNames: ['map.tmx', 'tiles_custom_path/map_custom_path.tmx'],
       );
       tiled = await TiledComponent.load('map.tmx', Vector2.all(16));
     });
@@ -40,6 +40,16 @@ void main() {
       expect(tiled.tileMap.renderableLayers.length, equals(3));
     });
 
+    test('correct loads the file, with different prefix', () async {
+      tiled = await TiledComponent.load(
+        'map_custom_path.tmx',
+        Vector2.all(16),
+        prefix: 'assets/tiles/tiles_custom_path/',
+      );
+
+      expect(tiled.tileMap.renderableLayers.length, equals(3));
+    });
+
     group('is positionable', () {
       test('size, width, and height are readable - not writable', () async {
         expect(tiled.size, Vector2(512.0, 2048.0));
@@ -101,6 +111,39 @@ void main() {
     );
   });
 
+  test('correctly loads external tileset with custom path', () async {
+    // Flame.bundle is a global static. Updating these in tests can lead to
+    // odd errors if you're trying to debug.
+    Flame.bundle = TestAssetBundle(
+      imageNames: ['map-level1.png', 'image1.png'],
+      stringNames: [
+        'map.tmx',
+        'tiles_custom_path/external_tileset_custom_path.tsx'
+      ],
+    );
+
+    // TestAssetBundle strips assets/tiles/ from the prefix.
+    final tsxProvider = await FlameTsxProvider.parse(
+      'external_tileset_custom_path.tsx',
+      null,
+      'assets/tiles/tiles_custom_path/',
+    );
+
+    expect(tsxProvider.getCachedSource() != null, true);
+    final source = tsxProvider.getCachedSource()!;
+    expect(source.getStringOrNull('name'), 'level1');
+    expect(source.getSingleChildOrNull('image'), isNotNull);
+    expect(
+      source.getSingleChildOrNull('image')!.getStringOrNull('width'),
+      '272',
+    );
+
+    expect(
+      tsxProvider.filename == 'external_tileset_custom_path.tsx',
+      true,
+    );
+  });
+
   group('Layered tiles render correctly with layered sprite batch', () {
     late Uint8List canvasPixelData;
     late RenderableTiledMap overlapMap;