[spydon]

Description

First half of the FCS core rewrite for #3957: replaces the OrderedSet children container with a Flame-owned ComponentList. Split out of #3960 so that the container change can be reviewed on its own; #3960 is stacked on top of this branch and adds the flattened update traversal.

Children live in a Flame-owned ComponentList

The ordered_set dependency is gone. Children are stored in a single flat array sorted by (priority, insertion order), and each component intrusively stores its container and slot index:

• remove and contains are O(1), with no hashing or tree walks; add is an O(1) append in the common case.
• Removals leave null tombstones that are compacted once per parent per tick, so removing k children among n costs O(k + n) instead of O(k*n).
• A priority change triggers at most one stable sort per parent per tick, skipped entirely when nothing actually reordered.
• The register<T>()/query<T>() cache surface is kept, and results are now always in priority order.
• Component.childrenFactory is replaced by an overridable createComponentList(), which accepts an optional Comparator<Component> for custom orderings such as y-sort.

The update, render, and hit-test passes iterate the backing array directly instead of going through an iterator, but the traversal itself is unchanged: updateTree is still recursive and virtual here. component_tree_ordering_test.dart pins lifecycle-event ordering, hit-test order, and equal-priority ordering across the rewrite.

Three backing designs were implemented and benchmarked before settling on this one; see the comparison in the issue.

Benchmarks

Measured against main (commit 7fd33dee9, which already includes the merged allocation-hygiene PRs), so both tables isolate this PR's own effect. The benchmark suite is in packages/flame/benchmark; ms per run, lower is better.

JIT (flutter test, host machine)

Benchmark	main	this PR	speedup
Update wide tree (10k x 1)	3.24	1.19	2.7x
Update nested tree (1k x 10)	8.08	2.57	3.1x
Update deep tree (100 levels)	8.46	3.23	2.6x
Update barrier tree (10% time-scaled)	9.15	3.85	2.4x
Render wide tree (10k x 1)	5.14	4.05	1.3x
Render nested tree (1k x 10)	9.95	4.92	2.0x
Render deep tree (100 levels)	12.34	6.56	1.9x
Lifecycle churn (100/tick, 1k pop)	1.80	1.15	1.6x
Lifecycle churn (100/tick, 10k pop)	4.86	2.82	1.7x
Mass add/remove (1k per cycle)	1.15	0.64	1.8x
Priority change (1 child per parent)	26.01	3.44	7.6x
Priority change (y-sort, all children)	11.72	3.33	3.5x
Type-query churn (2 registered queries)	3.41	2.83	1.2x
Game-like update pass	98.34	70.09	1.4x
Hit test + delivery (cached)	43.63	41.93	flat
Flat collision detection	4.95	2.04	2.4x
Nested collision detection	7.91	2.84	2.8x

AOT (flutter run --release, Android arm64 emulator on an Apple Silicon host)

Benchmark	main	container only	speedup
Update wide tree (10k x 1)	6.25	4.31	1.5x
Update nested tree (1k x 10)	9.53	3.91	2.4x
Update deep tree (100 levels)	11.28	4.27	2.6x
Update barrier tree (10% time-scaled)	12.35	6.81	1.8x
Render wide tree (10k x 1)	6.42	3.97	1.6x
Render nested tree (1k x 10)	12.44	4.70	2.6x
Render deep tree (100 levels)	14.74	6.53	2.3x
Lifecycle churn (100/tick, 1k pop)	1.54	0.90	1.7x
Lifecycle churn (100/tick, 10k pop)	4.80	3.08	1.6x
Mass add/remove (1k per cycle)	0.89	0.42	2.1x
Priority change (1 child per parent)	24.67	3.42	7.2x
Priority change (y-sort, all children)	11.28	3.30	3.4x
Type-query churn (2 registered queries)	5.36	4.75	1.1x
Game-like update pass	79.68	50.16	1.6x
Hit test + delivery (cached)	43.30	38.48	1.1x
Flat collision detection	4.26	1.47	2.9x
Nested collision detection	7.92	1.95	4.1x

