サポート終了通知: 2026 年 5 月 20 日に、 AWS は のサポートを終了します AWS SimSpace Weaver。2026 年 5 月 20 日以降、 SimSpace Weaver コンソールまたは SimSpace Weaver リソースにアクセスできなくなります。詳細については、[AWS SimSpace Weaver 「サポート終了](https://docs.aws.amazon.com/simspaceweaver/latest/userguide/simspaceweaver-end-of-support.html)」を参照してください。
翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# の使用 SimSpace Weaver
この章では、 SimSpace Weaverで独自のアプリケーションを構築するのに役立つ情報とガイダンスを提供します。
**Topics**
+ [シミュレーションの設定](working-with_configuring-simulation.md)
+ [シミュレーションの最大期間](working-with_max-duration.md)
+ [アプリケーション開発](working-with_developing-apps.md)
+ [クライアントアプリケーションの開発](working-with_developing-client-applications.md)
+ [カスタムアプリケーションの IP アドレスとポート番号を取得する](working-with_get-ip.md)
+ [Unreal Engine ビュークライアントの起動](working-with_unreal-client.md)
+ [でのローカル開発 SimSpace Weaver](working-with_local-development.md)
+ [AWS SimSpace Weaver アプリケーション SDK](working-with_app-sdk.md)
+ [AWS SimSpace Weaver デモフレームワーク](working-with_demo-framework.md)
+ [Service Quotas との連携](working-with_quotas.md)
+ [シミュレーションのデバッグ](working-with_debugging.md)
+ [カスタムコンテナ](working-with_custom-containers.md)
+ [Python の使用](working-with_python.md)
+ [他のエンジンのサポート](working-with_engines.md)
+ [でのライセンスソフトウェアの使用 AWS SimSpace Weaver](working-with_byol.md)
+ [を使用した リソースの管理 AWS CloudFormation](working-with_cloudformation.md)
+ [スナップショット](working-with_snapshots.md)
+ [メッセージング](working-with_messaging.md)
# シミュレーションの設定
**シミュレーションスキーマ** (または**スキーマ**) は、シミュレーションの設定を指定する YAML フォーマットのテキストファイルです。複数のシミュレーションの開始に同じスキーマを使用できます。スキーマファイルは、シミュレーションのプロジェクトフォルダにあります。任意のテキストエディタを使用してファイルを編集できます。 は、シミュレーションを開始するときに SimSpace Weaver のみスキーマを読み取ります。スキーマファイルに加えた編集は、編集後に開始する新しいシミュレーションにのみ影響します。
シミュレーションを設定するには、シミュレーションスキーマファイルを編集します (オペレーティングシステムに適したパス区切り文字を使用します）。
```
project-folder\tools\project-name-schema.yaml
```
シミュレーションスキーマは、新しいシミュレーションの作成時にアップロードします。プロジェクトのクイックスタートヘルパースクリプトは、シミュレーションを構築するプロセスの一環としてスキーマをアップロードします。
```
project-folder\tools\windows\quick-start.py
```
クイックスタートスクリプトの実行の詳細については、このガイドの[入門](getting-started.md)章[詳細なチュートリアル](getting-started_detailed.md)の「」を参照してください。
## シミュレーションの設定パラメータ
シミュレーションスキーマには、以下のようなブートストラップ情報が含まれています。
+ **シミュレーションプロパティ** — SDK バージョンおよびコンピューティングの設定 ([ワーカー](w2aac51.md#glossary_worker)のタイプと数)
+ **クロック** — ティックレートと許容誤差
+ **空間パーティショニング戦略** — 空間トポロジ (グリッドなど)、境界、配置グループ (ワーカーの空間パーティショングループ)
+ **ドメインとそのアプリケーション** — アプリケーションバケット、パス、起動コマンド
SimSpace Weaver は、スキーマ設定を使用して、空間パーティションの設定と配置、アプリの起動、指定したティックレートでのシミュレーションの進め方を行います。
**注記**
SimSpace Weaver アプリケーション SDK の create-project スクリプトは、サンプルアプリケーションに基づいてシミュレーションスキーマを自動的に生成します。
以下のトピックでは、シミュレーションスキーマのパラメータについて説明します。シミュレーションスキーマの詳細な説明については、[SimSpace Weaver シミュレーションスキーマリファレンス](schema-reference.md) を参照してください。
**Topics**
+ [シミュレーションの設定パラメータ](#working-with_configuring-simulation_config-parameters)
+ [SDK のバージョン](working-with_configuring-simulation_sdk-version.md)
+ [シミュレーションプロパティ](working-with_configuring-simulation_simulation-properties.md)
+ [ワーカー](working-with_configuring-simulation_workers.md)
+ [クロック](working-with_configuring-simulation_clock.md)
+ [パーティショニング戦略](working-with_configuring-simulation_partitioning-strategies.md)
+ [ドメイン](working-with_configuring-simulation_domains.md)
# SDK のバージョン
`sdk_version` フィールドは、スキーマがフォーマット SimSpace Weaver されている のバージョンを指定します。有効な値: `1.17`、`1.16`、`1.15`、`1.14`、`1.13`、`1.12`
**重要**
`sdk_version` の値には、メジャーバージョン番号と最初のマイナーバージョン番号のみが含まれます。例えば、値 `1.12` は `1.12.0`、`1.12.1`、`1.12.2` などのすべてのバージョン `1.12.x` を指定します。
# シミュレーションプロパティ
スキーマの `simulation_properties` セクションでは、エンティティのインデックスフィールド (通常は空間位置) のログ記録設定とデータタイプを指定します。
```
simulation_properties:
log_destination_service: "logs"
log_destination_resource_name: "MySimulationLogs"
default_entity_index_key_type: "Vector3"
```
`log_destination_service` の値によって、`log_destination_resource_name` の値の解釈が決まります。現在、サポートされている値は `logs` のみです。これは、`log_destination_resource_name` の値が Amazon CloudWatch Logs のロググループの名前であることを意味します。
**注記**
ログ記録はオプションです。ログ送信先のプロパティを設定しない場合、シミュレーションではログは生成されません。
`default_entity_index_key_type` プロパティは必須です。唯一の有効な値は `Vector3` です。
# ワーカー
`workers` セクションでは、シミュレーションに使用するワーカーのタイプと数を指定します。 は、Amazon EC2 インスタンスタイプにマッピングされる独自のワーカータイプ SimSpace Weaver を使用します。
```
workers:
MyComputeWorkers:
type: "sim.c5.24xlarge"
desired: 1
```
## マルチワーカーシミュレーションを有効にする
複数のワーカーを使用するシミュレーションを作成できます。デフォルトでは、シミュレーションは 1 人のワーカーを使用します。シミュレーションを開始する前に、シミュレーションスキーマを変更する必要があります。
**注記**
すでに開始されているシミュレーションは変更できません。実行中のシミュレーションで複数のワーカーを有効にする場合は、まずシミュレーションを停止して削除する必要があります。
複数のワーカーを使用するには、コンピュートインスタンスの `desired` の数を 1 より大きい値に設定します。各ワーカーにはアプリケーションの最大数があります。詳細については、「」を参照してください[SimSpace Weaver エンドポイントとクォータ](service-quotas.md)。 SimSpace Weaver は、ワーカーのアプリケーション数がこの制限を超えた場合にのみ、複数のワーカーを使用します。 は、使用可能なワーカーのいずれかにアプリケーションを配置 SimSpace Weaver できます。特定のワーカーへのアプリケーションの配置は保証されません。
以下のスキーマスニペットは、2 人のワーカーをリクエストするシミュレーションの設定を示しています。 SimSpace Weaver はアプリケーションの数がワーカーあたりの最大アプリケーション数を超えると、2 番目のワーカーの割り当てを試みます。
```
workers:
MyComputeWorkers:
type: "sim.c5.24xlarge"
desired: 2
```
# クロック
この `clock` セクションではシミュレーションクロックのプロパティを指定します。現在、設定できるのは**ティックレート** (クロックがアプリケーションに送信する 1 秒あたりのティック数) のみです。ティックレートは最大レートです。ティックに対するすべての操作 (エンティティの更新など) は次のティックの開始前に終了する必要があるため、実効ティック率が低くなる可能性があります。ティックレートは**クロックレート**とも呼ばれます。
`tick_rate`の有効値は、スキーマで特定される `sdk_version` によって異なります。
**ティックレートの有効値**
+ `"1.14"` 以前のバージョン:
+ `10`
+ `15`
+ `30`
+ `"1.14"` 以降のバージョン:
+ `"10"`
+ `"15"`
+ `"30"`
+ `"unlimited"`
詳細については、「[無制限のティックレート](#working-with_configuring-simulation_clock_unlimited)」を参照してください。
**重要**
`"1.14"` 以前の `sdk_version` のスキーマでは、`tick_rate` の値は `30` のような**整数**です。
`"1.14"` 以降の `sdk_version` のスキーマでは、`tick_rate` の値は `"30"` のような**文字列**です。値には**二重引用符を含める必要があります**。
バージョン `"1.12"` または `"1.13"` のスキーマをバージョン `"1.14"` 以降に変換する場合は、`tick_rate` の値を二重引用符で囲む必要があります。
## 無制限のティックレート
`tick_rate` を `"unlimited"` に設定すると、コードの実行と同じ速さでシミュレーションを実行できます。無制限のティックレートで、 はすべてのアプリが現在のティックのコミットを完了した直後に次のティック SimSpace Weaver を送信します。
**重要**
1.14.0 より前の SimSpace Weaver バージョンでは、無制限のティックレートはサポートされていません。スキーマの `sdk_version` の最小値は `"1.14"` です。
**SimSpace Weaver Local で無制限のティックレート**
SimSpace Weaver Local はスキーマでティックレートが 10 kHz (10000) と指定されているかのように `"unlimited"` を実装します。その効果は、 AWS クラウドでの無制限ティックレートと同じです。スキーマでは `tick_rate: "unlimited"` を引き続き指定できます。SimSpace Weaver Local の詳細については、「[でのローカル開発 SimSpace Weaver](working-with_local-development.md)」を参照してください。
## クロックに関するよくある質問
### Q1. 開始したシミュレーションを別のティックレートを使用するように変更できますか?
ライフサイクルのどの段階においても、 AWS クラウド にすでに存在しているシミュレーションのティックレートを変更することはできません。また、SimSpace Weaver Local で実行中のシミュレーションのティックレートは、変更できません。`tick_rate` をスキーマに設定して、そのスキーマから新しいシミュレーションを開始できます。
### Q2. 1.14 以前のバージョンで、無制限のティックレートでシミュレーションを実行できますか？
いいえ、1.14.0 以前のバージョンでは無制限のティックレートはサポートされていません。
## クロックに関するエラーのトラブルシューティング
シミュレーションが開始されない場合は、**DescribeSimulation** API の出力で `"StartError"` の値を確認できます。スキーマに無効な `tick_rate` の値があると、以下のエラーが発生します。
**注記**
ここに示すエラー出力は、読みやすくするために複数行で表示されています。実際のエラー出力は 1 行です。
+ `sdk_version` は `"1.14"` よりも前で、`tick_rate` の値は無効な整数です。有効な値: `10`、`15`、`30`
```
"[{\"errorType\":\"SchemaFormatInvalid\",\"errorMessage\":
\"$.clock.tick_rate: does not have a value in the enumeration [10, 15, 30]\"}]"
```
+ `sdk_version` は `"1.14"` よりも前で、`tick_rate` の値は文字列です。有効値: `10`、`15`、`30`
```
"[{\"errorType\":\"SchemaFormatInvalid\",\"errorMessage\":
\"$.clock.tick_rate: does not have a value in the enumeration [10, 15, 30]\"},
{\"errorType\":\"SchemaFormatInvalid\",
\"errorMessage\":\"$.clock.tick_rate: string found, integer expected\"}]"
```
+ `sdk_version` は `"1.14"` よりも後で、`tick_rate` の値は無効な文字列です。有効な値: `"10"`、`"15"`、`"30"`、`"unlimited"`
```
"[{\"errorType\":\"SchemaFormatInvalid\",\"errorMessage\":
\"$.clock.tick_rate: does not have a value in the enumeration [10, 15, 30, unlimited]\"}]"
```
+ `sdk_version` は `"1.14"` よりも後で、`tick_rate` の値は整数です。有効な値: `"10"`、`"15"`、`"30"`、`"unlimited"`
```
"[{\"errorType\":\"SchemaFormatInvalid\",\"errorMessage\":
\"$.clock.tick_rate: does not have a value in the enumeration [10, 15, 30, unlimited]\"},
{\"errorType\":\"SchemaFormatInvalid\",
\"errorMessage\":\"$.clock.tick_rate: integer found, string expected\"}]"
```
# パーティショニング戦略
`partitioning_strategies` セクションでは、空間アプリケーションのパーティションの設定プロパティを指定します。パーティショニング戦略 (このセクションではプロパティのセット) に独自の名前を指定し、それを空間アプリケーションの設定に使用します。
```
partitioning_strategies:
MyGridPartitioning:
topology: "Grid"
aabb_bounds:
x: [0, 1000]
y: [0, 1000]
grid_placement_groups:
x: 1
y: 1
```
`topology` プロパティは、シミュレーションで使用する座標システムのタイプを指定します。`Grid` 値は 2 次元 (2D) グリッドを指定します。
`Grid` トポロジーの場合、シミュレーション空間は軸に沿ったバウンディングボックス (AABB) としてモデル化されます。AABB の各軸の座標境界を `aabb_bounds` プロパティで指定します。シミュレーションに空間的に存在するすべてのエンティティは、AABB 内にある必要があります。
## グリッド配置グループ
**プレイスメントグループは**、同じワーカー SimSpace Weaver に配置する空間アプリケーションパーティションのコレクションです。`grid_placement_groups` プロパティでプレイスメントグループ (グリッド内) の数と配置を指定します。 SimSpace Weaver は、プレイスメントグループ間でパーティションを均等に分散しようとします。同じ配置グループ内のパーティションを持つ空間アプリケーションの所有権エリアは、空間的に隣接します。
x \$1 y は希望するワーカー数と同じにすることをお勧めします。等しくない場合、 は使用可能なワーカー間でプレイスメントグループのバランスを取り SimSpace Weaver ます。
プレイスメントグループ設定を指定しない場合、 SimSpace Weaver はそれを自動的に計算します。
# ドメイン
ドメインの設定プロパティのセットの名前を指定します。ドメイン内のアプリケーションの起動設定によって、ドメインのタイプが決まります。
+ **`launch_apps_via_start_app_call`** - カスタムドメイン
+ **`launch_apps_by_partitioning_strategy`** — 空間ドメイン
+ **`launch_apps_per_worker`** (サンプルアプリケーションには含まれていません) — サービスドメイン
**重要**
SimSpace Weaver は、シミュレーションごとに最大 5 つのドメインをサポートします。これには、すべての空間ドメイン、カスタムドメイン、およびサービスドメインが含まれます。
```
domains:
MyViewDomain:
launch_apps_via_start_app_call: {}
app_config:
package: "s3://weaver-myproject-111122223333-us-west-2/MyViewApp.zip"
launch_command: ["MyViewApp"]
required_resource_units:
compute: 1
endpoint_config:
ingress_ports:
- 7000
MySpatialDomain:
launch_apps_by_partitioning_strategy:
partitioning_strategy: "MyGridPartitioning"
grid_partition:
x: 2
y: 2
app_config:
package: "s3://weaver-myproject-111122223333-us-west-2/MySpatialApp.zip"
launch_command: ["MySpatialApp"]
required_resource_units:
compute: 1
```
**注記**
SimSpace Weaver app SDK バージョン 1.12.x プロジェクトでは、アプリケーションの .zip ファイルとスキーマに別々のバケットを使用します。
weaver-*lowercase-project-name*-*account-number*-app-zips-*region*
weaver-*lowercase-project-name*-*account-number*-schemas-*region*
**Topics**
+ [アプリケーションの設定](working-with_configuring-simulation_domains_app-config.md)
+ [空間ドメインの設定](working-with_configuring-simulation_domains_spatial.md)
+ [ネットワークエンドポイント](working-with_configuring-simulation_domains_endpoints.md)
+ [サービスドメインの設定](working-with_configuring-simulation_domains_service-domains.md)
# アプリケーションの設定
アプリケーション (`app_config`) の設定は、そのドメインの設定の一部として指定します。すべてのタイプのドメインが同じアプリケーション設定プロパティを使用します。
```
app_config:
package: "s3://weaver-myproject-111122223333-us-west-2/MyViewApp.zip"
launch_command: ["MyViewApp"]
required_resource_units:
compute: 1
```
**注記**
SimSpace Weaver app SDK バージョン 1.12.x プロジェクトでは、アプリケーションの .zip ファイルとスキーマに別々のバケットを使用します。
weaver-*lowercase-project-name*-*account-number*-app-zips-*region*
weaver-*lowercase-project-name*-*account-number*-schemas-*region*
`package` プロパティは、S3 バケット内の zipP ファイルの S3 URI を指定します。zip ファイルには、アプリケーションの実行ファイル (*バイナリ*とも呼ばれます) と、必要なその他のリソース (ライブラリなど) が含まれます。アプリケーション実行ファイルの各インスタンスは、ワーカーのDockerコンテナで実行されます。
`launch_command` プロパティは、実行ファイルの名前と、アプリケーションを実行するためのコマンドラインオプションを指定します。`launch_command` の値は配列です。起動コマンド文字列全体の各トークンは、配列内の要素です。
**例**
+ 起動コマンドの場合: `MyTestApp --option1 value1`
+ 指定: `launch_command: ["MyTestApp", "-option1", "value1"]`
`required_resource_units` プロパティは、 SimSpace Weaver がこのアプリに割り当てるコンピューティングリソースユニットの数を指定します。コンピュートリソースユニットは、ワーカーの容量 (vCPU) とメモリ (RAM) の固定量です。この値を増やすと、ワーカー上で実行されるアプリケーションの処理能力を増やすことができます。各ワーカーが利用できるコンピュートリソースユニットの数には制限があります。詳細については、「[SimSpace Weaver エンドポイントとクォータ](service-quotas.md)」を参照してください。
# 空間ドメインの設定
空間ドメインの場合は、`partitioning_strategy` を指定する必要があります。このプロパティの値は、スキーマの別の部分で定義したパーティショニング戦略に付けた名前です。
```
MySpatialDomain:
launch_apps_by_partitioning_strategy:
partitioning_strategy: "MyGridPartitioning"
grid_partition:
x: 2
y: 2
app_config:
package: "s3://weaver-myproject-111122223333-us-west-2/MySpatialApp.zip"
launch_command: ["MySpatialApp"]
required_resource_units:
compute: 1
```
**注記**
SimSpace Weaver app SDK バージョン 1.12.x プロジェクトでは、アプリケーションの .zip ファイルとスキーマに別々のバケットを使用します。
weaver-*lowercase-project-name*-*account-number*-app-zips-*region*
weaver-*lowercase-project-name*-*account-number*-schemas-*region*
`Grid` トポロジ (このリリースでサポートされている唯一のトポロジ) を使用したパーティショニング戦略では、 は、このドメインの空間アプリケーションパーティションをグリッドに配置する SimSpace Weaver ように に指示します。`grid_partition` プロパティは、パーティショングリッドの行数と列数を指定します。
SimSpace Weaver は、パーティショングリッド内のセルごとに空間アプリケーションの 1 つのインスタンスを起動します。たとえば、空間ドメインに`grid_partition`値 `x: 2`と がある場合`y: 2`、空間ドメインには 2 \$1 2 = 4 つのパーティションがあります。 SimSpace Weaver は、空間ドメインで設定されたアプリケーションの 4 つのインスタンスを開始し、各アプリケーションインスタンスに 1 つのパーティションを割り当てます。
**トピック**
+ [空間ドメインのリソース要件](#working-with_configuring-simulation_domains_spatial_resources)
+ [複数の空間ドメイン](#working-with_configuring-simulation_domains_spatial_multiple)
+ [空間ドメインに関するよくある質問](#working-with_configuring-simulation_domains_spatial_faq)
+ [空間ドメインのトラブルシューティング](#working-with_configuring-simulation_domains_spatial_troubleshooting)
## 空間ドメインのリソース要件
各ワーカーには最大 17 コンピュートリソースユニットを割り当てることができます。空間ドメインの `app_config` セクションで、各空間アプリケーションが使用するコンピュートリソースユニットの数を指定します。
**Example 空間アプリケーションのコンピュートリソースユニットを示すスキーマスニペット**
```
MySpatialDomain:
launch_apps_by_partitioning_strategy:
partitioning_strategy: "MyGridPartitioning"
grid_partition:
x: 2
y: 2
app_config:
package: "s3://weaver-myproject-111122223333-artifacts-us-west-2/MySpatialApp.zip"
launch_command: ["MySpatialApp"]
required_resource_units:
compute: 1
```
ドメインが必要とするコンピュートリソースユニットの数を計算するには、グリッド内のセル数 (`grid_partition` 内で `x` \$1 `y`) に、空間アプリケーションに割り当てられたコンピュートリソースユニットの数を掛けます。
前の例では、ドメイン `MySpatialDomain` は以下を指定します。
+ `x`: `2`
+ `y`: `2`
+ `compute`: `1`
`MySpatialDomain` のグリッドには 2 \$1 2 = 4 個のセルがあります。空間ドメインには 4 \$1 1 = 4 のコンピュートリソースユニットが必要です。
スキーマで指定する全ドメインのコンピュートリソースユニットの総数は、ワーカー数に各ワーカーのコンピュートリソースユニットの最大数 (17) を掛けた `desired` の数以下でなければなりません。
## 複数の空間ドメイン
複数の空間ドメインを使用するようにシミュレーションを設定できます。例えば、1 つの空間ドメインを使用してシミュレーションの主なアクター (人や車など) を制御し、別の空間ドメインを使用して環境を制御できます。
また、複数の空間ドメインを使用して、シミュレーションのさまざまな部分に異なるリソースを割り当てることもできます。例えば、あるタイプのエンティティが他のタイプの 10 倍のエンティティインスタンスを持つタイプのエンティティの場合、エンティティタイプごとに異なるドメインを作成して各エンティティタイプを処理し、そのエンティティの数が多いドメインにより多くのリソースを割り当てることができます。
**重要**
SimSpace Weaver 1.14.0 より前のバージョンでは、複数の空間ドメインをサポートしていません。
**重要**
AWS SimSpace Weaver Local は現在、複数の空間ドメインをサポートしていません。SimSpace Weaver Local の詳細については、「[でのローカル開発 SimSpace Weaver](working-with_local-development.md)」を参照してください。
**重要**
SimSpace Weaver は、シミュレーションごとに最大 5 つのドメインをサポートします。これには、すべての空間ドメイン、カスタムドメイン、およびサービスドメインが含まれます。
### 複数の空間ドメインを設定する
複数の空間ドメインを設定するには、他の空間ドメイン定義を個別の名前付きセクションとしてスキーマに追加します。各ドメインは `launch_apps_by_partitioning_strategy` キーを指定する必要があります。次のスキーマの例を参照してください。
```
sdk_version: "1.14"
workers:
MyComputeWorkers:
type: "sim.c5.24xlarge"
desired: 1
clock:
tick_rate: "30"
partitioning_strategies:
MyGridPartitioning:
topology: Grid
aabb_bounds:
x: [0, 1000]
y: [0, 1000]
domains:
MySpatialDomain:
launch_apps_by_partitioning_strategy:
partitioning_strategy: "MyGridPartitioning"
grid_partition:
x: 2
y: 2
app_config:
package: "s3://weaver-myproject-111122223333-artifacts-us-west-2/MySpatialApp.zip"
launch_command: ["MySpatialApp"]
required_resource_units:
compute: 1
MySecondSpatialDomain:
launch_apps_by_partitioning_strategy:
partitioning_strategy: "MyGridPartitioning"
grid_partition:
x: 2
y: 2
app_config:
package: "s3://weaver-myproject-111122223333-artifacts-us-west-2/MySpatialApp2.zip"
launch_command: ["MySpatialApp2"]
required_resource_units:
compute: 1
```
### 空間ドメインをまとめて配置する
シナリオによっては、空間ドメインのパーティションを別のドメインのパーティションの隣に配置する場合があります。これにより、これらのパーティションが相互にクロスドメインサブスクリプションを作成する場合に、パフォーマンス特性が向上する可能性があります。
最上位キー`placement_constraints`をスキーマに追加して、どのドメインを一緒に配置 SimSpace Weaver するかを指定します。必要な `on_workers` キーは、スキーマ内の名前付き `workers` 設定を参照している必要があります。
**Example 空間ドメインをまとめて配置したスキーマスニペット**
```
workers:
MyComputeWorkers:
type: "sim.c5.24xlarge"
desired: 2
placement_constraints:
- placed_together: ["MySpatialDomain", "MySecondSpatialDomain"]
on_workers: ["MyComputeWorkers"]
```
**重要**
配置グループを使用する場合:
x \$1 y がワーカー数の倍数であることを確認します。
配置グループの値が、まとめて配置するドメインのグリッド寸法の共通除数であることを確認します。
プレイスメントグループを**使用しない**場合:
空間ドメイングリッドの 1 つの軸に、ワーカー数と等しい公約数があることを確認します。
グループ配置の詳細については、「[パーティショニング戦略](working-with_configuring-simulation_partitioning-strategies.md#working-with_configuring-simulation_partitioning-strategies_placement-groups)」を参照してください。
## 空間ドメインに関するよくある質問
### Q1. 既存のシミュレーションに別の空間ドメインを追加する方法を教えてください。
+ **実行中のシミュレーションの場合** — 実行中のシミュレーションの設定は変更できません。スキーマのドメイン設定を変更し、スキーマとアプリケーションの zip をアップロードして、新しいシミュレーションを開始します。
+ **新しいシミュレーションの場合** — ドメイン設定をスキーマに追加し、スキーマとアプリケーション zip をアップロードして、新しいシミュレーションを開始します。
## 空間ドメインのトラブルシューティング
ドメインの設定が無効な状態でシミュレーションを開始しようとすると、以下のエラーが表示される可能性があります。
```
"StartError": "[{\"errorType\":\"SchemaFormatInvalid\",\"errorMessage\":
\"We were unable to determine an arrangement of your domains that would fit
within the provided set of workers. This can generally be resolved by
increasing the number of workers if able, decreasing your domains\u0027
[\u0027\u0027grid_partition\u0027\u0027] values, or adjusting the
dimensions of your [\u0027\u0027grid_placement_groups\u0027\u0027].\"}]"
```
**可能性のある原因**
+ スキーマが、ワーカーで使用可能な量よりも多くのコンピュートリソースユニットをアプリケーションに割り当てています。
+ SimSpace Weaver は、ワーカーにドメインをまとめて配置する配置を決定できません。これは、複数の空間ドメインを指定しても、ドメイングリッド間に共通の除数や倍数がない場合 (2x4 グリッドと 3x5 グリッドの間など) に発生します。
# ネットワークエンドポイント
カスタムアプリケーションとサービスアプリケーションには、外部クライアントが接続できるネットワークエンドポイントを設定できます。`endpoint_config` 内の `ingress_ports` の値としてポート番号のリストを指定します。これらのポート番号はどちらも TCP と UDP です。カスタムアプリケーションまたはサービスアプリケーションは、 で指定したポート番号にバインドする必要があります`ingress_ports`。 SimSpace Weaver は実行時に動的にポート番号を割り当て、これらのポートを動的ポートにマッピングします。**describe-app** API は、アプリケーションが動的 (実際の) ポート番号を見つけ始めた後に呼び出すことができます。詳細については、「クイックスタートチュートリアル」の「[カスタムアプリケーションの IP アドレスとポート番号を取得するIP アドレスとポート番号を取得する](working-with_get-ip.md)」を参照してください。
```
domains:
MyViewDomain:
launch_apps_via_start_app_call: {}
app_config:
package: "s3://weaver-myproject-111122223333-us-west-2/MyViewApp.zip"
launch_command: ["MyViewApp"]
required_resource_units:
compute: 1
endpoint_config:
ingress_ports:
- 7000
```
**注記**
SimSpace Weaver app SDK バージョン 1.12.x プロジェクトでは、アプリケーションの .zip ファイルとスキーマに別々のバケットを使用します。
weaver-*lowercase-project-name*-*account-number*-app-zips-*region*
weaver-*lowercase-project-name*-*account-number*-schemas-*region*
**注記**
`endpoint_config` はカスタムアプリケーションとサービスアプリケーションのオプションプロパティです。`endpoint_config` を指定しない場合、アプリケーションにはネットワークエンドポイントがありません。
# サービスドメインの設定
ドメイン設定`launch_apps_per_worker:`に が存在する場合は、サービスアプリがあるサービスドメインであることを示します。 は、サービスアプリ SimSpace Weaver を起動および停止します。がアプリ SimSpace Weaver を起動および停止すると、アプリは*マネージドライフサイクル* を持つと見なされます。 SimSpace Weaver は現在、ワーカーごとに 1 つまたは 2 つのサービスアプリの開始をサポートしています。
**Example 各ワーカーで 1 つのサービスアプリケーションを起動するように設定されたドメインの例**
```
domains:
MyServiceDomain:
launch_apps_per_worker:
count: 1
app_config:
package: "s3://weaver-myproject-111122223333-app-zips-us-west-2/PlayerConnectionServiceApp.zip"
launch_command: ["PlayerConnectionServiceApp"]
required_resource_units:
compute: 1
endpoint_config:
ingress_ports:
- 9000
- 9001
```
**Example 各ワーカーで 2 つのサービスアプリケーションを起動するように設定されたドメインの例**
```
domains:
MyServiceDomain:
launch_apps_per_worker:
count: 2
app_config:
package: "s3://weaver-myproject-111122223333-app-zips-us-west-2/PlayerConnectionServiceApp.zip"
launch_command: ["PlayerConnectionServiceApp"]
required_resource_units:
compute: 1
endpoint_config:
ingress_ports:
- 9000
- 9001
```
# シミュレーションの最大期間
の各シミュレーション AWS SimSpace Weaver には、シミュレーションを実行できる最大時間を指定する*最大時間*設定があります。シミュレーションの開始時に、最大期間をパラメータとして指定します。[`StartSimulation` アプリケーションプログラミングインターフェイス (API)](https://docs.aws.amazon.com/simspaceweaver/latest/APIReference/API_StartSimulation.html) にはオプションのパラメータ `MaximumDuration` があります。パラメータの値は、分 (m または M)、時間 (h または H)、日 (d または D) です。たとえば、`1h` または `1H` は 1 時間を意味します。 SimSpace Weaver はこの制限に達すると、シミュレーションを停止します。
## 最大値
`MaximumDuration` の有効な最大値は `14D`、またはそれと同等の時間 (`336H`) または分 (`20160M`) で表されます。
## デフォルト値
`MaximumDuration` パラメータはオプションです。値を指定しない場合、 は の値 SimSpace Weaver を使用します`14D`。
## 最小値
`MaximumDuration` の有効値の最小値は、数値的には `0` と等価な値です。例えば、`0M`、`0H`、`0D` の値はすべて数値的には `0` と等価です。
最大期間に最小値を指定すると、シミュレーションは `STOPPING`状態に達するとすぐに `STARTED`状態に移行します。
## コンソールを使用したシミュレーションの開始
[SimSpace Weaver コンソール](https://console.aws.amazon.com/simspaceweaver)でシミュレーションを開始するときに**最大期間**の値を指定できます。[**シミュレーションの開始**] を選択するときに、[**シミュレーション設定**] フォームの [**最大期間**] フィールドに値を入力します。
**重要**
[**最大期間**] に値を指定しない場合は、 SimSpace Weaver は[デフォルトの値](#working-with_max-duration_default-value) (`14D`) を使用します。
## 最大期間に達したシミュレーションのステータス
が最大期間に達するシミュレーション SimSpace Weaver を自動的に停止すると、シミュレーション**のステータス**は `STOPPING` (進行中の場合) または になります`STOPPED`。[SimSpace Weaver コンソール](https://console.aws.amazon.com/simspaceweaver)では、シミュレーションの**ターゲットステータス**はまだ `STARTED` です。これは、ユーザーが最後に要求した状態であったためです。
# アプリケーション開発
SimSpace Weaver 開発では、シミュレーションが の Amazon Linuxで実行されるため、アプリケーションを構築するためのAmazon Linux 2 (AL2)環境が必要ですAWS Cloud。を使用している場合はWindows、 SimSpace Weaver アプリケーション SDK のスクリプトを使用して、 SimSpace Weaver アプリケーションの構築に必要な依存関係AL2で実行されるDockerコンテナを作成して起動できます。Windows Subsystem for Linux (WSL) またはネイティブ AL2 システムを使用して AL2 環境を起動することもできます。詳細については、「[のローカル環境をセットアップする SimSpace Weaver](setting-up_local.md)」を参照してください。
**注記**
ローカル開発環境の設定にかかわらず、 AWS クラウドで実行するためにアプリケーションをアップロードして実行すると、アプリケーションは Docker コンテナ内で実行されます。**アプリケーションはホストオペレーティングシステムに直接アクセスできません**。
**SimSpace Weaver アプリケーションの一般的なフロー**
1. アプリケーションを作成します。
1. ループ:
1. `Transaction` を作成して更新を開始します。
1. シミュレーションが停止する場合はループを終了します。
1. サブスクリプションと所有エンティティイベントを処理します。
1. シミュレーションを更新します。
1. `Transaction` をコミットして更新を終了します。
1. アプリケーションを破棄します。
## 空間アプリケーション
各空間アプリケーションには、シミュレーション世界の空間領域である所有権エリアがあります。空間アプリケーションの所有権エリアにあるエンティティは、アプリケーションに割り当てられたパーティションに保存されます。1 つの空間アプリケーションが、割り当てられたパーティション内のすべてのエンティティに対して完全な所有権 (読み取り権と書き込み権限) を持ちます。他のアプリケーションはそれらのエンティティに書き込むことはできません。空間アプリケーションはエンティティの状態を進めます。各空間アプリケーションはパーティションを 1 つだけ所有します。 SimSpace Weaver はエンティティの空間位置を使用してインデックスを作成し、空間アプリケーションパーティションに割り当てます。
SimSpace Weaver アプリケーション SDK はサンプルアプリケーションを提供します。サンプルアプリケーションの空間アプリケーションのソースコードは、次のフォルダにあります (オペレーティングシステムには正しいパス区切り文字を使用してください）。
```
sdk-folder\Samples\PathfindingSample\src\SpatialApp
```
## カスタムアプリケーション
シミュレーションを操作するカスタムアプリケーションを作成して使用します。
**カスタムアプリケーションは以下を実行できます**
+ エンティティを作成する
+ 他のパーティションをサブスクライブする
+ 変更をコミットする
**カスタムアプリケーションの一般的なフロー**
1. アプリケーションを作成します。
1. シミュレーション内の特定のリージョンをサブスクライブします。
1. `Transaction` を作成して最初の更新を開始します。
1. 特定のリージョンのサブスクリプションを作成します。
1. `Transaction` をコミットして最初の更新を終了します。
1. ループ:
1. `Transaction` を作成して更新を開始します。
1. シミュレーションが停止する場合はループを終了します。
1. 状態の変更を処理します。
1. `Transaction` をコミットして更新を終了します。
1. アプリケーションを破棄します。
カスタムアプリケーションがエンティティを作成したら、エンティティを空間ドメインに転送して、エンティティがシミュレーション内に空間的に存在するようにする必要があります。 はエンティティの空間位置 SimSpace Weaver を使用して、エンティティを適切な空間アプリケーションパーティションに配置します。エンティティを作成したカスタムアプリケーションは、空間ドメインに転送した後でそのエンティティを更新または削除することはできません。
SimSpace Weaver アプリケーション SDK はサンプルアプリケーションを提供します。サンプルアプリケーションに含まれるカスタムアプリケーションを、独自のカスタムアプリケーションのモデルとして使用できます。サンプルアプリケーションのビューアプリ (カスタムアプリ) のソースコードは、次のフォルダにあります (オペレーティングシステムには正しいパス区切り文字を使用します）。
```
sdk-folder\Samples\PathfindingSample\src\ViewApp
```
# クライアントアプリケーションの開発
クライアントをシミュレーションに接続すべき理由は、以下のとおりです。
+ 都市規模のシミュレーションにリアルタイムの交通情報を注入します。
+ *human-in-the-loop* シミュレーションを作成して、人間のオペレーターがシミュレーションの一部を制御します。
+ トレーニングシミュレーションなどで、ユーザーがシミュレーションを操作できるようにします。
これらの例のカスタムアプリケーションが、シミュレーションの状態と外部とのインターフェースとして機能します。クライアントはカスタムアプリケーションに接続してシミュレーションを操作します。
SimSpace Weaver は、クライアントアプリケーションとそのカスタムアプリケーションとの通信を処理しません。クライアントアプリケーションの設計、作成、運用、セキュリティ、およびクライアントアプリケーションとカスタムアプリケーションとの通信については、お客様の責任となります。 SimSpace Weaver はクライアントが接続できるように、各カスタムアプリケーションの IP アドレスとポート番号のみを公開します。
SimSpace Weaver アプリケーション SDK は、サンプルアプリケーション用のクライアントを提供します。これらのクライアントは、独自のクライアントアプリケーションのモデルとして使用できます。サンプルアプリケーションクライアントのソースコードは、以下のフォルダで確認できます。
------
#### [ Docker ]
```
sdk-folder\packaging-tools\clients\PathfindingSampleClients
```
------
#### [ WSL ]
**重要**
便宜上、これらの指示を使用します。これらは Windows Subsystem for Linux (WSL) で使用するためのもので、サポートされていません。詳細については、「[のローカル環境をセットアップする SimSpace Weaver](setting-up_local.md)」を参照してください。
```
sdk-folder/packaging-tools/clients/PathfindingSampleClients
```
------
サンプルアプリケーションクライアントの構築と使用の詳細については、「」のチュートリアルを参照してください[の開始方法 SimSpace Weaver](getting-started.md)。
# カスタムアプリケーションの IP アドレスとポート番号を取得する
シミュレーションを表示するには、カスタムアプリケーションを作成し、クライアントで接続します。詳細については、「」のチュートリアルを参照してください[の開始方法 SimSpace Weaver](getting-started.md)。次の手順を使用して、カスタムアプリケーションの IP アドレスとポート番号を取得できます。オペレーティングシステムに適したパス区切り文字 (`\`Windows や Linux など) `/` を使用します。
**IP アドレスとポート番号を取得する**
1. **ListSimulations** API を使用してシミュレーション名を取得します。
```
aws simspaceweaver list-simulations
```
出力例:
```
{
"Simulations": [
{
"Status": "STARTED",
"CreationTime": 1664921418.09,
"Name": "MyProjectSimulation_22-10-04_22_10_15",
"Arn": "arn:aws:simspaceweaver:us-west-2: 111122223333:simulation/MyProjectSimulation_22-10-04_22_10_15",
"TargetStatus": "STARTED"
}
]
}
```
1. **DescribeSimulation** API を使用して、シミュレーション内のドメインのリストを取得します。
```
aws simspaceweaver describe-simulation --simulation simulation-name
```
出力の `LiveSimulationState` セクションで `Domains` セクションを探します。
出力例:
```
"LiveSimulationState": {
"Domains": [
{
"Type": "",
"Name": "MySpatialSimulation",
"Lifecycle": "Unknown"
},
{
"Type": "",
"Name": "MyViewDomain",
"Lifecycle": "ByRequest"
}
],
```
1. **ListApps** API を使用して、ドメイン内のカスタムアプリケーションのリストを取得します。たとえば、サンプルプロジェクトのビュー (カスタム) アプリケーションのドメイン名は です`MyViewDomain`。出力でアプリケーション名を探します。
```
aws simspaceweaver list-apps --simulation simulation-name --domain domain-name
```
出力例:
```
{
"Apps": [
{
"Status": "STARTED",
"Domain": "MyViewDomain",
"TargetStatus": "STARTED",
"Name": "ViewApp",
"Simulation": "MyProjectSimulation_22-10-04_22_10_15"
}
]
}
```
1. **DescribeApp** API を使用して IP アドレスとポート番号を取得します。サンプルプロジェクトでは、ドメイン名は `MyViewDomain` で、アプリケーション名は `ViewApp` です。
```
aws simspaceweaver describe-app --simulation simulation-name --domain domain-name --app app-name
```
IP アドレスとポート番号は出力の `EndpointInfo` ブロックに含まれます。IP アドレスは `Address` の値で、ポート番号は `Actual` の値です。
出力例:
```
{
"Status": "STARTED",
"Domain": "MyViewDomain",
"TargetStatus": "STARTED",
"Simulation": "MyProjectSimulation_22-10-04_22_10_15",
"LaunchOverrides": {
"LaunchCommands": []
},
"EndpointInfo": {
"IngressPortMappings": [
{
"Declared": 7000,
"Actual": 4321
}
],
"Address": "198.51.100.135"
},
"Name": "ViewApp"
}
```
**注記**
`Declared` の値はアプリケーションコードのバインド先となるポート番号です。の値は、 がクライアントに SimSpace Weaver 公開して app に接続するポート番号`Actual`です。 は`Declared`ポートを`Actual`ポートに SimSpace Weaver マッピングします。
# Unreal Engine ビュークライアントの起動
次に移動します。
```
sdk-folder/Samples/PathfindingSample/tools/cloud
```
1. 以下のいずれかのコマンドを実行します:
+ Docker: `python quick-start.py`
+ WSL: `python quick-start.py --al2`
1. IP アドレスと「実際の」ポート番号を取得します。これらは、quick-start.py」を実行するコンソール出力に表示されるか、「」の手順に従って取得します[カスタムアプリケーションの IP アドレスとポート番号を取得するIP アドレスとポート番号を取得する](working-with_get-ip.md)。
1. 次に移動します。
```
sdk-folder/Clients/TCP/UnrealClient/lib
```
1. 次のコマンドを実行して NNG ライブラリを構築します。
```
cmake -S . -B build
cmake --build build --config RelWithDebInfo
cmake --install build
```
1. **テキストエディタ**で `view_app_url.txt` を開きます。
1. ビューアプリケーションの IP アドレスとポート番号で URL を更新します: `tcp://ip-address:actual-port-number` (`tcp://198.51.100.135:1234` のようになります)。
1. **Unreal エディタ**で、**再生**を選択します。
## トラブルシューティング
+ **NNG CMake のインストールステップが「管理者権限が必要な場合があります」で失敗します。**
```
CMake Error at build/_deps/nng-build/src/cmake_install.cmake:39 (file):
file cannot create directory: C:/Program Files
(x86)/ThirdPartyNngBuild/lib. Maybe need administrative privileges.
Call Stack (most recent call first):
build/_deps/nng-build/cmake_install.cmake:37 (include)
build/cmake_install.cmake:73 (include)
```
+ **解決策：** UnrealClient/lib ディレクトリに `nng.lib`または `nng.so`が存在する場合、このエラーは無視しても問題ありません。そうでない場合は、管理者権限を持つターミナルで cmake ビルドコマンドを実行してみてください。
+ **CMake to find a package configuration file provided by nng」：**
```
CMake Error at CMakeLists.txt:23 (find_package):
By not providing "Findnng.cmake" in CMAKE_MODULE_PATH this project has
asked CMake to find a package configuration file provided by "nng", but
CMake did not find one.
```
+ **解決策：** CMake で`Findnng.cmake`ファイルを見つけることができません。CMake を使用して構築する場合は、引数 を追加します`-DTHIRD_PARTY_LIB_PATH sdk-folder/ThirdParty`。CMake ビルドを再実行する前に、 `Findnng.cmake` ファイルがまだ `ThirdParty` ディレクトリにあることを確認します。
```
cmake -S . -B build -DTHIRD_PARTY_LIB_PATH sdk-folder/ThirdParty
cmake --build build --config RelWithDebInfo
cmake --install build
```
# でのローカル開発 SimSpace Weaver
SimSpace Weaver アプリケーションをローカルにデプロイして、迅速なテストとデバッグを行うことができます。
**要件**
+ 「[のセットアップ SimSpace Weaver](setting-up.md)」のステップを完了します。
**Topics**
+ [ステップ 1: ローカルシミュレーションを起動する](working-with_local_launch.md)
+ [ステップ 2: ローカルシミュレーションを表示する](working-with_local-development_view.md)
+ [ステップ 3: ローカルシミュレーションを停止する (Windows ではオプション）](working-with_local-development_stop-sim.md)
+ [でのローカル開発のトラブルシューティング SimSpace Weaver](working-with_local-development_troubleshooting.md)
# ステップ 1: ローカルシミュレーションを起動する
1. に移動
```
cd sdk-folder/Samples/sample-name/tools/local
```
1. 次のコマンドを実行して、シミュレーションをローカルでビルドして起動します。
```
python quick-start.py
```
このスクリプトは以下の処理を実行します。
1. プロジェクトをビルドします。
+ `quick-start.py` は、 build.py定義された `build_project`関数を呼び出します。このステップはプロジェクトによって異なります。PathfindingSample には、CMake が使用されます。CMake および Docker コマンド。 は build.py://www.com にあります。
1. ローカルシミュレーションを起動する
+ スクリプトは、スキーマで定義された空間パーティションごとに 1 つのローカルプロセスを起動します。
+ スクリプトは、スキーマで定義されたカスタムアプリケーションごとに 1 つのプロセスを起動します。
+ 空間アプリケーションが最初に起動され、次にカスタムアプリケーションが続きます。それぞれがスキーマに表示される順序で起動されます。
**重要**
コンソールの SSH セッションなど、GUI をサポートしていない環境で を起動する場合は、 `--noappwindow`オプションを使用してすべての出力を現在のターミナルにリダイレクトします。
**重要**
Linux ユーザーの場合、スクリプトはシステムに `xterm` コマンドがあることを前提としています。Linux ディストリビューションに `xterm` コマンドがない場合は、 `--noappwindow`オプションを使用してすべての出力を現在のターミナルにリダイレクトします。
+ -h, --help
+ これらのパラメータを一覧表示します。
+ --clean
+ ビルドする前に、ビルドディレクトリの内容を削除します。
+ --nobuild
+ プロジェクトの再構築をスキップします。
+ --noappwindow
+ アプリごとに新しいウィンドウを開かないでください。代わりに、stdout を現在のターミナルにリダイレクトします。
+ --logfile
+ コンソール出力をログファイルに書き込みます。
+ --consoleclient
+ 設定にリストされているコンソールクライアントを自動的に接続します。
+ --スキーマスキーマ
+ この呼び出しで使用するスキーマ。デフォルトは config.py://www.jp の「SCHEMA」です。
# ステップ 2: ローカルシミュレーションを表示する
ローカルシミュレーションを表示するには、SimSpaceWeaverAppSDKDistributable に含まれている任意のクライアントを使用できます。サンプルクライアントの構築と使用の詳細については、「」のチュートリアルを参照してください[の開始方法 SimSpace Weaver](getting-started.md)。
ローカルシミュレーションのビューアプリケーションに接続するには、クライアントの IP アドレスとポート番号を更新する必要があります。SimSpace Weaver Local では常に以下の値を使用します。
```
tcp://127.0.0.1:7000
```
選択したクライアントによっては、IP アドレスとポート番号を以下のように更新できます。
+ **Unreal** — `view_app_url.txt` の 1 行目の URL を変更します
+ **コンソール** — IP アドレスとポート番号 URL をパラメータとしてクライアントを起動します
# ステップ 3: ローカルシミュレーションを停止する (Windows ではオプション）
**注記**
このステップは Linux では必須ですが、Windows ではオプションです。
1. 以下に移動します。
```
sdk-folder/Samples/sample-name/tools/local
```
1. 次のコマンドを実行してローカルシミュレーションを停止し、共有メモリリソースを削除します。
```
python stop-and-delete.py
```
このスクリプトは以下の処理を実行します。
+ ローカルプロセスを停止します。
+ 共有メモリオブジェクトを削除します (Linux でのみ必要）。
**stop-and-delete.py 「https://https://https**
+ -h, --help
+ これらのパラメータを一覧表示します。
+ --stop
+ プロセスの停止のみを試みます。
+ --delete
+ 共有メモリリソースの削除のみを試みます。
+ --process
+ 停止するプロセスの名前。プロセス名がスキーマのパッケージ名と一致しない場合に使用します。
+ --スキーマスキーマ
+ この呼び出しで使用するスキーマ。デフォルトは、config.py://www.jp」の「SCHEMA」の値です。
# でのローカル開発のトラブルシューティング SimSpace Weaver
+ **Linux: xterm コマンドが見つかりません/開くことができません**
+ ローカルスクリプトは、Linux で を実行するときに xterm コマンドが存在することを前提としています。xterm コマンドがない場合、または GUI をサポートしていない環境で実行している場合は、クイックスタートスクリプトを実行するときに `--noappwindow`オプションを使用します。
+ ** アプリウィンドウが開いていません。 **
+ これは、ローカルシミュレーションがすぐにクラッシュしたときに発生します。クラッシュ後にコンソール出力を表示するには、クイックスタートスクリプトを実行するときに `--noappwindow`または `--logfile`オプションを使用します。
+ ** ビューアプリの起動後またはビュークライアントの接続後にシミュレーションがティックしません。 **
+ `—noappwindow` オプションを使用して を実行すると、通常、このような問題が解決されます。それ以外の場合は、数回再起動しても成功します (ただし、はるかに低いレートで）。
# AWS SimSpace Weaver アプリケーション SDK
SimSpace Weaver アプリケーション SDK にはAPIs が用意されています。 SimSpace Weaver これには以下の名前空間が含まれます。
+ **API** — API のコア定義とその使用方法
以下のライブラリとリンクします。
+ `libweaver_app_sdk_cxx_v1_full.so`
**重要**
ライブラリは、 AWS クラウドでアプリケーションを実行するとダイナミックリンクに使用できます。アプリケーションと一緒にアップロードする必要はありません。
**注記**
SimSpace Weaver アプリケーション SDK APIsシミュレーション内のデータを制御します。これらの APIsは、 SimSpace Weaver のサービスリソース (シミュレーション、アプリケーション、クロックなど) を制御する SimSpace Weaver サービス APIs とは別です AWS。詳細については、「[SimSpace Weaver API リファレンス](api-reference.md)」を参照してください。
**Topics**
+ [API メソッドは Result を返します。](working-with_app-sdk_return-result.md)
+ [最上位レベルでのアプリケーション SDK とのやり取り](working-with_app-sdk_top-level.md)
+ [シミュレーション管理](working-with_app-sdk_sim.md)
+ [サブスクリプション](working-with_app-sdk_sub.md)
+ [エンティティ](working-with_app-sdk_ent.md)
+ [エンティティイベント](working-with_app-sdk_events.md)
+ [Result とエラー処理](working-with_app-sdk_result.md)
+ [ジェネリックとドメインタイプ](working-with_app-sdk_generics.md)
+ [その他のアプリケーション SDK 操作](working-with_app-sdk_misc.md)
# API メソッドは Result を返します。
ほとんどの SimSpace Weaver API 関数には戻り値型 があります`Aws::WeaverRuntime::Result`。関数が正常に実行されると、`Result` には `T` が含まれます。それ以外の場合、`Result` には Rust App SDK からのエラーコードを表す `Aws::WeaverRuntime::ErrorCode` が含まれます。
**Example 例**
```
Result BeginUpdate(Application& app)
```
この方法:
+ `BeginUpdate()` が正常に実行された場合は `Transaction` を返します。
+ `BeginUpdate()` に失敗した場合は `Aws::WeaverRuntime::ErrorCode` を返します。
# 最上位レベルでのアプリケーション SDK とのやり取り
**ライフサイクル**
+ SimSpace Weaver アプリケーション SDK はアプリケーションのライフサイクルを管理します。アプリケーションのライフサイクル状態を読み取ったり書き込んだりする必要はありません。
**パーティション**
+ `Result AssignedPartitions(Transaction& txn);` を使用して、所有しているパーティションを取得します。
+ `Result AllPartitions(Transaction& txn);` を使用して、シミュレーション内のすべてのパーティションを取得します。
# シミュレーション管理
このセクションでは、一般的なシミュレーション管理タスクのソリューションについて説明します。
**Topics**
+ [シミュレーションを開始する](working-with_app-sdk_sim_start.md)
+ [シミュレーションを更新する](working-with_app-sdk_sim_update.md)
+ [シミュレーションを終了する](working-with_app-sdk_sim_terminate.md)
# シミュレーションを開始する
`CreateApplication()` を使用して、アプリケーションを作成します。
**Example 例**
```
Result applicationResult = Api::CreateApplication();
if (!applicationResult)
{
ErrorCode errorCode = WEAVERRUNTIME_EXPECT_ERROR(applicationResult);
std::cout << "Failed to create application. Error code " <<
static_cast>(errorCode) <<
" Last error message "<< Api::LastErrorMessage() << ".";
return 1;
}
/**
* Run simulation
*/
RunSimulation(std::move(applicationResult.assume_value()));
```
# シミュレーションを更新する
以下の `BeginUpdate` 関数を使用してアプリケーションを更新します。
+ `Result BeginUpdate(Application& app)`
+ `Result BeginUpdateWillBlock(Application& app)` — `BeginUpdate()` がブロックするかしないかを伝えます。
`Result Commit(Transaction& txn)` を使用して、以下の変更をコミットします。
**Example 例**
```
Result AppDriver::RunSimulation(Api::Application app) noexcept
{
while (true)
{
{
bool willBlock;
do
{
WEAVERRUNTIME_TRY(willBlock, Api::BeginUpdateWillBlock(m_app));
} while (willBlock);
}
WEAVERRUNTIME_TRY(Transaction transaction, Api::BeginUpdate(app));
/**
* Simulate app.
*/
WEAVERRUNTIME_TRY(Simulate(transaction));
WEAVERRUNTIME_TRY(Api::Commit(std::move(transaction)));
}
return Success();
}
```
# シミュレーションを終了する
`Result DestroyApplication(Application&& app)` を使用して、アプリケーションとシミュレーションを終了します。
他のアプリケーションは、`BeginUpdateWillBlock()` または `BeginUpdate()` への呼び出しから `ErrorCode::ShuttingDown` を受信すると、シミュレーションがシャットダウン中であることを認識します。アプリケーションが `ErrorCode::ShuttingDown` を受信すると、`Result DestroyApplication(Application&& app)` 呼び出しを行って自動的に終了できます。
**Example 例**
```
Result AppDriver::EncounteredAppError(Application&& application) noexcept
{
const ErrorCode errorCode = WEAVERRUNTIME_EXPECT_ERROR(runAppResult);
switch (errorCode)
{
case ErrorCode::ShuttingDown:
{
// insert custom shutdown process here.
WEAVERRUNTIME_TRY(Api::DestroyApplication(std::move(application)));
return Success();
}
default:
{
OnAppError(errorCode);
return errorCode;
}
}
}
```
**重要**
`Api::Commit()` の後にのみ `Result DestroyApplication(Application&& app)` を呼び出しできます。更新中にアプリケーションを破棄すると、未定義の動作が発生する可能性があります。
**重要**
プログラムが終了する前に `DestroyApplication()` を呼び出して、アプリケーションの正常終了レポートを確認する必要があります。
プログラムの終了時に `DestroyApplication()` 呼び出しに失敗すると、ステータスは `FATAL` とみなされます。
# サブスクリプション
サブスクリプション領域とドメイン ID を使用してサブスクリプションを作成します。ドメイン ID は、そのサブスクリプション領域を所有するドメインを表します。`BoundingBox2F32` はサブスクリプション領域を表します。以下の関数を使用してサブスクリプションを作成します。
```
Result CreateSubscriptionBoundingBox2F32(Transaction& txn, DomainId id, const BoundingBox2F32& boundingBox)
```
**Example 例**
```
Result CreateSubscriptionInSpatialDomain(Transaction& transaction)
{
WEAVERRUNTIME_TRY(Api::PartitionSet partitionSet, Api::AllPartitions(transaction));
Api::DomainId spatialDomainId;
for (const Api::Partition& partition : partitionSet.partitions)
{
if (partition.domain_type == Api::DomainType::Spatial)
{
/**
* Get the spatial domain ID.
*/
spatialDomainId = partition.domain_id;
break;
}
}
constexpr Api::BoundingBox2F32 subscriptionBounds {
/* min */ { /* x */ 0, /* y */ 0 },
/* max */ { /* x */ 1000, /* y */ 1000 } }
WEAVERRUNTIME_TRY(
Api::SubscriptionHandle subscriptionHandle,
Api::CreateSubscriptionBoundingBox2F32(
transaction,
spatialDomainId,
subscriptionBounds));
return Success();
}
```
`CreateSubscriptionBoundingBox2F32()` から返送された `Api::SubscriptionHandle` を使用してサブスクリプションを変更できます。以下の関数の引数として渡します。
```
Result ModifySubscriptionBoundingBox2F32(Transaction& txn, SubscriptionHandle handle, const BoundingBox2F32& boundingBox)
```
```
Result DeleteSubscription(Transaction& txn, SubscriptionHandle handle)
```
# エンティティ
`Store`と `Load` API を呼び出すには、`CreateEntity()`、またはエンティティがアプリケーションのサブスクリプション領域に入った際の所有権変更イベントから返された、`Result` の `Api:Entity` を使用します (詳細については、「[エンティティイベント](working-with_app-sdk_events.md)」を参照してください)。これらの API で使用できるように、`Api::Entity` オブジェクトを追跡することをお勧めします。
**Topics**
+ [エンティティを作成する](working-with_app-sdk_ent_create.md)
+ [エンティティを空間ドメインに転送します。](working-with_app-sdk_ent_transfer.md)
+ [エンティティフィールドデータの書き込みおよび読み取り](working-with_app-sdk_ent_readwrite.md)
+ [エンティティの位置を保存する](working-with_app-sdk_ent_store-position.md)
+ [エンティティの位置をロードする](working-with_app-sdk_ent_load-position.md)
# エンティティを作成する
`CreateEntity()` を使用して、エンティティを作成します。この関数に渡す、`Api::TypeId` の意味を定義します。
```
Namespace
{
constexpr Api::TypeId k_entityTypeId { /* value */ 512 };
}
Result CreateEntity(Transaction& transaction)
{
WEAVERRUNTIME_TRY(
Api::Entity entity,
Api::CreateEntity(
transaction, Api::BuiltinTypeIdToTypeId(k_entityTypeId )));
}
```
**注記**
0～511 の `Api::BuiltinTypeId` の値は予約されています。エンティティ TypeID (この例では `k_entityTypeId`) の値は 512 以上である必要があります。
# エンティティを空間ドメインに転送します。
カスタムアプリケーションまたはサービスアプリケーションでエンティティを作成したら、そのエンティティを空間ドメインに転送して、そのエンティティをシミュレーションに空間的に存在させる必要があります。空間ドメイン内のエンティティは、他のアプリケーションで読み取ったり、空間アプリケーションで更新したりできます。`ModifyEntityDomain()` API を使用してエンティティを空間ドメインに転送します。
```
AWS_WEAVERRUNTIME_API Result ModifyEntityDomain(Transaction& txn, const Entity& entity, DomainId domainId) noexcept;
```
`DomainId` が呼び出し元のアプリケーションに割り当てられた `Partition` と一致しない場合、`DomainId` は `DomainType::Spatial` `Domain` のものである必要があります。新しい `Domain` への所有権の転送は、`Commit(Transaction&&)` の間に行われます。パラメータ
`txn`
現在の `Transaction`。
`entity`
`Domain` の変更ターゲット `Entity`。
`domainId`
`Entity` の送信先 `Domain` の `DomainId`。
この API は、エンティティドメインが正常に変更された場合に `Success` を返します。
# エンティティフィールドデータの書き込みおよび読み取り
エンティティデータフィールドはすべて BLOB タイプです。1 つのエンティティには最大 1,024 バイトのデータを書き込むことができます。BLOB のサイズを大きくするとパフォーマンスが低下するため、BLOB はできるだけ小さくすることをお勧めします。BLOB に書き込むときは、データとその長さに SimSpace Weaver ポインタを渡します。BLOB から読み取ると、 SimSpace Weaver は読み取るポインタと長さを提供します。すべての読み取りは、アプリケーションが `Commit()` を呼び出す前に完了する必要があります。読み取りの呼び出しから返されたポインタは、アプリケーションが `Commit()` を呼び出すと無効になります。
**重要**
`Commit()` の後のキャッシュされた BLOB ポインタからの読み取りはサポートされないため、シミュレーションが失敗する可能性があります。
読み取りの呼び出しから返された BLOB ポインタへの書き込みはサポートされないため、シミュレーションが失敗する可能性があります。
**Topics**
+ [エンティティのフィールドデータを保存する](working-with_app-sdk_ent_readwrite_store.md)
+ [エンティティのフィールドデータをロードする](working-with_app-sdk_ent_readwrite_load.md)
+ [削除されたエンティティのフィールドデータの読み込み](working-with_app-sdk_ent_readwrite_load-removed.md)
# エンティティのフィールドデータを保存する
以下の例は、アプリケーションが所有するエンティティのフィールドデータを保存する (ステートファブリックに書き込む) 方法を示しています。以下の例では、以下の関数を使用します。
```
AWS_WEAVERRUNTIME_API Result StoreEntityField(
Transaction& txn,
const Entity& entity,
TypeId keyTypeId,
FieldIndex index,
std::int8_t* src,
std::size_t length) noexcept;
```
`Api::TypeId keyTypeId` パラメータは渡されたデータのデータタイプを表します。
`Api::TypeId keyTypeId` パラメータは `Api::BuiltinTypeId` から対応する `Api::TypeId` を受け取る必要があります。適切な変換がない場合は、`Api::BuiltinTypeId::Dynamic` を使用できます。
複雑なデータタイプの場合は、`Api::BuiltInTypeId::Dynamic` を使用します。
**注記**
`FieldIndex index` の値はゼロより大きい必要があります。値 0 はインデックスキー専用です (`StoreEntityIndexKey()` を参照してください)。
**Example プリミティブデータタイプを使用する例**
```
namespace
{
constexpr Api::FieldIndex k_isTrueFieldId { /* value */ 1 };
}
Result SetEntityFields(
Api::Entity& entity,
Transaction& transaction)
{
bool value = true;
auto* src = reinterpret_cast(value);
size_t length = sizeof(*value);
WEAVERRUNTIME_TRY(Api::StoreEntityField(
transaction,
entity,
Api::BuiltinTypeIdToTypeId(
Aws::WeaverRuntime::Api::BuiltinTypeId::Bool),
k_isTrueFieldId,
src,
length));
}
```
**Example struct を使用してデータを保持する例**
```
namespace
{
constexpr Api::FieldIndex k_dataFieldId { /* value */ 1 };
}
struct Data
{
bool boolData;
float floatData;
};
Result SetEntityFields(
Api::Entity& entity,
Transaction& transaction)
{
Data data = { /* boolData */ false, /* floatData */ -25.93 };
auto* src = reinterpret_cast(data);
size_t length = sizeof(*data);
WEAVERRUNTIME_TRY(Api::StoreEntityField(
transaction,
entity,
Api::BuiltinTypeIdToTypeId(
Aws::WeaverRuntime::Api::BuiltinTypeId::Dynamic),
k_dataFieldId,
src,
length));
}
```
# エンティティのフィールドデータをロードする
以下の例は、エンティティのフィールドデータをロードする (ステートファブリックから読み取る) 方法を示しています。以下の例では、以下の関数を使用します。
```
Result LoadEntityField(
Transaction& txn,
const Entity& entity,
TypeId keyTypeId,
FieldIndex index,
std::int8_t** dest) noexcept;
```
`Api::TypeId keyTypeId` パラメータは `Api::BuiltinTypeId` から対応する `Api::TypeId` を受け取る必要があります。適切な変換がない場合は、`Api::BuiltinTypeId::Dynamic` を使用できます。
**注記**
`FieldIndex` インデックスの値は 0 より大きい必要があります。値 0 はインデックスキー専用です (`StoreEntityIndexKey()` を参照してください)。
**Example プリミティブデータタイプを使用する例**
```
namespace
{
constexpr Api::FieldIndex k_isTrueFieldId { /* value */ 1 };
}
Result LoadEntityFields(
Api::Entity& entity,
Transaction& transaction)
{
std::int8_t* dest = nullptr;
WEAVERRUNTIME_TRY(Api::LoadEntityField(
transaction,
entity,
Api::BuiltinTypeIdToTypeId(
Aws::WeaverRuntime::Api::BuiltinTypeId::Bool),
k_isTrueFieldId,
&dest));
bool isTrueValue = *reinterpret_cast(dest);
}
```
**Example struct を使用してデータを保持する例**
```
namespace
{
constexpr Api::FieldIndex k_dataFieldId { /* value */ 1 };
}
struct Data
{
bool boolData;
float floatData;
};
Result LoadEntityFields(
Api::Entity& entity,
Transaction& transaction)
{
std::int8_t* dest = nullptr;
WEAVERRUNTIME_TRY(Api::LoadEntityField(
transaction,
entity,
Api::BuiltinTypeIdToTypeId(
Aws::WeaverRuntime::Api::BuiltinTypeId::Dynamic),
k_dataFieldId,
&dest));
Data dataValue = *reinterpret_cast(dest);
}
```
# 削除されたエンティティのフィールドデータの読み込み
アプリケーションの所有権とサブスクリプション領域から削除されたエンティティのエンティティフィールドデータをロードする (ステートファブリックから読み取る) ことはできません。以下の例では、`Api::ChangeListAction::Remove` の結果としてエンティティの `Api::LoadIndexKey()` を呼び出しているため、エラーが発生します。2 番目の例は、エンティティデータをアプリケーションに直接保存して読み込む正しい方法を示しています。
**Example 誤ったコードの例**
```
Result ProcessSubscriptionChanges(Transaction& transaction)
{
/* ... */
WEAVERRUNTIME_TRY(Api::SubscriptionChangeList subscriptionChangeList,
Api::AllSubscriptionEvents(transaction));
for (const Api::SubscriptionEvent& event :
subscriptionChangeList.changes)
{
switch (event.action)
{
case Api::ChangeListAction::Remove:
{
std::int8_t* dest = nullptr;
/**
* Error!
* This calls LoadEntityIndexKey on an entity that
* has been removed from the subscription area.
*/
WEAVERRUNTIME_TRY(Api::LoadEntityIndexKey(
transaction,
event.entity,
Api::BuiltinTypeIdToTypeId(
Api::BuiltinTypeId::Vector3F32),
&dest));
AZ::Vector3 position =
*reinterpret_cast(dest);
break;
}
}
}
/* ... */
}
```
**Example アプリケーションにエンティティデータを保存して読み込む正しい方法の例**
```
Result ReadAndSaveSubscribedEntityPositions(Transaction& transaction)
{
static std::unordered_map
positionsBySubscribedEntity;
WEAVERRUNTIME_TRY(Api::SubscriptionChangeList subscriptionChangeList,
Api::AllSubscriptionEvents(transaction));
for (const Api::SubscriptionEvent& event :
subscriptionChangeList.changes)
{
switch (event.action)
{
case Api::ChangeListAction::Add:
{
std::int8_t* dest = nullptr;
/**
* Add the position when the entity is added.
*/
WEAVERRUNTIME_TRY(Api::LoadEntityIndexKey(
transaction,
event.entity,
Api::BuiltinTypeIdToTypeId(
Api::BuiltinTypeId::Vector3F32),
&dest));
AZ::Vector3 position =
*reinterpret_cast(dest);
positionsBySubscribedEntity.emplace(
event.entity.descriptor->id, position);
break;
}
case Api::ChangeListAction::Update:
{
std::int8_t* dest = nullptr;
/**
* Update the position when the entity is updated.
*/
WEAVERRUNTIME_TRY(Api::LoadEntityIndexKey(
transaction,
event.entity,
Api::BuiltinTypeIdToTypeId(
Api::BuiltinTypeId::Vector3F32),
&dest));
AZ::Vector3 position =
*reinterpret_cast(dest);
positionsBySubscribedEntity[event.entity.descriptor->id] =
position;
break;
}
case Api::ChangeListAction::Remove:
{
/**
* Load the position when the entity is removed.
*/
AZ::Vector3 position = positionsBySubscribedEntity[
event.entity.descriptor->id];
/**
* Do something with position...
*/
break;
}
}
}
/* ... */
}
```
# エンティティの位置を保存する
整数データ構造を使用してエンティティの位置を保存 (ステートファブリックへの書き込み) できます。以下の例では、以下の関数を使用します。
```
Result StoreEntityIndexKey(
Transaction& txn,
const Entity& entity,
TypeId keyTypeId,
std::int8_t* src,
std::size_t length)
```
**注記**
以下の例に示すように、`Api::BuiltinTypeId::Vector3F32` から `Api::StoreEntityIndexKey()` を指定する必要があります。
**Example 配列を使用して位置を表す例**
```
Result SetEntityPositionByFloatArray(
Api::Entity& entity,
Transaction& transaction)
{
std::array position = { /* x */ 25, /* y */ 21, /* z */ 0 };
auto* src = reinterpret_cast(position.data());
std::size_t length = sizeof(position);
WEAVERRUNTIME_TRY(Api::StoreEntityIndexKey(
transaction,
entity,
Api::BuiltinTypeIdToTypeId(Api::BuiltinTypeId::Vector3F32),
src,
length));
}
```
**Example struct を使用して位置を表す例**
```
struct Position
{
float x;
float y;
float z;
};
Result SetEntityPositionByStruct(
Api::Entity& entity,
Transaction& transaction)
{
Position position = { /* x */ 25, /* y */ 21, /* z */ 0 };
auto* src = reinterpret_cast(&position);
std::size_t length = sizeof(position);
WEAVERRUNTIME_TRY(Api::StoreEntityIndexKey(
transaction,
entity,
Api::BuiltinTypeIdToTypeId(Api::BuiltinTypeId::Vector3F32),
src,
length));
}
```
# エンティティの位置をロードする
整数データ構造を使用してエンティティの位置をロードする (ステートファブリックから読み取る) ことができます。以下の例では、以下の関数を使用します。
**注記**
以下の例に示すように、`Api::BuiltinTypeId::Vector3F32` から `Api::LoadEntityIndexKey()` を指定する必要があります。
**Example 配列を使用して位置を表す例**
```
Result GetEntityPosition(Api::Entity& entity,
Transaction& transaction)
{
std::int8_t* dest = nullptr;
WEAVERRUNTIME_TRY(Aws::WeaverRuntime::Api::LoadEntityIndexKey(
transaction,
entity,
Api::BuiltinTypeIdToTypeId(
Aws::WeaverRuntime::Api::BuiltinTypeId::Vector3F32),
&dest));
std::array position =
*reinterpret_cast*>(dest);
}
```
**Example struct を使用して位置を表す例**
```
struct Position
{struct
float x;
float y;
float z;
};
Result GetEntityPosition(Api::Entity& entity, Transaction& transaction)
{
std::int8_t* dest = nullptr;
WEAVERRUNTIME_TRY(Aws::WeaverRuntime::Api::LoadEntityIndexKey(
transaction,
entity,
Api::BuiltinTypeIdToTypeId(
Aws::WeaverRuntime::Api::BuiltinTypeId::Vector3F32),
&dest));
Position position = *reinterpret_cast(dest);
}
```
# エンティティイベント
SimSpace Weaver アプリケーション SDK で次の関数を使用して、すべての所有権イベントとサブスクリプションイベントを取得できます。
+ `Result OwnershipChanges(Transaction& txn) `
+ `Result AllSubscriptionEvents(Transaction& txn) `
コールバック駆動型のエンティティイベント処理が必要な場合は、 SimSpace Weaver デモフレームワークを使用できます。詳細については、以下のヘッダーファイルを参照してください。
+ `sdk-folder/packaging-tools/samples/ext/DemoFramework/include/DemoFramework/EntityEventProcessor.h`
独自のエンティティイベント処理を作成することもできます。
**Topics**
+ [所有エンティティのイベントを繰り返し処理します。](working-with_app-sdk_events_own.md)
+ [登録したエンティティのイベントを繰り返し処理します。](working-with_app-sdk_events_sub.md)
+ [エンティティの所有権変更イベントを繰り返し処理します。](working-with_app-sdk_events_change.md)
# 所有エンティティのイベントを繰り返し処理します。
`OwnershipChanges()` を使用して、所有エンティティ (アプリケーションの所有領域にあるエンティティ) のイベントのリストを取得します。関数には以下のような署名があります。
```
Result OwnershipChanges(Transaction& txn)
```
次に、以下の例に示すように、ループを使用してエンティティを繰り返し処理します。
**Example 例**
```
WEAVERRUNTIME_TRY(Result ownershipChangesResult, Api::OwnershipChanges(transaction));
for (const Api::OwnershipChange& event : ownershipChangeList.changes)
{
Api::Entity entity = event.entity;
Api::ChangeListAction action = event.action;
switch (action)
{
case Api::ChangeListAction::None:
// insert code to handle the event
break;
case Api::ChangeListAction::Remove:
// insert code to handle the event
break;
case Api::ChangeListAction::Add:
// insert code to handle the event
break;
case Api::ChangeListAction::Update:
// insert code to handle the event
break;
case Api::ChangeListAction::Reject:
// insert code to handle the event
break;
}
}
```
**イベントタイプ**
+ `None` — エンティティが領域内にあり、その位置とフィールドのデータは変更されていません。
+ `Remove` — エンティティが領域から削除されました。
+ `Add` — エンティティが領域に追加されました。
+ `Update` — エンティティが領域内にあり、変更されました。
+ `Reject` — アプリケーションは領域からエンティティを削除できませんでした。
**注記**
`Reject` イベントが発生した場合、アプリケーションは次のティックで転送を再試行します。
# 登録したエンティティのイベントを繰り返し処理します。
`AllSubscriptionEvents()` を使用して、登録済みエンティティ (アプリケーションのサブスクリプション領域にあるエンティティ) のイベントリストを取得します。関数には以下のような署名があります。
```
Result AllSubscriptionEvents(Transaction& txn)
```
次に、以下の例に示すように、ループを使用してエンティティを繰り返し処理します。
**Example 例**
```
WEAVERRUNTIME_TRY(Api::SubscriptionChangeList subscriptionChangeList, Api::AllSubscriptionEvents(transaction));
for (const Api::SubscriptionEvent& event : subscriptionChangeList.changes)
{
Api::Entity entity = event.entity;
Api::ChangeListAction action = event.action;
switch (action)
{
case Api::ChangeListAction::None:
// insert code to handle the event
break;
case Api::ChangeListAction::Remove:
// insert code to handle the event
break;
case Api::ChangeListAction::Add:
// insert code to handle the event
break;
case Api::ChangeListAction::Update:
// insert code to handle the event
break;
case Api::ChangeListAction::Reject:
// insert code to handle the event
break;
}
}
```
**イベントタイプ**
+ `None` — エンティティが領域内にあり、その位置とフィールドのデータは変更されていません。
+ `Remove` — エンティティが領域から削除されました。
+ `Add` — エンティティが領域に追加されました。
+ `Update` — エンティティが領域内にあり、変更されました。
+ `Reject` — アプリケーションは領域からエンティティを削除できませんでした。
**注記**
`Reject` イベントが発生した場合、アプリケーションは次のティックで転送を再試行します。
# エンティティの所有権変更イベントを繰り返し処理します。
エンティティが所有領域とサブスクリプション領域の間を移動するイベントを取得するには、現在と以前のエンティティの所有領域とサブスクリプションイベントの変化を比較します。
これらのイベントは、以下を読むことで処理できます。
+ `Api::SubscriptionChangeList`
+ `Api::OwnershipEvents`
その後、変更内容を以前に保存したデータと比較できます。
以下の例は、エンティティの所有権の変更イベントを処理する方法を示しています。この例では、サブスクライブされたエンティティと所有されたエンティティの間を (どちらの方向でも) 移行するエンティティについて、所有権の削除/追加イベントが最初に発生し、次のティックでサブスクリプションの削除/追加イベントが発生することを前提としています。
**Example 例**
```
Result ProcessOwnershipEvents(Transaction& transaction)
{
using EntityIdsByAction =
std::unordered_map>;
using EntityIdSetByAction =
std::unordered_map>;
static EntityIdsByAction m_entityIdsByPreviousOwnershipAction;
EntityIdSetByAction entityIdSetByAction;
/**
* Enumerate Api::SubscriptionChangeList items
* and store Add and Remove events.
*/
WEAVERRUNTIME_TRY(Api::SubscriptionChangeList subscriptionEvents,
Api::AllSubscriptionEvents(transaction));
for (const Api::SubscriptionEvent& event : subscriptionEvents.changes)
{
const Api::ChangeListAction action = event.action;
switch (action)
{
case Api::ChangeListAction::Add:
case Api::ChangeListAction::Remove:
{
entityIdSetByAction[action].insert(
event.entity.descriptor->id);
break;
}
case Api::ChangeListAction::None:
case Api::ChangeListAction::Update:
case Api::ChangeListAction::Reject:
{
break;
}
}
}
EntityIdsByAction entityIdsByAction;
/**
* Enumerate Api::OwnershipChangeList items
* and store Add and Remove events.
*/
WEAVERRUNTIME_TRY(Api::OwnershipChangeList ownershipChangeList,
Api::OwnershipChanges(transaction));
for (const Api::OwnershipChange& event : ownershipChangeList.changes)
{
const Api::ChangeListAction action = event.action;
switch (action)
{
case Api::ChangeListAction::Add:
case Api::ChangeListAction::Remove:
{
entityIdsByAction[action].push_back(
event.entity.descriptor->id);
break;
}
case Api::ChangeListAction::None:
case Api::ChangeListAction::Update:
case Api::ChangeListAction::Reject:
{
break;
}
}
}
std::vector fromSubscribedToOwnedEntities;
std::vector fromOwnedToSubscribedEntities;
/**
* Enumerate the *previous* Api::OwnershipChangeList Remove items
* and check if they are now in
* the *current* Api::SubscriptionChangeList Add items.
*
* If true, then that means
* OnEntityOwnershipChanged(bool isOwned = false)
*/
for (const Api::EntityId& id : m_entityIdsByPreviousOwnershipAction[
Api::ChangeListAction::Remove])
{
if (entityIdSetBySubscriptionAction[
Api::ChangeListAction::Add].find(id) !=
entityIdSetBySubscriptionAction[
Api::ChangeListAction::Add].end())
{
fromOwnedToSubscribedEntities.push_back(id);
}
}
/**
* Enumerate the *previous* Api::OwnershipChangeList Add items
* and check if they are now in
* the *current* Api::SubscriptionChangeList Remove items.
*
* If true, then that means
* OnEntityOwnershipChanged(bool isOwned = true)
*/
for (const Api::EntityId& id : m_entityIdsByPreviousOwnershipAction[
Api::ChangeListAction::Add])
{
if (entityIdSetBySubscriptionAction[
Api::ChangeListAction::Remove].find(id) !=
entityIdSetBySubscriptionAction[
Api::ChangeListAction::Remove].end())
{
fromSubscribedToOwnedEntities.push_back(id);
}
}
m_entityIdsByPreviousOwnershipAction = entityIdsByOwnershipAction;
return Success();
}
```
# Result とエラー処理
この `Aws::WeaverRuntime::Result` クラスはサードパーティの `Outcome` ライブラリを使用しています。以下のパターンを使用して、`Result` を確認し、API コールによって返されるエラーを発見できます。
```
void DoBeginUpdate(Application& app)
{
Result transactionResult = Api::BeginUpdate(app);
if (transactionResult)
{
Transaction transaction =
std::move(transactionResult).assume_value();
/**
* Do things with transaction ...
*/
}
else
{
ErrorCode errorCode = WEAVERRUNTIME_EXPECT_ERROR(transactionResult);
/**
* Macro compiles to:
* ErrorCode errorCode = transactionResult.assume_error();
*/
}
}
```
## Result 制御文マクロ
戻り値タイプ `Aws::WeaverRuntime::Result` を持つ関数内では、前のコードパターンの代わりに `WEAVERRUNTIME_TRY` マクロを使用できます。マクロは渡された関数を実行します。渡された関数が失敗すると、マクロは囲んでいる関数にエラーを返送させます。渡された関数が成功すると、実行は次の行に進みます。以下の例は、以前の `DoBeginUpdate()` 関数の再記述を示しています。このバージョンでは、if-else 制御構造の代わりに `WEAVERRUNTIME_TRY` マクロを使用しています。関数の戻り値タイプは `Aws::WeaverRuntime::Result` です。
```
Aws::WeaverRuntime::Result DoBeginUpdate(Application& app)
{
/**
* Execute Api::BeginUpdate()
* and return from DoBeginUpdate() if BeginUpdate() fails.
* The error is available as part of the Result.
*/
WEAVERRUNTIME_TRY(Transaction transaction, Api::BeginUpdate(m_app));
/**
* Api::BeginUpdate executed successfully.
*
* Do things here.
*/
return Aws::Success();
}
```
`BeginUpdate()` に失敗した場合、マクロは障害発生時に早く`DoBeginUpdate()` を返送します。`WEAVERRUNTIME_EXPECT_ERROR` マクロを使用して `BeginUpdate()` から `Aws::WeaverRuntime::ErrorCode` を取得できます。以下の例は、障害発生時に `Update()` 関数が `DoBeginUpdate()` を呼び出してエラーコードを取得する方法を示しています。
```
void Update(Application& app)
{
Result doBeginUpdateResult = DoBeginUpdate(app);
if (doBeginUpdateResult)
{
/**
* Successful.
*/
}
else
{
/**
* Get the error from Api::BeginUpdate().
*/
ErrorCode errorCode = WEAVERRUNTIME_EXPECT_ERROR(doBeginUpdateResult);
}
}
```
戻り値タイプを `Update()` から `Aws::WeaverRuntime::Result` に変更することで、`BeginUpdate()` からのエラーコードを `Update()` を呼び出す関数に利用できるようにすることができます。この手順を繰り返して、エラーコードを呼び出しスタックのさらに下位に送り続けることができます。
# ジェネリックとドメインタイプ
SimSpace Weaver アプリケーション SDK は、単精度データ型 `Api::Vector2F32`と `Api::BoundingBox2F32`、および倍精度 `Api::Vector2F64` と を提供します`Api::BoundingBox2F64`。これらのデータタイプは受動的なデータ構造で、便利な方法はありません。API は `Api::Vector2F32` および `Api::BoundingBox2F32` のみを使用することに注意してください。これらのデータタイプを使用してサブスクリプションを作成および変更できます。
SimSpace Weaver デモフレームワークは、 AzCore `Vector3`と を含む数学ライブラリの最小バージョンを提供します`Aabb`。詳細については、以下のヘッダーファイルを参照してください。
+ `sdk-folder/packaging-tools/samples/ext/DemoFramework/include/AzCore/Math`
# その他のアプリケーション SDK 操作
**Topics**
+ [AllSubscriptionEvents および OwnershipChanges は前回の呼び出しからのイベントを含みます](working-with_app-sdk_misc_events-from-last-call.md)
+ [SubscriptionChangeList の処理後に読み取りロックを解除する](working-with_app-sdk_misc_release-locks.md)
+ [テスト用のスタンドアロンアプリケーションインスタンスを作成する](working-with_app-sdk_misc_testing-app.md)
# AllSubscriptionEvents および OwnershipChanges は前回の呼び出しからのイベントを含みます
`Api::AllSubscriptionEvents()` および `Api::OwnershipChanges()` への呼び出しの戻り値が含むのは、最後の呼び出しからのイベントであり、**最後のティック**からのイベントではありません。以下の例では、`secondSubscriptionEvents` および `secondOwnershipChangeList` は空です。なぜなら、関数は最初の呼び出しの直後に呼び出されるからです。
10 ティック待ってから `Api::AllSubscriptionEvents()` および `Api::OwnershipChanges()` を呼び出した場合、その結果として (最後のティックではなく) 最後の 10 ティックからのイベントと変更の両方が含まれます。
**Example 例**
```
Result ProcessOwnershipChanges(Transaction& transaction)
{
WEAVERRUNTIME_TRY(
Api::SubscriptionChangeList firstSubscriptionEvents,
Api::AllSubscriptionEvents(transaction));
WEAVERRUNTIME_TRY(
Api::OwnershipChangeList firstOwnershipChangeList,
Api::OwnershipChanges(transaction));
WEAVERRUNTIME_TRY(
Api::SubscriptionChangeList secondSubscriptionEvents,
Api::AllSubscriptionEvents(transaction));
WEAVERRUNTIME_TRY(
Api::OwnershipChangeList secondOwnershipChangeList,
Api::OwnershipChanges(transaction));
/**
* secondSubscriptionEvents and secondOwnershipChangeList are
* both empty because there are no changes since the last call.
*/
}
```
**注記**
関数 `AllSubscriptionEvents()` は実装されていますが、関数 `SubscriptionEvents()` は**実装されていません**。
# SubscriptionChangeList の処理後に読み取りロックを解除する
更新を開始すると、コミットされたデータ用の共有メモリセグメントが他のパーティションに前回のティックで残ります。これらの共有メモリセグメントはリーダーによってロックされている可能性があります。すべてのリーダーがロックを解除するまで、アプリケーションは完全にコミットできません。最適化のため、アプリケーションは `Api::SubscriptionChangelist` アイテムを処理した後にロックを解除するための `Api::ReleaseReadLeases()` 呼び出しを行う必要があります。これにより、コミット時の競合が減少します。デフォルトでは `Api::Commit()` は読み取りリースを解放しますが、サブスクリプションの更新を処理した後に手動でリリースするのがベストプラクティスです。
**Example 例**
```
Result ProcessSubscriptionChanges(Transaction& transaction)
{
WEAVERRUNTIME_TRY(ProcessSubscriptionChanges(transaction));
/**
* Done processing Api::SubscriptionChangeList items.
* Release read locks.
*/
WEAVERRUNTIME_EXPECT(Api::ReleaseReadLeases(transaction));
...
}
```
# テスト用のスタンドアロンアプリケーションインスタンスを作成する
`Api::CreateStandaloneApplication()`を使用して、スタンドアロンアプリケーションを作成し、実際のシミュレーションでコードを実行する前にアプリケーションのロジックをテストできます。
**Example 例**
```
int main(int argc, char* argv[])
{
Api::StandaloneRuntimeConfig config = {
/* run_for_seconds (the lifetime of the app) */ 3,
/* tick_hertz (the app clock rate) */ 10 };
Result applicationResult =
Api::CreateStandaloneApplication(config);
...
}
```
# AWS SimSpace Weaver デモフレームワーク
AWS SimSpace Weaver デモフレームワーク (デモフレームワーク) は、 SimSpace Weaver アプリケーションの開発に使用できるユーティリティのライブラリです。
**デモフレームワークには以下のものが含まれます**
+ 使用したり調べたりできるコードサンプルとプログラミングパターン
+ シンプルなアプリケーションの開発を効率化する抽象化とユーティリティ関数
+ SimSpace Weaver アプリケーション SDK の実験的な機能をテストする簡単な方法
パフォーマンスを向上させるために、API への低レベルアクセスを備えた SimSpace Weaver アプリケーション SDK を設計しました。 SimSpace Weaver APIs これとは対照的に、より高いレベルの抽象化と、 SimSpace Weaver を使いやすくする API へのアクセスが可能なデモフレームワークを設計しました。使いやすさのコストは、 SimSpace Weaver アプリケーション SDK を直接使用するよりもパフォーマンスが低くなります。パフォーマンスの低下を許容できるシミュレーション (リアルタイムのパフォーマンス要件がないシミュレーションなど) は、デモフレームワークの使用に適している場合があります。デモフレームワークは完全なツールキットではないため、複雑なアプリケーションに SimSpace Weaver アプリケーション SDK のネイティブ機能を使用することをお勧めします。
**デモフレームワークには以下が含まれます**
+ 以下をサポートおよび実証する作業用コードサンプル:
+ アプリケーションフローの管理
+ コールバック主導型のエンティティイベント処理
+ 以下のサードパーティー製ユーティリティライブラリのセット:
+ spdlog (ログ記録ライブラリ)
+ AZCore (数学ライブラリ) の最小バージョンで、以下のみを含むもの:
+ Vector3
+ Aabb
+ cxxopts (コマンドラインオプションパーサーライブラリ)
+ に固有のユーティリティ関数 SimSpace Weaver
デモフレームワークは、ライブラリ、ソースファイル、CMakeLists で構成されています。ファイルは、 SimSpace Weaver アプリケーション SDK 配布パッケージに含まれています。
# Service Quotas との連携
このセクションでは、 のサービスクォータを使用する方法について説明します SimSpace Weaver。**Quotas** は**リミット**とも呼ばれます。Service Quotas のリストについては、「[SimSpace Weaver エンドポイントとクォータ](service-quotas.md)」を参照してください。このセクションの API は**アプリケーション API** セットの一部です。アプリケーション API はサービス API とは異なります。アプリ APIsは SimSpace Weaver アプリ SDK の一部です。アプリケーション API のドキュメントは、ローカルシステムのアプリケーション SDK フォルダで確認できます。
```
sdk-folder\SimSpaceWeaverAppSdk-sdk-version\documentation\index.html
```
**Topics**
+ [アプリケーションの制限を取得する](#working-with_quotas_get-app-limits)
+ [アプリケーションが使用しているリソース量を取得する](#working-with_quotas_get-app-resources)
+ [メトリクスをリセットする](#working-with_quotas_reset-metrics)
+ [制限の超過](#working-with_quotas_exceed-limit)
+ [メモリの不足](#working-with_quotas_out-of-memory)
+ [ベストプラクティス](#working-with_quotas_best-practices)
## アプリケーションの制限を取得する
**RuntimeLimits** アプリケーション SDK を使用してアプリケーションの制限をクエリできます。
```
Result RuntimeLimit(Application& app, LimitType type)
```パラメータ
**Application& アプリケーション**
アプリケーションへの参照。
**LimitType タイプ**
以下の制限タイプを含む列挙値。
```
enum LimitType {
Unset = 0,
EntitiesPerPartition = 1,
RemoteEntityTransfers = 2,
LocalEntityTransfers = 3
};
```
以下の例では、エンティティ数の制限をクエリします。
```
WEAVERRUNTIME_TRY(auto entity_limit,
Api::RuntimeLimit(m_app, Api::LimitType::EntitiesPerPartition))
Log::Info("Entity count limit", entity_limit.value);
```
## アプリケーションが使用しているリソース量を取得する
**RuntimeMetrics** アプリケーション SDK を呼び出して、アプリケーションが使用しているリソースの量を取得できます。
```
Result> RuntimeMetrics(Application& app) noexcept
```パラメータ
**Application& アプリケーション**
アプリケーションへの参照。
API は、メトリクスを含む struct への参照を返します。カウンターメトリクスには現在の合計値が含まれ、増加のみします。ゲージメトリクスには増減する値が含まれます。アプリケーションランタイムは、イベントによって値が増加するたびにカウンターを更新します。ランタイムは API を呼び出したときのみゲージを更新します。 SimSpace Weaver はリファレンスがアプリケーションの存続期間中有効であることを保証します。API を繰り返し呼び出しても、参照は変更されません。
```
struct AppRuntimeMetrics {
uint64_t total_committed_ticks_gauge,
uint32_t active_entity_gauge,
uint32_t ticks_since_reset_counter,
uint32_t load_field_counter,
uint32_t store_field_counter,
uint32_t created_entity_counter,
uint32_t deleted_entity_counter,
uint32_t entered_entity_counter,
uint32_t exited_entity_counter,
uint32_t rejected_incoming_transfer_counter,
uint32_t rejected_outgoing_transfer_counter
}
```
## メトリクスをリセットする
**ResetRuntimeMetrics** アプリケーション SDK は `AppRuntimeMetrics` struct 内の値をリセットします。
```
Result ResetRuntimeMetrics(Application& app) noexcept
```
次の例では、アプリケーション内での **ResetRuntimeMetrics** の呼び出し方法を示します。
```
if (ticks_since_last_report > 100)
{
auto metrics = WEAVERRUNTIME_EXPECT(Api::RuntimeMetrics(m_app));
Log::Info(metrics);
ticks_since_last_report = 0;
WEAVERRUNTIME_EXPECT(Api::ResetRuntimeMetrics(m_app));
}
```
## 制限の超過
アプリケーションの API コールが制限を超えると、エンティティ転送を除き、`ErrorCode::CapacityExceeded` が返されます。 SimSpace Weaver は**Commit** 操作および **BeginUpdate** アプリケーション API 操作の一部としてエンティティ転送を非同期的に処理するため、エンティティ転送の上限が原因で転送が失敗した場合にエラーを返す特定の操作はありません。転送の失敗を検出するには、 `rejected_incoming_transfer_counter` および `rejected_outgoing_transfer_counter` (`AppRuntimeMetrics` struct 内) の現在の値を以前の値と比較できます。拒否されたエンティティはパーティションには含まれませんが、アプリケーションではそのエンティティをシミュレートできます。
## メモリの不足
SimSpace Weaver はガベージコレクタープロセスを使用して、解放されたメモリをクリーンアップおよび解放します。ガベージコレクターがメモリを解放するよりも速くデータを書き込むことができます。この場合、書き込み操作がアプリケーションの予約メモリの制限を超える可能性があります。 SimSpace Weaver は `OutOfMemory` (および追加情報) を含むメッセージを含む内部エラーを返します。詳細については、「[書き込みを時系列に分散させる](#working-with_quotas_best-practices_spread-writes)」を参照してください。
## ベストプラクティス
以下のベストプラクティスは、制限を超えないようにアプリケーションを設計するための一般的なガイドラインです。特定のアプリケーションデザインには当てはまらない場合があります。
### 頻繁に監視し、速度を低下させる
メトリクスを頻繁に監視し、制限に近づいている処理は遅くする必要があります。
### サブスクリプション制限や転送制限の超過を避ける
可能であれば、リモートサブスクリプションとエンティティ転送の数を減らすようにシミュレーションを設計します。配置グループを使用して同じワーカーに複数のパーティションを配置し、ワーカー間のリモートエンティティ転送の必要性を減らすことができます。
### 書き込みを時系列に分散させる
ティック内の更新の数とサイズは、トランザクションのコミットに必要な時間とメモリに大きな影響を与える可能性があります。メモリ要件が大きいと、アプリケーションランタイムのメモリが不足する可能性があります。書き込みを時系列に分散させて、1 ティックあたりの更新の平均合計サイズを減らすことができます。これにより、パフォーマンスを向上させ、制限を超えないようにすることができます。各ティックに平均 12 MB、または各エンティティに平均 1.5 KB を超えて書き込まないことをお勧めします。
# シミュレーションのデバッグ
以下の方法を使用して、シミュレーションに関する情報を取得できます。
**トピック**
+ [SimSpace Weaver Local を使用してコンソール出力を確認する](#working-with_debugging_use-local)
+ [Amazon CloudWatch Logs のログを確認する](#working-with_debugging_logs)
+ [**describe** API コールを使用する](#working-with_debugging_api)
+ [クライアントを接続する](#working-with_debugging_client)
## SimSpace Weaver Local を使用してコンソール出力を確認する
まずシミュレーションをローカルで開発してから、 AWS クラウドで実行することをお勧めします。SimSpace Weaver Local を実行するとコンソールの出力を直接表示できます。詳細については、「[でのローカル開発 SimSpace Weaver](working-with_local-development.md)」を参照してください。
## Amazon CloudWatch Logs のログを確認する
コンソールでシミュレーションを実行すると AWS クラウド 、アプリケーションの出力が Amazon CloudWatch Logs のログストリームに送信されます。シミュレーションでは他のログデータも書き込まれます。シミュレーションでログデータを書き込むには、シミュレーションスキーマのログ記録を有効にする必要があります。詳細については、「[SimSpace Weaver Amazon CloudWatch Logs の ログ](cloudwatch-logs.md)」を参照してください。
**警告**
シミュレーションでは大量のログデータが生成される可能性があります。ログデータは非常に急速に増大する可能性があります。ログを注意深く観察し、実行する必要がなくなったらシミュレーションを停止する必要があります。ログ記録には多額のコストがかかる可能性があります。
## **describe** API コールを使用する
以下のサービス API を使用して、 AWS クラウド内のシミュレーションに関する情報を取得できます。
+ **ListSimulations** – ですべてのシミュレーションのリストを取得します AWS クラウド。
**Example 例**
```
aws simspaceweaver list-simulations
```
+ **DescribeSimulation** — シミュレーションの詳細を取得します。
**Example 例**
```
aws simspaceweaver describe-simulation --simulation MySimulation
```
+ **DescribeApp** — アプリケーションの詳細を取得します。
**Example 例**
```
aws simspaceweaver describe-app --simulation MySimulation --domain MyCustomDomain --app MyCustomApp
```
SimSpace Weaver APIs「」を参照してください[SimSpace Weaver API リファレンス](api-reference.md)。
## クライアントを接続する
シミュレーションスキーマの `endpoint_config` で定義した実行中のカスタムアプリケーションまたはサービスアプリケーションにクライアントを接続できます。 SimSpace Weaver アプリケーション SDK には、サンプルアプリケーションを表示するために使用できるサンプルクライアントが含まれています。これらのサンプルクライアントのソースコードとサンプルアプリケーションケーションを見て、独自のクライアントを作成する方法を確認できます。サンプルクライアントを構築して実行する方法の詳細については、「」のチュートリアルを参照してください[の開始方法 SimSpace Weaver](getting-started.md)。
サンプルクライアントのソースコードは、以下のフォルダで確認できます。
+ `sdk-folder\packaging-tools\clients\PathfindingSampleClients\`
# ローカルシミュレーションのデバッグ
Microsoft Visual Studio で SimSpace Weaver Local アプリケーションをデバッグできます。Visual Studio でデバッグする方法の詳細については、「[https://learn.microsoft.com/en-us/visualstudio/debugger/debugger-feature-tour](https://learn.microsoft.com/en-us/visualstudio/debugger/debugger-feature-tour)」を参照してください。
**ローカルシミュレーションをデバッグする方法**
1. `schema.yaml` が作業ディレクトリにあることを確認します。
1. **Visual Studio** で、デバッグする各アプリケーションのコンテキストメニュー (`PathfindingSampleLocalSpatial` または `PathfindingSampleLocalView` など) を開き、デバッグセクションで作業ディレクトリを設定します。
1. デバッグするアプリケーションのコンテキストメニューを開き、[**スタートアッププロジェクトとして設定**] を選択します。
1. F5 を選択して、アプリケーションのデバッグを開始します。
シミュレーションをデバッグするための要件は、シミュレーションを正常に実行するための要件と同じです。スキーマで指定された数の空間アプリケーションを起動する必要があります。例えば、スキーマで 2x2 グリッドが指定されている場合に、空間アプリケーションをデバッグモードで起動した場合、さらに 3 つの空間アプリケーションを (デバッグモードまたはデバッグモードでない状態で) 起動するまでシミュレーションは実行されません。
カスタムアプリケーションをデバッグするには、まず空間アプリケーションを起動し、次にデバッガーでカスタムアプリケーションを起動する必要があります。
シミュレーションはロックステップで実行されることに注意してください。アプリケーションがブレークポイントに達するとすぐに、他のすべてのアプリケーションは一時停止します。そのブレークポイントから続行すると、他のアプリケーションは続行されます。
# カスタムコンテナ
AWS SimSpace Weaver アプリケーションはコンテナ化された Amazon Linux 2 (AL2) 環境で実行されます。では AWS クラウド、 は Amazon Elastic Container Registry (Amazon ECR) が提供する`amazonlinux:2`イメージから構築された Docker コンテナでシミュレーション SimSpace Weaver を実行します。カスタム Docker イメージを作成して Amazon ECR に保存し、提供されているデフォルトの Docker イメージの代わりにそのイメージをシミュレーションに使用できます。
カスタムコンテナを使用してソフトウェアの依存関係を管理し、標準の Docker イメージにはないソフトウェアコンポーネントを追加できます。例えば、アプリケーションが使用する一般公開ソフトウェアライブラリをコンテナに追加し、カスタムコードをアプリケーションの zip ファイルのみに入れることができます。
**重要**
Amazon ECR Public Gallery またはお客様のプライベート Amazon ECR レジストリにある Amazon ECR リポジトリでホストされている AL2 Docker イメージのみをサポートします。Amazon ECR の外部でホストされている Docker イメージはサポートされていません。Amazon ECR の詳細については、「*[Amazon Elastic Container Registry のドキュメント](https://docs.aws.amazon.com/ecr)*」を参照してください。
**Topics**
+ [カスタムコンテナを作成する](working-with_custom-containers_create.md)
+ [カスタムコンテナを使用するようにプロジェクトを変更する](working-with_custom-containers_modify-project.md)
+ [カスタムコンテナに関するよくある質問](working-with_custom-containers_faq.md)
+ [カスタムコンテナのトラブルシューティング](working-with_custom-containers_troubleshooting.md)
# カスタムコンテナを作成する
これらの手順は、Docker と Amazon Elastic Container Registry (Amazon ECR) の使用方法についての知識があることを前提としています。Amazon ECR の詳細については、「*[Amazon ECR ユーザーガイド](https://docs.aws.amazon.com/AmazonECR/latest/userguide)*」を参照してください。
**前提条件**
+ これらのアクションを実行するために使用する IAM アイデンティティ (ユーザーまたはロール) には、Amazon ECR を使用するための適切なアクセス許可があります。
+ Docker は、ローカルシステムにインストールされます
**カスタムコンテナを作成する方法**
1. `Dockerfile` を作成します。
AWS SimSpace Weaver アプリケーションを実行する `Dockerfile` は、Amazon ECR のAmazon Linux 2イメージで始まります。
```
# parent image required to run AWS SimSpace Weaver apps
FROM public.ecr.aws/amazonlinux/amazonlinux:2
```
1. `Dockerfile` を構築します。
1. コンテナイメージを Amazon ECR にアップロードします。
+ [AWS マネジメントコンソールを使用します。](https://docs.aws.amazon.com/AmazonECR/latest/userguide/getting-started-console.html)
+ [AWS Command Line Interfaceを使用します。](https://docs.aws.amazon.com/AmazonECR/latest/userguide/getting-started-cli.html)
**注記**
コンテナイメージを Amazon ECR にアップロードしようとして `AccessDeniedException` エラーが発生した場合、お使いの IAM アイデンティティ (ユーザーまたはロール) には Amazon ECR を使用するために必要なアクセス許可がない可能性があります。`AmazonEC2ContainerRegistryPowerUser` AWS 管理ポリシーを IAM ID にアタッチして、もう一度試すことができます。ポリシーをアタッチする方法の詳細については、「*AWS Identity and Access Management ユーザーガイド*」の「[IAM アイデンティティの許可の追加および削除](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)」を参照してください。
# カスタムコンテナを使用するようにプロジェクトを変更する
この手順では、 の使用方法が既にわかって AWS SimSpace Weaver おり、 でアプリケーションストレージと開発ワークフローをより AWS クラウド 効率的にしたいことを前提としています。
**前提条件**
+ Amazon Elastic Container Registry (Amazon ECR) にはカスタムコンテナが用意されています。カスタムコンテナの作成方法の詳細については、「[カスタムコンテナを作成する](working-with_custom-containers_create.md)」を参照してください。
**カスタムコンテナを使用するようにプロジェクトを変更する方法**
1. Amazon ECR を使用するアクセス許可をプロジェクトのシミュレーションアプリケーションロールに追加します。
1. 以下のアクセス許可を持つ IAM ポリシーがない場合は、ポリシーを作成します。ポリシー名 `simspaceweaver-ecr` を付けることをお勧めします。IAM ポリシー作成方法の詳細については、「*AWS Identity and Access Management ユーザーガイド*」の「[IAM ポリシーの作成](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html)」を参照してください。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Statement",
"Effect": "Allow",
"Action": [
"ecr:BatchGetImage",
"ecr:GetDownloadUrlForLayer",
"ecr:GetAuthorizationToken"
],
"Resource": "*"
}
]
}
```
1. プロジェクトのシミュレーションアプリケーションロールの名前を検索します。
1. テキストエディタで、 CloudFormation テンプレートを開きます。
```
sdk-folder\PackagingTools\sample-stack-template.yaml
```
1. `WeaverAppRole` の下の [`RoleName`] プロパティを検索します。値はプロジェクトのシミュレーションアプリケーションロール名です。
**Example**
```
AWSTemplateFormatVersion: "2010-09-09"
Resources:
WeaverAppRole:
Type: 'AWS::IAM::Role'
Properties:
RoleName: 'weaver-MySimulation-app-role'
AssumeRolePolicyDocument:
Version: "2012-10-17"
Statement:
- Effect: Allow
Principal:
Service:
- 'simspaceweaver.amazonaws.com'
```
1. `simspaceweaver-ecr` ポリシーをプロジェクトのシミュレーションアプリケーションロールにアタッチします。ポリシーをアタッチする方法の詳細については、「*AWS Identity and Access Management ユーザーガイド*」の「[IAM アイデンティティの許可の追加および削除](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)」を参照してください。
1. に移動`sdk-folder`して次のコマンドを実行して、サンプル SimSpace Weaver スタックを更新します。
```
python setup.py --cloudformation
```
1. プロジェクトのシミュレーションスキーマでコンテナイメージを指定します。
+ `simulation_properties` の下にオプションの `default_image` プロパティを追加して、すべてのドメインのデフォルトのカスタムコンテナイメージを指定できます。
+ カスタムコンテナイメージを使用するドメインの `image` プロパティを `app_config` に追加します。値として Amazon ECR リポジトリ URI を指定します。ドメインごとに異なるイメージを指定できます。
+ `image` がドメインに指定されていない状態で `default_image` が指定されている場合、そのドメイン内のアプリケーションはデフォルトイメージを使用します。
+ `image` がドメインに指定されておらず、 が指定されていない場合、そのドメイン内のアプリケーション`default_image`は標準 SimSpace Weaver コンテナで実行されます。
**Example カスタムコンテナ設定を含むスキーマスニペット**
```
sdk_version: "1.17.0"
simulation_properties:
log_destination_service: "logs"
log_destination_resource_name: "MySimulationLogs"
default_entity_index_key_type: "Vector3"
default_image: "111122223333.dkr.ecr.us-west-2.amazonaws.com/my-ecr-repository:latest" # image to use if no image specified for a domain
domains:
MyCustomDomain:
launch_apps_via_start_app_call: {}
app_config:
package: "s3://weaver-myproject-111122223333-us-west-2/MyViewApp.zip"
launch_command: ["MyViewApp"]
required_resource_units:
compute: 1
endpoint_config:
ingress_ports:
- 7000
image: "111122223333.dkr.ecr.us-west-2.amazonaws.com/my-ecr-repository:latest" # custom container image to use for this domain
MySpatialDomain:
launch_apps_by_partitioning_strategy:
partitioning_strategy: "MyGridPartitioning"
grid_partition:
x: 2
y: 2
app_config:
package: "s3://weaver-myproject-111122223333-us-west-2/MySpatialApp.zip"
launch_command: ["MySpatialApp"]
required_resource_units:
compute: 1
image: "111122223333.dkr.ecr.us-west-2.amazonaws.com/my-ecr-repository:latest" # custom container image to use for this domain
```
1. 通常どおりプロジェクトを構築してアップロードします。
# カスタムコンテナに関するよくある質問
## Q1. コンテナの中身を変更したい場合はどうすればいいですか?
+ **実行中のシミュレーションの場合** — 実行中のシミュレーションのコンテナは変更できません。新しいコンテナを構築し、そのコンテナを使用する新しいシミュレーションを開始する必要があります。
+ **新しいシミュレーションの場合** — 新しいコンテナを構築して Amazon Elastic Container Registry (Amazon ECR) にアップロードし、そのコンテナを使用する新しいシミュレーションを開始します。
## Q2. シミュレーション用のコンテナイメージを変更する方法を教えてください。
+ **実行中のシミュレーションの場合** — 実行中のシミュレーションのコンテナは変更できません。新しいコンテナを使用する新しいシミュレーションを開始する必要があります。
+ **新しいシミュレーションの場合** — プロジェクトのシミュレーションスキーマに新しいコンテナイメージを指定します。詳細については、「[カスタムコンテナを使用するようにプロジェクトを変更する](working-with_custom-containers_modify-project.md)」を参照してください。
# カスタムコンテナのトラブルシューティング
**Topics**
+ [Amazon Elastic Container Registry (Amazon ECR) にイメージをアップロードすると AccessDeniedException が表示される](working-with_custom-containers_troubleshooting_access-denied.md)
+ [カスタムコンテナを使用するシミュレーションが開始できない](working-with_custom-containers_troubleshooting_no-start.md)
# Amazon Elastic Container Registry (Amazon ECR) にイメージをアップロードすると AccessDeniedException が表示される
コンテナイメージを Amazon ECR にアップロードしようとして `AccessDeniedException` エラーが発生した場合、お使いの IAM アイデンティティ (ユーザーまたはロール) には Amazon ECR を使用するために必要なアクセス許可がない可能性があります。`AmazonEC2ContainerRegistryPowerUser` AWS 管理ポリシーを IAM ID にアタッチして、もう一度試すことができます。ポリシーをアタッチする方法の詳細については、「*AWS Identity and Access Management ユーザーガイド*」の「[IAM アイデンティティの許可の追加および削除](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)」を参照してください。
# カスタムコンテナを使用するシミュレーションが開始できない
**トラブルシューティングのヒント**
+ シミュレーションでログ記録が有効になっている場合は、エラーログを確認します。
+ カスタムコンテナなしでシミュレーションをテストします。
+ シミュレーションをローカルでテストします。詳細については、「[でのローカル開発 SimSpace Weaver](working-with_local-development.md)」を参照してください。
# Python の使用
SimSpace Weaver アプリケーションとクライアントには Python を使用できます。Python ソフトウェア開発キット (Python SDK) は、標準の SimSpace Weaver アプリケーション SDK 配布パッケージの一部として含まれています。Python による開発は、サポートされている他の言語での開発と同様に機能します。
**重要**
SimSpace Weaver は Python バージョン 3.9 のみをサポートしています。
**重要**
SimSpace Weaver Python のサポートには SimSpace Weaver バージョン 1.15.0 以降が必要です。
**Topics**
+ [Python プロジェクトの作成](working-with_python_create-project.md)
+ [Python シミュレーションを開始する](working-with_python_start-sim.md)
+ [Python のサンプルクライアント](working-with_python_client.md)
+ [Python の使用に関するよくある質問](working-with_python_faq.md)
+ [Python に関連する問題のトラブルシューティング](working-with_python_troubleshooting.md)
# Python プロジェクトの作成
## Python カスタムコンテナ
で Python ベースの SimSpace Weaver シミュレーションを実行するには AWS クラウド、必要な依存関係を含むカスタムコンテナを作成できます。詳細については、「[カスタムコンテナ](working-with_custom-containers.md)」を参照してください。
Python カスタムコンテナには以下が含まれている必要があります。
+ gcc
+ openssl-devel
+ bzip2-devel
+ libffi-devel
+ wget
+ tar
+ gzip
+ make
+ Python (バージョン 3.9)
`PythonBubblesSample` テンプレートを使用してプロジェクトを作成する場合は、(プロジェクトの `tools` フォルダにある) `quick-start.py` スクリプトを実行して、必要な依存関係を含む Docker イメージを作成できます。このスクリプトは、Amazon Elastic Container Registry (Amazon ECR) にイメージをアップロードします。
`quick-start.py` スクリプトは以下の `Dockerfile` を使用します。
```
FROM public.ecr.aws/amazonlinux/amazonlinux:2
RUN yum -y install gcc openssl-devel bzip2-devel libffi-devel
RUN yum -y install wget
RUN yum -y install tar
RUN yum -y install gzip
RUN yum -y install make
WORKDIR /opt
RUN wget https://www.python.org/ftp/python/3.9.0/Python-3.9.0.tgz
RUN tar xzf Python-3.9.0.tgz
WORKDIR /opt/Python-3.9.0
RUN ./configure --enable-optimizations
RUN make altinstall
COPY requirements.txt ./
RUN python3.9 -m pip install --upgrade pip
RUN pip3.9 install -r requirements.txt
```
独自の依存関係を、`Dockerfile` に追加できます。
```
RUN yum -y install dependency-name
```
`requirements.txt` ファイルには、`PythonBubblesSample` サンプルシミュレーションに必要な Python パッケージのリストが含まれています。
```
Flask==2.1.1
```
独自の Python パッケージの依存関係を `requirements.txt` に追加できます。
```
package-name==version-number
```
`Dockerfile` および `requirements.txt` はプロジェクトの `tools` フォルダにあります。
**重要**
技術的には Python シミュレーションでカスタムコンテナを使用する必要はありませんが、カスタムコンテナを使用することを強くお勧めします。Amazon Linux 2 (AL2) の標準コンテナは、Python を提供していません。したがって、Python を含むカスタムコンテナを使用しない場合は、アップロードする各アプリの zip ファイルに Python と必要な依存関係を含める必要があります SimSpace Weaver。
# Python シミュレーションを開始する
Python ベースのシミュレーションは、通常の SimSpace Weaver シミュレーションと同じ方法で、 の SimSpace Weaver Localと SimSpace Weaver の両方で開始できます AWS クラウド。詳細については、「」のチュートリアルを参照してください[の開始方法 SimSpace Weaver](getting-started.md)。
`PythonBubblesSample` には独自の Python サンプルクライアントが含まれています。詳細については、「[Python のサンプルクライアント](working-with_python_client.md)」を参照してください。
# Python のサンプルクライアント
`PythonBubblesSample` テンプレートを使用してプロジェクトを作成する場合、プロジェクトには Python サンプルクライアントが含まれます。サンプルクライアントを使用して `PythonBubblesSample` シミュレーションを表示できます。サンプルクライアントを起点として使用して、独自の Python クライアントを作成することもできます。
以下の手順は、`PythonBubblesSample` プロジェクトを作成し、シミュレーションを開始済みであることを前提としています。
**Python クライアントを起動する方法**
1. **コマンドプロンプトウィンドウで**、`PyBubbleClient`サンプルプロジェクトフォルダに移動します。
```
cd sdk-folder\Clients\HTTP\PyBubbleClient
```
1. Python クライアントを実行します。
```
python tkinter_client.py --host ip-address --port port-number
```
**パラメータ**
**host**
シミュレーションの IP アドレス。で開始されたシミュレーションについては AWS クラウド、 [SimSpace Weaver コンソール](https://console.aws.amazon.com/simspaceweaver)でシミュレーションの IP アドレスを確認するか、クイックスタートチュートリアル[カスタムアプリケーションの IP アドレスとポート番号を取得するIP アドレスとポート番号を取得する](working-with_get-ip.md)の の手順を使用します。ローカルシミュレーションの場合は、IP アドレスとして `127.0.0.1` を使用します。
**port**
シミュレーションのポート番号。で開始されたシミュレーションの場合 AWS クラウド、これは`Actual`ポート番号です。シミュレーションのポート番号は [[SimSpace Weaver ] コンソール](https://console.aws.amazon.com/simspaceweaver)で確認するか、「クイックスタートチュートリアル」の「[カスタムアプリケーションの IP アドレスとポート番号を取得するIP アドレスとポート番号を取得する](working-with_get-ip.md)」手順を使用して確認できます。ローカルシミュレーションの場合は、ポート番号として `7000` を使用します。
**simsize**
クライアントに表示するエンティティの最大数。
# Python の使用に関するよくある質問
## Q1. どのバージョンの Python がサポートされていますか?
SimSpace Weaver は Python バージョン 3.9 のみをサポートしています。
# Python に関連する問題のトラブルシューティング
**Topics**
+ [カスタムコンテナ作成中の失敗](working-with_python_troubleshooting_create-container-failure.md)
+ [Python シミュレーションが開始されない](working-with_python_troubleshooting_no-start.md)
+ [Python シミュレーションまたはビュークライアントに ModuleNotFound エラーが表示される](working-with_python_troubleshooting_module-not-found.md)
# カスタムコンテナ作成中の失敗
`quick-start.py` の実行後にエラー `no basic auth credentials` が発生した場合は、Amazon ECR の一時的な認証情報に問題がある可能性があります。 AWS リージョン ID と AWS アカウント番号を使用して、次のコマンドを実行します。
```
aws ecr get-login-password --region region | docker login --username AWS --password-stdin account_id.dkr.ecr.region.amazonaws.com
```
**Example**
```
aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin 111122223333.dkr.ecr.region.amazonaws.com
```
**重要**
AWS リージョン 指定する がシミュレーションに使用するものと同じであることを確認します。が SimSpace Weaver サポート AWS リージョン する のいずれかを使用します。詳細については、「[SimSpace Weaver エンドポイントとクォータ](service-quotas.md)」を参照してください。
`aws ecr` コマンドを実行したら、もう一度 `quick-start.py` を実行してください。
**確認すべきその他のトラブルシューティングリソース**
+ [カスタムコンテナのトラブルシューティング](working-with_custom-containers_troubleshooting.md)
+ 「[Amazon ECR ユーザーガイド](https://docs.aws.amazon.com/AmazonECR/latest/userguide/troubleshooting.html)」の「*Amazon ECR トラブルシューティング*」
+ 詳細については、「*Amazon ECR ユーザーガイド*」の「[Amazon ECR での設定](https://docs.aws.amazon.com/AmazonECR/latest/userguide/get-set-up-for-amazon-ecr.html)」を参照してください
# Python シミュレーションが開始されない
シミュレーションの管理ログに `Unable to start app` エラーが表示される場合があります。これは、カスタムコンテナの作成に失敗した場合に発生する可能性があります。詳細については、「[カスタムコンテナ作成中の失敗](working-with_python_troubleshooting_create-container-failure.md)」を参照してください。ログの詳細については、[SimSpace Weaver Amazon CloudWatch Logs の ログ](cloudwatch-logs.md) を参照してください。
コンテナに問題がないと確信できる場合は、アプリケーションの Python ソースコードを確認します。SimSpace Weaver Local を使用してアプリケーションをテストできます。詳細については、「[でのローカル開発 SimSpace Weaver](working-with_local-development.md)」を参照してください。
# Python シミュレーションまたはビュークライアントに ModuleNotFound エラーが表示される
必要な Python パッケージが見つからない場合、Python は `ModuleNotFound` エラーを返します。
シミュレーションが にある場合は AWS クラウド、カスタムコンテナに必要な依存関係がすべて にリストされていることを確認します`requirements.txt`。`requirements.txt` を編集する場合は、必ずもう一度 `quick-start.py` を実行してください。
`PythonBubblesSample` クライアント側でエラーが発生した場合は、`pip` を使用して指定のパッケージをインストールします。
```
pip install package-name==version-number
```
# 他のエンジンのサポート
で独自のカスタムC\$1\$1エンジンを使用できます SimSpace Weaver。現在、以下のエンジンのサポートを開発中です。これらのエンジンにはそれぞれ個別のドキュメントが用意されています。
**重要**
ここに記載されているエンジンとの統合は実験段階です。これらはプレビューできます。
**エンジン**
+ [Unity](#working-with_engines_unity) (最小バージョン 2022.3.19.F1)
+ [Unreal Engine](#working-with_engines_unreal) (最小バージョン 5.0)
## Unity
Unity で SimSpace Weaver シミュレーションを構築する前に、Unity開発環境が既にインストールされている必要があります。詳細については、以下の個別の指示を参照してください。
```
sdk-folder\Unity-Guide.pdf
```
## Unreal Engine
ソースコードから Unreal Engine 専有サーバーを構築する必要があります。SimSpaceWeaverAppSDKDistributable には、Unreal Engine の PathfindingSample のバージョンが含まれています。詳細については、以下の個別の指示を参照してください。
```
sdk-folder\Unreal-Engine-Guide.pdf
```
# でのライセンスソフトウェアの使用 AWS SimSpace Weaver
AWS SimSpace Weaver では、選択したシミュレーションエンジンとコンテンツを使用してシミュレーションを構築できます。の使用に関連して SimSpace Weaver、シミュレーションで使用するソフトウェアまたはコンテンツのライセンス条項を取得、維持、遵守する責任はお客様にあります。仮想化ホスト環境でのソフトウェアとコンテンツの展開がライセンス契約書上で許可されていることを確認してください。
# を使用した リソースの管理 AWS CloudFormation
AWS CloudFormation を使用して AWS SimSpace Weaver リソースを管理できます。 CloudFormation は、 AWS インフラストラクチャをコードとして指定、プロビジョニング、管理するのに役立つ別の AWS サービスです。 CloudFormation では、*[テンプレート](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-whatis-concepts.html#cfn-concepts-templates template)*と呼ばれる JSON または YAML ファイルを作成します。テンプレートはインフラストラクチャの詳細を指定します。 CloudFormation はテンプレートを使用して、*[スタック](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-whatis-concepts.html#w2ab1b5c15b9)*と呼ばれる単一のユニットとしてインフラストラクチャをプロビジョニングします。スタックを削除すると、スタック内のすべてのものを同時に CloudFormation 削除できます。標準のソースコード管理プロセスを使用してテンプレートを管理できます (例えば、[Git](https://git-scm.com/) などのバージョン管理システムでテンプレートを追跡するなどです)。詳細については CloudFormation、[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide)」を参照してください。
**シミュレーションリソース**
では AWS、*リソース*はユーザーが操作できるエンティティです。例として、Amazon EC2 インスタンス、Amazon S3 バケット、IAM ロールなどがあります。 SimSpace Weaver シミュレーションはリソースです。設定では、通常、 形式で AWS リソースを指定します`AWS::service::resource`。では SimSpace Weaver、シミュレーションリソースを として指定します`AWS::SimSpaceWeaver::Simulation`。のシミュレーションリソースの詳細については CloudFormation、*AWS CloudFormation 「 ユーザーガイド*」の[SimSpace Weaver](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-simspaceweaver-simulation.html)「」セクションを参照してください。
**CloudFormation で を使用するにはどうすればよいですか SimSpace Weaver？**
プロビジョニングする AWS リソースを指定する CloudFormation テンプレートを作成できます。テンプレートでは、アーキテクチャ全体、アーキテクチャの一部、または小規模なソリューションを指定できます。例えば、Amazon S3 バケット、IAM アクセス許可、Amazon Relational Database Service または Amazon DynamoDB のサポートデータベース、`Simulation`リソースを含む SimSpace Weaver ソリューションのアーキテクチャを指定できます。その後、 CloudFormation を使用して、これらのすべてのリソースをユニットとして同時にプロビジョニングできます。
**Example IAM リソースを作成してシミュレーションを開始するテンプレート**
以下のテンプレート例は、 SimSpace Weaver がアカウントでアクションを実行するために必要な IAM ロールとアクセス許可を作成します。 SimSpace Weaver アプリケーション SDK スクリプトは、プロジェクトの作成 AWS リージョン 時に特定の にロールとアクセス許可を作成しますが、 CloudFormation テンプレートを使用して、スクリプトを再度実行せずにシミュレーションを別の AWS リージョン にデプロイできます。例えば、ディザスタリカバリを目的としたバックアップシミュレーションを設定できます。
この例では、元のシミュレーション名は `MySimulation` です。スキーマのバケットは、 AWS リージョン CloudFormation がスタックを構築する に既に存在します。バケットには、その AWS リージョンでシミュレーションを実行するように適切に設定されたバージョンのスキーマが含まれています。スキーマはアプリケーションのの場所を指定していることに留意します。この zip ファイルは、シミュレーションと同じ AWS リージョン にある Amazon S3 バケットです。アプリケーション zip バケットとファイルは、 がスタック CloudFormation を構築する AWS リージョン ときに に既に存在している必要があります。存在しない場合、シミュレーションは開始されません。この例のバケット名には が含まれていますが AWS リージョン、バケットが実際にどこにあるかは決定されません。バケットが実際にその にあることを確認する必要があります AWS リージョン （バケットのプロパティは、Amazon S3 コンソール、Amazon S3 APIs、または の Amazon S3 コマンドで確認できます AWS CLI）。
この例では、 の組み込み関数とパラメータ CloudFormation を使用して変数置換を実行します。詳細については、「*AWS CloudFormation ユーザーガイド*」の「[組み込み関数リファレンス](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference.html)」と「[疑似パラメータリファレンス](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/pseudo-parameter-reference.html)」を参照してください。
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
WeaverAppRole:
Type: AWS::IAM::Role
Properties:
RoleName: SimSpaceWeaverAppRole
AssumeRolePolicyDocument:
Version: 2012-10-17
Statement:
- Effect: Allow
Principal:
Service:
- simspaceweaver.amazonaws.com
Action:
- sts:AssumeRole
Path: /
Policies:
- PolicyName: SimSpaceWeaverAppRolePolicy
PolicyDocument:
Version: 2012-10-17
Statement:
- Effect: Allow
Action:
- logs:PutLogEvents
- logs:DescribeLogGroups
- logs:DescribeLogStreams
- logs:CreateLogGroup
- logs:CreateLogStream
Resource: *
- Effect: Allow
Action:
- cloudwatch:PutMetricData
Resource: *
- Effect: Allow
Action:
- s3:ListBucket
- s3:PutObject
- s3:GetObject
Resource: *
MyBackupSimulation:
Type: AWS::SimSpaceWeaver::Simulation
Properties:
Name: !Sub 'mySimulation-${AWS::Region}'
RoleArn: !GetAtt WeaverAppRole.Arn
SchemaS3Location:
BucketName: !Sub 'weaver-mySimulation-${AWS::AccountId}-schemas-${AWS::Region}'
ObjectKey: !Sub 'schema/mySimulation-${AWS::Region}-schema.yaml'
```
# でのスナップショットの使用 AWS CloudFormation
[スナップショット](working-with_snapshots.md)はシミュレーションのバックアップです。以下の例では、スキーマからではなくスナップショットから新しいシミュレーションを開始します。この例のスナップショットは、 SimSpace Weaver アプリケーション SDK プロジェクト simulation から作成されました。 は新しいシミュレーションリソース CloudFormation を作成し、スナップショットのデータを使用して初期化します。新しいシミュレーションは、元のシミュレーションとは異なる `MaximumDuration` を持つ可能性があります。
元のシミュレーションのアプリケーションロールのコピーを作成して使用することをお勧めします。元のシミュレーションのアプリケーションロールは、そのシミュレーションの CloudFormation スタックを削除すると削除される可能性があります。
```
Description: "Example - Start a simulation from a snapshot"
Resources:
MyTestSimulation:
Type: "AWS::SimSpaceWeaver::Simulation"
Properties:
MaximumDuration: "2D"
Name: "MyTestSimulation_from_snapshot"
RoleArn: "arn:aws:iam::111122223333:role/weaver-MyTestSimulation-app-role-copy"
SnapshotS3Location:
BucketName: "weaver-mytestsimulation-111122223333-artifacts-us-west-2"
ObjectKey: "snapshot/MyTestSimulation_22-12-15_12_00_00-230428-1207-13.zip"
```
# スナップショット
*スナップショット*を作成して、シミュレーションエンティティデータをいつでもバックアップできます。 SimSpace Weaver は Amazon S3 バケットに .zip ファイルを作成します。snapshot を使用して新しいシミュレーションを作成できます。 は、スナップショットに保存されているエンティティデータを使用して新しいシミュレーションのステートファブリックを SimSpace Weaver 初期化し、スナップショットの作成時に実行されていた空間アプリケーションとサービスアプリケーションを起動し、クロックを適切な tick に設定します。 は、スキーマファイルからではなく、スナップショットからシミュレーションの設定 SimSpace Weaver を取得します。アプリケーションの .zip ファイルは、Amazon S3 内の元のシミュレーションと同じ場所にある必要があります。カスタムアプリケーションはすべて個別に起動する必要があります。
**トピック**
+ [スナップショットのユースケース](#working-with_snapshots_use-cases)
+ [SimSpace Weaver コンソールを使用してスナップショットを操作する](working-with_snapshots_console.md)
+ [AWS CLI を使用してスナップショットを操作する](working-with_snapshots_cli.md)
+ [でのスナップショットの使用 AWS CloudFormation](working-with_cloudformation_snapshots.md)
+ [スナップショットに関するよくある質問](working-with_snapshots_faq.md)
## スナップショットのユースケース
### 前の状態に戻り、分岐シナリオを検討する
シミュレーションのスナップショットを作成して、特定の状態に保存できます。その後、そのスナップショットから複数の新しいシミュレーションを作成し、その状態から分岐する可能性のあるさまざまなシナリオを検討できます。
### ディザスタリカバリとセキュリティのベストプラクティス
特に 1 時間以上実行されるシミュレーションや複数のワーカーを使用するシミュレーションでは、定期的にシミュレーションをバックアップすることをお勧めします。バックアップは、障害やセキュリティインシデントからの回復に役立ちます。スナップショットは、シミュレーションのバックアップを提供する方法を提供します。スナップショットでは、アプリケーションの .zip ファイルが以前と同じ Amazon S3 の場所に存在している必要があります。アプリケーションの.zip ファイルを別の場所に移動できるようにする必要がある場合は、カスタムバックアップソリューションを使用する必要があります。
その他のベストプラクティスの詳細については、「[を使用する際のベストプラクティス SimSpace Weaver](best-practices.md)」および「[のセキュリティのベストプラクティス SimSpace Weaver](security_best-practices.md)」を参照してください。
### シミュレーション時間を延長する
*シミュレーションリソース*は、 SimSpace Weaverでのシミュレーションの表現です。すべてのシミュレーションリソースには `MaximumDuration` 設定があります。シミュレーションは、`MaximumDuration` に達すると自動的に停止します。`MaximumDuration` の最大値は `14D` (14 日間) です。
シミュレーションをそのシミュレーションリソースの `MaximumDuration` より長く持続させる必要がある場合は、シミュレーションリソースがその `MaximumDuration` に達する前にスナップショットを作成できます。スナップショットを使用して新しいシミュレーションを開始 (新しいシミュレーションリソースを作成) できます。 SimSpace Weaver はスナップショットからエンティティデータを初期化し、以前に実行したのと同じ空間アプリケーションとサービスアプリケーションを起動して、クロックを復元します。カスタムアプリケーションを起動して、その他のカスタム初期化を実行できます。新しいシミュレーションリソースの `MaximumDuration` は、起動時に別の値に設定できます。
# SimSpace Weaver コンソールを使用してスナップショットを操作する
SimSpace Weaver コンソールを使用してシミュレーションのスナップショットを作成できます。
**Topics**
+ [スナップショットを作成する](#working-with_snapshots_console_create)
+ [スナップショットからシミュレーションを開始する](#working-with_snapshots_console_start)
## コンソールでスナップショットを作成する
**スナップショットを作成する方法**
1. にサインイン AWS マネジメントコンソール し、 [SimSpace Weaver コンソール](https://console.aws.amazon.com/simspaceweaver)に接続します。
1. ナビゲーションペインで、[**シミュレーション**] を選択します。
1. シミュレーション名の横にあるラジオボタンを選択します。シミュレーションの [**ステータス**] は [**開始**] である必要があります。
1. ページの上部で、[**スナップショットの作成**] を選択します。
1. **スナップショット設定**の**スナップショット送信先**で、スナップショット SimSpace Weaver を作成するバケットまたはバケットとフォルダの Amazon S3 URI を入力します。使用可能なバケットをブラウズして場所を選択する場合は、[**S3 を参照**] を選択できます。
**重要**
Amazon S3 バケットはシミュレーションと同じ AWS リージョン にある必要があります。
**注記**
SimSpace Weaver は、選択したスナップショット送信先内に`snapshot`フォルダを作成します。 はその`snapshot`フォルダにスナップショット .zip ファイル SimSpace Weaver を作成します。
1. [**スナップショットを作成**] を選択します。
## コンソールを使用してスナップショットからシミュレーションを開始する
スナップショットからシミュレーションを開始するには、スナップショットの .zip ファイルが、シミュレーションがアクセスできる Amazon S3 バケットに存在している必要があります。シミュレーションでは、シミュレーションの開始時に選択したアプリケーションロールで定義されているアクセス許可を使用します。元のシミュレーションのアプリケーションの .zip ファイルはすべて、スナップショットが作成されたときと同じ場所に存在している必要があります。
**スナップショットからシミュレーションを開始する方法**
1. にサインイン AWS マネジメントコンソール し、 [SimSpace Weaver コンソール](https://console.aws.amazon.com/simspaceweaver)に接続します。
1. ナビゲーションペインで、[**シミュレーション**] を選択します。
1. ページ上部の [**シミュレーションを開始**] を選択します。
1. [**シミュレーション設定**] で、シミュレーションの名前と説明 (オプション) を入力します。シミュレーション名は AWS アカウント内で一意である必要があります。
1. [**シミュレーション開始方法**] で [**Amazon S3 のスナップショットを使用する**] を選択します。
1. **スナップショットの Amazon S3 URI** には、スナップショットファイルの Amazon S3 URI を入力するか、[**S3 を参照**] を選択してファイルを参照して選択します。
**重要**
Amazon S3 バケットはシミュレーションと同じ AWS リージョン にある必要があります。
1. [**IAM ロール**] には、シミュレーションで使用するアプリケーションロールを選択します。
1. [**最大期間**] には、シミュレーションリソースを実行する最大期間を入力します。最大値は `14D` です。最大期間の詳細については、「[https://docs.aws.amazon.com/simspaceweaver/latest/APIReference/API_StartSimulation.html](https://docs.aws.amazon.com/simspaceweaver/latest/APIReference/API_StartSimulation.html)」を参照してください
1. タグを追加する場合は、[**タグ - *オプション***] で [**新しいタグを追加**] を選択します。
1. [**シミュレーションを開始**] を選択します。
# AWS CLI を使用してスナップショットを操作する
を使用して AWS CLI 、コマンドプロンプトから SimSpace Weaver APIsを呼び出すことができます。が正しく AWS CLI インストールおよび設定されている必要があります。詳細については、[「 バージョン 2 AWS ユーザーガイド」の「 CLI の最新バージョンのインストールまたは更新](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)」を参照してください。 *AWS Command Line Interface *
**Topics**
+ [スナップショットを作成する](#working-with_snapshots_cli_create)
+ [スナップショットからシミュレーションを開始する](#working-with_snapshots_cli_start)
## を使用してスナップショット AWS CLI を作成する
**スナップショットを作成する方法**
+ **コマンドプロンプト**で `CreateSnapshot` API を呼び出します。
```
aws simspaceweaver create-snapshot --simulation simulation-name —destination s3-destination
```
**パラメータ**
シミュレーション
開始したシミュレーション名。`aws simspaceweaver list-simulations` を使用して、シミュレーション名およびステータスを確認できます。
宛先
スナップショットファイルの送信先の Amazon S3 バケットとオプションのオブジェクトキーのプレフィックス指定する文字列。オブジェクトキープレフィックスは通常、バケット内のフォルダです。 は、この宛先の`snapshot`フォルダ内にスナップショット SimSpace Weaver を作成します。
Amazon S3 バケットはシミュレーションと同じ AWS リージョン にある必要があります。
**例**
```
aws simspaceweaver create-snapshot —simulation MyProjectSimulation_23-04-29_12_00_00 —destination BucketName=weaver-myproject-111122223333-artifacts-us-west-2,ObjectKeyPrefix=myFolder
```
`CreateSnapshot` API の詳細については、「*AWS SimSpace Weaver API リファレンス*」の「[CreateSnapshot](https://docs.aws.amazon.com/simspaceweaver/latest/APIReference/API_CreateSnapshot.html)」を参照してください。
## を使用してスナップショットからシミュレーション AWS CLI を開始する
**スナップショットからシミュレーションを開始する方法**
+ **コマンドプロンプト**で `StartSimulation` API を呼び出します。
```
aws simspaceweaver start-simulation --name simulation-name --role-arn role-arn --snapshot-s3-location s3-location
```
**パラメータ**
名前
新しいシミュレーションの名前。シミュレーション名は 内で一意である必要があります AWS アカウント。`aws simspaceweaver list-simulations` を使用して、既存のシミュレーション名を確認できます。
role-arn
シミュレーションが使用するアプリケーションロールの Amazon リソースネーム (ARN)。
snapshot-s3-location
スナップショットファイルの Amazon S3 バケットとオブジェクトキーを指定する文字列。
Amazon S3 バケットはシミュレーションと同じ AWS リージョン にある必要があります。
**例**
```
aws simspaceweaver start-simulation —name MySimulation —role-arn arn:aws:iam::111122223333:role/weaver-MyProject-app-role —snapshot-s3-location BucketName=weaver-myproject-111122223333-artifacts-us-west-2,ObjectKey=myFolder/snapshot/MyProjectSimulation_23-04-29_12_00_00-230429-1530-27.zip
```
`StartSimulation` API の詳細については、「*AWS SimSpace Weaver API リファレンス*」の「[StartSimulation](https://docs.aws.amazon.com/simspaceweaver/latest/APIReference/API_StartSimulation.html)」を参照してください。
# スナップショットに関するよくある質問
**スナップショットの作成中もシミュレーションは実行され続けますか?**
シミュレーションリソースはスナップショット中も引き続き実行され、その間も引き続き料金が発生します。この時間はシミュレーションの最大期間に加算されます。スナップショットの進行中は、アプリケーションにティックを受け取りません。スナップショットの作成開始時にクロックのステータスが `STARTED` であった場合、クロックは `STARTED` ステータスのままになります。スナップショットの終了後、アプリケーションには再びティックを受け取ります。クロックのステータスが `STOPPED` であった場合、クロックの状態は `STOPPED` のままになります。`STARTED` ステータスのシミュレーションは、クロックのステータスが `STOPPED` であっても実行されることに注意してください。
**スナップショットが進行中に、シミュレーションが最大期間に達した場合はどうなりますか?**
シミュレーションはスナップショットを終了し、スナップショット処理が終了すると (成功か失敗かにかかわらず) すぐに停止します。所要時間、予測できるスナップショットファイルのサイズ、および正常に完了するかどうかを、スナップショット処理の前にテストして、確認することをお勧めします。
**スナップショットが進行中のシミュレーションを停止するとどうなりますか?**
進行中のスナップショットは、シミュレーションを停止するとすぐに停止します。スナップショットファイルは作成されません。
**実行中のスナップショットを停止する方法を教えてください。**
進行中のスナップショットを停止する唯一の方法は、シミュレーションを停止することです。**停止したシミュレーションは再開できません。**
**スナップショットの完了にはどれくらいの時間がかかりますか?**
スナップショットの作成に必要な時間は、シミュレーションによって異なります。シミュレーションにどれくらいの時間がかかるかをスナップショット処理の前にテストして、確認することをお勧めします。
**スナップショットファイルのサイズはどれくらいになりますか?**
スナップショットファイルのサイズは、シミュレーションによって異なります。シミュレーション用のファイルのサイズをスナップショット処理の前にテストして、確認することをお勧めします。
# メッセージング
メッセージング API は、シミュレーション内のアプリケーション間通信を簡素化します。メッセージを送受信するための APIsは、 SimSpace Weaver アプリケーション SDK の一部です。メッセージングは現在、メッセージの送受信にベストエフォートアプローチを使用しています。SimSpace Weaver は次のシミュレーションティックでメッセージの送受信を試みますが、配信、注文、到着時間の保証はありません。
**トピック**
+ [メッセージングのユースケース](#working-with_messaging_use-cases)
+ [メッセージング APIs](working-with_messaging_using.md)
+ [メッセージングを使用するタイミング](working-with_messaging_when-to-use.md)
+ [メッセージングを使用する際のヒント](working-with_messaging_tips.md)
+ [メッセージングエラーとトラブルシューティング](working-with_messaging_troubleshooting.md)
## メッセージングのユースケース
**シミュレーションアプリケーション間の通信**
メッセージング API を使用して、シミュレーション内のアプリケーション間で通信します。これを使用して、遠くのエンティティの状態を変更したり、エンティティの動作を変更したり、シミュレーション全体に情報をブロードキャストしたりできます。
**メッセージ受信の確認**
送信メッセージには、メッセージヘッダーの送信者に関する情報が含まれます。この情報を使用して、メッセージの受信時に確認応答を送り返します。
**カスタムアプリケーションによって受信したデータをシミュレーション内の他のアプリケーションに転送する**
メッセージングは、クライアントが で実行されているカスタムアプリケーションに接続する方法に代わるものではありません SimSpace Weaver。ただし、メッセージングでは、クライアントデータを受信するカスタムアプリケーションから、外部接続を持たない他のアプリケーションにデータを転送できます。メッセージフローは逆方向にも機能するため、外部接続のないアプリケーションはデータをカスタムアプリケーションに転送し、次にクライアントに転送できます。
# メッセージング APIs
メッセージング APIs は、 SimSpace Weaver アプリケーション SDK (最小バージョン 1.16.0) に含まれています。メッセージングは、C\$1\$1、Python、および Unreal Engine 5 および Unity との統合でサポートされています。
メッセージトランザクションを処理する関数は `SendMessage`と の 2 つです`ReceiveMessages`。送信されたすべてのメッセージには、送信先とペイロードが含まれます。`ReceiveMessages` API は、アプリのインバウンドメッセージキューに現在あるメッセージのリストを返します。
------
#### [ C\$1\$1 ]
**メッセージの送信**
```
AWS_WEAVERRUNTIME_API Result SendMessage(
Transaction& txn,
const MessagePayload& payload,
const MessageEndpoint& destination,
MessageDeliveryType deliveryType = MessageDeliveryType::BestEffort
) noexcept;
```
**メッセージを受信する**
```
AWS_WEAVERRUNTIME_API Result ReceiveMessages(
Transaction& txn) noexcept;
```
------
#### [ Python ]
**メッセージの送信**
```
api.send_message(
txn, # Transaction
payload, # api.MessagePayload
destination, # api.MessageDestination
api.MessageDeliveryType.BestEffort # api.MessageDeliveryType
)
```
**メッセージを受信する**
```
api.receive_messages(
txn, # Transaction
) -> api.MessageList
```
------
**トピック**
+ [メッセージの送信](#working-with_messaging_using_send)
+ [メッセージの受信](#working-with_messaging_using_receive)
+ [送信者への返信](#working-with_messaging_using_reply)
## メッセージの送信
メッセージは、トランザクション (他の Weaver API コールと同様）、ペイロード、および送信先で構成されます。
### メッセージペイロード
メッセージペイロードは、最大 256 バイトの柔軟なデータ構造です。メッセージペイロードを作成するためのベストプラクティスとして、以下をお勧めします。
**メッセージペイロードを作成するには**
1. メッセージの内容を定義するデータ構造 (C\$1\$1 `struct`の など) を作成します。
1. メッセージで送信する値を含むメッセージペイロードを作成します。
1. `MessagePayload` オブジェクトを作成します。
### メッセージの送信先
メッセージの送信先は、 `MessageEndpoint` オブジェクトによって定義されます。これには、エンドポイントタイプとエンドポイント ID の両方が含まれます。現在サポートされているエンドポイントタイプは のみです。これにより`Partition`、シミュレーション内の他のパーティションへのメッセージに対処できます。エンドポイント ID は、ターゲットの送信先のパーティション ID です。
メッセージには送信先アドレスを 1 つだけ指定できます。複数のパーティションに同時にメッセージを送信する場合は、複数のメッセージを作成して送信します。
位置からメッセージエンドポイントを解決する方法のガイダンスについては、「」を参照してください[メッセージングを使用する際のヒント](working-with_messaging_tips.md)。
### メッセージを送信する
`SendMessage` API は、送信先オブジェクトとペイロードオブジェクトを作成した後に使用できます。
------
#### [ C\$1\$1 ]
```
Api::SendMessage(transaction, payload, destination, MessageDeliveryType::BestEffort);
```
------
#### [ Python ]
```
api.send_message(txn, payload, destination, api.MessageDeliveryType.BestEffort)
```
------
**メッセージを送信する完全な例**
次の例は、汎用メッセージを作成して送信する方法を示しています。この例では、16 個の個別のメッセージを送信します。各メッセージには、値が 0～15 のペイロードと、現在のシミュレーションティックが含まれます。
**Example**
```
// Message struct definition
struct MessageTickAndId
{
uint32_t id;
uint32_t tick;
};
Aws::WeaverRuntime::Result SendMessages(Txn& txn) noexcept
{
// Fetch the destination MessageEndpoint with the endpoint resolver
WEAVERRUNTIME_TRY(
Api::MessageEndpoint destination,
Api::Utils::MessageEndpointResolver::ResolveFromPosition(
txn,
"MySpatialSimulation",
Api::Vector2F32 {231.3, 654.0}
)
);
Log::Info("destination: ", destination);
WEAVERRUNTIME_TRY(auto tick, Api::CurrentTick(txn));
uint16_t numSentMessages = 0;
for (std::size_t i=0; i<16; i++)
{
// Create the message that'll be serialized into payload
MessageTickAndId message {i, tick.value};
// Create the payload out of the struct
const Api::MessagePayload& payload = Api::Utils::CreateMessagePayload(
reinterpret_cast(&message),
sizeof(MessageTickAndId)
);
// Send the payload to the destination
Result result = Api::SendMessage(txn, payload, destination);
if (result.has_failure())
{
// SendMessage has failure modes, log them
auto error = result.as_failure().error();
std::cout<< "SendMessage failed, ErrorCode: " << error << std::endl;
continue;
}
numSentMessages++;
}
std::cout << numSentMessages << " messages is sent to endpoint"
<< destination << std::endl;
return Aws::WeaverRuntime::Success();
}
```
```
# Message data class
@dataclasses.dataclass
class MessageTickAndId:
tick: int = 0
id: int = 0
# send messages
def _send_messages(self, txn):
tick = api.current_tick(txn)
num_messages_to_send = 16
# Fetch the destination MessageEndpoint with the endpoint resolver
destination = api.utils.resolve_endpoint_from_domain_name_position(
txn,
"MySpatialSimulation",
pos
)
Log.debug("Destination_endpoint = %s", destination_endpoint)
for id in range(num_messages_to_send):
# Message struct that'll be serialized into payload
message_tick_and_id = MessageTickAndId(id = id, tick = tick.value)
# Create the payload out of the struct
message_tick_and_id_data = struct.pack(
'
SimSpace Weaver は、パーティションのインバウンドメッセージキューにメッセージを配信します。`ReceiveMessages` API を使用して、キューからのメッセージを含む`MessageList`オブジェクトを取得します。`ExtractMessage` API を使用して各メッセージを処理し、メッセージデータを取得します。
**Example**
```
Result ReceiveMessages(Txn& txn) noexcept
{
// Fetch all the messages sent to the partition owned by the app
WEAVERRUNTIME_TRY(auto messages, Api::ReceiveMessages(txn));
std::cout << "Received" << messages.messages.size() << " messages" << std::endl;
for (Api::Message& message : messages.messages)
{
std::cout << "Received message: " << message << std::endl;
// Deserialize payload to the message struct
const MessageTickAndId& receivedMessage
= Api::Utils::ExtractMessage(message);
std::cout << "Received MessageTickAndId, Id: " << receivedMessage.id
<<", Tick: " << receivedMessage.tick << std::endl;
}
return Aws::WeaverRuntime::Success();
}
```
```
# process incoming messages
def _process_incoming_messages(self, txn):
messages = api.receive_messages(txn)
for message in messages:
payload_list = message.payload.data
payload_bytes = bytes(payload_list)
message_tick_and_id_data_struct
= MessageTickAndId(*struct.unpack('
受信したすべてのメッセージには、メッセージの元の送信者に関する情報を含むメッセージヘッダーが含まれます。message.header.source\$1endpoint を使用して返信を送信できます。
**Example**
```
Result ReceiveMessages(Txn& txn) noexcept
{
// Fetch all the messages sent to the partition owned by the app
WEAVERRUNTIME_TRY(auto messages, Api::ReceiveMessages(txn));
std::cout << "Received" << messages.messages.size() << " messages" << std::endl;
for (Api::Message& message : messages.messages)
{
std::cout << "Received message: " << message << std::endl;
// Deserialize payload to the message struct
const MessageTickAndId& receivedMessage
= Api::Utils::ExtractMessage(message);
std::cout << "Received MessageTickAndId, Id: " << receivedMessage.id
<<", Tick: " << receivedMessage.tick << std::endl;
// Get the sender endpoint and payload to bounce the message back
Api::MessageEndpoint& sender = message.header.source_endpoint;
Api::MessagePayload& payload = message.payload;
Api::SendMessage(txn, payload, sender);
}
return Aws::WeaverRuntime::Success();
}
```
```
# process incoming messages
def _process_incoming_messages(self, txn):
messages = api.receive_messages(txn)
for message in messages:
payload_list = message.payload.data
payload_bytes = bytes(payload_list)
message_tick_and_id_data_struct
= MessageTickAndId(*struct.unpack('
のメッセージング SimSpace Weaver は、シミュレーションアプリケーション間で情報を交換するための別のパターンを提供します。サブスクリプションは、シミュレーションの特定のアプリケーションまたは領域からデータを読み取るプルメカニズムを提供します。メッセージは、シミュレーションの特定のアプリケーションまたは領域にデータを送信するプッシュメカニズムを提供します。
以下は、サブスクリプションを通じてデータをプルまたは読み取るよりも、メッセージングを使用してデータをプッシュする方が役立つ 2 つのユースケースです。
**Example 1: エンティティの位置を変更するコマンドを別のアプリケーションに送信する**
```
// Message struct definition
struct MessageMoveEntity
{
uint64_t entityId;
std::array destinationPos;
};
// Create the message
MessageMoveEntity message {45, {236.67, 826.22, 0.0} };
// Create the payload out of the struct
const Api::MessagePayload& payload = Api::Utils::CreateMessagePayload(
reinterpret_cast(&message),
sizeof(MessageTickAndId)
);
// Grab the MessageEndpoint of the recipient app.
Api::MessageEndpoint destination = ...
// One way is to resolve it from the domain name and position
WEAVERRUNTIME_TRY(
Api::MessageEndpoint destination,
Api::Utils::MessageEndpointResolver::ResolveFromPosition(
txn,
"MySpatialSimulation",
Api::Vector2F32 {200.0, 100.0}
)
);
// Then send the message
Api::SendMessage(txn, payload, destination);
```
受信側では、アプリケーションはエンティティの位置を更新し、ステートファブリックに書き込みます。
```
Result ReceiveMessages(Txn& txn) noexcept
{
WEAVERRUNTIME_TRY(auto messages, Api::ReceiveMessages(txn));
for (Api::Message& message : messages.messages)
{
std::cout << "Received message: " << message << std::endl;
// Deserialize payload to the message struct
const MessageMoveEntity& receivedMessage
= Api::Utils::ExtractMessage(message);
ProcessMessage(txn, receivedMessage);
}
return Aws::WeaverRuntime::Success();
}
void ProcessMessage(Txn& txn, const MessageMoveEntity& receivedMessage)
{
// Get the entity corresponding to the entityId
Entity entity = EntityFromEntityId (receivedMessage.entityId);
// Update the position and write to StateFabric
WEAVERRUNTIME_TRY(Api::StoreEntityIndexKey(
txn,
entity,
k_vector3f32TypeId, // type id of the entity
reinterpret_cast(&receivedMessage.destinationPos),
sizeof(receivedMessage.destinationPos)));
}
```
**Example 2: エンティティ作成メッセージを空間アプリケーションに送信する**
```
struct WeaverMessage
{
const Aws::WeaverRuntime::Api::TypeId messageTypeId;
};
const Aws::WeaverRuntime::Api::TypeId k_createEntityMessageTypeId = { 1 };
struct CreateEntityMessage : WeaverMessage
{
const Vector3 position;
const Aws::WeaverRuntime::Api::TypeId typeId;
};
CreateEntityMessage messageData {
k_createEntityMessageTypeId,
Vector3{ position.GetX(), position.GetY(), position.GetZ() },
Api::TypeId { 0 }
}
WEAVERRUNTIME_TRY(Api::MessageEndpoint destination, Api::Utils::MessageEndpointResolver::ResolveFromPosition(
transaction, "MySpatialDomain", DemoFramework::ToVector2F32(position)
));
Api::MessagePayload payload = Api::Utils::CreateMessagePayload(
reinterpret_cast(&messageData),
sizeof(CreateEntityMessage));
Api::SendMessage(transaction, payload, destination);
```
受信側では、アプリはステートファブリックに新しいエンティティを作成し、その位置を更新します。
```
Result ReceiveMessages(Txn& txn) noexcept
{
WEAVERRUNTIME_TRY(auto messageList, Api::ReceiveMessages(transaction));
WEAVERRUNTIME_TRY(auto tick, Api::CurrentTick(transaction));
for (auto& message : messageList.messages)
{
// cast to base WeaverMessage type to determine MessageTypeId
WeaverMessage weaverMessageBase = Api::Utils::ExtractMessage(message);
if (weaverMessageBase.messageTypeId == k_createEntityMessageTypeId)
{
CreateEntityMessage createEntityMessageData =
Api::Utils::ExtractMessage(message);
CreateActorFromMessage(transaction, createEntityMessageData));
}
else if (weaverMessageBase.messageTypeId == k_tickAndIdMessageTypeId)
{
...
}
}
}
void ProcessMessage(Txn& txn, const CreateEntityMessage& receivedMessage)
{
// Create entity
WEAVERRUNTIME_TRY(
Api::Entity entity,
Api::CreateEntity(transaction, receivedMessage.typeId)
);
// Update the position and write to StateFabric
WEAVERRUNTIME_TRY(Api::StoreEntityIndexKey(
transaction,
entity,
receivedMessage.typeId,
reinterpret_cast(&receivedMessage.position),
sizeof(receivedMessage.position)));
}
```
# メッセージングを使用する際のヒント
## 位置またはアプリケーション名からエンドポイントを解決する
`AllPartitions` 関数を使用して、メッセージパーティション ID とメッセージ送信先を決定するために必要な空間境界とドメイン IDsを取得できます。ただし、メッセージする位置がわかっていてもパーティション ID がわかっていない場合は、MessageEndpointResolver 関数を使用できます。
```
/**
* Resolves MessageEndpoint's from various inputs
**/
class MessageEndpointResolver
{
public:
/**
* Resolves MessageEndpoint from position information
**/
Result ResolveEndpointFromPosition(
const DomainId& domainId,
const weaver_vec3_f32_t& pos);
/**
* Resolves MessageEndpoint from custom app name
**/
Result ResolveEndpointFromCustomAppName(
const DomainId& domainId,
const char* agentName);
};
```
## メッセージペイロードのシリアル化と逆シリアル化
次の関数を使用して、メッセージペイロードを作成および読み取ることができます。詳細については、ローカルシステムのアプリケーション SDK ライブラリの MessagingUtils.h を参照してください。
```
/**
* Utility function to create MessagePayload from a custom type
*
* @return The @c MessagePayload.
*/
template
AWS_WEAVERRUNTIME_API MessagePayload CreateMessagePayload(const T& message) noexcept
{
const std::uint8_t* raw_data = reinterpret_cast(&message);
MessagePayload payload;
std::move(raw_data, raw_data + sizeof(T), std::back_inserter(payload.data));
return payload;
}
/**
* Utility function to convert MessagePayload to custom type
*/
template
AWS_WEAVERRUNTIME_API T ExtractMessage(const MessagePayload& payload) noexcept
{
return *reinterpret_cast(payload.data.data());
}
```
# メッセージングエラーとトラブルシューティング
メッセージング APIs を使用すると、次のエラーが発生することがあります。
## エンドポイント解決エラー
これらのエラーは、アプリケーションがメッセージを送信する前に発生する可能性があります。
### ドメイン名チェック
無効なエンドポイントにメッセージを送信すると、次のエラーが発生します。
```
ManifoldError::InvalidArgument {"No DomainId found for the given domain name" }
```
これは、カスタムアプリにメッセージを送信しようとして、そのカスタムアプリがまだシミュレーションに参加していない場合に発生する可能性があります。`DescribeSimulation` API を使用して、メッセージを送信する前にカスタムアプリが起動していることを確認します。この動作は、 SimSpace Weaver Localと で同じです AWS クラウド。
### 位置チェック
有効なドメイン名で無効な位置のエンドポイントを解決しようとすると、次のエラーが発生します。
```
ManifoldError::InvalidArgument {"Could not resolve endpoint from domain : DomainId { value: domain-id } and position: Vector2F32 { x: x-position, y: y-position}" }
```
SimSpace Weaver アプリケーション SDK に含まれる`MessageUtils`ライブラリ`MessageEndpointResolver`で を使用することをお勧めします。
## メッセージ送信エラー
アプリケーションがメッセージを送信すると、次のエラーが発生する可能性があります。
### アプリ、ティック、超過あたりのメッセージ送信制限
シミュレーションティックごとにアプリケーションごとに送信できるメッセージ数の現在の制限は 128 です。同じティックの後続の呼び出しは、次のエラーで失敗します。
```
ManifoldError::CapacityExceeded {"At Max Outgoing Message capacity: {}", 128}
```
SimSpace Weaver は、次のティックで未送信メッセージを送信しようとします。この問題を解決するには、送信頻度を下げます。256 バイトの制限より小さいメッセージペイロードを組み合わせて、アウトバウンドメッセージの数を減らします。
この動作は、 SimSpace Weaver Localと で同じです AWS クラウド。
### メッセージペイロードのサイズ制限を超えました
メッセージペイロードサイズの現在の制限は、 SimSpace Weaver Localと の両方で 256 バイトです AWS クラウド。ペイロードが 256 バイトを超えるメッセージを送信すると、次のエラーが発生します。
```
ManifoldError::CapacityExceeded {"Message data too large! Max size: {}", 256}
```
SimSpace Weaver は各メッセージをチェックし、制限を超えたメッセージのみを拒否します。たとえば、アプリが 10 件のメッセージを送信しようとしたときに 1 件のチェックに失敗した場合、その 1 件のメッセージのみが拒否されます。 SimSpace Weaver は他の 9 件のメッセージを送信します。
この動作は、 SimSpace Weaver Localと で同じです AWS クラウド。
### 送信先は送信元と同じです
アプリケーションは、所有するパーティションにメッセージを送信できません。アプリケーションが所有しているパーティションにメッセージを送信すると、次のエラーが発生します。
```
ManifoldError::InvalidArgument { "Destination is the same as source" }
```
この動作は、 SimSpace Weaver Localと で同じです AWS クラウド。
### ベストエフォートメッセージング
SimSpace Weaver はメッセージの配信を保証しません。サービスは、後続のシミュレーションティックでメッセージの配信を完了しようとしますが、メッセージが失われたり遅延したりする可能性があります。