chore!: Remove deprecated old event classes with replacements

doc/flame/inputs/gesture_input.md

@@ -24,33 +24,6 @@ Detectors will be deprecated in the future. Prefer `Callbacks` instead.
 ```
 
 ```text
-- TapDetector
-  - onTap
-  - onTapCancel
-  - onTapDown
-  - onLongTapDown
-  - onTapUp
-
-- SecondaryTapDetector
-  - onSecondaryTapDown
-  - onSecondaryTapUp
-  - onSecondaryTapCancel
-
-- TertiaryTapDetector
-  - onTertiaryTapDown
-  - onTertiaryTapUp
-  - onTertiaryTapCancel
-
-- DoubleTapDetector
-  - onDoubleTap
-
-- LongPressDetector
-  - onLongPress
-  - onLongPressStart
-  - onLongPressMoveUpdate
-  - onLongPressUp
-  - onLongPressEnd
-
 - VerticalDragDetector
   - onVerticalDragDown
   - onVerticalDragStart
@@ -209,23 +182,25 @@ The position where the event occurred relative to the `GameWidget` position and
 ## Example
 
 ```dart
-class MyGame extends FlameGame with TapDetector {
+class MyGame extends FlameGame with MultiTouchTapDetector {
   // Other methods omitted
 
   @override
-  bool onTapDown(TapDownInfo info) {
-    print("Player tap down on ${info.eventPosition.widget}");
-    return true;
+  void onTapDown(int pointerId, TapDownInfo info) {
+    print('Player tap down on ${info.eventPosition.widget}');
   }
 
   @override
-  bool onTapUp(TapUpInfo info) {
-    print("Player tap up on ${info.eventPosition.widget}");
-    return true;
+  void onTapUp(int pointerId, TapUpInfo info) {
+    print('Player tap up on ${info.eventPosition.widget}');
   }
 }
 ```
 
