feat: Add HasAutoBatchedChildren mixin#3850
Merged
ufrshubham merged 11 commits intomainfrom Mar 13, 2026
Merged
Conversation
Introduce protected renderChild(Canvas, Component) to centralize per-child rendering (propagates parent's render contexts to the child and cleans them up). Add afterChildrenRendered(Canvas) as a hook to flush state after all children are rendered (useful for batching). Update renderTree to delegate child rendering to renderChild and call afterChildrenRendered once after the child loop.
Introduce `HasAutoBatchedChildren`. The mixin batches eligible `SpriteComponent` and `SpriteAnimationComponent` leaf children into per-atlas `SpriteBatch` draws (using `RSTransform`) to reduce draw calls, while preserving render order by flushing at priority-group boundaries and after children. Eligibility checks reject non-uniform scale, decorators, snapshot caching, complex paint effects, and non-leaf or non-sprite children. Adds a runtime `batchingEnabled` toggle, per-image accumulators reused across frames, and safe fallbacks to individual rendering when batching is not possible.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces an auto-batching mechanism for sprite rendering to reduce draw calls, by adding a HasAutoBatchedChildren mixin and extending the core Component rendering pipeline with child-level interception hooks. It also updates the Rogue Shooter example to demonstrate the feature with a runtime toggle, and adds tests to validate batching behavior.
Changes:
- Added
HasAutoBatchedChildrenmixin to batch eligibleSpriteComponent/SpriteAnimationComponentchildren viaCanvas.drawAtlas. - Extended
ComponentwithrenderChildandafterChildrenRenderedhooks to enable clean per-child render interception and post-pass flushing. - Updated Rogue Shooter example to organize sprites into batching groups and toggle batching via keyboard input; added comprehensive batching tests.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/flame/lib/src/components/mixins/has_auto_batched_children.dart | New mixin implementing automatic sprite batching with eligibility checks and per-priority flushing. |
| packages/flame/lib/src/components/core/component.dart | Adds render pipeline hooks (renderChild, afterChildrenRendered) used by batching and similar features. |
| packages/flame/lib/components.dart | Exports the new HasAutoBatchedChildren mixin from the public API. |
| packages/flame/test/components/has_auto_batched_children_test.dart | New tests validating batching behavior, eligibility rules, and render-order correctness. |
| examples/games/rogue_shooter/lib/rogue_shooter_game.dart | Introduces BatchGroups, batching toggle UI/keyboard control, and adjusts component counting. |
| examples/games/rogue_shooter/lib/components/star_background_creator.dart | Routes star creation into the new starGroup batch group and adds typed game reference. |
| examples/games/rogue_shooter/lib/components/player_component.dart | Routes bullets/explosions into batch groups and adds typed game reference. |
| examples/games/rogue_shooter/lib/components/enemy_creator.dart | Routes enemies into enemyGroup and adds typed game reference. |
| examples/games/rogue_shooter/lib/components/enemy_component.dart | Routes explosions into explosionGroup. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
packages/flame/lib/src/components/mixins/has_auto_batched_children.dart
Outdated
Show resolved
Hide resolved
packages/flame/lib/src/components/mixins/has_auto_batched_children.dart
Outdated
Show resolved
Hide resolved
packages/flame/lib/src/components/mixins/has_auto_batched_children.dart
Outdated
Show resolved
Hide resolved
packages/flame/lib/src/components/mixins/has_auto_batched_children.dart
Outdated
Show resolved
Hide resolved
- Fix render-context cleanup in `Component.renderChild` to use the child's original context length - Accumulators key by `Image` (instead of identity hash) - Allow `ShapeHitbox` children to render hitbox debug visuals when needed - Add stricter eligibility checks (decorator constraints, and excluding non-srcOver blend modes) - Minor test string updates and removal of an unused import in the example.
ufrshubham
force-pushed
the
devkage/auto-batching
branch
from
75c6855 to
913d93a
Compare
spydon
reviewed
Mar 9, 2026
packages/flame/lib/src/components/mixins/has_auto_batched_children.dart
Outdated
Show resolved
Hide resolved
packages/flame/lib/src/components/mixins/has_auto_batched_children.dart
Outdated
Show resolved
Hide resolved
erickzanardo
reviewed
Mar 9, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This pull request introduces automatic sprite batching for improved rendering performance. The main change is the addition of the
HasAutoBatchedChildrenmixin, which enables groups of sprite components to be rendered in a single draw call per atlas, reducing overheadSprite batching implementation:
HasAutoBatchedChildrenmixin, which accumulates eligible sprite and animation components for batch rendering, flushes batches at priority boundaries, and provides runtime togglingComponentclass to support per-child rendering interception (renderChild) and post-children rendering hooks (afterChildrenRendered), enabling batching logic to be integrated cleanlyUpdated the Rogue Shooter example to use auto-batching with a toggle to see the performance difference.
Flame-AutoBatch.mp4
Checklist
docsand added dartdoc comments with///.examplesordocs.Breaking Change?
Related Issues