Merge branch 'main' into luan.context-api

.github/.cspell/flame_dictionary.txt

@@ -27,3 +27,4 @@ vantablack # brand name for a famous super-black ink known as the darkest ever m
 Weasley # Ron Weasley, a character from the book Harry Potter
 Wyrmsun # An open-source real-time strategy game https://www.indiedb.com/games/wyrmsun
 yarnspinner # A tool for building branching narrative and dialogue in games # https://yarnspinner.dev/
+terminui # A terminal UI library for Flutter

.github/.cspell/words_dictionary.txt

@@ -27,6 +27,7 @@ rebalance
 refreshable
 renderable
 rescan
+strikethrough # of a text with a horizontal line across
 tappable
 tappables
 toolset

.github/workflows/benchmark.yml

@@ -0,0 +1,20 @@
+name: Benchmark
+
+on: [pull_request]
+
+jobs:
+  benchmark:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: subosito/flutter-action@v2
+      - uses: bluefireteam/melos-action@v3
+
+      - uses: luanpotter/[email protected]
+        with:
+          paths: "packages/flame/"
+          ignore-tag: "no-benchmark"
+          is-flutter: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

doc/flame/examples/pubspec.yaml

@@ -8,8 +8,8 @@ environment:
   flutter: ">=3.24.0"
 
 dependencies:
-  flame: ^1.22.0
-  flame_rive: ^1.10.6
+  flame: ^1.23.0
+  flame_rive: ^1.10.7
   flutter:
     sdk: flutter
 

doc/flame/other/other.md

