feat: Add dynamic layer opacity support to flame_tiled (#3843)

`flame_tiled` supported reading layer opacity from `.tmx` files at load
time, but there was no way to change a layer's opacity at runtime. This
PR adds `setLayerOpacity` and `getLayerOpacity` methods to
`RenderableTiledMap`, enabling users to dynamically adjust layer opacity
after the map has loaded.

- `RenderableLayer.opacity` is converted from a late field (computed
once at init) to a getter/setter pair. The getter returns the effective
opacity (own × parent chain); the setter stores the own opacity and
fires onOpacityChanged().
- A protected `onOpacityChanged()` hook is added to `RenderableLayer`.
`FlameTileLayer` overrides it to rebuild its cached Paint object;
`GroupLayer` overrides it to propagate the call recursively to all
children so nested tile layers stay in sync.
- `RenderableTiledMap` gains `setLayerOpacity(int layerIndex, {required
double opacity})` and `getLayerOpacity(int layerIndex)`.
- `FlameImageLayer` required no changes — it already reads opacity live
on every render() call.

Author: ufrshubham

packages/flame_tiled/lib/src/renderable_layers/group_layer.dart

@@ -47,4 +47,11 @@ class GroupLayer extends RenderableLayer<Group> {
       child.update(dt);
     }
   }
+
+  @override
+  void onOpacityChanged() {
+    for (final child in children) {
+      child.onOpacityChanged();
+    }
+  }
 }

packages/flame_tiled/lib/src/renderable_layers/renderable_layer.dart

