refactor(flame_3d)!: Allow LightComponents to be nested (#3883)

`LightComponents` can now be nested inside any `Component3D` allowing
for a more flexible light system. On top of that refactored the light
system so that every Material decided how lights should be applied.



https://github.com/user-attachments/assets/c3bceb92-5ed6-4910-b9fe-4efda6e4b600

Author: wolfenrain

packages/flame_3d/example/lib/components/player.dart

@@ -36,6 +36,13 @@ class Player extends MeshComponent
             albedoTexture: ColorTexture(BasicPalette.yellow.color),
           ),
         ),
+        children: [
+          LightComponent.point(
+            position: Vector3(0, 1.5, 0.8),
+            color: BasicPalette.white.color,
+            intensity: 10,
+          ),
+        ],
       );
 
   @override

packages/flame_3d/example/lib/components/rendered_point_light.dart

@@ -1,51 +1,29 @@
 import 'dart:async';
+import 'dart:ui';
 
-import 'package:flame/components.dart';
-import 'package:flame/palette.dart';
 import 'package:flame_3d/components.dart';
-import 'package:flame_3d/game.dart';
 import 'package:flame_3d/resources.dart';
 
-class RenderedPointLight extends Component with HasGameReference<FlameGame3D> {
-  final Vector3 position;
+class RenderedPointLight extends Component3D {
   final Color color;
 
   RenderedPointLight({
-    required this.position,
+    required super.position,
     required this.color,
   });
 
-  late LightComponent _light;
-
   @override
   FutureOr<void> onLoad() async {
-    // TODO(luan): support lights being added nested in the component tree.
-    game.world.add(
-      _light = LightComponent.point(
-        position: position,
-        color: color,
-      ),
-    );
     addAll([
+      LightComponent.point(color: color),
       MeshComponent(
         mesh: SphereMesh(
           radius: 0.05,
           material: SpatialMaterial(
-            albedoTexture: ColorTexture(
-              color,
-            ),
+            albedoTexture: ColorTexture(color),
           ),
         ),
-        position: position,
       ),
     ]);
   }
-
-  @override
-  void onRemove() {
-    if (_light.isMounted) {
-      game.world.remove(_light);
-    }
-    super.onRemove();
-  }
 }

packages/flame_3d/lib/src/camera/world_3d.dart

@@ -20,16 +20,21 @@ class World3D extends flame.World with flame.HasGameReference {
     super.children,
     super.priority,
     Color clearColor = const Color(0x00000000),
-  }) : device = GraphicsDevice(clearValue: clearColor) {
-    children.register<LightComponent>();
-  }
+  }) : device = GraphicsDevice(clearValue: clearColor);
 
   /// The graphical device attached to this world.
   @internal
   final GraphicsDevice device;
 
-  Iterable<Light> get lights =>
-      children.query<LightComponent>().map((component) => component.light);
+  final List<Light> _lights = [];
+
+  /// Register a [light] with this world.
+  @internal
+  void addLight(Light light) => _lights.add(light);
+
+  /// Unregister a [light] from this world.
+  @internal
+  void removeLight(Light light) => _lights.remove(light);
 
   final _paint = Paint();
 
@@ -46,6 +51,7 @@ class World3D extends flame.World with flame.HasGameReference {
     );
 
     device
+      ..lights = _lights
       // Set the view matrix
       ..view.setFrom(camera.viewMatrix)
       // Set the projection matrix
@@ -54,7 +60,6 @@ class World3D extends flame.World with flame.HasGameReference {
 
     culled = 0;
 
-    _prepareDevice();
     // ignore: invalid_use_of_internal_member
     super.renderFromCamera(canvas);
 
@@ -69,11 +74,6 @@ class World3D extends flame.World with flame.HasGameReference {
     image.dispose();
   }
 
-  // TODO(luan): consider making this a fixed-size array later
-  void _prepareDevice() {
-    device.lightingInfo.lights = lights;
-  }
-
   // TODO(wolfenrain): this is only here for testing purposes
   int culled = 0;
 }

packages/flame_3d/lib/src/components/light_component.dart

@@ -1,11 +1,11 @@
+import 'dart:typed_data';
 import 'dart:ui';
 
-import 'package:flame_3d/camera.dart';
 import 'package:flame_3d/components.dart';
 import 'package:flame_3d/game.dart';
 import 'package:flame_3d/resources.dart';
 
