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:

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

What is inside

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.

See also