perf!: Replace the children OrderedSet with ComponentList and flatten the update traversal

doc/flame/components/components.md

@@ -146,6 +146,38 @@ class MyComponent extends PositionComponent with TapCallbacks {
 ```
 
 
+### Custom update traversal and pausing
+
+The engine drives the update pass through a flattened traversal list owned by the game, so
+`updateTree` is non-virtual and cannot be overridden. Components that need to control how their
+subtree is updated (changing the effective `dt`, skipping children, or updating them manually)
+should implement the `CustomTraversal` marker and override the `updateSubtree` method:
+
+```dart
+class SlowMotionArea extends Component implements CustomTraversal {
+  @override
+  void updateSubtree(double dt) => super.updateSubtree(dt / 2);
+}
+```
+
+The engine treats every `CustomTraversal` component as a traversal barrier: it appears in the
+flattened list itself and its `updateSubtree` drives its subtree. `updateSubtree` lives on
+`Component`, but it is only invoked for components carrying the marker. Mixins that provide a
+custom traversal (like `HasTimeScale`) declare `implements CustomTraversal`, so their users do not
+need to add the marker themselves, and chain via `super.updateSubtree`.
+
+To temporarily stop updating a component and its whole subtree, set `updatePaused` to true. While
+paused, no `update` calls happen in the subtree, but rendering and event handling continue, and
+pending lifecycle events (adds and removes) are still processed:
+
+```dart
+enemySquad.updatePaused = true; // freeze the squad
+enemySquad.updatePaused = false; // resume it
+```
+
+This is unrelated to `Game.paused`, which stops the whole game loop including rendering.
+
+
 ### Composability of components
 
 Sometimes it is useful to wrap other components inside of your component. For example by grouping
@@ -331,7 +363,7 @@ flameGame.findByKeyName('player');
 
 ### Querying child components
 
-The children that have been added to a component live in a `QueryableOrderedSet` called
+The children that have been added to a component live in a `ComponentList` called
 `children`. To query for a specific type of components in the set, the `query<T>()` function can be
 used. By default `strictMode` is `false` in the children set, but if you set it to true, then the
 queries will have to be registered with `children.register` before a query can be used.

doc/flame/migration.md

@@ -25,3 +25,89 @@ GameWidget.managed(
   gameFactory: MyGame.new,
 );
 ```
+
+
+### `children` is now a `ComponentList` instead of an `OrderedSet`
+
+The `ordered_set` package is no longer used; children live in a Flame-owned `ComponentList` that
+is significantly faster. The iterable surface, `query<T>()`, `register<T>()`, and `reversed()` are
+unchanged, so most code compiles as is. If you imported `package:ordered_set` types to annotate
+variables, use `ComponentList` (from `package:flame/components.dart`) instead:
+
+```dart
+// Before
+import 'package:ordered_set/ordered_set.dart';
+OrderedSet<Component> children = component.children;
+
+// After
+ComponentList children = component.children;
+```
+
+Two behavioral notes:
+
+- `query<T>()` results are now always in priority order.
+- Mutating `children` while iterating it now tolerates removals and appends at the end; only
+  position-shifting operations (a mid-list insertion, a reorder, or tombstone compaction) throw
+  `ConcurrentModificationError`.
+
+
+### `Component.childrenFactory` is removed
+
+The global children-container factory is gone. Override `createComponentList()` on the component
+instead. The constructor accepts an optional `Comparator<Component>` that replaces priority
+ordering for that parent, which gives custom orderings such as y-sort a supported home:
+
+```dart
+// Before
+Component.childrenFactory = () => OrderedSet.mapping<num, Component>((c) => c.priority);
+
+// After
+class YSortedWorld extends World {
+  @override
+  ComponentList createComponentList() {
+    return ComponentList(
+      comparator: (a, b) => (a as PositionComponent)
+          .position.y
+          .compareTo((b as PositionComponent).position.y),
+    );
+  }
+}
+```
+
+
+### `Component.updateTree` is non-virtual
+
+The update pass runs over a flattened traversal list owned by the game, so `updateTree` can no
+longer be overridden. If you overrode it, implement the `CustomTraversal` marker interface and
+override `Component.updateSubtree` instead; call `super.updateSubtree(dt)` to run the standard
+traversal:
+
+```dart
+// Before
+class SlowMotionArea extends Component {
+  @override
+  void updateTree(double dt) => super.updateTree(dt / 2);
+}
+
+// After
+class SlowMotionArea extends Component implements CustomTraversal {
+  @override
+  void updateSubtree(double dt) => super.updateSubtree(dt / 2);
+}
+```
+
+`HasTimeScale` usage is unchanged (`with HasTimeScale` still works; the mixin carries the marker
+itself). To simply stop updating a subtree, the new `updatePaused` flag replaces the common
+gating override: `component.updatePaused = true` pauses the update pass for the component and its
+whole subtree while rendering, event handling, and lifecycle processing continue.
+
+
+### `Route.stopTime()` no longer zeroes `timeScale`
+
+A stopped route is now paused through `updatePaused` instead of `timeScale = 0`:
+
+- While stopped, `timeScale` keeps its previous value, so a slow-motion factor survives a
+  stop/resume cycle.
+- Assigning a new `timeScale` no longer resumes a stopped route; use `resumeTime()` or
+  `updatePaused = false`.
+- Pending lifecycle events (adding or removing components) on a stopped route now still complete.

examples/lib/stories/collision_detection/quadtree_example.dart

@@ -363,15 +363,16 @@ mixin GameCollidable on PositionComponent {
 
 //#region Utils
 
+/// Lets the subtree update once and then pauses it; set [updateOnce] back to
+/// true to let it update once more.
 mixin UpdateOnce on PositionComponent {
-  bool updateOnce = true;
+  bool get updateOnce => !updatePaused;
+  set updateOnce(bool value) => updatePaused = !value;
 
   @override
-  void updateTree(double dt) {
-    if (updateOnce) {
-      super.updateTree(dt);
-      updateOnce = false;
-    }
+  void update(double dt) {
+    super.update(dt);
+    updatePaused = true;
   }
 }
 

examples/lib/stories/components/time_scale_example.dart

@@ -102,9 +102,9 @@ class _Chopper extends SpriteAnimationComponent
   }
 
   @override
-  void updateTree(double dt) {
+  void update(double dt) {
     position.setFrom(position + _moveDirection * _speed * dt);
-    super.updateTree(dt);
+    super.update(dt);
   }
 
   @override

examples/lib/stories/experimental/layout_component_example_1.dart

@@ -99,7 +99,7 @@ class LayoutDemo1 extends LinearLayoutComponent {
     _expandedMode = value;
     removeAll(children.toList());
     addAll(
-      createComponentList(
+      createLayoutChildren(
         expandedMode: expandedMode,
         padding: padding,
         inflateChild: paddingInflateChild,
@@ -122,7 +122,7 @@ class LayoutDemo1 extends LinearLayoutComponent {
   FutureOr<void> onLoad() {
     super.onLoad();
     addAll(
-      createComponentList(
+      createLayoutChildren(
         expandedMode: expandedMode,
         padding: padding,
         inflateChild: paddingInflateChild,
@@ -137,7 +137,7 @@ class LayoutDemo1 extends LinearLayoutComponent {
   /// This needs to be a method rather than a static list
   /// because each of these components needs to be recreated.
   /// Otherwise, they'll be operated on by reference and re-parented.
-  static List<Component> createComponentList({
+  static List<Component> createLayoutChildren({
     required bool expandedMode,
     required EdgeInsets padding,
     required bool inflateChild,

examples/lib/stories/experimental/layout_component_example_2.dart

@@ -82,7 +82,7 @@ class LayoutDemo2 extends LinearLayoutComponent {
   FutureOr<void> onLoad() {
     super.onLoad();
     addAll(
-      createComponentList(
+      createLayoutChildren(
         direction: direction,
       ),
     );
@@ -95,7 +95,7 @@ class LayoutDemo2 extends LinearLayoutComponent {
   /// This needs to be a method rather than a static list
   /// because each of these components needs to be recreated.
   /// Otherwise, they'll be operated on by reference and re-parented.
-  static List<Component> createComponentList({
+  static List<Component> createLayoutChildren({
     required Direction direction,
   }) {
     return [

packages/flame/lib/components.dart

@@ -12,6 +12,7 @@ export 'src/components/components_notifier.dart';
 export 'src/components/core/component.dart';
 export 'src/components/core/component_key.dart';
 export 'src/components/core/component_render_context.dart';
+export 'src/components/core/custom_traversal.dart';
 export 'src/components/custom_painter_component.dart';
 export 'src/components/fps_component.dart';
 export 'src/components/fps_text_component.dart';