feat: Adding bleed option to SpriteBatch

examples/lib/stories/sprites/sprite_batch_bleed_example.dart

@@ -0,0 +1,194 @@
+import 'dart:math';
+
+import 'package:flame/components.dart';
+import 'package:flame/game.dart';
+import 'package:flame/sprite.dart';
+import 'package:flutter/material.dart';
+
+class SpriteBatchBleedExample extends FlameGame {
+  static const String description = '''
+    In this example we show how `bleed` can be used to prevent edge artifacts
+    (seams) between tiles when rendering with `SpriteBatch`.
+
+    The top rows show tiles rendered without bleed, where slight gaps or
+    color bleeding may appear at the edges.
+
+    The bottom rows show the same tiles rendered with bleed, which expands
+    the destination rectangle outward while keeping the source region the
+    same, eliminating edge artifacts.
+
+    The rotated tiles on the right demonstrate that bleed works correctly
+    even with rotation, preserving the center point.
+  ''';
+
+  static const tileSize = 32.0;
+  static const scale = 3.0;
+  static const scaledTile = tileSize * scale;
+  static const bleed = 1.0;
+
+  @override
+  Future<void> onLoad() async {
+    final spriteBatch = await SpriteBatch.load('retro_tiles.png');
+
+    const tile1 = Rect.fromLTWH(0, 0, tileSize, tileSize);
+    const tile2 = Rect.fromLTWH(tileSize, 0, tileSize, tileSize);
+
+    // --- Section 1: Without bleed (top) ---
+    const startYNoBleed = 40.0;
+    const startX = 40.0;
+    const gap = 16.0;
+    const startXRotated = startX + scaledTile * 6 + gap * 2;
+
+    _addTileRow(
+      spriteBatch,
+      startX: startX,
+      startY: startYNoBleed,
+      tile1: tile1,
+      tile2: tile2,
+      bleed: 0,
+    );
+
+    _addTileRow(
+      spriteBatch,
+      startX: startX,
+      startY: startYNoBleed + scaledTile + gap,
+      tile1: tile2,
+      tile2: tile1,
+      bleed: 0,
+    );
+
+    // --- Section 2: With bleed (bottom) ---
+    const startYBleed = startYNoBleed + (scaledTile + gap) * 2 + gap * 2;
+
+    _addTileRow(
+      spriteBatch,
+      startX: startX,
+      startY: startYBleed,
+      tile1: tile1,
+      tile2: tile2,
+      bleed: bleed,
+    );
+
+    _addTileRow(
+      spriteBatch,
+      startX: startX,
+      startY: startYBleed + scaledTile + gap,
+      tile1: tile2,
+      tile2: tile1,
+      bleed: bleed,
+    );
+
+    // --- Section 3: Rotated tiles with bleed (right side) ---
+    final centerY = size.y / 2;
+
+    // Without bleed, rotated
+    spriteBatch.add(
+      source: tile1,
+      offset: Vector2(startXRotated, centerY - scaledTile - gap),
+      scale: scale,
+      rotation: pi / 6,
+      anchor: Vector2(tileSize / 2, tileSize / 2),
+    );
+
+    spriteBatch.add(
+      source: tile2,
+      offset: Vector2(
+        startXRotated + scaledTile + gap,
+        centerY - scaledTile - gap,
+      ),
+      scale: scale,
+      rotation: pi / 6,
+      anchor: Vector2(tileSize / 2, tileSize / 2),
+    );
+
+    // With bleed, rotated
+    spriteBatch.add(
+      source: tile1,
+      offset: Vector2(startXRotated, centerY + gap),
+      scale: scale,
+      rotation: pi / 6,
+      anchor: Vector2(tileSize / 2, tileSize / 2),
+      bleed: bleed,
+    );
+
+    spriteBatch.add(
+      source: tile2,
+      offset: Vector2(
+        startXRotated + scaledTile + gap,
+        centerY + gap,
+      ),
+      scale: scale,
+      rotation: pi / 6,
+      anchor: Vector2(tileSize / 2, tileSize / 2),
+      bleed: bleed,
+    );
+
+    add(
+      SpriteBatchComponent(
+        spriteBatch: spriteBatch,
+        blendMode: BlendMode.srcOver,
+      ),
+    );
+
+    // Add labels
+    add(
+      TextComponent(
+        text: 'Without bleed',
+        position: Vector2(startX, startYNoBleed - 20),
+        textRenderer: TextPaint(
+          style: const TextStyle(
+            color: Colors.red,
+            fontSize: 14,
+            fontWeight: FontWeight.bold,
+          ),
+        ),
+      ),
+    );
+
+    add(
+      TextComponent(
+        text: 'With bleed (bleed=$bleed)',
+        position: Vector2(startX, startYBleed - 20),
+        textRenderer: TextPaint(
+          style: const TextStyle(
+            color: Colors.green,
+            fontSize: 14,
+            fontWeight: FontWeight.bold,
+          ),
+        ),
+      ),
+    );
+
+    add(
+      TextComponent(
+        text: 'Rotated',
+        position: Vector2(startXRotated, 20),
+        textRenderer: TextPaint(
+          style: const TextStyle(
+            color: Colors.orange,
+            fontSize: 14,
+            fontWeight: FontWeight.bold,
+          ),
+        ),
+      ),
+    );
+  }
+
+  void _addTileRow(
+    SpriteBatch batch, {
+    required double startX,
+    required double startY,
+    required Rect tile1,
+    required Rect tile2,
+    required double bleed,
+  }) {
+    for (var i = 0; i < 6; i++) {
+      batch.add(
+        source: i.isEven ? tile1 : tile2,
+        offset: Vector2(startX + i * scaledTile, startY),
+        scale: scale,
+        bleed: bleed,
+      );
+    }
+  }
+}