@@ -113,7 +113,20 @@ abstract class RenderableLayer<T extends Layer> {
 
   late double offsetY = layer.offsetY * scaleY + (parent?.offsetY ?? 0);
 
-  late double opacity = layer.opacity * (parent?.opacity ?? 1);
+  double get opacity => layer.opacity * (parent?.opacity ?? 1);
+
+  set opacity(double value) {
+    layer.opacity = value;
+    onOpacityChanged();
+  }
+
+  /// Called after [opacity] is changed.
+  ///
+  /// Override to react to opacity updates (e.g. to rebuild a cached paint).
+  /// When overriding inside a container layer, propagate the call to children
+  /// so that descendant layers with cached paints are also updated.
+  @protected
+  void onOpacityChanged() {}
 
   late double parallaxX = layer.parallaxX * (parent?.parallaxX ?? 1);
 

packages/flame_tiled/lib/src/renderable_layers/tile_layers/tile_layer.dart

@@ -33,7 +33,7 @@ import 'package:meta/meta.dart';
 /// {@endtemplate}
 @internal
 abstract class FlameTileLayer extends RenderableLayer<TileLayer> {
-  late final _layerPaint = layerPaintFactory(opacity);
+  late Paint _layerPaint;
   final TiledAtlas tiledAtlas;
   late List<List<MutableRSTransform?>> transforms;
   final animations = <TileAnimation>[];
@@ -51,7 +51,14 @@ abstract class FlameTileLayer extends RenderableLayer<TileLayer> {
     required this.ignoreFlip,
     required this.layerPaintFactory,
     super.filterQuality,
-  });
+  }) {
+    _layerPaint = layerPaintFactory(opacity);
+  }
+
+  @override
+  void onOpacityChanged() {
+    _layerPaint = layerPaintFactory(opacity);
+  }
 
   /// {@macro flame_tile_layer}
   static FlameTileLayer load({

packages/flame_tiled/lib/src/renderable_tile_map.dart

@@ -90,6 +90,23 @@ class RenderableTiledMap {
     return map.layers[layerId].visible;
   }
 
+  /// Changes the opacity of the layer at [layerIndex] to [opacity].
+  ///
+  /// [opacity] must be between 0.0 (fully transparent) and 1.0 (fully opaque).
+  void setLayerOpacity(int layerIndex, {required double opacity}) {
+    assert(
+      opacity >= 0.0 && opacity <= 1.0,
+      'opacity must be between 0.0 and 1.0',
+    );
+    final renderableLayer = renderableLayers[layerIndex];
+    renderableLayer.opacity = opacity;
+  }
+
+  /// Gets the opacity of the layer at [layerIndex].
+  double getLayerOpacity(int layerIndex) {
+    return renderableLayers[layerIndex].opacity;
+  }
+
   /// Changes the Gid of the corresponding layer at the given layerId,
   /// if different
   void setTileData({

packages/flame_tiled/test/tiled_test.dart

@@ -6,6 +6,7 @@ import 'package:flame/extensions.dart';
 import 'package:flame/flame.dart';
 import 'package:flame/game.dart';
 import 'package:flame_tiled/flame_tiled.dart';
+import 'package:flame_tiled/src/renderable_layers/group_layer.dart';
 import 'package:flame_tiled/src/renderable_layers/tile_layers/tile_layer.dart';
 import 'package:flutter/services.dart';
 import 'package:flutter_test/flutter_test.dart';
@@ -1141,4 +1142,104 @@ void main() {
       expect(renderableTiledMap.getTileData(layerId: 5, x: 1, y: 1), isNull);
     });
   });
+
+  group('RenderableTiledMap.LayerOpacity', () {
+    late RenderableTiledMap renderableTiledMap;
+
+    setUp(() async {
+      Flame.bundle = TestAssetBundle(
+        imageNames: ['map-level1.png'],
+        stringNames: ['layers_test.tmx'],
+      );
+      renderableTiledMap = await RenderableTiledMap.fromFile(
+        'layers_test.tmx',
+        Vector2.all(32),
+        bundle: Flame.bundle,
+      );
+    });
+
+    test('getLayerOpacity returns 1.0 by default', () {
+      expect(renderableTiledMap.getLayerOpacity(0), equals(1.0));
+    });
+
+    test('setLayerOpacity changes the layer opacity', () {
+      renderableTiledMap.setLayerOpacity(0, opacity: 0.5);
+      expect(renderableTiledMap.getLayerOpacity(0), equals(0.5));
+    });
+
+    test('setLayerOpacity sets opacity to 0', () {
+      renderableTiledMap.setLayerOpacity(0, opacity: 0.0);
+      expect(renderableTiledMap.getLayerOpacity(0), equals(0.0));
+    });
+
+    test('setLayerOpacity sets opacity to 1', () {
+      renderableTiledMap.setLayerOpacity(0, opacity: 0.25);
+      renderableTiledMap.setLayerOpacity(0, opacity: 1.0);
+      expect(renderableTiledMap.getLayerOpacity(0), equals(1.0));
+    });
+
+    test('setLayerOpacity asserts on out-of-range value', () {
+      expect(
+        () => renderableTiledMap.setLayerOpacity(0, opacity: 1.5),
+        throwsA(isA<AssertionError>()),
+      );
+      expect(
+        () => renderableTiledMap.setLayerOpacity(0, opacity: -0.1),
+        throwsA(isA<AssertionError>()),
+      );
+    });
+  });
+
+  group('RenderableTiledMap.LayerOpacity nested groups', () {
+    // map.tmx layer structure (renderableLayers indices):
+    //   0: FlameTileLayer  "Ground"          (opacity 1.0)
+    //   1: GroupLayer      "Background"      (opacity 0.8)
+    //      └─ FlameTileLayer "Sky tiles"     (own opacity 0.9, effective 0.72)
+    //   2: FlameImageLayer "Image Layer 2"   (opacity 1.0)
+    //   3: FlameImageLayer "Sky artifact"    (opacity 0.2)
+    late RenderableTiledMap renderableTiledMap;
+
+    setUp(() async {
+      Flame.bundle = TestAssetBundle(
+        imageNames: ['image1.png', 'map-level1.png'],
+        stringNames: ['map.tmx'],
+      );
+      renderableTiledMap = await RenderableTiledMap.fromFile(
+        'map.tmx',
+        Vector2.all(16),
+        bundle: Flame.bundle,
+      );
+    });
+
+    test('child effective opacity is parent * own', () {
+      // GroupLayer opacity=0.8, child TileLayer own opacity=0.9 → 0.72
+      final group = renderableTiledMap.renderableLayers[1] as GroupLayer;
+      final child = group.children.first as FlameTileLayer;
+      expect(child.opacity, closeTo(0.72, 1e-6));
+    });
+
+    test('setting GroupLayer opacity updates child effective opacity', () {
+      // Change group from 0.8→0.5; child own opacity stays 0.9→effective 0.45
+      renderableTiledMap.setLayerOpacity(1, opacity: 0.5);
+      final group = renderableTiledMap.renderableLayers[1] as GroupLayer;
+      expect(group.opacity, equals(0.5));
+      final child = group.children.first as FlameTileLayer;
+      expect(child.opacity, closeTo(0.45, 1e-6));
+    });
+
+    test('setting GroupLayer opacity to 0 makes child fully transparent', () {
+      renderableTiledMap.setLayerOpacity(1, opacity: 0.0);
+      final group = renderableTiledMap.renderableLayers[1] as GroupLayer;
+      final child = group.children.first as FlameTileLayer;
+      expect(child.opacity, equals(0.0));
+    });
+
+    test('sibling layers are not affected by group opacity change', () {
+      renderableTiledMap.setLayerOpacity(1, opacity: 0.1);
+      // "Ground" at index 0 has no parent, so remains 1.0
+      expect(renderableTiledMap.getLayerOpacity(0), equals(1.0));
+      // "Sky artifact" at index 3 is independent
+      expect(renderableTiledMap.getLayerOpacity(3), equals(0.2));
+    });
+  });
 }