Merge branch 'main' into feat-add-rewind-textboxcomponent

Author: Wilhansen

CHANGELOG.md

@@ -3,6 +3,27 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## 2025-12-17
+
+### Changes
+
+---
+
+Packages with breaking changes:
+
+ - There are no breaking changes in this release.
+
+Packages with other changes:
+
+ - [`flame_riverpod` - `v5.5.0`](#flame_riverpod---v550)
+
+---
+
+#### `flame_riverpod` - `v5.5.0`
+
+ - **FEAT**: Riverpod 3.0 in flame_riverpod ([#3789](https://github.com/flame-engine/flame/issues/3789)). ([57f7f9d8](https://github.com/flame-engine/flame/commit/57f7f9d8b30632717fdf894321758a26d4985907))
+
+
 ## 2025-11-23
 
 ### Changes

README.md

@@ -99,6 +99,7 @@ network.
 framework.
 - [flame_rive][flame_rive] for [Rive][rive]: Create interactive animations.
 - [flame_svg][flame_svg] for [flutter_svg][flutter_svg]: Draw SVG files in Flutter.
+- [flame_texturepacker][flame_texturepacker]: Load and use sprite sheets generated with [TexturePacker][texturepacker]
 - [flame_tiled][flame_tiled] for [Tiled][tiled]: 2D tile map level editor.
 
 
@@ -194,5 +195,7 @@ via an issue, GitHub discussion, or reach out to the team either using the
 [rive]: https://rive.app/
 [flame_svg]: https://github.com/flame-engine/flame/tree/main/packages/flame_svg
 [flutter_svg]: https://github.com/dnfield/flutter_svg
+[flame_texturepacker]: https://github.com/flame-engine/flame/tree/main/packages/flame_texturepacker
+[texturepacker]: https://www.codeandweb.com/texturepacker
 [flame_tiled]: https://github.com/flame-engine/flame/tree/main/packages/flame_tiled
 [tiled]: https://www.mapeditor.org/

doc/bridge_packages/bridge_packages.md

@@ -81,6 +81,12 @@ Add the "Powered by Flame" splash screen.
 Draw SVG files in Flutter (bridge package for [flutter_svg]).
 :::
 
+:::{package} flame_texturepacker
+
+Load sprite sheets created by TexturePacker tool (bridge package for
+[TexturePacker]).
+:::
+
 :::{package} flame_tiled
 
 2D tilemap level editor (bridge package for [Tiled]).
@@ -94,6 +100,7 @@ Draw SVG files in Flutter (bridge package for [flutter_svg]).
 [Rive]: https://rive.app/
 [Riverpod]: https://github.com/rrousselGit/riverpod
 [Spine]: https://pub.dev/packages/spine_flutter
+[TexturePacker]: https://www.codeandweb.com/texturepacker
 [Tiled]: https://www.mapeditor.org/
 [flutter_svg]: https://github.com/dnfield/flutter_svg
 
@@ -115,5 +122,6 @@ flame_riverpod              <flame_riverpod/flame_riverpod.md>
 flame_splash_screen         <flame_splash_screen/flame_splash_screen.md>
 flame_spine                 <flame_spine/flame_spine.md>
 flame_svg                   <flame_svg/flame_svg.md>
+flame_texturepacker         <flame_texturepacker/flame_texturepacker.md>
 flame_tiled                 <flame_tiled/flame_tiled.md>
 ```

doc/bridge_packages/flame_texturepacker/flame_texturepacker.md

@@ -0,0 +1,153 @@
+# flame_texturepacker
+
+**flame_texturepacker**
+is a bridge package that allows you to load sprite sheets generated by [CodeAndWeb's TexturePacker]
+into your Flame game.
+
+A sprite sheet (or texture atlas) is a larger image that packs many smaller sprites together.
+This reduces the number of separate textures a game must load, which lowers overhead
+and can improve loading speed and rendering performance.
+
+
+## Installation
+
+Add  *flame_texturepacker* to your project:
+
+```shell
+flutter pub add flame_texturepacker
+```
+
+Then import it in your Dart code:
+
+```dart
+import 'package:flame_texturepacker/flame_texturepacker.dart';
+```
+
+
+## Usage
+
+
+### Loading from Assets
+
+First, add your ``.atlas`` data file and sprite sheet images to your assets directory and reference
+them in your `pubspec.yaml`:
+
+```yaml
+flutter:
+  assets:
+    - assets/images/atlas_map.atlas
+    - assets/images/sprite_sheet1.png
+    - assets/images/sprite_sheet2.png
+    - assets/images/sprite_sheet3.png
+```
+
+Then load the atlas in your game:
+
+```dart
+class MyGame extends FlameGame {
+  @override
+  Future<void> onLoad() async {
+    // Load the texture atlas
+    final atlas = await atlasFromAssets('atlas_map.atlas');
+    
+    // Use the atlas to get sprites
+    final sprite = atlas.findSpriteByName('robot_jump')!;
+    add(SpriteComponent(sprite: sprite));
+  }
+}
+```
+
+
+## TexturePackerAtlas
+
+The `TexturePackerAtlas` class is the main interface for working with texture atlases. It provides
+several methods to query and retrieve sprites.
+
+
+### Finding Sprites
+
+**Find a single sprite by name:**
+
+```dart
+final jumpSprite = atlas.findSpriteByName('robot_jump')!;
+final fallSprite = atlas.findSpriteByName('robot_fall')!;
+```
+
+**Find a sprite by name and index:**
+
+```dart
+final sprite = atlas.findSpriteByNameIndex('robot_walk', 0);
+```
+
+**Find all sprites with the same name:**
+
+This is particularly useful for creating animations from indexed sprites:
+
+```dart
+// Get all sprites with the name 'robot_walk'
+// (e.g., robot_walk_0, robot_walk_1, etc.)
+final walkingSprites = atlas.findSpritesByName('robot_walk');
+
+// Create an animation from the sprite list
+final walkingAnimation = SpriteAnimation.spriteList(
+  walkingSprites,
+  stepTime: 0.1,
+  loop: true,
+);
+
+add(SpriteAnimationComponent(animation: walkingAnimation));
+```
+
+
+## Advanced Options
+
+
+### Whitelist Filtering
+
+To optimize memory usage, you can specify a whitelist of sprite names to load. Only sprites whose
+names contain any of the whitelist strings will be loaded:
+
+```dart
+final atlas = await TexturePackerAtlas.load(
+  'atlas_map.atlas',
+  whiteList: [ 'robot_walk' ]
+);
+```
+
+This is particularly useful for large atlases where you only need a subset of sprites.
+
+
+### Original Size vs Packed Size
+
+TexturePacker can trim transparent pixels from sprites to save space. By default,
+`flame_texturepacker` uses the original (untrimmed) size. You can change this behavior:
+
+```dart
+final atlas = await TexturePackerAtlas.load(
+  'atlas_map.atlas',
+  useOriginalSize: false, // Use the trimmed/packed size instead
+);
+```
+
+
+### Custom Asset Prefix
+
+If your ``.atlas`` data file is not stored in the default `images` directory:
+
+```dart
+final atlas = await atlasFromAssets(
+  'atlas_map.atlas',
+  assetsPrefix: 'custom_path',
+);
+```
+
+
+## Full Example
+
+A complete working example can be found in the [flame_texturepacker example] or
+in this [tutorial from CodeAndWeb].
+
+
+[flame_texturepacker example]: https://github.com/flame-engine/flame/tree/main/packages/flame_texturepacker/example
+[tutorial from CodeAndWeb]: https://www.codeandweb.com/texturepacker/tutorials/how-to-create-sprite-sheets-and-animations-with-flame-engine
+[CodeAndWeb's TexturePacker]: https://www.codeandweb.com/texturepacker

examples/lib/stories/experimental/experimental.dart

@@ -54,6 +54,10 @@ void addExperimentalStories(Dashbook dashbook) {
                 'Wrap with ExpandedComponent',
                 false,
               ),
+              paddingInflateChild: context.boolProperty(
+                'Padding Component inflates child',
+                false,
+              ),
             ),
           );
         },

examples/lib/stories/experimental/layout_component_example_1.dart

@@ -16,6 +16,7 @@ class LayoutComponentExample1 extends FlameGame with DragCallbacks {
     required this.demoSize,
     required this.padding,
     required this.expandedMode,
+    required this.paddingInflateChild,
   });
 
   static const String description = '''
@@ -31,6 +32,7 @@ the various ways you can change this layout.
   final LayoutComponentExampleSize demoSize;
   final EdgeInsets padding;
   final bool expandedMode;
+  final bool paddingInflateChild;
 
   @override
   FutureOr<void> onLoad() {
@@ -54,6 +56,7 @@ the various ways you can change this layout.
           position: Vector2.zero(),
           padding: padding,
           expandedMode: expandedMode,
+          paddingInflateChild: paddingInflateChild,
           size: demoSize.toVector2(),
         ),
       ],
@@ -83,6 +86,7 @@ class LayoutDemo1 extends LinearLayoutComponent {
     required super.position,
     required EdgeInsets padding,
     required bool expandedMode,
+    required this.paddingInflateChild,
     super.size,
     super.key,
   }) : _padding = padding,
@@ -96,7 +100,13 @@ class LayoutDemo1 extends LinearLayoutComponent {
   set expandedMode(bool value) {
     _expandedMode = value;
     removeAll(children.toList());
-    addAll(createComponentList(expandedMode: expandedMode, padding: padding));
+    addAll(
+      createComponentList(
+        expandedMode: expandedMode,
+        padding: padding,
+        inflateChild: paddingInflateChild,
+      ),
+    );
   }
 
   EdgeInsets _padding = EdgeInsets.zero;
@@ -108,10 +118,18 @@ class LayoutDemo1 extends LinearLayoutComponent {
     paddingComponent?.padding = padding;
   }
 
+  final bool paddingInflateChild;
+
   @override
   FutureOr<void> onLoad() {
     super.onLoad();
-    addAll(createComponentList(expandedMode: expandedMode, padding: padding));
+    addAll(
+      createComponentList(
+        expandedMode: expandedMode,
+        padding: padding,
+        inflateChild: paddingInflateChild,
+      ),
+    );
   }
 
   PaddingComponent? get paddingComponent {
@@ -124,6 +142,7 @@ class LayoutDemo1 extends LinearLayoutComponent {
   static List<Component> createComponentList({
     required bool expandedMode,
     required EdgeInsets padding,
+    required bool inflateChild,
   }) {
     return [
       TextComponent(text: 'Some short text'),
@@ -143,6 +162,7 @@ class LayoutDemo1 extends LinearLayoutComponent {
         ExpandedComponent(
           child: PaddingComponent(
             padding: padding,
+            inflateChild: inflateChild,
             child: RectangleComponent(
               size: Vector2(96, 96),
               paint: Paint()..color = Colors.blue,
@@ -152,6 +172,7 @@ class LayoutDemo1 extends LinearLayoutComponent {
       else
         PaddingComponent(
           padding: padding,
+          inflateChild: inflateChild,
           child: RectangleComponent(
             size: Vector2(96, 96),
             paint: Paint()..color = Colors.blue,

packages/flame/lib/src/experimental/expanded_component.dart

@@ -38,13 +38,10 @@ class ExpandedComponent extends SingleLayoutComponent
     super.position,
     super.anchor,
     super.priority,
-    this.inflateChild = true,
+    super.inflateChild = true,
     super.child,
   }) : super(size: null);
 
-  /// Whether or not this [ExpandedComponent] will set [child]'s size to its own
-  final bool inflateChild;
-
   @override
   void setLayoutAxisLength(LayoutAxis axis, double? value) {
     super.setLayoutAxisLength(axis, value);

packages/flame/lib/src/experimental/layout_component.dart

@@ -34,9 +34,8 @@ abstract class LayoutComponent extends PositionComponent {
   /// vector components, and subsequently selective setting of the
   /// size components.
   void setLayoutSize(double? layoutSizeX, double? layoutSizeY) {
-    _layoutSizeX = layoutSizeX;
-    _layoutSizeY = layoutSizeY;
-    resetSize();
+    setLayoutAxisLength(LayoutAxis.x, layoutSizeX);
+    setLayoutAxisLength(LayoutAxis.y, layoutSizeY);
   }
 
   /// A helper function to set the appropriate layout dimension based on

packages/flame/lib/src/experimental/padding_component.dart

@@ -16,6 +16,10 @@ import 'package:flutter/rendering.dart';
 /// You may set [padding] as well as the [child] after the fact, and it will
 /// cause the layout to refresh.
 ///
+/// If [inflateChild] is true, [resetSize] sets the child's size to fill up
+/// available space via [syncChildSize]. If the child is a [LayoutComponent]
+/// descendant, then [resetSize] uses the [LayoutComponent.setLayoutSize].
+///
 /// Example usage:
 /// ```dart
 /// PaddingComponent(
@@ -31,6 +35,7 @@ class PaddingComponent extends SingleLayoutComponent {
     super.position,
     super.priority,
     super.size,
+    super.inflateChild = false,
     PositionComponent? child,
   }) : _padding = padding ?? EdgeInsets.zero,
        super(child: null) {
@@ -48,8 +53,6 @@ class PaddingComponent extends SingleLayoutComponent {
 
   @override
   void layoutChildren() {
-    // Only resets to null if it's already null. This way, we avoid overwriting
-    // an explicit width/height.
     resetSize();
     final child = this.child;
     if (child == null) {
@@ -59,6 +62,11 @@ class PaddingComponent extends SingleLayoutComponent {
     child.topLeftPosition.setFrom(padding.topLeft.toVector2());
   }
 
+  @override
+  Vector2 get availableSize {
+    return padding.deflateSize(size.toSize()).toVector2();
+  }
+
   @override
   Vector2 get intrinsicSize {
     final childWidth = child?.size.x ?? 0;