
# spring_boot_starter_flutter_scene

`spring_boot_starter_flutter_scene` adds 3D scenes to a Flutter app built on [spring_boot_starter_flutter](../spring-boot-starter-flutter/index.md). 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**: `SpringSceneView` among the app's widgets, `SceneBackdrop` behind 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 `.fmat` files the build hook compiles, drawn with by `SpringSceneMesh`; 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

```yaml
# 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.

```dart
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](native-platforms.md). 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:

```properties
# 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
```

```yaml
# 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
```

```yaml
# pubspec.yaml: the model's file is an asset of the app
flutter:
  assets:
    - assets/models/
```

```dart
// 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

```bash
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 `hero` is 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](native-platforms.md): Flutter GPU turned on for iOS, macOS, Android, Linux and Windows.
- [Scenes as widgets](scenes.md): `SpringSceneView`, what the starter does around the engine's view, the still frame.
- [A scene behind a widget](scene-backdrop.md): `SceneBackdrop` and `SceneSurface`.
- [Where scenes do not draw](without-scenes.md): scenes turned off, no WebGL2, a failed start; beans that may be absent.
- [Models](models.md): `spring.flutter.scene.models.*`, `SpringSceneModel`, `SceneModels`.
- [The application's scene](application-scene.md): one scene under every screen, `SceneCustomizer`.
- [The start in events and words](start.md): `SceneEvent`, `SceneStatus`, what the splash waits for.
- [What a scene costs](cost.md): the measurements, and what helps.
- [The engine's shaders](shaders.md): a shader bundle of the app's own, built in its hook.
- [The debug tab](debug-tab.md): every scene and model by name.
- [The engine's log](engine-log.md): the engine's messages in the application's log.
- [Things of the engine to know](engine-notes.md): `Component`, linear colours, per-frame values.
- [Testing](testing.md): scenes in widget tests, without a GPU.
- [All properties](properties.md): 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.

## See also

- [spring_boot_starter_flutter](../spring-boot-starter-flutter/index.md)
- [The splash and the start](../spring-boot-starter-flutter/splash.md)
- [The debug panel](../spring-boot-starter-flutter/debug-panel.md)
- [All properties](properties.md)
- [What a build contains](optimizations.md)
