feat: Add support to use convex/concave Path shapes in PolygonComponent, PolygonHitbox and Polygon by adario · Pull Request #4048 · flame-engine/flame

adario · 2026-09-15T13:15:37Z

Description

The purpose of this PR is to add support for using both convex and concave Path shapes when creating PolygonComponent, PolygonHitbox and Polygon objects: the contours of a Path object are sampled and converted to a list of polygon vertices. Support for concave polygons, described below, is available in PolygonRayIntersection.

A complete testbed for all changes is available here; the relevant examples have been ported here too.

The changes add to and introduce a few extensions:

PathExtension on Path gets contours, walkContours, walkContourAt, resizeTo, toOrigin and centered
PathMetricExtension on PathMetric has walkContour
PathMetricListExtension on List<PathMetric> has contoursLength
OffsetListExtension on List<Offset> has vertices and rectangle
RectExtension.fromOffsets and Aabb2Extension.fromVertices create the bounds of a list of offsets and of vertices

The walkContours, walkContourAt and walkContour methods extract the vertex lists from the contours of a Path:

The contour is walked with strides that follow how much it bends, so straight stretches cost a few lookups and tight curves are followed below the step. The granularity parameter is that step, which defaults to 1.0.
The corners between straight lines are placed exactly, and the points where the contour reaches its bounds are kept, so that the polygon has the size of the contour.
The samples that are not needed to stay within the tolerance are removed, which defaults to half of the granularity. This also works across the point where a closed contour starts and ends.

Direct construction from Path objects is available via:

All three take the index of the contour to use, the first one by default, and the granularity, and only walk that contour of the path.

As long as the Path contours represent valid polygons, the PolygonRayIntersection mixin now supports both convex and concave polygons. Whether the ray starts inside of the polygon is decided by the parity of the edges that it crosses, instead of their absolute quantity. The hits and the crossings come from the same test of which side of the ray each vertex is on, which both edges of a vertex share, so a ray through or next to a vertex is not misjudged and can not slip through between two edges.

isSolid is now an argument of the ShapeComponent constructor, which the polygon, rectangle and circle components and their hitboxes pass on instead of assigning it in their constructor bodies.

The shape components and collision detection pages of the documentation describe the new constructors, and no longer say that polygon hitboxes have to be convex.

In terms of performance, @spydon was kind enough to provide the new path_collision and path_contour benchmarks (thank you very much, Lukas.) There is also a new ray_intersection benchmark for rays against concave and convex contour hitboxes.

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

Closes #4040

…ours.

…ath.

…ection.

… property.

