feat: Promote PathComponent to a standard component by adario · Pull Request #4050 · flame-engine/flame

adario · 2026-09-19T18:18:06Z

Description

The PathComponent class introduced in PR #4048 was moved from examples/lib/commons into lib/src/geometry in the core package, on suggestion from @spydon; all affected examples have been updated accordingly. There's also documentation and a test for PathComponent.

I have added the missing granularity parameter in the constructor, as well as the hitboxesPriority parameter. For convenience, I've also added the renderShape parameter (still true by default).

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

adario · 2026-09-19T18:31:17Z

Marking as draft since it can't be stacked properly.

Copilot

Copilot review overview

🟡 Changes recommended

Critical benchmark and ray-intersection regressions, plus unresolved path-contour handling issues, block approval.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 2 · 2

Open (4)

Mount benchmark hitboxes under a PositionComponent · New
Use half-open edge tests for vertex ray crossings · New
Order contours by area rather than bounding-box diagonal · New
Reject open contours before constructing PolygonHitbox · New

What changed in this PR

Promotes PathComponent into Flame’s core geometry API and adds path-to-polygon conversion, concave ray intersections, and related ecosystem updates.

Changes:

Adds path sampling, transformations, and fromPath constructors.
Extends shape and hitbox APIs with isSolid support.
Updates tests, examples, documentation, reusable fixtures, and benchmarks.

File	Reviewed change / note
`packages/flame/test/geometry/polygon_ray_intersection_test.dart`	Adds convex, concave, and vertex ray-intersection tests.
`packages/flame/test/geometry/polygon_component_from_path_test.dart`	Tests polygon construction from paths.
`packages/flame/test/geometry/path_component_test.dart`	Tests `PathComponent` sizing and filtering.
`packages/flame/test/extensions/rect_test.dart`	Tests offset bounds.
`packages/flame/test/extensions/path_test.dart`	Tests path sampling and transformations.
`packages/flame/test/extensions/aabb_test.dart`	Tests vertex AABB conversion.
`packages/flame/test/experimental/geometry/shapes/polygon_test.dart`	Tests experimental polygon path conversion.
`packages/flame/test/collisions/screen_hibox_test.dart`	Tests path hitbox containment.
`packages/flame/lib/src/geometry/shape_intersections.dart`	Updates polygon intersection documentation.
`packages/flame/lib/src/geometry/shape_component.dart`	Adds constructor-level `isSolid` support.
`packages/flame/lib/src/geometry/rectangle_component.dart`	Forwards `isSolid`.
`packages/flame/lib/src/geometry/polygon_ray_intersection.dart`	Adds concave ray parity handling. Critical, 1 vote: vertex crossings can be double-counted, regressing corner raycasts.
`packages/flame/lib/src/geometry/polygon_component.dart`	Adds `fromPath` and `isSolid`. Moderate, 1 vote: open contours can form unintended triangles or fail.
`packages/flame/lib/src/geometry/path_component.dart`	Adds the standard path component. Moderate: open contours can fail hitbox construction (2 votes); contour ordering uses diagonal length instead of area (2 votes); AABB filtering can remove valid concave contours (1 vote); nested contours are incompletely compared (1 vote).
`packages/flame/lib/src/geometry/circle_component.dart`	Forwards `isSolid`.
`packages/flame/lib/src/extensions/rect.dart`	Adds offset-bound construction.
`packages/flame/lib/src/extensions/path.dart`	Adds path utilities. Nit, 1 vote: unused import creates an unnecessary barrel cycle.
`packages/flame/lib/src/extensions/offset.dart`	Adds offset-list conversions.
`packages/flame/lib/src/extensions/aabb.dart`	Adds vertex-bound construction.
`packages/flame/lib/src/experimental/geometry/shapes/polygon.dart`	Adds `Polygon.fromPath`. Moderate, 1 vote: open contours are silently closed or can assert.
`packages/flame/lib/src/collisions/hitboxes/rectangle_hitbox.dart`	Forwards `isSolid`.
`packages/flame/lib/src/collisions/hitboxes/polygon_hitbox.dart`	Adds path construction support.
`packages/flame/lib/src/collisions/hitboxes/circle_hitbox.dart`	Forwards `isSolid`.
`packages/flame/lib/geometry.dart`	Exports `PathComponent`.
`packages/flame/lib/components.dart`	Exports `PathComponent`.
`packages/flame/benchmark/README.md`	Documents new benchmarks.
`packages/flame/benchmark/ray_intersection_benchmark.dart`	Adds ray-intersection benchmarks. Critical, 1 vote: hitboxes mounted directly under `FlameGame` fail because a `PositionComponent` ancestor is required.
`packages/flame/benchmark/path_contour_benchmark.dart`	Adds contour sampling benchmarks.
`packages/flame/benchmark/path_collision_benchmark.dart`	Adds path collision benchmarks.
`packages/flame/benchmark/main.dart`	Registers benchmarks.
`packages/flame_test/test/test_paths_test.dart`	Tests reusable path fixtures.
`packages/flame_test/lib/test_paths.dart`	Exposes reusable test paths.
`packages/flame_test/lib/src/test_paths.dart`	Defines reusable path fixtures.
`examples/pubspec.yaml`	Adds path-related dependencies.
`examples/lib/stories/input/gesture_hitboxes_example.dart`	Demonstrates path gesture hitboxes. Moderate, 1 vote: the path is sampled redundantly by a discarded hitbox and `PathComponent`.
`examples/lib/stories/experimental/shapes.dart`	Demonstrates path-derived experimental shapes.
`examples/lib/stories/collision_detection/raytrace_example.dart`	Adds path raytrace shapes.
`examples/lib/stories/collision_detection/rays_in_shape_example.dart`	Adds interactive path ray tests.
`examples/lib/stories/collision_detection/raycast_max_distance_example.dart`	Adds path raycast targets.
`examples/lib/stories/collision_detection/raycast_light_example.dart`	Adds path lighting targets.
`examples/lib/stories/collision_detection/raycast_example.dart`	Adds path raycast targets.
`examples/lib/stories/collision_detection/multiple_shapes_example.dart`	Adds collidable path shapes.
`examples/lib/commons/rounded_rect_component.dart`	Adds rounded rectangle rendering.
`examples/lib/commons/paths.dart`	Adds shared path helpers.
`examples/lib/commons/paths_creation_mixin.dart`	Adds reusable path creation behavior.
`doc/flame/components/shape_components.md`	Documents path-based shape components.
`doc/flame/collision_detection.md`	Documents concave polygon hitboxes.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

