feat: Add SpriteBatch.replace to allow the replacement of the batch information

packages/flame/lib/src/sprite_batch.dart

@@ -243,6 +243,43 @@ class SpriteBatch {
     return picture.toImageSafe(image.width * 2, image.height);
   }
 
+  int get length => _sources.length;
+
+  /// Replace a batch item at the [index] with the new values.
+  ///
+  /// Throws an [ArgumentError] if the [index] is out of bounds.
+  /// At least one of the parameters must be different from null.
+  void replace(int index, {
+    Rect? source,
+    Color? color,
+    RSTransform? transform,
+  }) {
+    assert(
+      source != null || color != null || transform != null,
+      'At least one of the parameters must be different from null.',
+    );
+
+    if (index < 0 || index >= length) {
+      throw ArgumentError('Index out of bounds: $index');
+    }
+
+    final currentBatchItem = _batchItems[index];
+    final newBatchItem = BatchItem(
+      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;
+    if (color != null) {
+      _colors[index] = color;
+    }
+  }
+
   /// Add a new batch item using a RSTransform.
   ///
   /// The [source] parameter is the source location on the [atlas].

packages/flame/test/sprite_batch_test.dart

@@ -0,0 +1,68 @@
+import 'dart:ui';
+
+import 'package:flame/sprite.dart';
+import 'package:flutter/material.dart' hide Image;
+import 'package:flutter_test/flutter_test.dart';
+import 'package:mocktail/mocktail.dart';
+
+class _MockImage extends Mock implements Image {}
+
+void main() {
+  group('SpriteBatch', () {
+    test('can add to the batch', () {
+      final image = _MockImage();
+      final spriteBatch = SpriteBatch(image);
+      spriteBatch.add(source: Rect.zero);
+
+      expect(spriteBatch.transforms, hasLength(1));
+    });
+
+    test('can add to the batch', () {
+      final image = _MockImage();
+      final spriteBatch = SpriteBatch(image);
+      spriteBatch.add(source: Rect.zero);
+
+      expect(spriteBatch.transforms, hasLength(1));
+    });
+
+    test('can replace the color of a batch', () {
+      final image = _MockImage();
+      final spriteBatch = SpriteBatch(image);
+      spriteBatch.add(source: Rect.zero, color: Colors.blue);
+
+      spriteBatch.replace(0, color: Colors.red);
+
+      expect(spriteBatch.colors, hasLength(1));
+      expect(spriteBatch.colors.first, Colors.red);
+    });
+
+    test('can replace the source of a batch', () {
+      final image = _MockImage();
+      final spriteBatch = SpriteBatch(image);
+      spriteBatch.add(source: Rect.zero);
+
+      spriteBatch.replace(0, source: const Rect.fromLTWH(1, 1, 1, 1));
+
+      expect(spriteBatch.sources, hasLength(1));
+      expect(spriteBatch.sources.first, const Rect.fromLTWH(1, 1, 1, 1));
+    });
+
+    test('can replace the transform of a batch', () {
+      final image = _MockImage();
+      final spriteBatch = SpriteBatch(image);
+      spriteBatch.add(source: Rect.zero);
+
+      spriteBatch.replace(0, transform: RSTransform(1, 1, 1, 1));
+
+      expect(spriteBatch.transforms, hasLength(1));
+      expect(
+        spriteBatch.transforms.first,
+        isA<RSTransform>()
+            .having((t) => t.scos, 'scos', 1)
+            .having((t) => t.ssin, 'ssin', 1)
+            .having((t) => t.tx, 'tx', 1)
+            .having((t) => t.ty, 'ty', 1),
+      );
+    });
+  });
+}