@@ -7,7 +7,7 @@
 
 ```{toctree}
 :hidden:
-    
+
 Debugging    <debug.md>
 Utils        <util.md>
 Widgets      <widgets.md>

doc/flame/other/util.md

@@ -5,6 +5,13 @@ On this page you can find documentation for some utility classes and methods.
 
 ## Device Class
 
+```{warning}
+Many methods in this class only work on mobile platforms (Android and iOS).
+
+Using these methods on other platforms will not have any effect and you will
+get a warning printed on your console when running in debug mode.
+```
+
 This class can be accessed from `Flame.device` and it has some methods that can be used to control
 the state of the device, for instance you can change the screen orientation and set whether the
 application should be fullscreen or not.

doc/tutorials/klondike/app/pubspec.yaml

@@ -7,7 +7,7 @@ environment:
   sdk: ">=3.4.0 <4.0.0"
 
 dependencies:
-  flame: ^1.22.0
+  flame: ^1.23.0
   flutter:
     sdk: flutter
 

doc/tutorials/platformer/app/pubspec.yaml

@@ -8,7 +8,7 @@ environment:
   flutter: ">=3.24.0"
 
 dependencies:
-  flame: ^1.22.0
+  flame: ^1.23.0
   flutter:
     sdk: flutter
 

doc/tutorials/space_shooter/app/pubspec.yaml

@@ -9,7 +9,7 @@ environment:
   sdk: ">=3.4.0 <4.0.0"
 
 dependencies:
-  flame: ^1.22.0
+  flame: ^1.23.0
   flutter:
     sdk: flutter
 

examples/games/padracing/pubspec.yaml

@@ -8,8 +8,8 @@ environment:
 
 dependencies:
   collection: ^1.17.1
-  flame: ^1.22.0
-  flame_forge2d: ^0.18.2+3
+  flame: ^1.23.0
+  flame_forge2d: ^0.18.2+4
   flutter:
     sdk: flutter
   google_fonts: ^4.0.4

examples/games/rogue_shooter/pubspec.yaml

@@ -10,7 +10,7 @@ environment:
   flutter: ">=3.24.0"
 
 dependencies:
-  flame: ^1.22.0
+  flame: ^1.23.0
   flutter:
     sdk: flutter
 

examples/games/trex/pubspec.yaml

@@ -11,7 +11,7 @@ environment:
 
 dependencies:
   collection: ^1.16.0
-  flame: ^1.22.0
+  flame: ^1.23.0
   flutter:
     sdk: flutter
 

examples/lib/stories/image/brighten.dart

@@ -0,0 +1,40 @@
+import 'package:flame/components.dart';
+import 'package:flame/extensions.dart';
+import 'package:flame/game.dart';
+
+class ImageBrightnessExample extends FlameGame {
+  ImageBrightnessExample({
+    required this.brightness,
+  });
+
+  final double brightness;
+
+  static const String description = '''
+     Shows how a dart:ui `Image` can be brightened using Flame Image extensions.
+     Use the properties on the side to change the brightness of the image.
+  ''';
+
+  @override
+  Future<void> onLoad() async {
+    final image = await images.load('flame.png');
+    final brightenedImage = await image.brighten(brightness / 100);
+
+    add(
+      SpriteComponent(
+        sprite: Sprite(image),
+        position: (size / 2) - Vector2(0, image.height / 2),
+        size: image.size,
+        anchor: Anchor.center,
+      ),
+    );
+
+    add(
+      SpriteComponent(
+        sprite: Sprite(brightenedImage),
+        position: (size / 2) + Vector2(0, brightenedImage.height / 2),
+        size: image.size,
+        anchor: Anchor.center,
+      ),
+    );
+  }
+}

examples/lib/stories/image/darken.dart

@@ -0,0 +1,40 @@
+import 'package:flame/components.dart';
+import 'package:flame/extensions.dart';
+import 'package:flame/game.dart';
+
+class ImageDarknessExample extends FlameGame {
+  ImageDarknessExample({
+    required this.darkness,
+  });
+
+  final double darkness;
+
+  static const String description = '''
+     Shows how a dart:ui `Image` can be darkened using Flame Image extensions.
+     Use the properties on the side to change the darkness of the image.
+  ''';
+
+  @override
+  Future<void> onLoad() async {
+    final image = await images.load('flame.png');
+    final darkenedImage = await image.darken(darkness / 100);
+
+    add(
+      SpriteComponent(
+        sprite: Sprite(image),
+        position: (size / 2) - Vector2(0, image.height / 2),
+        size: image.size,
+        anchor: Anchor.center,
+      ),
+    );
+
+    add(
+      SpriteComponent(
+        sprite: Sprite(darkenedImage),
+        position: (size / 2) + Vector2(0, darkenedImage.height / 2),
+        size: image.size,
+        anchor: Anchor.center,
+      ),
+    );
+  }
+}

examples/lib/stories/image/image.dart

@@ -1,6 +1,8 @@
 import 'package:dashbook/dashbook.dart';
 
 import 'package:examples/commons/commons.dart';
+import 'package:examples/stories/image/brighten.dart';
+import 'package:examples/stories/image/darken.dart';
 import 'package:examples/stories/image/resize.dart';
 import 'package:flame/game.dart';
 
@@ -19,5 +21,25 @@ void addImageStories(Dashbook dashbook) {
       ),
       codeLink: baseLink('image/resize.dart'),
       info: ImageResizeExample.description,
+    )
+    ..add(
+      'brightness',
+      (context) => GameWidget(
+        game: ImageBrightnessExample(
+          brightness: context.numberProperty('brightness', 50),
+        ),
+      ),
+      codeLink: baseLink('image/brighten.dart'),
+      info: ImageBrightnessExample.description,
+    )
+    ..add(
+      'darkness',
+      (context) => GameWidget(
+        game: ImageDarknessExample(
+          darkness: context.numberProperty('darkness', 50),
+        ),
+      ),
+      codeLink: baseLink('image/darkness.dart'),
+      info: ImageDarknessExample.description,
     );
 }

examples/pubspec.yaml

@@ -11,15 +11,15 @@ environment:
 
 dependencies:
   dashbook: ^0.1.15
-  flame: ^1.22.0
-  flame_audio: ^2.10.6
-  flame_forge2d: ^0.18.2+3
-  flame_isolate: ^0.6.2+3
-  flame_lottie: ^0.4.2+3
-  flame_noise: ^0.3.2+3
-  flame_spine: ^0.2.2+3
-  flame_svg: ^1.11.3
-  flame_tiled: ^1.21.1
+  flame: ^1.23.0
+  flame_audio: ^2.10.7
+  flame_forge2d: ^0.18.2+4
+  flame_isolate: ^0.6.2+4
+  flame_lottie: ^0.4.2+4
+  flame_noise: ^0.3.2+4
+  flame_spine: ^0.2.2+4
+  flame_svg: ^1.11.4
+  flame_tiled: ^1.21.2
   flutter:
     sdk: flutter
   google_fonts: ^4.0.4

melos.yaml

@@ -23,7 +23,7 @@ command:
       vector_math: ^2.1.4
     dev_dependencies:
       dartdoc: ^8.0.8
-      mocktail: ^1.0.3
+      mocktail: ^1.0.4
       test: any
 
   publish:

packages/flame/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 1.23.0
+
+ - **REFACTOR**: Fix lint issues from latest flutter release ([#3390](https://github.com/flame-engine/flame/issues/3390)). ([978ad31b](https://github.com/flame-engine/flame/commit/978ad31b429d1801097b0db385a600c85a157867))
+ - **FIX**: Take into consideration when child is added to parent that is removed in the same tick ([#3428](https://github.com/flame-engine/flame/issues/3428)). ([9a5c54be](https://github.com/flame-engine/flame/commit/9a5c54bea858fc8e9e84878f3ac0a0f7bc190b46))
+ - **FIX**: Add missing export of GroupTextElement to text.dart ([#3424](https://github.com/flame-engine/flame/issues/3424)). ([c9c0f691](https://github.com/flame-engine/flame/commit/c9c0f691412bb026c1d766ec7b424a468f8929f7))
+ - **FIX**: Add missing export of GroupElement to text.dart ([#3423](https://github.com/flame-engine/flame/issues/3423)). ([c0c4bb02](https://github.com/flame-engine/flame/commit/c0c4bb02a32306120a8770122116631f55c1c700))
+ - **FIX**: Fix brighten and darken alpha issue ([#3414](https://github.com/flame-engine/flame/issues/3414)). ([de8e3bce](https://github.com/flame-engine/flame/commit/de8e3bcea2c2c2fa5e01dd288176c8f5623d21fb))
+ - **FIX**: Set button size in onMount if not set ([#3413](https://github.com/flame-engine/flame/issues/3413)). ([916aa5ce](https://github.com/flame-engine/flame/commit/916aa5ce2ad3851b3044e043d2be7cbe923f2c40))
+ - **FIX**: Fix bug preventing removeAll(children) from be called before mount ([#3408](https://github.com/flame-engine/flame/issues/3408)). ([726cb8b6](https://github.com/flame-engine/flame/commit/726cb8b6390c839f9cbab959b2268a7b45fa691c))
+ - **FEAT**: Add support for strike-through text for flame_markdown ([#3426](https://github.com/flame-engine/flame/issues/3426)). ([1f9b0ea9](https://github.com/flame-engine/flame/commit/1f9b0ea9f35a7180725ec7f8f79a561c5f544bb7))
+ - **FEAT**: Warning and docs about fullscreen methods outside the mobile platforms ([#3419](https://github.com/flame-engine/flame/issues/3419)). ([994e098b](https://github.com/flame-engine/flame/commit/994e098bd699a30aa13aed65f2bd0ab7254ad779))
+ - **FEAT**: Add baseColor to Shadow3DDecorator ([#3375](https://github.com/flame-engine/flame/issues/3375)). ([b5d7ee07](https://github.com/flame-engine/flame/commit/b5d7ee0752ee1f2dddf1da4ac817f138296e1c96))
+
 ## 1.22.0
 
  - **FIX**: Remove extra `implements SizeProvider`s ([#3358](https://github.com/flame-engine/flame/issues/3358)). ([47ba0d87](https://github.com/flame-engine/flame/commit/47ba0d8738b101ed59781f8ba384cf05a16d65f1))

packages/flame/benchmark/main.dart

@@ -0,0 +1,5 @@
+import 'update_components_benchmark.dart';
+
+Future<void> main() async {
+  await UpdateComponentsBenchmark.main();
+}

packages/flame/benchmark/update_components_benchmark.dart

@@ -0,0 +1,96 @@
+import 'dart:math';
+
+import 'package:benchmark_harness/benchmark_harness.dart';
+import 'package:flame/components.dart';
+import 'package:flame/game.dart';
+
+const _amountComponents = 20;
+const _amountTicks = 1000;
+const _amountInputs = 100;
+
+class UpdateComponentsBenchmark extends AsyncBenchmarkBase {
+  final Random random;
+
+  late final FlameGame _game;
+  late final List<_BenchmarkComponent> _components;
+  late final List<double> _dts;
+  late final Set<int> _inputTicks;
+
+  UpdateComponentsBenchmark(this.random)
+      : super('Updating Components Benchmark');
+
+  static Future<void> main() async {
+    final r = Random(69420);
+    await UpdateComponentsBenchmark(r).report();
+  }
+
+  @override
+  Future<void> setup() async {
+    _game = FlameGame();
+    await _game.addAll(
+      List.generate(_amountComponents, _BenchmarkComponent.new),
+    );
+
+    await _game.ready();
+
+    _components =
+        _game.children.whereType<_BenchmarkComponent>().toList(growable: false);
+
+    _dts = List.generate(_amountTicks, (_) => random.nextDouble());
+    _inputTicks = List.generate(
+      _amountInputs,
+      (_) => random.nextInt(_amountTicks),
+    ).toSet();
+  }
+
+  @override
+  Future<void> exercise() async {
+    for (final (idx, dt) in _dts.indexed) {
+      if (_inputTicks.contains(idx)) {
+        _components[random.nextInt(_amountComponents)].input(
+          xDirection: random.nextInt(3) - 1,
+          doJump: random.nextBool(),
+        );
+      }
+      _game.update(dt);
+    }
+  }
+}
+
+class _BenchmarkComponent extends PositionComponent {
+  static const _groundY = -20.0;
+
+  final int id;
+  final Vector2 velocity = Vector2.zero();
+
+  _BenchmarkComponent(this.id);
+
+  void input({
+    required int xDirection,
+    required bool doJump,
+  }) {
+    // move x
+    velocity.x = xDirection * 100;
+
+    // jump
+    if (position.y == _groundY) {
+      velocity.y -= 100;
+    }
+  }
+
+  @override
+  void update(double dt) {
+    super.update(dt);
+
+    position.add(velocity * dt);
+    velocity.add(Vector2(0, 10 * dt));
+
+    if (position.y > _groundY) {
+      position.y = _groundY;
+      velocity.setValues(0, 0);
+    }
+  }
+
+  @override
+  String toString() => '[Component $id]';
+}