From 7c4ec659d64157e13eafa38b5f4f883864fb52f4 Mon Sep 17 00:00:00 2001
From: Lukas Klingsbo <lukas.klingsbo@gmail.com>
Date: Wed, 5 Aug 2026 18:31:30 +0200
Subject: [PATCH 1/2] perf: Make render contexts and debug caches lazily
 allocated

---
 .../lib/src/components/core/component.dart    | 34 +++++++++----------
 1 file changed, 17 insertions(+), 17 deletions(-)

diff --git a/packages/flame/lib/src/components/core/component.dart b/packages/flame/lib/src/components/core/component.dart
index 7fca4bb0510..94a9daf2e91 100644
--- a/packages/flame/lib/src/components/core/component.dart
+++ b/packages/flame/lib/src/components/core/component.dart
@@ -598,19 +598,16 @@ class Component {
   /// cleans them up afterwards.
   @protected
   void renderChild(Canvas canvas, Component child) {
-    int? originalLength;
-    final hasContext = _renderContexts.isNotEmpty;
-    if (hasContext) {
-      originalLength = child._renderContexts.length;
-      child._renderContexts.addAll(_renderContexts);
+    final contexts = _renderContexts;
+    if (contexts == null || contexts.isEmpty) {
+      child.renderTree(canvas);
+      return;
     }
+    final childContexts = child._renderContexts ??= [];
+    final originalLength = childContexts.length;
+    childContexts.addAll(contexts);
     child.renderTree(canvas);
-    if (hasContext) {
-      child._renderContexts.removeRange(
-        originalLength!,
-        child._renderContexts.length,
-      );
-    }
+    childContexts.removeRange(originalLength, childContexts.length);
   }
 
   /// Called once after all children have been rendered in [renderTree].
@@ -623,7 +620,7 @@ class Component {
   void renderTree(Canvas canvas) {
     final context = renderContext;
     if (context != null) {
-      _renderContexts.add(context);
+      (_renderContexts ??= []).add(context);
     }
 
     render(canvas);
@@ -641,7 +638,7 @@ class Component {
     }
 
     if (context != null) {
-      _renderContexts.removeLast();
+      _renderContexts!.removeLast();
     }
   }
 
@@ -1217,14 +1214,16 @@ class Component {
 
   //#region Context
 
-  final QueueList<ComponentRenderContext> _renderContexts = QueueList();
+  /// The stack of render contexts inherited from ancestors during the render
+  /// pass. Created lazily: most components never provide or receive one.
+  List<ComponentRenderContext>? _renderContexts;
 
   /// Override this method if you want your component to provide a custom
   /// render context to all its children (recursively).
   ComponentRenderContext? get renderContext => null;
 
   T? findRenderContext<T extends ComponentRenderContext>() {
-    return _renderContexts.whereType<T>().lastOrNull;
+    return _renderContexts?.whereType<T>().lastOrNull;
   }
 
   //#endregion
@@ -1255,8 +1254,9 @@ class Component {
   /// The color that the debug output should be rendered with.
   Color debugColor = const Color(0xFFFF00FF);
 
-  final ValueCache<Paint> _debugPaintCache = ValueCache<Paint>();
-  final ValueCache<TextPaint> _debugTextPaintCache = ValueCache<TextPaint>();
+  late final ValueCache<Paint> _debugPaintCache = ValueCache<Paint>();
+  late final ValueCache<TextPaint> _debugTextPaintCache =
+      ValueCache<TextPaint>();
 
   /// The [debugColor] represented as a [Paint] object.
   Paint get debugPaint {

From 264fc664599f72bea48fce91ee322530ea735873 Mon Sep 17 00:00:00 2001
From: Lukas Klingsbo <lukas.klingsbo@gmail.com>
Date: Sun, 16 Aug 2026 15:35:52 +0200
Subject: [PATCH 2/2] refactor: Address review comments on lazy render contexts

---
 .../flame/lib/src/components/core/component.dart     | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/packages/flame/lib/src/components/core/component.dart b/packages/flame/lib/src/components/core/component.dart
index 94a9daf2e91..620a7fa624e 100644
--- a/packages/flame/lib/src/components/core/component.dart
+++ b/packages/flame/lib/src/components/core/component.dart
@@ -598,8 +598,8 @@ class Component {
   /// cleans them up afterwards.
   @protected
   void renderChild(Canvas canvas, Component child) {
-    final contexts = _renderContexts;
-    if (contexts == null || contexts.isEmpty) {
+    final contexts = _renderContexts ?? const <ComponentRenderContext>[];
+    if (contexts.isEmpty) {
       child.renderTree(canvas);
       return;
     }
@@ -619,8 +619,10 @@ class Component {
 
   void renderTree(Canvas canvas) {
     final context = renderContext;
+    List<ComponentRenderContext>? renderContexts;
     if (context != null) {
-      (_renderContexts ??= []).add(context);
+      renderContexts = _renderContexts ??= [];
+      renderContexts.add(context);
     }
 
     render(canvas);
@@ -637,9 +639,7 @@ class Component {
       renderDebugMode(canvas);
     }
 
-    if (context != null) {
-      _renderContexts!.removeLast();
-    }
+    renderContexts?.removeLast();
   }
 
   //#endregion