Models

A model is named in the properties with its file. The starter loads it once, with the splash or when a scene first shows it, and every use of it is a clone. SpringSceneModel shows it in a scene; the SceneModels bean gives it to code.

Why

Loading a model is code every app writes again: read the file, import it, keep the result, show something meanwhile, handle a failure. And a model used in three places should be read and sent to the GPU once. Here the app names the model, and the starter does the rest.

Example

# lib/resources/application.yml
spring:
  flutter:
    scene:
      models:
        hero:
          source: asset:assets/models/hero.glb
          preload: eager     # not set: as spring.flutter.scene.preload
SpringSceneView.declarative(
  children: [
    SpringSceneModel('hero', position: Vector3(0, 1, 0)),
  ],
)

The file

source says where the model's file is. The file is a binary glTF (.glb):

Source Example How it is read
An asset of the app asset:assets/models/hero.glb From the app's assets: the file is listed under flutter: assets: of pubspec.yaml
An address https://cdn.example.com/hero.glb With one GET through the app's HttpTransport bean (the platform's client without one), in a browser too
# pubspec.yaml
flutter:
  assets:
    - assets/models/

The file at an address is a RemoteModelResource. The server is asked only when the model is loaded; an answer that is not a success fails the load, naming the address and the status.

Another format is a SceneModelImporter bean of the app. It takes the place of the starter's (GlbModelImporter, the bean sceneModelImporter):

abstract interface class SceneModelImporter {
  /// The template of model [name] from the [bytes] of its file.
  Future<Node> import(Uint8List bytes, {required String name});
}

Eager and lazy

Either way it is loaded once and kept: a model that left the screen and came back is not imported again.

A model in a scene

SpringSceneModel('hero') shows the model in a scene: a clone of its template, so every use has its own transform and animation while the geometry, textures and materials stay shared on the GPU. It is a scene widget: it goes among the children of a SpringSceneView (or of the engine's own scene widgets), never among ordinary widgets.

Parameter Type Meaning
name (positional) String The model's name in spring.flutter.scene.models
variant String? A material variant of the model (KHR_materials_variants)
animations List<SceneAnimationSpec> Which of its animations play, and how
placeholder WidgetBuilder? Scene widgets in its place while it loads
error Widget Function(BuildContext, Object)? Scene widgets in its place when it failed to load
onLoaded void Function(Node)? Called with the clone once it is in the scene
position, rotation, scale Vector3?, Quaternion?, Vector3? Where it stands, how it is turned, its scale
visible bool Whether it is drawn; true by default
components List<Component> Behaviour on its node (the engine's Component)
children List<Widget> Scene widgets under its node

A view waits for its SpringSceneModel widgets before it shows, so a scene is never drawn half-built.

Models in code

SceneModels (sceneModels) gives a model to code:

@Component()
class Showroom {
  Showroom(this.models);

  final ObjectProvider<SceneModels> models;

  // No bean when the app runs with scenes turned off.
  Future<void> open() async => models.getIfAvailable()?['hero'].load();
}
Member of SceneModels Meaning
models['hero'] The model's SceneModelHandle; an unknown name fails naming those there are
names, all, eager The names, every model, the models loaded with the splash
contains(name) Whether there is a model of that name
Member of SceneModelHandle Meaning
load() Loads the model, once: every call answers the same load. Starts the engine when nothing has yet
reload() Loads it again after a failure
state idle, loading, ready or failed (SceneModelState)
template The loaded node tree, cloned by every use; null until state is ready
failure What the load threw, when it failed
name, location, eager Its name, where its file is as the properties say, whether it is loaded with the splash
bytes, readTook, importTook The size of the file, the time to read it (to download, for an address) and to import it

A handle is a ChangeNotifier: it notifies its listeners when its state changes.

When a model fails

A model that fails to load is logged as a warning and published as a SceneFailedEvent. The start goes on: an eager model that failed is skipped, and its scenes show their placeholders. reload() on its handle tries again.

See also