examples/lib/stories/sprites/sprites.dart

@@ -2,6 +2,7 @@ import 'package:dashbook/dashbook.dart';
 import 'package:examples/commons/commons.dart';
 import 'package:examples/stories/sprites/base64_sprite_example.dart';
 import 'package:examples/stories/sprites/basic_sprite_example.dart';
+import 'package:examples/stories/sprites/sprite_batch_bleed_example.dart';
 import 'package:examples/stories/sprites/sprite_batch_example.dart';
 import 'package:examples/stories/sprites/sprite_batch_load_example.dart';
 import 'package:examples/stories/sprites/sprite_group_example.dart';
@@ -40,6 +41,12 @@ void addSpritesStories(Dashbook dashbook) {
       codeLink: baseLink('sprites/sprite_batch_load_example.dart'),
       info: SpriteBatchLoadExample.description,
     )
+    ..add(
+      'SpriteBatch Bleed',
+      (_) => GameWidget(game: SpriteBatchBleedExample()),
+      codeLink: baseLink('sprites/sprite_batch_bleed_example.dart'),
+      info: SpriteBatchBleedExample.description,
+    )
     ..add(
       'SpriteGroup',
       (_) => GameWidget(game: SpriteGroupExample()),

packages/flame/CHANGELOG.md

@@ -1,5 +1,6 @@
 ## 1.37.0
 
+ - **FEAT**: Add `bleed` option to `SpriteBatch` to prevent seam artifacts in tilemaps ([#3871](https://github.com/flame-engine/flame/issues/3871)).
  - **FIX**: Use proper hash combining in CollisionProspect to fix flaky test ([#3864](https://github.com/flame-engine/flame/issues/3864)). ([bff137e5](https://github.com/flame-engine/flame/commit/bff137e5c1c97ae98e867a933f6790aeb349f90f))
  - **FIX**: Remove async from flame test helpers ([#3860](https://github.com/flame-engine/flame/issues/3860)). ([4e63e93e](https://github.com/flame-engine/flame/commit/4e63e93eb78d5e6e3c48e0cc02577bf2581b0e87))
  - **FEAT**: Add OverlayManager.setActive() ([#3875](https://github.com/flame-engine/flame/issues/3875)). ([86495694](https://github.com/flame-engine/flame/commit/86495694665cc4e85f7d3a94b05766cc6f6b95ba))