feat: Use a Free List Strategy on BatchItem indexes within SpriteBatch and return index from .add()

doc/flame/rendering/images.md

@@ -316,6 +316,11 @@ A `SpriteBatchComponent` is also available for your convenience.
 See how to use it in the
 [SpriteBatch examples](https://github.com/flame-engine/flame/blob/main/examples/lib/stories/sprites/sprite_batch_example.dart)
 
+When using a SpriteBatch to render animations, it's helpful to set a unique ID of the `BatchItem`
+related to the frame of your animation to make replacing and removing frames more reliable. When
+replacing a `BatchItem`, you can use the `findIndexById` to retrieve the associated index
+for replacement.
+
 
 ## ImageComposition
 

packages/flame/lib/src/sprite_batch.dart

@@ -37,11 +37,15 @@ class BatchItem {
   BatchItem({
     required this.source,
     required this.transform,
+    this.id,
     Color? color,
     this.flip = false,
   })  : paint = Paint()..color = color ?? const Color(0x00000000),
         destination = Offset.zero & source.size;
 
+  /// Optional identifier for the batch item.
+  final String? id;
+
   /// The source rectangle on the [SpriteBatch.atlas].
   final Rect source;
 
@@ -144,6 +148,12 @@ class SpriteBatch {
 
   FlippedAtlasStatus _flippedAtlasStatus = FlippedAtlasStatus.none;
 
+  /// A map to keep track of the index of each batch item by its id.
+  final Map<String, int> _idToIndex = {};
+
+  /// Returns all ids currently in the batch (excluding nulls).
+  Iterable<String> get ids => _batchItems.map((item) => item.id!);
+
   /// List of all the existing batch items.
   final _batchItems = <BatchItem>[];
 
@@ -252,6 +262,7 @@ class SpriteBatch {
   /// At least one of the parameters must be different from null.
   void replace(
     int index, {
+    String? id,
     Rect? source,
     Color? color,
     RSTransform? transform,
@@ -267,17 +278,23 @@ class SpriteBatch {
 
     final currentBatchItem = _batchItems[index];
     final newBatchItem = BatchItem(
+      id: id ?? currentBatchItem.id,
       source: source ?? currentBatchItem.source,
       transform: transform ?? currentBatchItem.transform,
       color: color ?? currentBatchItem.paint.color,
       flip: currentBatchItem.flip,
     );
 
     _batchItems[index] = newBatchItem;
-
     _sources[index] = newBatchItem.source;
     _transforms[index] = newBatchItem.transform;
     _colors[index] = color ?? _defaultColor;
+
+    if (id == null) {
+      return;
+    }
+
+    _idToIndex[id] = index;
   }
 
   /// Add a new batch item using a RSTransform.
@@ -300,8 +317,10 @@ class SpriteBatch {
     RSTransform? transform,
     bool flip = false,
     Color? color,
+    String? id,
   }) {
     final batchItem = BatchItem(
+      id: id,
       source: source,
       transform: transform ??= defaultTransform ?? RSTransform(1, 0, 0, 0),
       flip: flip,
@@ -327,6 +346,13 @@ class SpriteBatch {
     );
     _transforms.add(batchItem.transform);
     _colors.add(color ?? _defaultColor);
+
+    if (id == null) {
+      return;
+    }
+
+    final newIdx = _batchItems.length - 1;
+    _idToIndex[id] = newIdx;
   }
 
   /// Add a new batch item.
@@ -349,6 +375,7 @@ class SpriteBatch {
   /// method instead.
   void add({
     required Rect source,
+    String? id,
     double scale = 1.0,
     Vector2? anchor,
     double rotation = 0,
@@ -382,15 +409,57 @@ class SpriteBatch {
       transform: transform,
       flip: flip,
       color: color,
+      id: id,
     );
   }
 
+  /// Finds the index of the batch item with the given [id].
+  int? findIndexById(String id) {
+    if (_idToIndex.containsKey(id)) {
+      return _idToIndex[id];
+    }
+    for (var i = 0; i < _batchItems.length; i++) {
+      if (_batchItems[i].id == id) {
+        _idToIndex[id] = i; // repair mapping
+        return i;
+      }
+    }
+    return null;
+  }
+
+  /// Removes a batch item by its [id].
+  void removeById(String id) {
+    final index = _idToIndex[id];
+    if (index == null) {
+      return;
+    }
+
+    removeAt(index);
+    _idToIndex.remove(id);
+
+    // adjust indices > removed index
+    _idToIndex.updateAll((key, idx) => idx > index ? idx - 1 : idx);
+  }
+
+  /// Removes a batch item at the given [index].
+  void removeAt(int index) {
+    if (index < 0 || index >= length) {
+      throw ArgumentError('Index out of bounds: $index');
+    }
+
+    _batchItems.removeAt(index);
+    _sources.removeAt(index);
+    _transforms.removeAt(index);
+    _colors.removeAt(index);
+  }
+
   /// Clear the SpriteBatch so it can be reused.
   void clear() {
     _sources.clear();
     _transforms.clear();
     _colors.clear();
     _batchItems.clear();
+    _idToIndex.clear();
   }
 
   // Used to not create new Paint objects in [render] and

packages/flame/test/sprite_batch_test.dart

@@ -61,6 +61,33 @@ void main() {
       );
     });
 
+    test('can add a batch item with an id', () {
+      final image = _MockImage();
+      final spriteBatch = SpriteBatch(image);
+      spriteBatch.add(source: Rect.zero, id: 'item1');
+
+      final batchItem = spriteBatch.findIndexById('item1');
+
+      expect(batchItem, isNotNull);
+    });
+
+    test('can replace a batch item with an id', () {
+      final image = _MockImage();
+      final spriteBatch = SpriteBatch(image);
+      spriteBatch.add(source: Rect.zero, id: 'item1');
+
+      spriteBatch.replace(
+        spriteBatch.findIndexById('item1')!,
+        source: const Rect.fromLTWH(1, 1, 1, 1),
+        id: 'item2',
+      );
+
+      final batchItem = spriteBatch.findIndexById('item2');
+
+      expect(batchItem, isNotNull);
+      expect(spriteBatch.sources.first, const Rect.fromLTWH(1, 1, 1, 1));
+    });
+
     const margin = 2.0;
     const tileSize = 6.0;