feat: Add collision completed listener

doc/flame/collision_detection.md

@@ -120,6 +120,41 @@ other way around. If there are no intersections with the edges on a solid hitbox
 position is instead returned.
 
 
+### Collision order
+
+If a `PositionComponent` collides with more than one other object within a given time step, then
+the `onCollision` callbacks will be called in an essentially random order.  In some cases this can
+be a problem, such as in a bouncing ball game where the trajectory of the ball can differ depending
+on which other object was hit first.  To help resolve this the `collisionsCompleted` listener can be
+used - this triggers at the end of the collision detection process.
+
+An example of how this might be used is to add a local variable in your `PositionComponent` to save
+the other components with which this one is colliding:
+`List<PositionComponent> collisionComponents = [];`.  The `onCollision` callback is then used to
+save all the other `PositionComponent`s to this list:
+
+```dart
+@override
+void onCollision(Set<Vector2> intersectionPoints, PositionComponent other) {
+  collisionComponents.add(other);
+  super.onCollision(intersectionPoints, other);
+}
+
+```
+
+Finally, one adds a listener to the `onLoad` method of the `PositionComponent` to call a routine
+which will resolve how the collisions should be dealt with:
+
+```dart
+(game as HasCollisionDetection).collisionDetection.collisionsCompleted.
+                                addListener(() {
+  resolveCollisions();
+});
+```
+
+The list `collisionComponents` would need to be cleared in each call to `update`.
+
+
 ## ShapeHitbox
 
 The `ShapeHitbox`s are normal components, so you add them to the component that you want to add

packages/flame/lib/src/collisions/collision_detection.dart

@@ -1,6 +1,7 @@
 import 'package:flame/collisions.dart';
 import 'package:flame/components.dart';
 import 'package:flame/geometry.dart';
+import 'package:flutter/material.dart';
 
 /// [CollisionDetection] is the foundation of the collision detection system in
 /// Flame.
@@ -13,6 +14,7 @@ abstract class CollisionDetection<T extends Hitbox<T>,
 
   List<T> get items => broadphase.items;
   final _lastPotentials = <CollisionProspect<T>>[];
+  final collisionsCompleted = CollisionDetectionCompletionNotifier();
 
   CollisionDetection({required this.broadphase});
 
@@ -62,6 +64,9 @@ abstract class CollisionDetection<T extends Hitbox<T>,
       }
     }
     _updateLastPotentials(potentials);
+
+    // Let any listeners know that the collision detection step has completed
+    collisionsCompleted.notifyListeners();
   }
 
   final _lastPotentialsPool = <CollisionProspect<T>>[];
@@ -161,3 +166,24 @@ abstract class CollisionDetection<T extends Hitbox<T>,
     List<RaycastResult<T>>? out,
   });
 }
+
+/// Add a basic class which implements a Listener.
+class CollisionDetectionCompletionNotifier implements Listenable {
+  final List<VoidCallback> _listenFunctions = [];
+
+  @override
+  void addListener(VoidCallback listener) {
+    _listenFunctions.add(listener);
+  }
+
+  @override
+  void removeListener(VoidCallback listener) {
+    _listenFunctions.remove(listener);
+  }
+
+  void notifyListeners() {
+    for (final callback in _listenFunctions) {
+      callback();
+    }
+  }
+}