Skip to content

feat: HitTestBehavior for GameWidget#3815

Open
spydon wants to merge 8 commits intomainfrom
fix/events-should-passthrough
Open

feat: HitTestBehavior for GameWidget#3815
spydon wants to merge 8 commits intomainfrom
fix/events-should-passthrough

Conversation

@spydon
Copy link
Member

@spydon spydon commented Feb 19, 2026

Description

This adds the ability for Flutter widgets to receive events when they are underneath a GameWidget, for example in a Stack.

Checklist

  • I have followed the Contributor Guide when preparing my PR.
  • I have updated/added tests for ALL new/updated/fixed functionality.
  • I have updated/added relevant documentation in docs and added dartdoc comments with ///.
  • I have updated/added relevant examples in examples or docs.

Breaking Change?

  • Yes, this PR is a breaking change.
  • No, this PR is not a breaking change.

Related Issues

GameWidget previously blocked all pointer events from reaching Flutter
widgets behind it, even when transparent and without input handling.

- Replace ColoredBox with DecoratedBox to avoid opaque hit testing
- Set MouseRegion opaque to false since it only tracks cursor changes
- Change RawGestureDetector to HitTestBehavior.deferToChild so it
  only intercepts events when a game component reports a hit
- Add GameRenderBox.hitTestSelf that delegates to Game
- Add Game.containsEventHandlerAt with FlameGame override that checks
  componentsAtPoint for event callback mixins (TapCallbacks, etc.)

Events now pass through empty game space to widgets behind the
GameWidget, while still being intercepted by game components that
have event handling mixins.
…ivery

The hit test in containsEventHandlerAt now caches the full tree
traversal so the immediate event delivery can replay it, reducing
redundant componentsAtPoint calls from 3 to 2 per tap.
…ivery

The hit test in containsEventHandlerAt now caches the full tree
traversal so the immediate event delivery can replay it, reducing
redundant componentsAtPoint calls from 3 to 2 per tap. Uses a
position-keyed map to support concurrent multitouch correctly.

# Conflicts:
#	packages/flame/lib/src/game/flame_game.dart
Benchmarking showed the cache added complexity without measurable
performance benefit. containsEventHandlerAt now simply uses
super.componentsAtPoint to check for event handlers at a position.
Adds HitTestBehavior parameter (default opaque) so users can opt into
event passthrough with deferToChild or translucent. Includes tests for
all three behaviors.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

Comments