Skip to content

feat!: Return a list instead of a set from the collision detection methods - #4003

Merged
spydon merged 2 commits into
mainfrom
feat/collision-detection-lists
Aug 16, 2026
Merged

feat!: Return a list instead of a set from the collision detection methods#4003
spydon merged 2 commits into
mainfrom
feat/collision-detection-lists

Conversation

@spydon

@spydon spydon commented Aug 16, 2026

Copy link
Copy Markdown
Member

Description

The collision detection system previously passed the intersection points around as a
Set<Vector2>, which meant that every collision check in the hot loop had to hash
Vector2s and allocate hash sets. This PR changes all of these APIs to use
List<Vector2> instead.

The returned points are still guaranteed to be unique: the polygon and circle-polygon
intersection accumulation now deduplicates with a linear contains check (the point
lists are tiny, so this is cheaper than hashing), and tangent circles now explicitly
return a single point instead of relying on the set to collapse the two identical
solutions.

Changed APIs (all from Set<Vector2> to List<Vector2>):

  • CollisionCallbacks.onCollision/onCollisionStart and the corresponding methods on
    GenericCollisionCallbacks, ShapeHitbox and CollisionPassthrough, as well as the
    CollisionCallback typedef.
  • CollisionDetection.intersections, handleCollisionStart and handleCollision
    (and the StandardCollisionDetection overrides).
  • Hitbox.intersections and ShapeHitbox.intersections.
  • Intersections.intersect/unorderedIntersect and the top-level intersections
    function in the geometry package.
  • The experimental Rectangle.intersections.

Benchmarked the accumulation strategies against each other with the real intersection
workloads (200k iterations per case): the list version is roughly 2x faster for
circle-circle intersections, faster for overlapping axis-aligned rectangles (which
produce collinear duplicate candidates), and equal within noise for tilted polygons.

flame_behaviors and all examples, docs and tutorials have been updated accordingly.

Migration: change the Set<Vector2> intersectionPoints parameter type to
List<Vector2> in onCollision/onCollisionStart overrides (and in custom
CollisionDetection/Hitbox implementations).

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.

Migration instructions

Replace Set<Vector2> with List<Vector2> in your onCollision and onCollisionStart
overrides and collision callbacks:

@override
void onCollision(List<Vector2> intersectionPoints, PositionComponent other) {
  // ...
}

The same applies to custom CollisionDetection, Hitbox and Intersections
implementations, which now return List<Vector2> from their intersection methods.
The points in the list are still unique.

Related Issues

Closes #4001

@luanpotter luanpotter left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not happy, but I accept

@spydon
spydon merged commit 698f261 into main Aug 16, 2026
8 checks passed
@spydon
spydon deleted the feat/collision-detection-lists branch August 16, 2026 16:49
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.

Return a list instead of a set from the collision detection methods.

2 participants