…ent`.

…arameter.

…All();

… lists.

…tainment.

…n polygons Reports vertex counts and sampling error of walkContours, per-ray intersection cost, agreement between the crossings heuristic, containment, and odd parity for the inside-hitbox check on concave shapes, the effect of simplifying the sampled contour, and polygon-polygon intersection cost.

…yline.

chore: Add benchmark comparing Path contour hitboxes with hand-written polygons

…ctor.

…haviour.

Runs the collision detection system with a hitbox sampled from a Path contour against circles, rectangles, hand-written polygons, and itself, next to the same scenes with a hand-written polygon of the same shape. The polygon scenes also compile on main, so the two can be compared by running the file on both branches.

…cations from segment intersection ShapeHitbox.intersections now passes the overlap of the two AABBs to the intersection systems, which already knew how to filter edges by a rect but never received one. LineSegment.intersections rejects segment pairs whose bounding boxes do not overlap before doing any math and no longer allocates Line objects or result lists for misses.

chore: Add a collision benchmark for Path contour hitboxes

perf: Only test polygon edges inside the hitbox overlap and drop allocations from segment intersection

luanpotter

Overall, LGTM, nice addition! Left a few comments and questions, but nothing blocking

adario · 2026-09-21T13:20:59Z

Overall, LGTM, nice addition! Left a few comments and questions, but nothing blocking

Thank you very much, Luan. :-)

This reverts commit 5e0386e, reversing changes made to f716480.

… edge

…tion and its benchmark

adario · 2026-09-21T17:17:22Z

Apologies for the latest erroneous merge and subsequent revert... blush

…ests

…path

spydon

Thanks for this massive undertaking, this will be really useful!

@spydon

The `PathComponent` class [introduced](https://github.com/flame-engine/flame/pull/4048/changes#diff-0c50838cfe31110765e9616e8ae15ab9cbbd3818310d5376acf74f9bce14ea4e) in PR #4048 is moved from `examples/lib/commons` into `lib/src/geometry` in the core package, on suggestion from @spydon, and it gets a hitbox counterpart, `PathHitbox`, so that the pair mirrors `PolygonComponent` and `PolygonHitbox`. `PathComponent` renders a `Path` and follows each of its closed contours with a polygon, in the same way as `PolygonComponent.fromPath` follows a single contour. The polygons are kept as vertices, not as child components, and they decide whether a point is inside of the component. The constructor takes `sampling` and `tolerance` to control how the contours are followed, and `filter` to leave out the polygons that lie inside of the largest one, like the eyes of a face. `PathHitbox` is a `PathComponent` with `ShapeHitbox`, and it is a single hitbox: it collides, contains points and is hit by rays as a whole, whichever of its polygons is involved, and it reports one collision to its parent even when several polygons touch the other hitbox. It computes its aabb from all the polygons, a ray hits the nearest polygon, and it takes the `collisionType` like the other hitboxes. `PathPathIntersections`, `PathPolygonIntersections` and `CirclePathIntersections` are added to the intersection systems. The affected examples are updated accordingly, with a `CollidablePathComponent` in the examples that pairs a `PathComponent` with a `PathHitbox`. There is documentation for both classes in `shape_components.md` and `collision_detection.md`, and tests for `PathComponent` and `PathHitbox`. --------- Co-authored-by: Lukas Klingsbo <lukas.klingsbo@gmail.com> Co-authored-by: Lukas Klingsbo <me@lukas.fyi>

adario and others added 30 commits September 6, 2026 17:39

feat: Added Path/Offset extensions and Polygon* support for Path cont…

7a5de02

…ours.

feat: Added resizeTo extension method on class Path.

14af9e8

feat: Added toOrigin and centered extension properties on class P…

96faa64

…ath.

Merge branch 'main' into feat/path-shapes

da49504

Merge branch 'main' into feat/path-shapes

55f0f74

fix: Removed unnecessary import in the Path extension.

d4dba22

refactor: Rewrite closest segment lookup in PolygonRayIntersection.

29755b2

refactor: Add crossings (default) and containment in PolygonRayInters…

9771c2b

…ection.

test: Add batch tests for the PolygonRayIntersection.useContainment…

d2a5132

… property.

test: Tweaked the batch tests for `PolygonRayIntersection.useContainm…

c52fa29

…ent`.

Merge branch 'main' into feat/path-shapes

72f59cc

refactor!: Change useContainment from property to rayIntersection() p…

854713c

…arameter.

refactor: Propagate useContainment parameter to raycast() and raycast…

accef2d

…All();

refactor: Add extensions to extract Path contours as filtered Vector2…

bb86b11

… lists.

refactor: Add missing contour parameters in Polygon/Component/Hitbox.

4bf7ef1

test: Add benchmark for PolygonRayIntersection with crossings and con…

5b51ea2

…tainment.

refactor!: Rewrite path contour walking: use point step, simplify pol…

3390095

…yline.

Merge pull request #2 from adario/chore/path-contour-benchmark

f586372

chore: Add benchmark comparing Path contour hitboxes with hand-written polygons

fix: Restore build for path_contour_benchmark after the previous refa…

9231442

…ctor.

chore: Clean up style issues in the Contour extension on PathMetric.

f96f7b3

refactor: Switch to odd counting in the ray intersection crossings be…

1cb923b

…haviour.

feat: Add rectangle extension on List<Offset>.

d0616b2

benchmark: Add a few paths for the path_contour_shapes benchmark.

6ab42b2

benchmark: Add a couple of test paths for the contours benchmark.

8d791bf

Merge pull request #3 from adario/benchmark/path-collision

501d53d

chore: Add a collision benchmark for Path contour hitboxes

Merge pull request #4 from adario/perf/narrow-phase-overlap-path

ee2be95

perf: Only test polygon edges inside the hitbox overlap and drop allocations from segment intersection

Merge branch 'main' into feat/path-shapes

6ecbca7