perf!: Rebuild the FCS core: ComponentList children, allocation hygiene, and flattened 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';

packages/flame/lib/src/camera/camera_component.dart

@@ -203,16 +203,6 @@ class CameraComponent extends Component {
       canvas.save();
       try {
         currentCameras.add(this);
-        void renderWorld(Canvas canvas) {
-          canvas.transform2D(viewfinder.transform);
-          world!.renderFromCamera(canvas);
-
-          // Render the viewfinder elements, which will be in front of
-          // the world,
-          // but with the same transforms applied to them.
-          viewfinder.renderTree(canvas);
-        }
-
         final postProcessors = children.query<PostProcessComponent>();
         if (postProcessors.isNotEmpty) {
           assert(
@@ -223,13 +213,11 @@ class CameraComponent extends Component {
           postProcessor.render(
             canvas,
             viewport.virtualSize,
-            renderWorld,
-            (context) {
-              renderContext.currentPostProcess = context;
-            },
+            _renderWorld,
+            _updatePostProcessContext,
           );
         } else {
-          renderWorld(canvas);
+          _renderWorld(canvas);
         }
       } finally {
         currentCameras.removeLast();
@@ -242,6 +230,24 @@ class CameraComponent extends Component {
     canvas.restore();
   }
 
+  /// Renders the world and the viewfinder elements through the camera
+  /// transform. An instance method rather than a local function, so that the
+  /// render pass does not allocate a closure per camera per frame.
+  void _renderWorld(Canvas canvas) {
+    canvas.transform2D(viewfinder.transform);
+    world!.renderFromCamera(canvas);
+    // Render the viewfinder elements, which will be in front of the world,
+    // but with the same transforms applied to them.
+    viewfinder.renderTree(canvas);
+  }
+
+  // Not a setter: this is passed as a `ValueSetter` tear-off to
+  // `PostProcess.render`.
+  // ignore: use_setters_to_change_properties
+  void _updatePostProcessContext(PostProcess? context) {
+    renderContext.currentPostProcess = context;
+  }
+
   /// Converts from the global (canvas) coordinate space to
   /// local (camera = viewport + viewfinder).
   ///

packages/flame/lib/src/collisions/broadphase/sweep/sweep.dart

@@ -17,7 +17,21 @@ class Sweep<T extends Hitbox<T>> extends Broadphase<T> {
 
   @override
   void update() {
-    items.sort((a, b) => a.aabb.min.x.compareTo(b.aabb.min.x));
+    // Between two ticks the hitboxes only move a little, so [items] is
+    // always nearly sorted: an insertion sort runs in close to linear time
+    // here, where a general-purpose sort would pay its full O(n log n) on
+    // every tick. This also avoids allocating a comparator closure per tick.
+    final items = this.items;
+    for (var i = 1; i < items.length; i++) {
+      final item = items[i];
+      final minX = item.aabb.min.x;
+      var previousIndex = i - 1;
+      while (previousIndex >= 0 && items[previousIndex].aabb.min.x > minX) {
+        items[previousIndex + 1] = items[previousIndex];
+        previousIndex--;
+      }
+      items[previousIndex + 1] = item;
+    }
   }
 
   @override
@@ -44,7 +58,10 @@ class Sweep<T extends Hitbox<T>> extends Broadphase<T> {
             _prospectPool.acquire(item, activeItem);
           }
         } else {
-          _active.remove(activeItem);
+          // The order of the active list does not matter, so the removal can
+          // swap in the last element instead of searching and shifting.
+          _active[i] = _active.last;
+          _active.removeLast();
         }
       }
       _active.add(item);