Merge branch 'main' into feat/brightness-example

.github/.cspell/dart_dictionary.txt

@@ -5,5 +5,4 @@ dartdoc # documentation tool for dart
 dartdocs # plural of dartdoc
 endtemplate # Use @endtemplate to close a @template block in dartdoc
 pubspec # dependency and configuration file of every Dart project
-typedefs # plural of typedef
 writeln # StringBuffer.writeln

.github/.cspell/flame_dictionary.txt

@@ -8,6 +8,7 @@ Dashbook # UI development tool for Flutter https://github.com/bluefireteam/dashb
 emberquest # Ember Quest, our platformer tutorial game
 Hermione # A character from the book Harry Potter
 Kawabunga # Word expressing exhilaration, of unclear origins but popularized by the show Teenage Mutant Ninja Turtles
+Kenobi # Eminent Jedi Master, General of the Republic Army, Obi-Wan Kenobi
 Mocktail # A library for Dart that automatically creates mocks for tests https://github.com/felangel/mocktail
 Nakama # An open-source server designed to power modern games and apps https://github.com/Allan-Nava/nakama-flutter
 Overmind # A character in the game StarCraft

.github/.cspell/gamedev_dictionary.txt

@@ -14,7 +14,6 @@ backquote # another word for backtick
 Bezier # Bézier curves are parametric curves used in computer graphics
 bimedian # line segment joining the midpoints of opposite sides of a shape
 bitfield # data structure consisting of adjacent bits
-blockquote # HTML tag
 broadphase # common division of collision detection between broad and narrow phases
 cathetus # the non-hypotenuse sides of a right triangle
 clusterized # past tense of clusterize

.github/.cspell/words_dictionary.txt

@@ -14,19 +14,15 @@ hoverables
 inactives
 microtask
 orientable
-overridable
 platformer
 positionable
 postmultiply
 preorder
 prerender
 prerendered
 pressable
-proxied
-proxying
 ptero # short for pterodactyl
 rebalance
-redeclaration
 refreshable
 renderable
 rescan

.github/workflows/cicd.yml

@@ -9,7 +9,7 @@ on:
 
 
 env:
-  FLUTTER_MIN_VERSION: '3.19.0'
+  FLUTTER_MIN_VERSION: '3.22.0'
 
 jobs:
   # BEGIN LINTING STAGE

.github/workflows/spell_checker.yml

@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
-      - run: npm -g install cspell
+      - run: npm -g install cspell@8.8.2
       # spell check
       - run: ./scripts/cspell-run.sh
       # verify dictionary words are sorted and not orphan

.gitignore

@@ -1,5 +1,3 @@
-pubspec.lock
-
 # Miscellaneous
 *.class
 *.bak
@@ -35,7 +33,7 @@ macos/
 windows/
 linux/
 desktop/
-build/
+**/build/
 coverage/
 pubspec.lock
 pubspec_overrides.yaml

doc/README.md

@@ -63,7 +63,7 @@ Flame doesn't bundle any network feature, which may be needed to write online mu
 
 If you are building a multiplayer game, here are some recommendations of packages/services:
 