PathComponent now lives in src/geometry and it is exported by components.dart: all affected examples now import it from there.

…ructor.

The path_component_test uses the TestPaths to verify both dimensions match and hitboxes filtering.

From Copilot: path.contours includes open contours, and walkContourAt returns only the endpoints for a line. This unconditionally constructs a PolygonHitbox for every contour, while PolygonComponent requires at least three vertices, so a valid Path with an open contour fails when hitboxes load. Skip or reject non-polygon contours explicitly and document the requirement.

…pling'.

spydon · 2026-09-21T20:34:32Z

+  /// The default paint used to render hitboxes.
+  static Paint hitboxStroke = Paint()
+    ..color = const Color(0xffffffff)
+    ..style = .stroke;


We should follow the same standard for painting this as the other shape components, like PolygonComponent.

spydon · 2026-09-21T20:35:03Z

    required Path path,
+    this.sampling = 1.0,
+    this.tolerance,
+    this.hitboxesPriority,


This should not live here, the hitboxes should handle their own priority.

spydon · 2026-09-21T20:37:15Z

    super.key,
    super.paint,
    super.paintLayers,
+    bool renderShape = true,


This shouldn't be here, since it doesn't exist on PolygonComponent.

spydon · 2026-09-21T20:38:06Z

@@ -16,8 +15,11 @@
    with CollisionCallbacks, CollisionPassthrough {
  PathComponent({


Follow PolygonComponent to see which arguments that should exist on here, remember this is no longer an example helper when moved in here, so it needs to be consistent with the rest of the code.

spydon · 2026-09-21T20:38:27Z

    this.addHitboxes = false,
    this.loadHitboxes = true,
    this.renderHitboxes = false,
    this.filterHitboxes = true,
    this.hitboxesPaint,


Suggested change

spydon · 2026-09-21T20:41:02Z

-          ..renderShape = renderHitboxes,
-    ];
+  // Create a hitbox for each path contour with at least three vertices.
+  List<PolygonHitbox> _createHitboxes() {


The component should not create hitboxes for itself, we probably need a PathHitbox that can fill this up when added to it.

adario marked this pull request as ready for review September 19, 2026 18:26

adario marked this pull request as draft September 19, 2026 18:30

spydon requested a lite review from Copilot September 20, 2026 09:55

Copilot started reviewing on behalf of spydon September 20, 2026 09:55 View session

Copilot AI reviewed Sep 20, 2026

View reviewed changes

adario mentioned this pull request Sep 21, 2026

feat: Add support to use convex/concave Path shapes in PolygonComponent, PolygonHitbox and Polygon #4048

Merged

6 tasks

adario added 8 commits September 21, 2026 19:47

feat: Promote PathComponent to a standard component.

7604df2

PathComponent now lives in src/geometry and it is exported by components.dart: all affected examples now import it from there.

fix: Use white for the default hitboxStroke paint in PathComponent.

2b79442

refactor: Use PathComponent.hitboxStroke in the examples.

9ecc8f0

feat: Add granularity and hitboxesPriority to the PathComponent const…

73c5155

…ructor.

feat: Add renderShape parameter in the PathComponent constructor.

886b412

docs: Add documentation for PathComponent.

312e74b

chore: Add test for PathComponent.

a89df6d

The path_component_test uses the TestPaths to verify both dimensions match and hitboxes filtering.

spydon force-pushed the feat/path-component branch from 5e0386e to 6055c4f Compare September 21, 2026 17:48

adario added 2 commits September 21, 2026 20:13

refactor: Rename the 'granularity' parameter in PathComponent to 'sam…

24c69de

…pling'.

feat: Add tolerance parameter in the PathComponent constructor.

7001abe

adario marked this pull request as ready for review September 21, 2026 19:38

spydon reviewed Sep 21, 2026

View reviewed changes

Navigation Menu

Uh oh!

feat: Promote PathComponent to a standard component - #4050

feat: Promote PathComponent to a standard component#4050
adario wants to merge 10 commits into
flame-engine:mainfrom
adario:feat/path-component

adario commented Sep 19, 2026 •

edited

Loading

Uh oh!

adario commented Sep 19, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

spydon Sep 21, 2026

Uh oh!

spydon Sep 21, 2026

Uh oh!

spydon Sep 21, 2026

Uh oh!

spydon Sep 21, 2026

Uh oh!

spydon Sep 21, 2026

Uh oh!

spydon Sep 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		@@ -16,8 +15,11 @@
		with CollisionCallbacks, CollisionPassthrough {
		PathComponent({

Uh oh!

Conversation

adario commented Sep 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Breaking Change?

Related Issues

Uh oh!

adario commented Sep 19, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

spydon Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

spydon Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

spydon Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

spydon Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

spydon Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

spydon Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

adario commented Sep 19, 2026 •

edited

Loading