
# イベントと言葉で表す起動

エンジンはアプリのために一度だけ起動し、その起動の各ステップはアプリケーションイベントです。エンジン、各モデル、失敗です。`SceneStatus` は、現在のステップを言葉で表したもので、ローダーがそれを伝えます。スプラッシュは eager なものを待ちます。

## 使う理由

エンジンの起動ではシェーダーがコンパイルされ、モデルは読んでインポートするファイルです。どちらも、ユーザーに見える時間がかかります。そのすべてに "Loading…" を表示するアプリは、知っていることより少ないことしか伝えません。ここでは、ステップは他のイベントと同じイベントで、その言葉は他のメッセージと同じメッセージです。

## 例

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

  // 読み込みが終わったモデルを一つずつ聞く。
  @EventListener()
  void onLoaded(SceneModelLoadedEvent event) => names.add(event.name);
}
```

```properties
# lib/resources/messages.properties
scene.loading.engine=Compiling shaders…
scene.loading.model=Loading {0}, {1} of {2}…
```

```dart
// ローダーの中で。`status` は SceneStatus Bean:
// "Compiling shaders…"、次に "Loading hero, 2 of 5…"。
ValueListenableBuilder(
  valueListenable: status,
  builder: (context, step, _) => Text(status.text ?? ''),
)
```

## エンジンの一度きりの起動

`spring.flutter.scene.preload` は、エンジンがいつ起動するかを示します。

| 値 | エンジンが起動する時 |
|---|---|
| `lazy` (デフォルト) | 最初のシーンが表示されるとき。その間はプレースホルダーが表示される |
| `eager` | スプラッシュとともに。アプリは、エンジンの準備ができた状態で現れる |

eager なモデルとアプリケーションのシーンも、スプラッシュとともにエンジンを起動します。起動は `sceneEngine` Bean (`SceneEngine`) のものです。`start()` は、どの呼び出し元にも同じ起動を返します。シーンが描画できるなら `true`、起動が失敗したなら `false` です。

## イベント

各ステップは `SceneEvent` で、他のアプリケーションイベントと同じように聞きます ([@EventListener](../spring-core-dart/events/event-listener.md) を参照)。

| イベント | いつ | 持っているもの |
|---|---|---|
| `SceneEngineStartingEvent` | エンジンが起動する。シェーダーがコンパイルされる | `backend` |
| `SceneEngineReadyEvent` | エンジンが起動した | `backend`、`took` |
| `SceneModelLoadingEvent` | モデルが読み込まれている | `name`、`location`、`index`、`count` (一緒に読み込まれるモデルの中での順番) |
| `SceneModelLoadedEvent` | モデルが読み込まれた | `name`、`took`、`bytes` |
| `SceneReadyEvent` | スプラッシュとともに求められたものがすべて準備できた | `took` |
| `SceneFailedEvent` | ステップが失敗した。アプリは動き続ける | `step` (`SceneStep.engine`、`model`、`application`)、モデルなら `name`、`error` |
| `SceneUnavailableEvent` | ここではシーンが描画されない。一度だけ伝えられる | `reason` (`SceneUnavailable.off` または `engine`) |

## 言葉

イベントは `MessageSourceResolvable` です。その言葉は、コードによってアプリのメッセージから取られ、なければイベント自身の英語になります。

| コード | 引数 | デフォルトのテキスト |
|---|---|---|
| `scene.loading.engine` | なし | Compiling shaders |
| `scene.ready.engine` | なし | The 3D engine is ready |
| `scene.loading.model` | `{0}` 名前、`{1}` 順番、`{2}` 総数 | Loading {0}, {1} of {2} |
| `scene.ready.model` | `{0}` 名前 | {0} is loaded |
| `scene.ready` | なし | The scenes are ready |
| `scene.failed.engine` | なし | The 3D engine did not start |
| `scene.failed.model` | `{0}` 名前 | {0} did not load |
| `scene.failed.application` | なし | The application's scene was not made |
| `scene.unavailable.off` | なし | Scenes are turned off |
| `scene.unavailable.engine` | なし | Scenes cannot be drawn on this device |

`messages.properties` のキーがステップの言葉を変え、`messages_ja.properties` がそれを日本語で伝えます。[メッセージと言語](../spring-boot-starter-flutter/messages.md) を参照してください。

## SceneStatus

`SceneStatus` (`sceneStatus`) は、ローダーのための現在のステップです。何かが読み込まれている間に最後に発行されたステップの `ValueListenable` です。

| メンバー | 意味 |
|---|---|
| `value` | 現在の `SceneEvent`。何も読み込まれていなければ `null` |
| `text` | 言葉で表した現在のステップ。何も読み込まれていなければ `null` |
| `history` | これまでに聞いたすべてのステップ。古い順 |

シーンをオフにすると、この Bean はありません。ウィジェットは、存在しないかもしれない Bean として受け取ります ([シーンが描画されない場所](without-scenes.md) を参照)。

## スプラッシュが待つもの

起動のうちシーンの部分は `SplashTask` (`sceneStart`) なので、スプラッシュは他のタスクと同じようにそれを待ち、ローダーはステップとともに進みます。

- エンジン。`preload: eager`、eager なモデル、またはアプリケーションのシーンがあるとき。
- eager なモデル。一つずつ順に。
- アプリケーションのシーン (`spring.flutter.scene.app.enabled`)。

eager なものが何もなければ、何もしません。エンジンは、最初のシーンが表示されるときに起動します。`render: off` でも何もしません。失敗したステップが起動を止めることはありません。すべてのスプラッシュのタスクの制限が、これにも当てはまります。[スプラッシュのタスク](../spring-boot-starter-flutter/splash.md#スプラッシュのタスク) を参照してください。

## Spring (Java) との対応

Spring には、これらのイベントに相当するものはありません。発行と受け取りは Spring 自身のイベントと同じで、`ApplicationEventPublisher` と `@EventListener` です。テキストは、`MessageSourceResolvable` として `MessageSource` が解決します。

## 関連項目

- [モデル](models.md)
- [アプリケーションのシーン](application-scene.md)
- [エンジンのシェーダー](shaders.md): エンジンの起動にかかる時間
- [スプラッシュと起動](../spring-boot-starter-flutter/splash.md)
- [MessageSource](../spring-core-dart/messages/message-source.md)
