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

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

  // Hears each model that finished loading.
  @EventListener()
  void onLoaded(SceneModelLoadedEvent event) => names.add(event.name);
}
# lib/resources/messages.properties
scene.loading.engine=Compiling shaders…
scene.loading.model=Loading {0}, {1} of {2}…
// 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):

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.

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).

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:

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.

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