docs: Deprecate TapDetector in favour of TapCallbacks

doc/bridge_packages/flame_spine/flame_spine.md

@@ -21,7 +21,7 @@ void main() async {
   runApp(const GameWidget.controlled(gameFactory: SpineExample.new));
 }
 
-class FlameSpineExample extends FlameGame with TapDetector {
+class FlameSpineExample extends FlameGame {
  late final SpineComponent spineboy;
 
  @override

doc/flame/examples/lib/ember.dart

@@ -35,5 +35,19 @@ class EmberPlayer extends SpriteAnimationComponent with TapCallbacks {
   }
 
   @override
-  void onTapUp([TapUpEvent? event]) => _onTap?.call(this);
+  void onTapDown(TapDownEvent event) {
+    if (_onTap == null) {
+      event.continuePropagation = true;
+    }
+  }
+
+  @override
+  void onTapUp(TapUpEvent event) {
+    final onTap = _onTap;
+    if (onTap == null) {
+      event.continuePropagation = true;
+    } else {
+      onTap.call(this);
+    }
+  }
 }

doc/flame/examples/lib/ray_trace.dart

@@ -9,7 +9,7 @@ import 'package:flame/palette.dart';
 import 'package:flutter/material.dart';
 
 class RayTraceExample extends FlameGame
-    with HasCollisionDetection, TapDetector {
+    with HasCollisionDetection, TapCallbacks {
   Paint paint = Paint()..color = Colors.red.withOpacity(0.6);
   bool isClicked = false;
 
@@ -79,8 +79,7 @@ class RayTraceExample extends FlameGame
   }
 
   @override
-  void onTap() {
-    super.onTap();
+  void onTapUp(TapUpEvent event) {
     if (!isClicked) {
       isClicked = true;
       return;

doc/flame/examples/lib/remove_effect.dart

@@ -4,7 +4,7 @@ import 'package:flame/effects.dart';
 import 'package:flame/events.dart';
 import 'package:flame/game.dart';
 
-class RemoveEffectGame extends FlameGame with TapDetector {
+class RemoveEffectGame extends FlameGame with TapCallbacks {
   static const double delayTime = 3;
   late EmberPlayer ember;
   late TextComponent textComponent;
@@ -22,7 +22,7 @@ class RemoveEffectGame extends FlameGame with TapDetector {
   }
 
   @override
-  void onTap() {
+  void onTapUp(TapUpEvent event) {
     if (children.contains(ember)) {
       ember.add(effect);
     } else {

packages/flame/lib/src/events/component_mixins/tap_callbacks.dart

@@ -11,7 +11,8 @@ import 'package:meta/meta.dart';
 /// [containsLocalPoint] method -- the component will only be considered
 /// "tapped" if the point where the tap has occurred is inside the component.
 ///
-/// This mixin is the replacement of the Tappable mixin.
+/// Note that FlameGame _is_ a [Component] and does implement
+/// [containsLocalPoint]; so this can be used at the game level.
 mixin TapCallbacks on Component {
   void onTapDown(TapDownEvent event) {}
   void onLongTapDown(TapDownEvent event) {}

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

@@ -2,7 +2,7 @@ import 'package:flame/src/game/game.dart';
 import 'package:flame/src/gestures/events.dart';
 import 'package:flutter/gestures.dart';
 
-// Basic touch detectors
+@Deprecated('Use TapCallbacks instead')
 mixin TapDetector on Game {
   void onTap() {}
   void onTapCancel() {}