feat: Added getImageLayer to flame_tiled (flame-engine#1405)

doc/other_modules/tiled.md

@@ -9,6 +9,17 @@ the tiles, objects and everything in there.
 Flame also provides a simple `Tiled` class and its component wrapper `TiledComponent`, for the map
 rendering, which renders the tiles on the screen and supports rotations and flips.
 
+At its simplest, layers can be retrieved from a Tilemap by invoking:
+
+```
+getLayer<ObjectGroup>("myObjectGroupLayer");
+getLayer<ImageLayer>("myImageLayer");
+getLayer<TileLayer>("myTileLayer");
+getLayer<Group>("myGroupLayer");
+```
+
+These methods will either return the requested layer type or null if it does not exist.
+
 Other advanced features are not yet supported, but you can easily read the objects and other
 features of the tmx and add custom behaviour (eg regions for triggers and walking areas, custom
 animated objects).

packages/flame_tiled/example/lib/main.dart

@@ -3,6 +3,7 @@ import 'package:flame/flame.dart';
 import 'package:flame/game.dart';
 import 'package:flame_tiled/flame_tiled.dart';
 import 'package:flutter/widgets.dart' hide Animation, Image;
+import 'package:tiled/tiled.dart';
 
 void main() {
   runApp(GameWidget(game: TiledGame()));
@@ -15,9 +16,12 @@ class TiledGame extends FlameGame {
     final tiledMap = await TiledComponent.load('map.tmx', Vector2.all(16));
     add(tiledMap);
 
-    final objGroup = tiledMap.tileMap.getObjectGroupFromLayer('AnimatedCoins');
+    final objGroup = tiledMap.tileMap.getLayer<ObjectGroup>('AnimatedCoins');
     final coins = await Flame.images.load('coins.png');
-    for (final obj in objGroup.objects) {
+
+    // We are 100% sure that an object layer named `AnimatedCoins`
+    // exists in the example `map.tmx`.
+    for (final obj in objGroup!.objects) {
       add(
         SpriteAnimationComponent(
           position: Vector2(obj.x, obj.y),

packages/flame_tiled/lib/src/renderable_tile_map.dart

@@ -202,10 +202,18 @@ class RenderableTiledMap {
 
   /// This returns an object group fetch by name from a given layer.
   /// Use this to add custom behaviour to special objects and groups.
+  @Deprecated('This method is deprecated. Use the getLayer() method instead.')
   ObjectGroup getObjectGroupFromLayer(String name) {
     final g = map.layers.firstWhere((layer) {
       return layer is ObjectGroup && layer.name == name;
     });
     return g as ObjectGroup;
   }
+
+  /// Returns a layer of type [T] with given [name] from all the layers
+  /// of this map. If no such layer is found, null is returned.
+  T? getLayer<T extends Layer>(String name) {
+    return map.layers
+        .firstWhereOrNull((layer) => layer is T && layer.name == name) as T?;
+  }
 }

packages/flame_tiled/test/assets/layers_test.tmx

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<map version="1.5" tiledversion="1.7.2" orientation="orthogonal" renderorder="right-down" width="10" height="6" tilewidth="32" tileheight="32" infinite="0" nextlayerid="5" nextobjectid="10">
+ <layer id="1" name="MyTileLayer" width="10" height="6">
+  <data encoding="base64">
+   AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
+  </data>
+ </layer>
+ <objectgroup id="2" name="MyObjectLayer" offsetx="0" offsety="-32">
+  <object id="9" x="64" y="160" width="200" height="40">
+   <text wrap="1" color="#ffffff">Just a dummy map for 
+ testing layers</text>
+  </object>
+ </objectgroup>
+ <imagelayer id="3" name="MyImageLayer">
+  <image source="map-level1.png" width="272" height="128"/>
+ </imagelayer>
+ <group id="4" name="MyGroupLayer"/>
+</map>

packages/flame_tiled/test/tiled_test.dart

@@ -8,6 +8,7 @@ import 'package:flame/flame.dart';
 import 'package:flame_tiled/flame_tiled.dart';
 import 'package:flutter/services.dart' show CachingAssetBundle;
 import 'package:test/test.dart';
+import 'package:tiled/tiled.dart';
 
 void main() {
   test('correct loads the file', () async {
@@ -123,6 +124,53 @@ void main() {
       expect(allGreen, true);
     });
   });
+
+  group('Test getLayer:', () {
+    late RenderableTiledMap _renderableTiledMap;
+    setUp(() async {
+      Flame.bundle = TestAssetBundle(
+        imageNames: ['map-level1.png'],
+        mapPath: 'test/assets/layers_test.tmx',
+      );
+      _renderableTiledMap =
+          await RenderableTiledMap.fromFile('layers_test.tmx', Vector2.all(32));
+    });
+
+    test('Get Tile Layer', () {
+      expect(
+        _renderableTiledMap.getLayer<TileLayer>('MyTileLayer'),
+        isNotNull,
+      );
+    });
+
+    test('Get Object Layer', () {
+      expect(
+        _renderableTiledMap.getLayer<ObjectGroup>('MyObjectLayer'),
+        isNotNull,
+      );
+    });
+
+    test('Get Image Layer', () {
+      expect(
+        _renderableTiledMap.getLayer<ImageLayer>('MyImageLayer'),
+        isNotNull,
+      );
+    });
+
+    test('Get Group Layer', () {
+      expect(
+        _renderableTiledMap.getLayer<Group>('MyGroupLayer'),
+        isNotNull,
+      );
+    });
+
+    test('Get no layer', () {
+      expect(
+        _renderableTiledMap.getLayer<TileLayer>('Nonexistent layer'),
+        isNull,
+      );
+    });
+  });
 }
 
 class TestAssetBundle extends CachingAssetBundle {