spring_boot_starter_flutter_scene
spring_boot_starter_flutter_scene adds 3D scenes to a Flutter app built on spring_boot_starter_flutter. The engine is the package flutter_scene: WebGL2 in a browser, Impeller elsewhere. A scene is a widget among the app's widgets. When the engine starts, what is loaded and how many frames a scene draws come from spring.flutter.scene.*.
Why
The engine gives a view that draws a scene. An app needs more around it: one start of the engine, something to show where a device cannot draw, a limit on frames, the loading of models, and numbers that say what a scene costs. The starter does this from configuration:
- Scenes that are widgets:
SpringSceneViewamong the app's widgets,SceneBackdropbehind one. Where scenes do not draw (turned off, no WebGL2, the engine failed) they are plain widgets over their placeholders: the app's code has no branch for it. - What a scene costs, from properties: a ceiling on frames, a still frame, a pause off the screen, the scenes' own pixel ratio.
- One start of the engine, with the splash or when the first scene shows; the splash waits for what is eager.
- Models from properties:
spring.flutter.scene.models.<name>, loaded once, cloned by every use. - Materials from properties:
spring.flutter.scene.materials.<name>, the.fmatfiles the build hook compiles, drawn with bySpringSceneMesh; the build fails for one it did not compile. - The application's scene: one scene for the whole app, under every screen.
- The start in events and in words: what is being loaded right now, for a loader to say.
- A tab of the debug panel: every scene and model by name, with what it costs.
Setup
# pubspec.yaml
environment:
sdk: ^3.14.0
flutter: '>=3.50.0'
dependencies:
flutter:
sdk: flutter
spring_boot_starter_flutter_scene: ^0.9.0
# The engine's own scene widgets and geometry (SceneNode, SceneMesh,
# materials), when the app's code names them.
flutter_scene: ^0.24.3
dev_dependencies:
build_runner: ^2.17.0
spring_core_dart_generator: ^0.9.0
The starter brings and re-exports spring_boot_starter_flutter; an app lists this package instead. It does not re-export the engine: an app whose code names the engine's scene widgets lists flutter_scene too, and vector_math for the vectors it writes.
import 'package:flutter_scene/scene.dart';
import 'package:spring_boot_starter_flutter_scene/spring_boot_starter_flutter_scene.dart';
It needs Flutter 3.50 or later (Dart 3.14), as the Flutter starter does. flutter_scene compiles its shaders with the SDK's shader compiler when the app is built. Then dart run build_runner build: the generator finds the starter and adds its beans to lib/spring_gen/main.spring.dart.
In a browser nothing more is needed. On every other platform Flutter GPU is turned on once, with a line in the platform's own file: see Native platforms. Without it the engine does not start there, and the scenes are their placeholders.
Example
A model named in the properties, shown in a scene of its own, with a line that says what is being loaded:
# lib/resources/application.properties
spring.flutter.app.title=Showroom
spring.flutter.scene.max-frame-rate=30
spring.flutter.scene.models.hero.source=asset:assets/models/hero.glb
# the same in lib/resources/application.yml
spring:
flutter:
app:
title: Showroom
scene:
max-frame-rate: 30
models:
hero:
source: asset:assets/models/hero.glb
# pubspec.yaml: the model's file is an asset of the app
flutter:
assets:
- assets/models/
// lib/main.dart
import 'package:flutter/widgets.dart';
import 'package:spring_boot_starter_flutter_scene/spring_boot_starter_flutter_scene.dart';
import 'spring_gen/main.spring.dart';
@SpringBootApplication()
void main() => runApp(
SpringApplicationWidget(
application: () => springApplication,
home: const Showroom(),
),
);
class Showroom extends StatelessWidget {
const Showroom({super.key});
@override
Widget build(BuildContext context) {
// No bean when the app runs with spring.flutter.scene.enabled=false:
// the scene below is then its placeholder, and there is no status.
final status = context.springContext
.getBeanProvider<SceneStatus>()
.getIfAvailable();
return Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
const SizedBox(
width: 320,
height: 320,
// A scene that owns itself. Where scenes do not draw, only the
// placeholder is built.
child: SpringSceneView.declarative(
name: 'showroom',
placeholder: Center(child: Text('hero')),
// spring.flutter.scene.models.hero: loaded once, a clone here.
children: [SpringSceneModel('hero')],
),
),
if (status != null)
ValueListenableBuilder(
valueListenable: status,
// "Compiling shaders", "Loading hero, 1 of 1", then nothing.
builder: (context, step, _) => Text(status.text ?? ''),
),
],
);
}
}
// Every step of the scenes' start is an application event.
@Service()
class LoadedModels {
final List<String> names = [];
@EventListener()
void onLoaded(SceneModelLoadedEvent event) => names.add(event.name);
}
Running it
dart run build_runner build # adds the starter's beans to main.spring.dart
flutter run -d chrome
- The first scene that shows starts the engine, with the placeholder meanwhile. The model
herois loaded when the scene first shows it, once. - The scene shows when it is whole: its models loaded, and the engine asked to compile the programs of its materials beforehand.
- Where scenes do not draw (
spring.flutter.scene.enabled=false, a browser without WebGL2) the same app shows the placeholder and no status. Its code has no branch for it. - In a debug build, the debug panel (⌘⇧D, Ctrl+Shift+D elsewhere) has a "Scenes" tab with the scene and the model by name.
What is inside
- Native platforms: Flutter GPU turned on for iOS, macOS, Android, Linux and Windows.
- Scenes as widgets:
SpringSceneView, what the starter does around the engine's view, the still frame. - A scene behind a widget:
SceneBackdropandSceneSurface. - Where scenes do not draw: scenes turned off, no WebGL2, a failed start; beans that may be absent.
- Models:
spring.flutter.scene.models.*,SpringSceneModel,SceneModels. - The application's scene: one scene under every screen,
SceneCustomizer. - The start in events and words:
SceneEvent,SceneStatus, what the splash waits for. - What a scene costs: the measurements, and what helps.
- The engine's shaders: a shader bundle of the app's own, built in its hook.
- The debug tab: every scene and model by name.
- The engine's log: the engine's messages in the application's log.
- Things of the engine to know:
Component, linear colours, per-frame values. - Testing: scenes in widget tests, without a GPU.
- All properties: every key of the starter.
In Spring (Java)
Spring has no 3D scenes and no counterpart of this starter. The shape is Spring's: a starter that adds a feature by being in the dependencies, an auto-configuration with its beans, customizer beans (SceneCustomizer, as Spring Boot's WebServerFactoryCustomizer), application events for the steps of the start, and ObjectProvider for a bean that may be absent.