
# The application's scene

With `spring.flutter.scene.app.enabled: true` the app has one scene of its own, the `applicationScene` bean, made with the splash. It shows under every screen and in every `const SpringSceneView()`.

## Why

A backdrop that stays while the screens change cannot belong to one screen: it would be made again with each of them. The application's scene is made once, lives as long as the app, and is filled by beans.

## Example

```yaml
# lib/resources/application.yml
spring:
  flutter:
    scene:
      models:
        stage:
          source: asset:assets/models/stage.glb
      app:
        enabled: true          # the application's scene
        placement: background  # background | none
        camera:
          position: 0, 1.5, -4
          target: 0, 1, 0
          fov: 45
```

```dart
// The engine has a class Component of its own: only what is used here.
import 'package:flutter_scene/scene.dart' show Scene;
import 'package:spring_boot_starter_flutter_scene/spring_boot_starter_flutter_scene.dart';

@Component()
class Stage implements SceneCustomizer {
  Stage(this.models);

  final ObjectProvider<SceneModels> models;

  @override
  Future<void> customize(Scene scene) async {
    scene.add((await models.getObject()['stage'].load()).clone());
  }
}
```

The models come through an `ObjectProvider`: with `spring.flutter.scene.enabled: false` no scene bean exists, and this bean must still be made. Nothing calls `customize` then.

## What goes into it

Every `SceneCustomizer` bean receives the scene once, in `@Order`, after the engine started and before the scene is first drawn. It adds nodes and sets the scene's light, fog and anti-aliasing.

A screen adds to the scene with the engine's `SceneSubtree` and takes its part away when it leaves. The `children` of a `SpringSceneView()` are added to it while that view shows.

## Where it shows

| `spring.flutter.scene.app.placement` | The scene shows |
|---|---|
| `background` (the default) | Under every screen of the app, and in every `SpringSceneView()` |
| `none` | Only in the `SpringSceneView()` widgets of the app |

With `background`, the screens must not paint an opaque background of their own. The scene under the screens is a `SpringSceneView` named `application` in [the debug tab](debug-tab.md), put below the app's content by a `FlutterAppCustomizer` (`applicationSceneBackground`). It takes no pointer events, and it is a plain widget where scenes do not draw.

## The camera

The scene is seen through the camera of the properties where a view gives none:

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.flutter.scene.app.camera.position` | `x, y, z` | `0, 0, -5` | Where the camera is |
| `spring.flutter.scene.app.camera.target` | `x, y, z` | `0, 0, 0` | What it looks at |
| `spring.flutter.scene.app.camera.fov` | degrees | `45` | Its vertical field of view |

A view of its own gives another: `SpringSceneView(camera: ...)` or `cameraBuilder:`.

## The bean

`applicationScene` (`ApplicationScene`, a `ChangeNotifier`) exists only with `app.enabled: true`:

| Member | Meaning |
|---|---|
| `scene` | The engine's `Scene`; `null` until it is made, and for good where the engine did not start |
| `camera` | The camera of `spring.flutter.scene.app.camera` |
| `create()` | Makes the scene, once: every call answers the same one. `null` when the engine did not start or a customizer failed |

The scene is made with the splash, which waits for it (see [The start in events and words](start.md)). A customizer that fails is logged as a warning and published as a `SceneFailedEvent`; the app goes on without the scene.

## What it costs

This is where scenes cost most: a scene under every screen draws the whole page again for each of its frames. See [What a scene costs](cost.md).

## In Spring (Java)

Spring Boot customizes what it makes the same way: `WebServerFactoryCustomizer` beans receive the web server's factory before the server is made.

## See also

- [Scenes as widgets](scenes.md)
- [Models](models.md)
- [What a scene costs](cost.md)
- [The app widget](../spring-boot-starter-flutter/app-widget.md): `FlutterAppCustomizer`
