feat: Add flame_3d_component, a Component3D backed by flutter_scene

[spydon]

Description

Screen.Recording.2026-10-01.at.18.15.36.mov

This adds flame_3d_component, a bridge package for flutter_scene (the Flutter Scene engine by @bdero) that lets you put a 3D object into the regular 2D component tree of a Flame game.

The package has one class, Component3D. It is a plain PositionComponent that holds a flutter_scene Scene and a Camera, and draws the camera's view of the scene into its own size with Scene.render. Everything else is Flame as usual: position, size, anchor, scale, angle, priority, children, and the regular update and render loop.

This is deliberately not a 3D engine and not a replacement for one. All the 3D work (scene graph, cameras, materials, lighting, animation, model loading, physics) is done by flutter_scene. The package only draws a flutter_scene scene into a Flame component, which the README spells out. It is also separate from flame_3d, which has a different purpose.

Design notes:

• Flame drives the scene clock. The dt from update is accumulated and handed to Scene.update right before the scene renders, so pausing the game pauses animations and node components inside the scene, instead of flutter_scene falling back to its own wall clock tick.
• onLoad awaits Scene.initializeStaticResources, so subclasses can create meshes and materials after super.onLoad().
• The offscreen render target is sized by device pixel ratio times the current canvas zoom, so the 3D content stays sharp when the Flame camera zooms in. A pixelRatio override exists.
• Frames are skipped quietly while Flutter GPU is not ready, instead of flutter_scene printing a warning every frame.
• updateScene and renderScene are protected hooks, so a subclass can use Scene.renderViews for several cameras, and so the component is testable: flutter_scene's Scene constructor touches the GPU context and cannot be built under flutter test, so the scene is created lazily and the tests go through a recording subclass.
• The library re-exports flutter_scene except Component and Sprite, which clash with Flame's names.

The example renders the animated KayKit skeleton (CC0, already in the repo) as a Component3D between a ParallaxComponent in the camera backdrop and a SpriteAnimationComponent walking across the viewport in front of it. It was verified as a web build, which needs no Flutter GPU flag. Native runs need flutter run --enable-flutter-gpu.

Things to keep an eye on:

• flutter_scene needs Flutter 3.47 or newer, so the package is excluded from the lowest supported version analyze job, which the existing flame_3d* ignore glob already covers.
• Adding flutter_scene to the pub workspace changes the shared resolution by about 200 packages, and the CI test job now runs flutter_scene's shader build hook. It worked locally.
• The package is new, so publishing it needs pub.dev workflow dispatch publishing enabled before the first release.

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.