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:
- 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.
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
- The application's scene
- The engine's shaders: how long the engine's start takes
- The splash and the start
- MessageSource