-- [Nakama](https://github.com/obrunsmann/flutter_nakama/): Nakama is an open-source server designed
+- [Nakama](https://github.com/obrunsmann/flutter_nakama/): An open-source server designed
  to power modern games and apps.
 - [Firebase](https://firebase.google.com/): Provides dozens of services that can be used to write
 simpler multiplayer experiences.

doc/_sphinx/requirements.txt

@@ -6,5 +6,5 @@ sphinxcontrib-mermaid==0.9.2
 sphinxcontrib-jquery==4.1
 sphinx-autobuild==2021.3.14
 sphinx-copybutton==0.5.2
-Jinja2==3.1.3
+Jinja2==3.1.4
 psutil==5.9.7

doc/_sphinx/theme/flames.css

@@ -20,8 +20,8 @@
 }
 
 body {
-  background-color: #484848;
-  color: #b8b8b8;
+  background-color: #383838;
+  color: #cccccc;
   font-family: var(--font-sans);
   font-size: 15px;
   line-height: 1.5;
@@ -32,14 +32,18 @@ body {
 }
 
 a {
-  color: #ffbb3e;
+  color: #ff9500;
   text-decoration: none;
 }
 
 a:hover {
   color: #ddbb99;
 }
 
+a:visited {
+  color: #ffbc70;
+}
+
 a:hover code {
   color: white;
 }
@@ -69,7 +73,7 @@ code {
 
 code.xref {
   background: none;
-  color: #f75151;
+  color: #ff9500;
   padding: 0;
 }
 
@@ -84,6 +88,7 @@ strong {
   color: white;
 }
 
+
 div.expander {
   flex: 1;
 }
@@ -140,7 +145,7 @@ div.top-bar .btn {
   background-color: transparent;
   border: none;
   border-radius: 0.25rem;
-  color: #ffd78d;
+  color: #ff9500;
   cursor: pointer;
   display: inline-flex;
   font-size: 1rem;
@@ -195,7 +200,7 @@ div.top-bar #menu-button {
 }
 
 #versions-menu > .btn > .version-id {
-  color: #ffe95c;
+  color: #ff9500;
   font-weight: bold;
   padding: 0 0 0 6px;
 }
@@ -347,7 +352,7 @@ div.nav-left li {
 div.nav-left li > a,
 div.nav-left li > div.submenu > a.reference {
   border-radius: 5px 0 0 5px;
-  color: #9d9175;
+  color: #ff9500;
   display: block;
   font-size: 13px;
   margin-left: -5px;
@@ -420,7 +425,7 @@ div.nav-right > #toc-local {
   flex-direction: column;
   margin: 0 0 0 6px;
   max-width: var(--right-menu-width);
-  padding: 0 0 0 10px;
+  padding: 0 0 0 1rem;
 }
 
 div.nav-right > #toc-local > div.header {
@@ -431,7 +436,7 @@ div.nav-right > #toc-local > div.header {
 div.nav-right > #toc-local > a.list-group-item {
   border: none;
   border-left: 4px solid transparent;
-  color: #9d9175;
+  color: #ff9500;
   display: block;
   font-size: 13px;
   line-height: 1.2;
@@ -514,7 +519,7 @@ div.warning .version {
 
 div.document {
   background-color: #282828;
-  color: #b0b0b0;
+  color: #D6D6D6;
   border-radius: 2pt;
   box-shadow: 2px 2px 3px 0 #000;
   padding: var(--document-padding);
@@ -526,12 +531,18 @@ div.document::after { /* clearfix */
   clear: both;
 }
 
+
 div.copyright {
+  color: #cccccc;
   font-size: 12px;
   margin-top: 3px;
   opacity: 0.5;
 }
 
+.copyright a {
+  color: #ff9500;
+  text-decoration: underline;
+}
 div.document h1 {
   border-bottom: 1px solid #555;
   color: #ccc;
@@ -626,7 +637,7 @@ div.document :is(h1, h2, h3, h4) > code {
 }
 
 .prev-next-area > a > .prev-next-info > p.prev-next-subtitle {
-  color: #888;
+  color: #ffffe8;
 }
 
 .prev-next-area > a:hover > .prev-next-info > p.prev-next-title {
@@ -690,7 +701,9 @@ div.highlight-text pre:before {
   content: "text";
   color: #666;
 }
-
+span.keyword {
+  color: #ffffcA;
+}
 
 /*----------------------------------------------------------------------------*
  * Search elements
@@ -867,7 +880,7 @@ table.docutils td {
 }
 
 table.docutils th {
-  color: #9d9175;
+  color: #ff9500;
 }
 
 /* This ensures that when navigating to a link within a page, the link

doc/_sphinx/theme/layout.html

@@ -83,8 +83,8 @@
     });
   </script>
 
-  <a href="{{pathto('index')}}" class="logo_image">
-    <img src="{{pathto('_static/logo_flame.png', 1)}}">
+  <a href="{{pathto('index')}}" class="logo_image" aria-label="Navigate to home page">
+    <img src="{{pathto('_static/logo_flame.png', 1)}}" alt="Flame logo: a fiery symbol along with the FLAME wordmark.">
   </a>  
   <div class="highlight-box" role="alert" style="display:none">
     <div>

doc/bridge_packages/flame_forge2d/joints.md

@@ -482,7 +482,7 @@ joint.getCurrentLengthB()
 
 ```{warning}
 `PulleyJoint` can get a bit troublesome by itself. They often work better when
-combined with prismatic joints. You should also cover the the anchor points 
+combined with prismatic joints. You should also cover the anchor points 
 with static shapes to prevent one side from going to zero length.
 ```
 

doc/bridge_packages/flame_riverpod/component.md

@@ -44,3 +44,5 @@ class RiverpodAwareTextComponent extends PositionComponent
 
 `RiverpodGameMixin` provides listeners from all components to the build method of the
 `RiverpodAwareGameWidget`.
+The `addToGameWidgetBuild` method is available in the `RiverpodGameMixin` as well,
+enabling you to access `ComponentRef` methods directly in your Game class.

doc/development/documentation.md

@@ -194,7 +194,7 @@ rebuild the documents that have changed since the previous run, so usually, a re
 second or two.
 
 If you want to automatically recompile the docs every time there is a change to one of the files
-you can use the the built-in Melos target below, which will also serve and open your default
+you can use the built-in Melos target below, which will also serve and open your default
 browser with the docs.
 
 ```shell

doc/flame/collision_detection.md

@@ -630,7 +630,7 @@ need some of the following things (since it is simpler to not involve Forge2D):
 
 ## Examples
 
-- [https://examples.flame-engine.org/#/Collision%20Detection_Collidable%20AnimationComponent]
-- [https://examples.flame-engine.org/#/Collision%20Detection_Circles]
-- [https://examples.flame-engine.org/#/Collision%20Detection_Multiple%20shapes]
-- [https://github.com/flame-engine/flame/tree/main/examples/lib/stories/collision_detection]
+- [Collidable AnimationComponent](https://examples.flame-engine.org/#/Collision_Detection_Collidable_AnimationComponent)
+- [Circles](https://examples.flame-engine.org/#/Collision_Detection_Circles)
+- [Multiple shapes](https://examples.flame-engine.org/#/Collision_Detection_Multiple_shapes)
+- [More Examples](https://github.com/flame-engine/flame/tree/main/examples/lib/stories/collision_detection)

doc/flame/components.md

@@ -1231,7 +1231,7 @@ A simple example on how to use it:
 // Creates a tileset, the block ids are automatically assigned sequentially
 // starting at 0, from left to right and then top to bottom.
 final tilesetImage = await images.load('tileset.png');
-final tileset = IsometricTileset(tilesetImage, 32);
+final tileset = SpriteSheet(image: tilesetImage, srcSize: Vector2.all(32));
 // Each element is a block id, -1 means nothing
 final matrix = [[0, 1, 0], [1, 0, 0], [1, 1, 1]];
 add(IsometricTileMapComponent(tileset, matrix));
@@ -1254,7 +1254,7 @@ This is an example of how a quarter-length map looks like:
 Flame's Example app contains a more in-depth example, featuring how to parse coordinates to make a
 selector. The code can be found
 [here](https://github.com/flame-engine/flame/blob/main/examples/lib/stories/rendering/isometric_tile_map_example.dart),
-and a live version can be seen [here](https://examples.flame-engine.org/#/Rendering_Isometric%20Tile%20Map).
+and a live version can be seen [here](https://examples.flame-engine.org/#/Rendering_Isometric_Tile_Map).
 
 
 ## NineTileBoxComponent

doc/flame/effects.md

@@ -91,6 +91,8 @@ functionality inherited by all other effects. This includes:
 - Optional user-provided `onComplete`, which will be invoked when the effect has just
   completed its execution but before it is removed from the game.
 
+- A `completed` future that completes when the effect finishes.
+
 - The `reset()` method reverts the effect to its original state, allowing it to run once again.
 
 

doc/flame/examples/lib/router.dart

@@ -111,6 +111,7 @@ class RoundedButton extends PositionComponent with TapCallbacks {
     required this.action,
     required Color color,
     required Color borderColor,
+    super.position,
     super.anchor = Anchor.center,
   }) : _textDrawable = TextPaint(
           style: const TextStyle(

doc/flame/examples/lib/value_route.dart

@@ -54,22 +54,21 @@ class RateRoute extends ValueRoute<int>
     final size = Vector2(250, 130);
     const radius = 18.0;
     final starGap = (size.x - 5 * 2 * radius) / 6;
-    return RectangleComponent(
+    return DialogBackground(
       position: game.size / 2,
       size: size,
-      anchor: Anchor.center,
-      paint: Paint()..color = const Color(0xee858585),
       children: [
         RoundedButton(
           text: 'Ok',
+          position: position = Vector2(size.x / 2, 100),
           action: () {
             completeWith(
               descendants().where((c) => c is Star && c.active).length,
             );
           },
           color: const Color(0xFFFFFFFF),
           borderColor: const Color(0xFF000000),
-        )..position = Vector2(size.x / 2, 100),
+        ),
         for (var i = 0; i < 5; i++)
           Star(
             value: i + 1,
@@ -81,6 +80,14 @@ class RateRoute extends ValueRoute<int>
   }
 }
 
+class DialogBackground extends RectangleComponent with TapCallbacks {
+  DialogBackground({super.position, super.size, super.children})
+      : super(
+          anchor: Anchor.center,
+          paint: Paint()..color = const Color(0xee858585),
+        );
+}
+
 class Star extends PositionComponent with TapCallbacks {
   Star({required this.value, required this.radius, super.position})
       : super(size: Vector2.all(2 * radius), anchor: Anchor.center);

doc/flame/examples/pubspec.yaml

@@ -4,12 +4,12 @@ version: 1.0.0
 publish_to: none
 
 environment:
-  sdk: ">=3.0.0 <4.0.0"
-  flutter: ^3.19.0
+  sdk: ">=3.3.0 <4.0.0"
+  flutter: ">=3.22.0"
 
 dependencies:
-  flame: ^1.15.0
-  flame_rive: ^1.9.11
+  flame: ^1.17.0
+  flame_rive: ^1.10.1
   flutter:
     sdk: flutter
 

doc/flame/game.md

@@ -244,3 +244,18 @@ class MyGame extends FlameGame {
 
 On the current Flutter stable (3.13), this flag is effectively ignored on
 non-mobile platforms including the web.
+
+
+## HasPerformanceTracker mixin
+
+While optimizing a game, it can be useful to track the time it took for the game to update and render
+each frame. This data can help in detecting areas of the code that are running hot. It can also help
+in detecting visual areas of the game that are taking the most time to render.
+
+To get the update and render times, just add the `HasPerformanceTracker` mixin to the game class.
+
+```dart
+class MyGame extends FlameGame with HasPerformanceTracker {
+  // access `updateTime` and `renderTime` getters.
+}
+```