
# The start in events and words

The engine starts once for the app, and each step of its start is an application event: the engine, each model, a failure. `SceneStatus` is the current step in words, for a loader to say. The splash waits for what is eager.

## Why

Starting the engine compiles shaders, and a model is a file to read and import: both take time a user sees. An app that shows "Loading…" for all of it says less than it knows. Here the steps are events like any other, and their words are messages like any other.

## Example

```dart
@Service()
class LoadedModels {
  final List<String> names = [];

  // Hears each model that finished loading.
  @EventListener()
  void onLoaded(SceneModelLoadedEvent event) => names.add(event.name);
}
```

```properties
# lib/resources/messages.properties
scene.loading.engine=Compiling shaders…
scene.loading.model=Loading {0}, {1} of {2}…
```

```dart
// In a loader, with the SceneStatus bean as `status`:
// "Compiling shaders…", then "Loading hero, 2 of 5…".
ValueListenableBuilder(
  valueListenable: status,
  builder: (context, step, _) => Text(status.text ?? ''),
)
```

## One start of the engine

`spring.flutter.scene.preload` says when the engine starts:

| Value | The engine starts |
|---|---|
| `lazy` (the default) | When the first scene shows, with its placeholder meanwhile |
| `eager` | With the splash: the app appears with it ready |

An eager model and the application's scene start the engine with the splash too. The start is the `sceneEngine` bean's (`SceneEngine`): `start()` answers the same start to every caller, `true` when scenes can draw and `false` when the start failed.

## The events

Each step is a `SceneEvent`, heard like any other application event (see [@EventListener](../spring-core-dart/events/event-listener.md)):

| Event | When | It carries |
|---|---|---|
| `SceneEngineStartingEvent` | The engine starts: its shaders are compiled | `backend` |
| `SceneEngineReadyEvent` | The engine started | `backend`, `took` |
| `SceneModelLoadingEvent` | A model is being loaded | `name`, `location`, `index`, `count` (its place among those loaded together) |
| `SceneModelLoadedEvent` | A model is loaded | `name`, `took`, `bytes` |
| `SceneReadyEvent` | Everything asked for with the splash is ready | `took` |
| `SceneFailedEvent` | A step failed; the app goes on | `step` (`SceneStep.engine`, `model` or `application`), `name` for a model, `error` |
| `SceneUnavailableEvent` | Scenes do not draw here, said once | `reason` (`SceneUnavailable.off` or `engine`) |

## The words

An event is a `MessageSourceResolvable`: its words come from the app's messages by its code, else its own English.

| Code | Arguments | The default text |
|---|---|---|
| `scene.loading.engine` | none | Compiling shaders |
| `scene.ready.engine` | none | The 3D engine is ready |
| `scene.loading.model` | `{0}` the name, `{1}` its place, `{2}` how many | Loading {0}, {1} of {2} |
| `scene.ready.model` | `{0}` the name | {0} is loaded |
| `scene.ready` | none | The scenes are ready |
| `scene.failed.engine` | none | The 3D engine did not start |
| `scene.failed.model` | `{0}` the name | {0} did not load |
| `scene.failed.application` | none | The application's scene was not made |
| `scene.unavailable.off` | none | Scenes are turned off |
| `scene.unavailable.engine` | none | Scenes cannot be drawn on this device |

A key of `messages.properties` rewords a step, and `messages_ja.properties` says it in Japanese. See [Messages and languages](../spring-boot-starter-flutter/messages.md).

## SceneStatus

`SceneStatus` (`sceneStatus`) is the current step for a loader: a `ValueListenable` of the last step published while something is being loaded.

| Member | Meaning |
|---|---|
| `value` | The current `SceneEvent`; `null` when nothing is being loaded |
| `text` | The current step in words; `null` when nothing is being loaded |
| `history` | Every step heard so far, oldest first |

With scenes turned off there is no such bean: a widget takes it as one that may be absent (see [Where scenes do not draw](without-scenes.md)).

## What the splash waits for

The scenes' part of the start is a `SplashTask` (`sceneStart`), so the splash waits for it as for any other, and its loader moves with the steps:

- the engine, with `preload: eager`, an eager model or the application's scene;
- the eager models, one after another;
- the application's scene (`spring.flutter.scene.app.enabled`).

With nothing eager it does nothing: the engine starts when the first scene shows. With `render: off` it does nothing either. A step that fails does not stop the start. The limits of every splash task hold for it: see [Splash tasks](../spring-boot-starter-flutter/splash.md#splash-tasks).

## In Spring (Java)

Spring has no counterpart of these events. They are published and heard as Spring's own are: `ApplicationEventPublisher` and `@EventListener`, and their texts are resolved by the `MessageSource` as a `MessageSourceResolvable`.

## See also

- [Models](models.md)
- [The application's scene](application-scene.md)
- [The engine's shaders](shaders.md): how long the engine's start takes
- [The splash and the start](../spring-boot-starter-flutter/splash.md)
- [MessageSource](../spring-core-dart/messages/message-source.md)
