feat: (#3851) add HueEffect and HueDecorator for color hue manipulation.

Author: s1r1m1r1

doc/flame/effects/color_effects.md

@@ -136,3 +136,29 @@ final effect = GlowEffect(
 ```
 
 Currently this effect can only be applied to components that have a `HasPaint` mixin.
+
+
+## HueEffect
+
+This effect will rotate the hue of the target over time. It can only be applied to components that
+implement the `PaintProvider`.
+
+```{flutter-app}
+:sources: ../flame/examples
+:page: hue_effect
+:show: widget code infobox
+:width: 180
+:height: 160
+```
+
+```dart
+final effect = HueEffect(
+  2 * tau,
+  EffectController(duration: 3),
+);
+```
+
+> [!TIP]
+> **Performance Note**: `HueEffect` is extremely efficient because it modifies the `Paint`'s
+> `colorFilter` directly. If you have many components, prefer this effect over the `HueDecorator`,
+> which uses `saveLayer()` and has much higher overhead.

doc/flame/examples/lib/hue_decorator.dart

@@ -0,0 +1,32 @@
+import 'dart:math';
+
+import 'package:doc_flame_examples/flower.dart';
+import 'package:flame/game.dart';
+import 'package:flame/rendering.dart';
+
+class HueDecoratorGame extends FlameGame {
+  @override
+  Future<void> onLoad() async {
+    var step = 0;
+    add(
+      Flower(
+        size: 100,
+        position: canvasSize / 2,
+        onTap: (flower) {
+          final decorator = flower.decorator;
+          step++;
+          if (step == 1) {
+            decorator.addLast(HueDecorator(pi / 4));
+          } else if (step == 2) {
+            decorator.replaceLast(HueDecorator(pi / 2));
+          } else if (step == 3) {
+            decorator.replaceLast(HueDecorator(pi));
+          } else {
+            decorator.replaceLast(null);
+            step = 0;
+          }
+        },
+      )..onTapUp(),
+    );
+  }
+}

doc/flame/examples/lib/hue_effect.dart

@@ -0,0 +1,26 @@
+import 'dart:math';
+
+import 'package:doc_flame_examples/ember.dart';
+import 'package:flame/components.dart';
+import 'package:flame/effects.dart';
+import 'package:flame/game.dart';
+
+class HueEffectExample extends FlameGame {
+  @override
+  Future<void> onLoad() async {
+    final ember = EmberPlayer(
+      position: size / 2,
+      size: size / 4,
+      onTap: (ember) {
+        ember.add(
+          HueEffect(
+            2 * pi,
+            EffectController(duration: 3),
+          ),
+        );
+      },
+    )..anchor = Anchor.center;
+
+    add(ember);
+  }
+}

doc/flame/examples/lib/main.dart

@@ -10,6 +10,8 @@ import 'package:doc_flame_examples/decorator_shadow3d.dart';
 import 'package:doc_flame_examples/decorator_tint.dart';
 import 'package:doc_flame_examples/drag_events.dart';
 import 'package:doc_flame_examples/glow_effect.dart';
+import 'package:doc_flame_examples/hue_decorator.dart';
+import 'package:doc_flame_examples/hue_effect.dart';
 import 'package:doc_flame_examples/move_along_path_effect.dart';
 import 'package:doc_flame_examples/move_by_effect.dart';
 import 'package:doc_flame_examples/move_to_effect.dart';
@@ -49,8 +51,10 @@ final routes = <String, Game Function()>{
   'decorator_rotate3d': DecoratorRotate3DGame.new,
   'decorator_shadow3d': DecoratorShadowGame.new,
   'decorator_tint': DecoratorTintGame.new,
+  'decorator_hue': HueDecoratorGame.new,
   'drag_events': DragEventsGame.new,
   'glow_effect': GlowEffectExample.new,
+  'hue_effect': HueEffectExample.new,
   'move_along_path_effect': MoveAlongPathEffectGame.new,
   'move_by_effect': MoveByEffectGame.new,
   'move_to_effect': MoveToEffectGame.new,

doc/flame/rendering/decorators.md

@@ -1,13 +1,17 @@
-# Decorators
+## Performance Warning: Decorators vs Effects
 
-**Decorators** are classes that can encapsulate certain visual effects and then apply those visual
-effects to a sequence of canvas drawing operations. Decorators are not [Component]s, but they can
-be applied to components either manually or via the [HasDecorator] mixin. Likewise, decorators are
-not [Effect]s, although they can be used to implement certain `Effect`s.
+Applying a [Decorator] to a component can have a significant performance overhead, especially when
+it involves `canvas.saveLayer()`.
 
-There are a certain number of decorators available in Flame, and it is simple to add one's own if
-necessary. We are planning to add shader-based decorators once Flutter fully supports them on the
-web.
+- **Decorators** (e.g., [HueDecorator]): Use `canvas.saveLayer()` to isolate rendering and apply
+  filters. This requires off-screen buffer allocation and GPU context switches. In high-density
+  scenes (100+ sprites), this can be significantly slower than direct paint manipulation.
+- **Effects** (e.g., [HueEffect]): Modify the component's [Paint] directly. These are
+  hardware-accelerated in the fragment shader with virtually zero memory overhead.
+
+**Recommendation**: Always prefer **Effects** for simple color transformations on large numbers of
+units. Use **Decorators** only when you need complex visual composition or when targeting raw
+canvas drawing that isn't governed by a single [Paint].
 
 
 ## Flame built-in decorators
@@ -157,6 +161,29 @@ limitation is that the shadows are flat and cannot interact with the environment
 decorator cannot handle shadows that fall onto walls or other vertical structures.
 
 
+### HueDecorator
+
+```{flutter-app}
+:sources: ../flame/examples
+:page: decorator_hue
+:show: widget code infobox
+:width: 180
+:height: 160
+```
+
+This decorator shifts the hue of the underlying component by the specified angle in radians.
+
+```dart
+final decorator = HueDecorator(tau / 4);
+```
+
+Possible uses:
+
+- alternative color schemes for enemies ("palette swapping");
+- environmental changes (e.g., world turning purple/surreal);
+- power-up indicators.
+
+
 ## Using decorators
 
 

examples/lib/stories/effects/effects.dart

@@ -5,6 +5,7 @@ import 'package:examples/stories/effects/combined_effect_example.dart';
 import 'package:examples/stories/effects/dual_effect_removal_example.dart';
 import 'package:examples/stories/effects/effect_controllers_example.dart';
 import 'package:examples/stories/effects/function_effect_example.dart';
+import 'package:examples/stories/effects/hue_effect_example.dart';
 import 'package:examples/stories/effects/move_effect_example.dart';
 import 'package:examples/stories/effects/opacity_effect_example.dart';
 import 'package:examples/stories/effects/remove_effect_example.dart';
@@ -59,6 +60,12 @@ void addEffectsStories(Dashbook dashbook) {
       codeLink: baseLink('effects/opacity_effect_example.dart'),
       info: OpacityEffectExample.description,
     )
+    ..add(
+      'Hue Effect',
+      (_) => GameWidget(game: HueEffectExample()),
+      codeLink: baseLink('effects/hue_effect_example.dart'),
+      info: HueEffectExample.description,
+    )
     ..add(
       'Color Effect',
       (_) => GameWidget(game: ColorEffectExample()),

examples/lib/stories/effects/hue_effect_example.dart

@@ -0,0 +1,30 @@
+import 'dart:math';
+
+import 'package:examples/commons/ember.dart';
+import 'package:flame/effects.dart';
+import 'package:flame/game.dart';
+
+class HueEffectExample extends FlameGame {
+  static const String description = '''
+    In this example we show how the `HueEffect` can be used.
+    Ember will shift its hue over time.
+  ''';
+
+  @override
+  Future<void> onLoad() async {
+    add(
+      Ember(
+        position: Vector2(size.x / 2, size.y / 2),
+        size: Vector2.all(100),
+      )..add(
+        HueEffect(
+          2 * pi,
+          EffectController(
+            duration: 3,
+            infinite: true,
+          ),
+        ),
+      ),
+    );
+  }
+}

examples/lib/stories/rendering/hue_decorator_example.dart

@@ -0,0 +1,42 @@
+import 'dart:math';
+
+import 'package:examples/commons/ember.dart';
+import 'package:flame/events.dart';
+import 'package:flame/game.dart';
+import 'package:flame/rendering.dart';
+
+class HueDecoratorExample extends FlameGame with TapCallbacks {
+  static const String description = '''
+    In this example we show how the `HueDecorator` can be used.
+    Click anywhere to cycle through different hue shifts on Ember.
+  ''';
+
+  late final Ember ember;
+  int step = 0;
+
+  @override
+  Future<void> onLoad() async {
+    add(
+      ember = Ember(
+        position: size / 2,
+        size: Vector2.all(100),
+      )..decorator = HueDecorator(),
+    );
+  }
+
+  @override
+  void onTapDown(TapDownEvent event) {
+    step++;
+    final decorator = ember.decorator as HueDecorator;
+    if (step == 1) {
+      decorator.hue = pi / 4;
+    } else if (step == 2) {
+      decorator.hue = pi / 2;
+    } else if (step == 3) {
+      decorator.hue = pi;
+    } else {
+      decorator.hue = 0;
+      step = 0;
+    }
+  }
+}

examples/lib/stories/rendering/rendering.dart

@@ -1,6 +1,7 @@
 import 'package:dashbook/dashbook.dart';
 import 'package:examples/commons/commons.dart';
 import 'package:examples/stories/rendering/flip_sprite_example.dart';
+import 'package:examples/stories/rendering/hue_decorator_example.dart';
 import 'package:examples/stories/rendering/isometric_tile_map_example.dart';
 import 'package:examples/stories/rendering/layers_example.dart';
 import 'package:examples/stories/rendering/nine_tile_box_example.dart';
@@ -14,6 +15,12 @@ import 'package:flutter/material.dart';
 
 void addRenderingStories(Dashbook dashbook) {
   dashbook.storiesOf('Rendering')
+    ..add(
+      'Hue Decorator',
+      (_) => GameWidget(game: HueDecoratorExample()),
+      codeLink: baseLink('rendering/hue_decorator_example.dart'),
+      info: HueDecoratorExample.description,
+    )
     ..add(
       'Text',
       (_) => GameWidget(game: TextExample()),

packages/flame/lib/effects.dart

@@ -25,6 +25,7 @@ export 'src/effects/effect.dart';
 export 'src/effects/effect_target.dart';
 export 'src/effects/function_effect.dart';
 export 'src/effects/glow_effect.dart';
+export 'src/effects/hue_effect.dart';
 export 'src/effects/move_along_path_effect.dart';
 export 'src/effects/move_by_effect.dart';
 export 'src/effects/move_effect.dart';