+Note that there is no single-pointer tap detector at the game level; for that, use the component
+level [`TapCallbacks`](tap_events.md) instead, which `FlameGame` can mix in directly since it is
+itself a `Component`.
+
 You can also check more complete examples in the
 [input examples directory](https://github.com/flame-engine/flame/tree/main/examples/lib/stories/input/).
 

doc/flame/migration.md

@@ -7,6 +7,52 @@ major versions of Flame, together with the steps required to migrate your code.
 ## Migrating from v1.38.0 to v2.0.0
 
 
+### Deprecated tap and long press game detectors removed
+
+The game-level detector mixins that were deprecated in v1.38.0 have now been removed, together with
+the event classes that only they used:
+
+| Removed | Use instead |
+| --- | --- |
+| `TapDetector` | `TapCallbacks` |
+| `SecondaryTapDetector` | `SecondaryTapCallbacks` |
+| `TertiaryTapDetector` | `TertiaryTapCallbacks` |
+| `DoubleTapDetector` | `DoubleTapCallbacks` |
+| `LongPressDetector` | `LongPressCallbacks` |
+| `LongPressStartInfo` | `LongPressStartEvent` |
+| `LongPressMoveUpdateInfo` | `LongPressMoveUpdateEvent` |
+| `LongPressEndInfo` | `LongPressEndEvent` |
+
+The replacements are mixed into a component rather than into the game, and each callback takes a
+single event object:
+
+```dart
+// Before
+class MyGame extends FlameGame with TapDetector {
+  @override
+  void onTapDown(TapDownInfo info) {
+    final position = info.eventPosition.widget;
+  }
+}
+
+// After
+class MyComponent extends PositionComponent with TapCallbacks {
+  @override
+  void onTapDown(TapDownEvent event) {
+    final position = event.localPosition;
+  }
+}
+```
+
+Note that a component only receives events that occur on top of it, as determined by
+`containsLocalPoint()`, whereas the old game-level detectors received every event on the game
+surface. To keep the old whole-screen behavior, add the mixin to your `FlameGame` subclass directly
+— `FlameGame` is itself a `Component`.
+
+See [Tap Events](inputs/tap_events.md) and [Long Press Events](inputs/long_press_events.md) for the
+full replacement APIs.
+
+
 ### `onDragCancel` no longer delegates to `onDragEnd`
 
 `DragCallbacks.onDragCancel` used to convert the cancellation into an `onDragEnd` event by default,

packages/flame/lib/events.dart

@@ -80,16 +80,12 @@ export 'src/game/mixins/keyboard.dart'
     show HasKeyboardHandlerComponents, KeyboardEvents;
 export 'src/gestures/detectors.dart'
     show
-        DoubleTapDetector,
         ForcePressDetector,
         HorizontalDragDetector,
-        LongPressDetector,
         MouseMovementDetector,
         PanDetector,
         ScaleDetector,
         ScrollDetector,
-        TertiaryTapDetector,
-        SecondaryTapDetector,
         VerticalDragDetector;
 export 'src/gestures/events.dart'
     show
@@ -98,9 +94,6 @@ export 'src/gestures/events.dart'
         DragStartInfo,
         DragUpdateInfo,
         ForcePressInfo,
-        LongPressEndInfo,
-        LongPressMoveUpdateInfo,
-        LongPressStartInfo,
         PointerHoverInfo,
         PointerScrollInfo,
         PositionInfo,

packages/flame/lib/src/game/flame_game.dart

@@ -245,15 +245,9 @@ class FlameGame<W extends World> extends ComponentTreeRoot
 
   @override
   bool containsEventHandlerAt(Vector2 position) {
-    // Deprecated game-level detector mixins handle events for the entire
-    // game surface, so any in-bounds point is a hit.
-    // ignore: deprecated_member_use_from_same_package
-    if (this is TapDetector ||
-        this is SecondaryTapDetector ||
-        this is TertiaryTapDetector ||
-        this is DoubleTapDetector ||
-        this is LongPressDetector ||
-        this is VerticalDragDetector ||
+    // Game-level detector mixins handle events for the entire game surface,
+    // so any in-bounds point is a hit.
+    if (this is VerticalDragDetector ||
         this is HorizontalDragDetector ||
         this is ForcePressDetector ||
         this is PanDetector ||

packages/flame/lib/src/game/game_widget/gesture_detector_builder.dart

@@ -1,5 +1,4 @@
 import 'package:flame/events.dart';
-import 'package:flame/input.dart';
 import 'package:flame/src/game/game.dart';
 import 'package:flutter/gestures.dart';
 import 'package:flutter/widgets.dart';
@@ -45,58 +44,6 @@ class GestureDetectorBuilder {
   }
 
   void initializeGestures(Game game) {
-    // support for deprecated detectors
-    // ignore: deprecated_member_use_from_same_package
-    if (game is TapDetector ||
-        game is SecondaryTapDetector ||
-        game is TertiaryTapDetector) {
-      register(
-        TapGestureRecognizer.new,
-        (TapGestureRecognizer instance) {
-          // support for deprecated detectors
-          // ignore: deprecated_member_use_from_same_package
-          if (game is TapDetector) {
-            instance.onTap = game.onTap;
-            instance.onTapCancel = game.onTapCancel;
-            instance.onTapUp = game.handleTapUp;
-            instance.onTapDown = game.handleTapDown;
-          }
-          if (game is SecondaryTapDetector) {
-            instance.onSecondaryTapCancel = game.onSecondaryTapCancel;
-            instance.onSecondaryTapUp = game.handleSecondaryTapUp;
-            instance.onSecondaryTapDown = game.handleSecondaryTapDown;
-          }
-          if (game is TertiaryTapDetector) {
-            instance.onTertiaryTapCancel = game.onTertiaryTapCancel;
-            instance.onTertiaryTapUp = game.handleTertiaryTapUp;
-            instance.onTertiaryTapDown = game.handleTertiaryTapDown;
-          }
-        },
-      );
-    }
-    if (game is DoubleTapDetector) {
-      register(
-        DoubleTapGestureRecognizer.new,
-        (DoubleTapGestureRecognizer instance) {
-          instance.onDoubleTap = game.onDoubleTap;
-          instance.onDoubleTapDown = game.handleDoubleTapDown;
-          instance.onDoubleTapCancel = game.onDoubleTapCancel;
-        },
-      );
-    }
-    if (game is LongPressDetector) {
-      register(
-        LongPressGestureRecognizer.new,
-        (LongPressGestureRecognizer instance) {
-          instance.onLongPress = game.onLongPress;
-          instance.onLongPressStart = game.handleLongPressStart;
-          instance.onLongPressMoveUpdate = game.handleLongPressMoveUpdate;
-          instance.onLongPressEnd = game.handleLongPressEnd;
-          instance.onLongPressUp = game.onLongPressUp;
-          instance.onLongPressCancel = game.onLongPressCancel;
-        },
-      );
-    }
     if (game is VerticalDragDetector) {
       register(
         VerticalDragGestureRecognizer.new,

packages/flame/lib/src/gestures/detectors.dart

@@ -2,85 +2,6 @@ import 'package:flame/src/game/game.dart';
 import 'package:flame/src/gestures/events.dart';
 import 'package:flutter/gestures.dart';
 
-@Deprecated('Use TapCallbacks instead')
-mixin TapDetector on Game {
-  void onTap() {}
-  void onTapCancel() {}
-  void onTapDown(TapDownInfo info) {}
-  void onTapUp(TapUpInfo info) {}
-
-  void handleTapUp(TapUpDetails details) {
-    onTapUp(TapUpInfo.fromDetails(this, details));
-  }
-
-  void handleTapDown(TapDownDetails details) {
-    onTapDown(TapDownInfo.fromDetails(this, details));
-  }
-}
-
-@Deprecated('Use SecondaryTapCallbacks instead')
-mixin SecondaryTapDetector on Game {
-  void onSecondaryTapDown(TapDownInfo info) {}
-  void onSecondaryTapUp(TapUpInfo info) {}
-  void onSecondaryTapCancel() {}
-
-  void handleSecondaryTapUp(TapUpDetails details) {
-    onSecondaryTapUp(TapUpInfo.fromDetails(this, details));
-  }
-
-  void handleSecondaryTapDown(TapDownDetails details) {
-    onSecondaryTapDown(TapDownInfo.fromDetails(this, details));
-  }
-}
-
-@Deprecated('Use TertiaryTapCallbacks instead')
-mixin TertiaryTapDetector on Game {
-  void onTertiaryTapDown(TapDownInfo info) {}
-  void onTertiaryTapUp(TapUpInfo info) {}
-  void onTertiaryTapCancel() {}
-
-  void handleTertiaryTapUp(TapUpDetails details) {
-    onTertiaryTapUp(TapUpInfo.fromDetails(this, details));
-  }
-
-  void handleTertiaryTapDown(TapDownDetails details) {
-    onTertiaryTapDown(TapDownInfo.fromDetails(this, details));
-  }
-}
-
-@Deprecated('Use DoubleTapCallbacks instead')
-mixin DoubleTapDetector on Game {
-  void onDoubleTap() {}
-  void onDoubleTapCancel() {}
-  void onDoubleTapDown(TapDownInfo info) {}
-
-  void handleDoubleTapDown(TapDownDetails details) {
-    onDoubleTapDown(TapDownInfo.fromDetails(this, details));
-  }
-}
-
-@Deprecated('Use LongPressCallbacks instead')
-mixin LongPressDetector on Game {
-  void onLongPress() {}
-  void onLongPressStart(LongPressStartInfo info) {}
-  void onLongPressMoveUpdate(LongPressMoveUpdateInfo info) {}
-  void onLongPressUp() {}
-  void onLongPressEnd(LongPressEndInfo info) {}
-  void onLongPressCancel() {}
-
-  void handleLongPressStart(LongPressStartDetails details) {
-    onLongPressStart(LongPressStartInfo.fromDetails(this, details));
-  }
-
-  void handleLongPressMoveUpdate(LongPressMoveUpdateDetails details) {
-    onLongPressMoveUpdate(LongPressMoveUpdateInfo.fromDetails(this, details));
-  }
-
-  void handleLongPressEnd(LongPressEndDetails details) {
-    onLongPressEnd(LongPressEndInfo.fromDetails(this, details));
-  }
-}
-
 mixin VerticalDragDetector on Game {
   void onVerticalDragDown(DragDownInfo info) {}
   void onVerticalDragStart(DragStartInfo info) {}

packages/flame/lib/src/gestures/events.dart

@@ -75,29 +75,6 @@ class TapUpInfo extends PositionInfo<TapUpDetails> {
   ) : super(game, raw.globalPosition, raw);
 }
 
-class LongPressStartInfo extends PositionInfo<LongPressStartDetails> {
-  LongPressStartInfo.fromDetails(
-    Game game,
-    LongPressStartDetails raw,
-  ) : super(game, raw.globalPosition, raw);
-}
-
-class LongPressEndInfo extends PositionInfo<LongPressEndDetails> {
-  late final Vector2 velocity = raw.velocity.pixelsPerSecond.toVector2();
-
-  LongPressEndInfo.fromDetails(
-    Game game,
-    LongPressEndDetails raw,
-  ) : super(game, raw.globalPosition, raw);
-}
-
-class LongPressMoveUpdateInfo extends PositionInfo<LongPressMoveUpdateDetails> {
-  LongPressMoveUpdateInfo.fromDetails(
-    Game game,
-    LongPressMoveUpdateDetails raw,
-  ) : super(game, raw.globalPosition, raw);
-}
-
 class ForcePressInfo extends PositionInfo<ForcePressDetails> {
   late final double pressure = raw.pressure;