-/// A [Component3D] that represents a light source in the 3D world.
+/// A [Component3D] that represents a light source in 3D space.
 class LightComponent extends Component3D {
   LightComponent({
     required this.source,
@@ -37,7 +37,10 @@ class LightComponent extends Component3D {
   final LightSource source;
 
   late final Light _light = Light(
-    transform: transform,
+    position: Vector3.fromBuffer(
+      worldTransformMatrix.storage.buffer,
+      12 * Float32List.bytesPerElement,
+    ),
     source: source,
   );
 
@@ -46,9 +49,20 @@ class LightComponent extends Component3D {
   @override
   void onMount() {
     super.onMount();
-    assert(
-      parent is World3D,
-      'Lights must be added to the root of the World3D',
-    );
+    world.addLight(_light);
+  }
+
+  @override
+  void onRemove() {
+    world.removeLight(_light);
+    super.onRemove();
+  }
+
+  @override
+  void update(double dt) {
+    // NOTE: this ensures the matrix gets computed if need be, so that
+    // the light position moves with it's ancestors.
+    worldTransformMatrix;
+    super.update(dt);
   }
 }

packages/flame_3d/lib/src/graphics/graphics_device.dart

@@ -76,7 +76,7 @@ class GraphicsDevice {
 
   /// Must be set by the rendering pipeline before elements are bound.
   /// Can be accessed by elements in their bind method.
-  final LightingInfo lightingInfo = LightingInfo();
+  Iterable<Light> lights = [];
 
   /// Begin a new rendering batch.
   ///

packages/flame_3d/lib/src/resources/light.dart

@@ -1,5 +1,4 @@
 export 'light/ambient_light.dart';
 export 'light/light.dart';
 export 'light/light_source.dart';
-export 'light/lighting_info.dart';
 export 'light/point_light.dart';

packages/flame_3d/lib/src/resources/light/ambient_light.dart

@@ -7,9 +7,4 @@ class AmbientLight extends LightSource {
     super.color = const Color(0xFFFFFFFF),
     super.intensity = 0.2,
   });
-
-  void apply(Shader shader) {
-    shader.setColor('AmbientLight.color', color);
-    shader.setFloat('AmbientLight.intensity', intensity);
-  }
 }

packages/flame_3d/lib/src/resources/light/light.dart

@@ -10,21 +10,16 @@ import 'package:flame_3d/resources.dart';
 ///
 /// {@endtemplate}
 class Light extends Resource<void> {
-  final Transform3D transform;
+  final Vector3 position;
+
   final LightSource source;
 
   /// {@macro light}
   Light({
-    required this.transform,
+    required this.position,
     required this.source,
   });
 
   @override
   void createResource() {}
-
-  void apply(int index, Shader shader) {
-    shader.setVector3('Lights.positions[$index]', transform.position);
-    shader.setColor('Lights.colors[$index]', source.color);
-    shader.setFloat('Lights.intensities[$index]', source.intensity);
-  }
 }

packages/flame_3d/lib/src/resources/light/lighting_info.dart

@@ -82,7 +82,29 @@ class SpatialMaterial extends Material {
   }
 
   void _applyLights(GraphicsDevice device) {
-    device.lightingInfo.apply(fragmentShader);
+    final lights = device.lights;
+
+    // Apply ambient light (at most one, fallback to default).
+    final ambient =
+        lights.map((e) => e.source).whereType<AmbientLight>().firstOrNull ??
+        AmbientLight();
+    fragmentShader
+      ..setColor('AmbientLight.color', ambient.color)
+      ..setFloat('AmbientLight.intensity', ambient.intensity);
+
+    // Apply point lights.
+    final points = lights.where((e) => e.source is PointLight);
+
+    // NOTE: using floats because Android GLES does not support integer uniforms
+    // Refer to https://github.com/flutter/engine/pull/55329
+    fragmentShader.setFloat('Lights.numLights', points.length.toDouble());
+
+    for (final (index, light) in points.indexed) {
+      fragmentShader
+        ..setVector3('Lights.positions[$index]', light.position)
+        ..setColor('Lights.colors[$index]', light.source.color)
+        ..setFloat('Lights.intensities[$index]', light.source.intensity);
+    }
   }
 
   static const _maxJoints = 16;