
# モデル

モデルは、プロパティでそのファイルとともに名前を付けます。スターターは、スプラッシュとともに、またはシーンが最初に表示するときに一度だけ読み込み、使うたびにクローンを作ります。`SpringSceneModel` はそれをシーンに表示し、`SceneModels` Bean はそれをコードに渡します。

## 使う理由

モデルの読み込みは、どのアプリも繰り返し書くコードです。ファイルを読み、インポートし、結果を保持し、その間は何かを表示し、失敗を処理します。そして、三か所で使うモデルは、一度だけ読み、一度だけ GPU に送るべきです。ここでは、アプリがモデルに名前を付け、残りはスターターが行います。

## 例

```yaml
# lib/resources/application.yml
spring:
  flutter:
    scene:
      models:
        hero:
          source: asset:assets/models/hero.glb
          preload: eager     # 未設定: spring.flutter.scene.preload と同じ
```

```dart
SpringSceneView.declarative(
  children: [
    SpringSceneModel('hero', position: Vector3(0, 1, 0)),
  ],
)
```

## ファイル

`source` は、モデルのファイルの場所を示します。ファイルはバイナリー glTF (`.glb`) です。

| ソース | 例 | 読み方 |
|---|---|---|
| アプリのアセット | `asset:assets/models/hero.glb` | アプリのアセットから。ファイルは `pubspec.yaml` の `flutter: assets:` の下に列挙する |
| アドレス | `https://cdn.example.com/hero.glb` | アプリの `HttpTransport` Bean (なければプラットフォームのクライアント) を通じた一度の GET で。ブラウザーでも同じ |

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

- `lib/resources/` のファイルではありません。それらはアプリのコードに埋め込まれ、最大でも 1 メガバイトです。
- アドレスは `https` だけです。`http` は `spring.remote.allow-insecure: true` のときだけ読まれます。
- ブラウザーでは、サーバーがページのオリジンを許可する必要があります (CORS)。また、`require-corp` の分離のもとでは、それ以外のものは別のオリジンから読み込まれません ([シーンのコスト](cost.md) を参照)。
- `source` のないモデルは、設定すべきキー `spring.flutter.scene.models.<name>.source` を示して失敗します。

アドレスにあるファイルは `RemoteModelResource` です。サーバーへの問い合わせは、モデルが読み込まれるときだけ行われます。成功でない応答は、アドレスとステータスを示して読み込みを失敗させます。

別の形式は、アプリの `SceneModelImporter` Bean です。スターターのもの (`GlbModelImporter`、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 と lazy

- eager なモデル (`preload: eager`) は、スプラッシュの表示中に読み込まれます。最初の画面は、それをすぐに持っています。
- lazy なモデルは、シーンが最初にそれを表示するときに読み込まれます。
- 設定されていなければ、モデルは `spring.flutter.scene.preload` に従います。そのデフォルトは `lazy` です。

どちらの場合も、一度だけ読み込まれて保持されます。画面から消えて戻ってきたモデルが、もう一度インポートされることはありません。

## シーンの中のモデル

`SpringSceneModel('hero')` は、モデルをシーンに表示します。テンプレートのクローンなので、使うたびに独自の変換とアニメーションを持ち、ジオメトリ、テクスチャ、マテリアルは GPU 上で共有されたままです。これはシーンウィジェットです。`SpringSceneView` (またはエンジン自身のシーンウィジェット) の子の中に置き、通常のウィジェットの中には置きません。

| パラメーター | 型 | 意味 |
|---|---|---|
| `name` (位置引数) | `String` | `spring.flutter.scene.models` でのモデルの名前 |
| `variant` | `String?` | モデルのマテリアルバリアント (`KHR_materials_variants`) |
| `animations` | `List<SceneAnimationSpec>` | どのアニメーションを、どのように再生するか |
| `placeholder` | `WidgetBuilder?` | 読み込み中に、その場所に置くシーンウィジェット |
| `error` | `Widget Function(BuildContext, Object)?` | 読み込みに失敗したときに、その場所に置くシーンウィジェット |
| `onLoaded` | `void Function(Node)?` | クローンがシーンに入ったときに、クローンとともに呼ばれる |
| `position`、`rotation`、`scale` | `Vector3?`、`Quaternion?`、`Vector3?` | 位置、向き、スケール |
| `visible` | `bool` | 描画されるかどうか。デフォルトは `true` |
| `components` | `List<Component>` | そのノードの振る舞い (エンジンの `Component`) |
| `children` | `List<Widget>` | そのノードの下のシーンウィジェット |

ビューは、表示の前に自分の `SpringSceneModel` ウィジェットを待ちます。そのため、作りかけのシーンが描画されることはありません。

## コードの中のモデル

`SceneModels` (`sceneModels`) は、モデルをコードに渡します。

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

  final ObjectProvider<SceneModels> models;

  // シーンをオフにしてアプリが動くときは Bean がない。
  Future<void> open() async => models.getIfAvailable()?['hero'].load();
}
```

| `SceneModels` のメンバー | 意味 |
|---|---|
| `models['hero']` | モデルの `SceneModelHandle`。未知の名前は、存在する名前を示して失敗する |
| `names`、`all`、`eager` | 名前、すべてのモデル、スプラッシュとともに読み込まれるモデル |
| `contains(name)` | その名前のモデルがあるかどうか |

| `SceneModelHandle` のメンバー | 意味 |
|---|---|
| `load()` | モデルを一度だけ読み込む。どの呼び出しも同じ読み込みを返す。まだ起動していなければエンジンを起動する |
| `reload()` | 失敗の後に、もう一度読み込む |
| `state` | `idle`、`loading`、`ready`、`failed` (`SceneModelState`) |
| `template` | 読み込まれたノードツリー。使うたびにクローンされる。`state` が `ready` になるまでは `null` |
| `failure` | 読み込みが失敗したときに投げられたもの |
| `name`、`location`、`eager` | 名前、プロパティが示すファイルの場所、スプラッシュとともに読み込まれるかどうか |
| `bytes`、`readTook`、`importTook` | ファイルの大きさ、読む (アドレスならダウンロードする) のにかかった時間、インポートにかかった時間 |

ハンドルは `ChangeNotifier` です。`state` が変わるとリスナーに通知します。

## モデルが失敗したとき

読み込みに失敗したモデルは、警告としてログに出て、`SceneFailedEvent` として発行されます。起動は続きます。失敗した eager なモデルは飛ばされ、そのシーンはプレースホルダーを表示します。ハンドルの `reload()` がもう一度試します。

## 関連項目

- [ウィジェットとしてのシーン](scenes.md)
- [イベントと言葉で表す起動](start.md): 読み込みのイベント
- [デバッグタブ](debug-tab.md): すべてのモデルを名前で、そのコストとともに
- [アセットとフォント](../spring-boot-starter-flutter/assets-and-fonts.md)
- [HTTP トランスポート](../spring-web-dart/http-transport.md)
