
# 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

```yaml
# lib/resources/application.yml
spring:
  flutter:
    scene:
      models:
        hero:
          source: asset:assets/models/hero.glb
          preload: eager     # not set: as spring.flutter.scene.preload
```

```dart
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 |

```yaml
# pubspec.yaml
flutter:
  assets:
    - assets/models/
```

- Not a file of `lib/resources/`: those are embedded into the app's code, a megabyte at most.
- An address is `https` only; `http` is read only with `spring.remote.allow-insecure: true`.
- In a browser the server must allow the page's origin (CORS), and under `require-corp` isolation nothing else is loaded from another origin (see [What a scene costs](cost.md)).
- A model without a `source` fails, naming the key to set: `spring.flutter.scene.models.<name>.source`.

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`):

```dart
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

- An eager model (`preload: eager`) is loaded while the splash shows: the first screen has it at once.
- A lazy one is loaded when a scene first shows it.
- Not set, a model follows `spring.flutter.scene.preload`, which is `lazy` by default.

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:

```dart
@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

- [Scenes as widgets](scenes.md)
- [The start in events and words](start.md): the events of a load
- [The debug tab](debug-tab.md): every model by name, with what it costs
- [Assets and fonts](../spring-boot-starter-flutter/assets-and-fonts.md)
- [HTTP transport](../spring-web-dart/http-transport.md)