Both tables are single runs per checkpoint (the JIT one is the container only column of the attribution run in #3960), so treat the exact multiples loosely. The AOT numbers come from the crud_test AVD (API 34, arm64-v8a, 4 cores), which executes the AOT snapshot natively on the host CPU, so they are representative of release-mode Dart rather than of any particular phone.

Update pass with real game logic (JIT and AOT)

@luanpotter asked whether the traversal gains above still matter once components do real work, so update_workload_benchmark.dart reuses the wide and nested trees from the traversal suite but gives every component a bog-standard, allocation-free update body:

• light: bullet or particle style movement, position.addScaled(velocity, dt) plus bouncing off the world bounds.
• heavy: enemy AI style steering, scanning 32 moving targets for the nearest one, steering towards it with clamped acceleration, atan2 facing, and a cooldown timer.

The no-op rows are the traversal benchmarks re-run in the same session for reference. Light rows do 500k component visits per run and heavy rows 100k (the no-op rows do 1M), so compare each row against its no-op counterpart rather than across rows. Median of 3 alternating runs, ms per run, same machines as the tables above (main at b4578fc6a).

Benchmark	JIT main	JIT this PR	speedup	AOT main	AOT this PR	speedup
Wide tree (10k x 1), no-op	3.28	1.21	2.7x	4.51	2.38	1.9x
Wide tree (10k x 1), light logic	21.20	19.62	1.1x	12.50	11.22	1.1x
Wide tree (10k x 1), heavy logic	13.41	13.41	flat	10.86	10.47	flat
Nested tree (1k x 10), no-op	8.57	2.55	3.4x	8.98	2.66	3.4x
Nested tree (1k x 10), light logic	22.23	19.58	1.1x	21.41	17.59	1.2x
Nested tree (1k x 10), heavy logic	15.50	14.64	1.1x	12.57	11.36	1.1x

Per component visit in AOT, the framework overhead on main is about 4.5ns in the wide tree and 9ns in the nested tree, against roughly 25-45ns for the light update body (most of which is the NotifyingVector2 change notification that marks the transform dirty) and 110-130ns for the heavy one. So on main the traversal accounts for around 18% (wide) to 21% (nested) of a light-logic update pass and 4-7% of a heavy-logic one, and this PR removes most of that: the whole update pass gets 10-20% cheaper with light logic and 4-10% cheaper with heavy logic. The nested shape, which is what real games look like (entities holding a handful of child components), is where the gain is largest, and the heavy-logic rows are the floor: the container change cannot speed up the game's own code, so a game that is bound by its own update bodies sees single-digit percent gains from this PR on its own. The traversal flattening in #3960 stacks on top of these numbers.

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

• children is now a ComponentList instead of an OrderedSet. The iterable surface, query<T>(), and register<T>() are unchanged, so most code compiles as is. The ordered_set dependency is gone.
• children.reversed() is now a getter: children.reversed.
• Component.strictQueryMode is removed. Strict mode is off by default; to enable it for a component, override createComponentList() to return ComponentList(strictMode: true).
• Component.childrenFactory is removed. Override createComponentList() on the component instead; it accepts an optional Comparator<Component> for custom orderings (for example y-sort).
• Mutating children while iterating it now tolerates removals and tail appends; only position-shifting operations (mid-list insertion, reorder, compaction) throw ConcurrentModificationError.

Related Issues

Part of #3957 (closed by #3960, which is stacked on this PR).

[luanpotter]

This is great and super clean @spydon thanks for breaking it up.

I left some comments but have 3 overarching comments:

1. as we agreed before, dart's for each (I mean the language construct- not the lambda) compiles just the same as the indexed for

2. I am considering if we can extract a mixin, base class, whatever from Component to hold the "bears children" logic - it would include all the 3 related fields (the children, the parent list ref, and the index). these are the only things ComponentList cares about for Component specifically (other than the default priority comparator that can move to createComponentList. that way ComponentList becomes truly component agnostic, and the component class can remove some of this related index tracking and children logic. not sure it would be as clean as I am envisioning, but worth investigating.

3. I am curious about the efficacy of our benchmarks in real life:

   All components are plain [Component]s with no-op [Component.update] and [Component.render], so any time measured here is framework overhead rather than game logic.

   while yes that isolate engine overhead, I wonder if the magnitude is even relevant on real cases (I suspect yes, but not 100% sure). would be awesome to run the same bench with some bog-standard possible implementations of updates, like a light and a heavy one, to see how the optimizations fare into a real game.

but overall, all things being said - I am very happy with this direction :)

[spydon]

This is great and super clean @spydon thanks for breaking it up.

I left some comments but have 3 overarching comments:

1. as we agreed before, dart's for each (I mean the language construct- not the lambda) compiles just the same as the indexed for

Yes, for-in, not for each. I'll fix that up. :)

2. I am considering if we can extract a mixin, base class, whatever from Component to hold the "bears children" logic - it would include all the 3 related fields (the children, the parent list ref, and the index). these are the only things `ComponentList` cares about for Component specifically (other than the default priority comparator that can move to `createComponentList`. that way `ComponentList` becomes truly component agnostic, and the component class can remove some of this related index tracking and children logic. not sure it would be as clean as I am envisioning, but worth investigating.

It sounds like overengineering to me... It's not that much overhead in the Component, and it really is the core of the Component.

3. I am curious about the efficacy of our benchmarks in real life:
   > All components are plain [Component]s with no-op [Component.update] and [Component.render], so any time measured here is framework overhead rather than game logic.
   
   
   while yes that isolate engine overhead, I wonder if the magnitude is even relevant on real cases (I suspect yes, but not 100% sure). would be awesome to run the same bench with some bog-standard possible implementations of updates, like a light and a heavy one, to see how the optimizations fare into a real game.

Setting up more "real life" benchmark too and adding the results to the description.

[luanpotter]

LGTM

[luanpotter]

[luanpotter]

lovely