Lumberyard
開発者ガイド
Version 1.6
Lumberyard 開発者ガイド
Lumberyard 開発者ガイド
Lumberyard: 開発者ガイド
Copyright ©
Lumberyard 開発者ガイド
Table of Contents
プログラマー向け Lumberyard ........................................................................................................ 1
AI ............................................................................................................................................... 4
AIシステムの概念 .................................................................................................................. 4
AI システム概要 ............................................................................................................ 5
パス探索コスト ............................................................................................................. 8
感覚モデル ................................................................................................................. 11
飛行 .......................................................................................................................... 16
AI の C++ クラス階層 .................................................................................................. 17
AI システムの概念の例 ................................................................................................. 18
AIバブルシステム ................................................................................................................ 20
メッセージ表示タイプ .................................................................................................. 20
通知表示タイプを指定する ............................................................................................ 20
AI タクティカルポイントシステム ......................................................................................... 21
タクティカルポイントシステムの概要 ............................................................................ 22
TPS クエリ実行フロー ................................................................................................. 23
C++ を使用した TPS のクエリ ...................................................................................... 23
Lua を使用した TPS のクエリ ...................................................................................... 25
TPSクエリ言語参照 ..................................................................................................... 26
ポイントの生成および評価 ............................................................................................ 29
モジュラー動作ツリーシステムとの統合 ......................................................................... 31
今後の計画と可能性 ..................................................................................................... 32
ナビゲーションに関する Q & A ............................................................................................. 33
大きな三角形とその間にある小さいリンク ...................................................................... 33
パスの追従 ................................................................................................................. 33
自動無効化 ................................................................................................................. 33
経路追従 ............................................................................................................................ 33
Goalop "Followpath" .................................................................................................... 34
COPTrace::ExecuteTrace と COPTrace::Execute ............................................................. 34
COPTrace::Execute2D ................................................................................................. 34
動作システム ...................................................................................................................... 35
動作システムの利用について ......................................................................................... 35
潜在的改善点 .............................................................................................................. 36
自動無効化 ......................................................................................................................... 36
グローバルな自動無効化 ............................................................................................... 37
AI ごとの自動無効化 .................................................................................................... 37
AI スクリプト ..................................................................................................................... 37
コミュニケーションンシステム ..................................................................................... 37
ファクション .............................................................................................................. 43
モジュラー動作ツリー .................................................................................................. 44
Refpoint ..................................................................................................................... 87
シグナル .................................................................................................................... 88
アニメーション ........................................................................................................................... 99
アニメーションの概要 .......................................................................................................... 99
線形アニメーション ..................................................................................................... 99
インタラクティブアニメーション ................................................................................. 100
スクリプトアニメーション .......................................................................................... 102
アニメーションイベント ..................................................................................................... 102
イベントによるアニメーションのマークアップ .............................................................. 102
ゲームコードでのアニメーションイベントの受信 ........................................................... 102
Limb IK テクニカル ........................................................................................................... 103
セットアップ ............................................................................................................ 103
コードからの LimbIK の使用 ....................................................................................... 103
アニメーションストリーミング ............................................................................................ 103
アニメーションデータ ................................................................................................ 103
アニメーションのヘッダーデータ ................................................................................. 103
Version 1.6
iv
Lumberyard 開発者ガイド
アニメーションコントローラーデータ ........................................................................... 104
アニメーションのデバッグ .................................................................................................. 106
多層的移行のキューデバッギング ................................................................................. 106
CommandBufferのデバッギング ................................................................................... 111
警告レベル ............................................................................................................... 111
落下と再生 ....................................................................................................................... 111
アニメーションシステムにおける時間 ................................................................................... 112
セグメント化 ............................................................................................................ 113
再生速度 .................................................................................................................. 114
セグメント化されたパラメトリックアニメーション ........................................................ 114
キーが 1 つだけのアニメーション ................................................................................ 115
時間の方向 ............................................................................................................... 115
コントローラー内部の時間 .......................................................................................... 115
アセットビルダー API ................................................................................................................ 117
ビルダーモジュール ........................................................................................................... 117
ビルダーモジュールの作成 .................................................................................................. 118
メインエントリポイント ............................................................................................. 118
ライフサイクルコンポーネント .................................................................................... 119
ビルダーの作成 ......................................................................................................... 120
メッセージのログ記録 ........................................................................................................ 124
アセットインポーター（プレビュー）テクニカルオーバービュー ...................................................... 125
アーキテクチャーとコンセプト ............................................................................................ 125
他のコンポーネント ........................................................................................................... 127
Core Libraries ................................................................................................................... 127
FBX インポーター ワークフローの例 .................................................................................... 128
可能なアセットインポーターのカスタマイズ ......................................................................... 129
AZ モジュール (プレビュー) ........................................................................................................ 130
AZ モジュールとレガシーモジュールの比較 ......................................................................... 130
初期化の自動認識方法 ............................................................................................... 132
AZ フレームワークとの関係 ............................................................................................... 132
よりスマートなシングルトン .............................................................................................. 132
現在の Lumberyard AZ モジュール ..................................................................................... 132
LmbrCentral ............................................................................................................. 132
LmbrCentralEditor ..................................................................................................... 133
AZ モジュールのパーツ、説明 ............................................................................................. 133
モジュールのクラス ................................................................................................... 133
イベントバス ............................................................................................................ 135
システムコンポーネントのクラス ................................................................................. 135
外部コードからのモジュール呼び出し ........................................................................... 138
システムコンポーネント ..................................................................................................... 138
スマート初期化の順序 ................................................................................................ 138
簡単に設定可能なコンポーネント ................................................................................. 139
システムコンポーネントの作成 .................................................................................... 140
必須のシステムコンポーネント .................................................................................... 140
gem と AZ モジュール ....................................................................................................... 140
gem の構造 .............................................................................................................. 141
Waf の統合 ............................................................................................................... 141
AZ モジュールとしてビルドされる gem ........................................................................ 141
gem ではない AZ モジュールの作成 ..................................................................................... 142
A. gem を使用して開始 .............................................................................................. 142
B. AZ モジュールの宣言の編集 .................................................................................... 142
C. CryEngine 参照の削除 (オプション) ........................................................................ 143
D. Wscript および Waf Spec ファイルの変更 ................................................................. 143
E. 新しいモジュールをロードするようにプロジェクトを設定する .................................... 144
F. モジュールのパブリックインターフェイスをプロジェクトのインクルードパスに追加す
る ............................................................................................................................ 145
システムエンティティの設定 ............................................................................................... 145
アプリケーション記述子ファイル ................................................................................ 149
Version 1.6
v
Lumberyard 開発者ガイド
AZ ブートストラップのプロセス .......................................................................................... 150
AZ コードジェネレーター ................................................................................................... 151
ワークフローの概要 ................................................................................................... 151
WAF ........................................................................................................................ 152
Clang ....................................................................................................................... 152
中間の JSON データ .................................................................................................. 152
AZ コードジェネレーターと Python ............................................................................. 153
テンプレートドライバーとテンプレートのレンダリング .................................................. 154
生成されるファイル ................................................................................................... 154
AZ コードジェネレーターと Waf の統合 ....................................................................... 156
AZ コードジェネレーターのパラメーター ...................................................................... 158
コード生成テンプレート ............................................................................................. 162
テンプレートドライバー ............................................................................................. 164
カスタムコードジェネレーターの注釈 ........................................................................... 169
AZ コードジェネレーターによる Waf のデバッグ ........................................................... 173
テンプレートドライバーのデバッグ .............................................................................. 179
AZ コードジェネレーターユーティリティのデバッグ ...................................................... 180
中間 JSON データ形式 ............................................................................................... 182
コールバックのリファレンス ....................................................................................................... 184
エンティティシステムスクリプトのコールバック ................................................................... 184
デフォルト状態の関数 ................................................................................................ 184
スクリプトの状態の関数 ............................................................................................. 185
ゲームルールスクリプトのコールバック ............................................................................... 186
Cloud Canvas ........................................................................................................................... 189
特徴 ................................................................................................................................. 189
使用例 ............................................................................................................................. 189
ツール ............................................................................................................................. 190
前提知識 .......................................................................................................................... 190
料金表 ............................................................................................................................. 191
Cloud Canvas の主要概念 ................................................................................................... 191
前提条件 ................................................................................................................. 192
AWS、Cloud Canvas、および Lumberyard .................................................................. 192
Cloud Canvas でサポートされる Amazon Web Services ................................................. 192
Cloud Canvas リソース管理 ...................................................................................... 194
Cloud Canvas Resource Manager の概要 ............................................................................. 196
AWS CloudFormation のロール .................................................................................. 197
チュートリアル: Cloud Canvas の開始方法 ........................................................................... 198
前提条件 .................................................................................................................. 198
ステップ 1: AWS にサインアップする ......................................................................... 198
ステップ 2: Cloud Canvas プロジェクトを管理する AWS Identity and Access Management
(IAM) ユーザーを作成する .......................................................................................... 199
ステップ 3: IAM ユーザーとしてサインインする ............................................................ 201
ステップ 4: Cloud Canvas Gem（拡張機能）Package を有効にする ................................. 201
ステップ 5: Lumberyard への管理者認証情報を追加する .................................................. 202
ステップ 6: コマンドラインから Cloud Canvas を開始する .............................................. 203
ステップ 7: リソースグループを見つけて追加する ......................................................... 204
ステップ 8: デプロイを作成する ................................................................................. 205
ステップ 9: AWS でリソースを確認する ...................................................................... 207
ステップ 10: IAM を使用して Cloud Canvas チームを管理する ........................................ 207
ステップ 11: Cloud Canvas 機能と AWS リソースを削除する ......................................... 209
Don't Die サンプルプロジェクト .......................................................................................... 209
設定 ......................................................................................................................... 209
Visual Studio での Lambda コードの表示 ...................................................................... 212
AWS プロジェクトスタックの削除 ............................................................................... 214
使用した AWS サービス ............................................................................................. 214
Cloud Canvas の使用 ......................................................................................................... 215
Lumberyard エディタ の Cloud Canvas ツール .............................................................. 216
Cloud Canvas ファイルを編集する .............................................................................. 216
Version 1.6
vi
Lumberyard 開発者ガイド
Cloud Canvas Resource Manager を初期化する ............................................................ 218
Cloud Canvas プロファイルの管理 .............................................................................. 219
リソースのステータスの説明について ........................................................................... 220
Cloud Canvas コマンドラインの使用 ........................................................................... 221
Cloud Canvas の進行状況ログを表示 ........................................................................... 236
デプロイでの作業 ...................................................................................................... 236
JSON ファイルでの作業 ............................................................................................. 245
プロジェクトスタックの操作 ....................................................................................... 246
リソースグループの使用 ............................................................................................. 247
Cloud Canvas フローグラフ ノードのリファレンス ................................................................ 257
Cloud Canvas Configuration ノード .............................................................................. 258
Cognito (プレイヤー ID) ノード ................................................................................... 261
DynamoDB (データベース) ノード ............................................................................... 263
Lambda (クラウド関数) ノード .................................................................................... 269
S3 (ストレージ) ノード .............................................................................................. 270
SNS (Notification Service) ノード ................................................................................ 272
SQS (メッセージキューサービス) ノード ...................................................................... 275
静的データ (プロトタイプ) ノード ............................................................................... 277
リソースの定義 ................................................................................................................. 280
リソースの定義の場所 ................................................................................................ 281
[project-settings.json] .................................................................................................. 281
user-settings.json ....................................................................................................... 283
project-template.json .................................................................................................. 284
deployment-template.json ............................................................................................ 289
deployment-access-template.json ................................................................................. 291
プロジェクトコードのサブディレクトリ ....................................................................... 298
resource-group\{resource-group} サブディレクトリ ................................................... 298
resource-template.json ................................................................................................ 298
lambda-function-code サブディレクトリ ........................................................................ 302
リソースのデプロイ ........................................................................................................... 302
設定バケット ............................................................................................................ 303
リソースマッピング ........................................................................................................... 304
AWS フローノードでマッピングを使用する ................................................................... 305
AWS C++ SDK でマッピングを使用する ....................................................................... 305
Lambda 関数でマッピングを使用する ........................................................................... 306
カスタムリソース .............................................................................................................. 306
CognitoIdentityPool .................................................................................................... 306
EmptyDeployment ...................................................................................................... 307
ResourceGroupConfiguration ....................................................................................... 307
LambdaConfiguration ................................................................................................. 308
PlayerAccess ............................................................................................................ 309
アクセスコントロールとプレイヤ ID ..................................................................................... 310
プロジェクトのアクセスコントロール ........................................................................... 310
プレイヤのアクセスコントロール ................................................................................. 311
Lambda 関数のアクセスコントロール ........................................................................... 311
プレイヤ ID .............................................................................................................. 313
AWS クライアント設定 ...................................................................................................... 319
AWS フローグラフノードの設定 .................................................................................. 319
C++で設定 ................................................................................................................ 319
C++から設定済みクライアントを使用 ........................................................................... 320
コンポーネントエンティティシステム ........................................................................................... 322
コンポーネントの作成 ........................................................................................................ 322
コンポーネントの例 .................................................................................................. 322
コンポーネントの要素 ............................................................................................... 323
シリアル化と編集のためのコンポーネントのリフレクション .................................................... 325
シリアル化 .............................................................................................................. 327
AWS OpsWorks の ................................................................................................... 328
属性 ....................................................................................................................... 329
Version 1.6
vii
Lumberyard 開発者ガイド
変更通知コールバック ............................................................................................... 329
スライスと動的スライス ..................................................................................................... 331
スライスの構造 ......................................................................................................... 331
動的スライスの使用 ................................................................................................... 332
動的スライスのインスタンス化 .................................................................................... 333
コントローラデバイスとゲームの入力 ........................................................................................... 335
アクションマップ .............................................................................................................. 335
Action Map Manager の初期化 .................................................................................... 335
Action Map Manager のイベント ................................................................................. 336
実行時のアクションの受信 .......................................................................................... 336
CryInput ........................................................................................................................... 336
IInput ....................................................................................................................... 336
IInputEventListener .................................................................................................... 337
SInputEvent .............................................................................................................. 337
IInputDevice .............................................................................................................. 337
コントロールおよびアクションマップの設定 ......................................................................... 338
アクションマップ ...................................................................................................... 339
アクションフィルタ ................................................................................................... 340
コントローラーのレイアウト ....................................................................................... 340
ランタイムのアクションマップの操作 ........................................................................... 341
デフォルトのコントローラーマッピング ....................................................................... 341
キー命名規則 ............................................................................................................ 343
CryCommon ............................................................................................................................. 345
CryExtension .................................................................................................................... 345
コンポジット ............................................................................................................ 346
共有インターフェイスポインタと raw インターフェイスポインタ ..................................... 346
GUID ....................................................................................................................... 346
ICryUnknown ............................................................................................................ 347
ICryFactory ............................................................................................................... 348
ICryFactoryRegistry .................................................................................................... 349
その他の拡張機能 ...................................................................................................... 350
グルーコードマクロ ................................................................................................... 352
CryExtension のサンプル ............................................................................................ 356
拡張機能の使用 ......................................................................................................... 358
フレームワークの使用による拡張機能の実装 ................................................................. 360
クライストリング .............................................................................................................. 370
STLコンテナの主要な値として文字列を使用する方法 ...................................................... 370
使用詳細ヒント ......................................................................................................... 370
ICrySizer .......................................................................................................................... 371
ICrySizer インターフェイスの使用方法 ......................................................................... 371
シリアル化ライブラリ ........................................................................................................ 371
チュートリアル ......................................................................................................... 371
ユースケース ............................................................................................................ 374
デモと動画キャプチャ ................................................................................................................ 384
動画および音声をキャプチャします。 ................................................................................... 384
準備 ......................................................................................................................... 384
ビデオ設定 ............................................................................................................... 384
録画の開始と終了 ...................................................................................................... 387
オーディオ設定 ......................................................................................................... 387
設定ファイル ............................................................................................................ 388
タイムデモの記録 .............................................................................................................. 389
概要 ......................................................................................................................... 389
記録の制御 ............................................................................................................... 389
関連するコンソール変数 ............................................................................................. 390
エンティティシステム ................................................................................................................ 391
エンティティプロパティのプレフィックス ............................................................................ 391
新しいエンティティクラスの作成 ......................................................................................... 392
エンティティプールシステム ............................................................................................... 394
Version 1.6
viii
Lumberyard 開発者ガイド
エディタの使用 ......................................................................................................... 395
静的と動的なエンティティ .......................................................................................... 395
エンティティプールの定義 .......................................................................................... 395
エンティティプールの作成 .......................................................................................... 397
プールを使用した静的エンティティの作成と破棄 ........................................................... 398
プールを使用した動的エンティティの作成と破棄 ........................................................... 401
シリアル化 ............................................................................................................... 402
リスナー/イベント登録 ............................................................................................... 403
デバッグユーティリティ ............................................................................................. 403
説明されるエンティティ ID ................................................................................................. 404
エンティティに使用可能なサポートの追加 ............................................................................ 405
概要 ......................................................................................................................... 405
スクリプトの準備 ...................................................................................................... 405
実装使用可能 ............................................................................................................ 405
使用中の実行 ............................................................................................................ 406
エンティティのスクリプト化 ............................................................................................... 406
スクリプトエンティティの構造 .................................................................................... 406
エンティティ状態の使用 ............................................................................................. 409
エンティティスロットの使用 ....................................................................................... 410
エンティティのリンク ................................................................................................ 411
ネットワークへのエンティティの公開 ........................................................................... 412
イベントバス（EBus） ............................................................................................................... 415
バスの構成 ....................................................................................................................... 415
単一ハンドラー ........................................................................................................ 415
複数ハンドラー ......................................................................................................... 416
複数アドレスと単一ハンドラーの Ebus ......................................................................... 417
複数アドレスと複数ハンドラーの Ebus ......................................................................... 419
同期と非同期 .................................................................................................................... 420
その他の機能 .................................................................................................................... 421
使用方法と例 .................................................................................................................... 421
EBus の宣言 ............................................................................................................. 421
EBus の構成オプション ............................................................................................. 422
ハンドラーの実装 ...................................................................................................... 423
EBus へのメッセージ送信 ........................................................................................... 424
戻り値の取得 ............................................................................................................ 424
複数ハンドラーからの戻り値 ...................................................................................... 424
非同期/キューを使用する EBus .................................................................................... 425
ファイルへのアクセス ................................................................................................................ 426
CryPakファイルアーカイブ ................................................................................................. 426
特徴 ......................................................................................................................... 426
ユニコードおよび絶対パスの処理 ................................................................................. 426
レイヤリング ............................................................................................................ 427
スラッシュ ............................................................................................................... 427
特別なフォルダの処理 ................................................................................................ 427
内部 ......................................................................................................................... 427
7-Zipを使用したpakファイルの作成 .............................................................................. 427
大きなPakファイルの処理 ........................................................................................... 427
CryPakを使用してファイルにアクセスする .................................................................... 428
ファイルのアクセスをトラックする ...................................................................................... 435
CVars ...................................................................................................................... 435
不正アクセスが定義されるに対し、 .............................................................................. 435
グラフィックスとレンダリング .................................................................................................... 437
レンダリングノード ........................................................................................................... 437
新しいレンダリングノードの作成 ................................................................................. 438
TrueType フォントのレンダリング ....................................................................................... 441
サポートされている機能 ............................................................................................. 441
便利なコンソールコマンド .......................................................................................... 442
Stars DAT ファイルの生成 .................................................................................................. 442
Version 1.6
ix
Lumberyard 開発者ガイド
ファイル形式 ............................................................................................................ 443
アンチエイリアス処理とスーパーサンプリング ...................................................................... 443
アンチエイリアシング処理をコントロールする .............................................................. 443
スーパーサンプリングをコントロールする .................................................................... 446
Lua スクリプト ......................................................................................................................... 447
Lua スクリプトリファレンス ............................................................................................... 447
ノードの索引 ............................................................................................................ 447
Lua の一般的なグローバルと関数 ................................................................................. 449
EntityUtils Lua 関数 ................................................................................................... 453
数学Luaグローバルと関数 ........................................................................................... 456
Physics Lua 関数 ...................................................................................................... 466
Integrating Lua and C++ ..................................................................................................... 467
アクセス スクリプト テーブル ..................................................................................... 467
C++関数と値の表示 ................................................................................................... 467
Luaスクリプトの使用 ......................................................................................................... 468
スクリプトの実行 ...................................................................................................... 468
ランタイム時のリロードのスクリプト ........................................................................... 469
Lua Editor ........................................................................................................................ 469
チュートリアル: Lua Editor を使用した Lumberyard Editor でのデバッグ ............................ 469
個別の検索結果の保持 ................................................................................................ 472
AWS OpsWorks の .................................................................................................... 474
Perforce 統合 ............................................................................................................ 474
Luaのリモートデバッガーを使用する .................................................................................... 475
Luaリモートデバッガー内でタスクを実行する ............................................................... 476
Lua XML ローダーの使用 ................................................................................................... 477
XML データ .............................................................................................................. 477
Lua からのテーブルのロードと保存 .............................................................................. 478
データ型 .................................................................................................................. 478
列挙型 ..................................................................................................................... 479
例 ............................................................................................................................ 479
推奨する参照情報 .............................................................................................................. 480
ネットワークシステム ................................................................................................................ 481
マルチプレイヤの開始方法 .................................................................................................. 481
マルチプレイヤサーバーのセットアップ ....................................................................... 481
レベルのホスティング ................................................................................................ 482
サーバーへの接続 ...................................................................................................... 482
コンソールコマンドの概要 .......................................................................................... 482
サンプルプロジェクト ............................................................................................... 484
セッションサービス ........................................................................................................... 484
セッションサービスの開始と停止 ................................................................................. 484
セッションのホスティング .......................................................................................... 484
セッションの検索 ...................................................................................................... 487
セッションへの参加 ................................................................................................... 487
セッションイベントへの対応 ....................................................................................... 489
GameLift によるクラウドホスティング ........................................................................ 490
Carrier ............................................................................................................................. 490
チャネルとメッセージの優先順位 ................................................................................. 491
カスタマイズ可能なクラス .......................................................................................... 491
CarrierDesc .............................................................................................................. 491
レプリカを使用したゲームの状態の同期 ............................................................................... 493
レプリカ .................................................................................................................. 494
レプリカチャンク ...................................................................................................... 497
データセット ............................................................................................................ 500
リモートプロシージャ呼び出し (RPC) .......................................................................... 501
レプリカマネージャー ................................................................................................ 503
マーシャリングとアンマーシャリング ........................................................................... 505
コンポーネントによるネットワークへのゲーム オブジェクトのバインド ............................ 506
OpenSSL の使用 ............................................................................................................... 510
Version 1.6
x
Lumberyard 開発者ガイド
制約事項 .................................................................................................................. 511
実装サポート ............................................................................................................ 511
暗号 ......................................................................................................................... 511
暗号化してビルドする ................................................................................................ 511
暗号化の有効化 ......................................................................................................... 512
帯域幅の利用率の制御 ........................................................................................................ 515
送信レートの制御 ..................................................................................................... 515
帯域幅振幅リミッター ............................................................................................... 515
バーストの長さの制御 ............................................................................................... 515
レプリカの更新の優先順位付け ................................................................................... 516
実行時の帯域幅調整 .................................................................................................. 517
ネットワークのシリアル化と各側面 ...................................................................................... 517
側面 ......................................................................................................................... 517
プロファイル ............................................................................................................ 517
RMI 関数 .......................................................................................................................... 518
RMIファンクションのオーダリング .............................................................................. 518
オーダリングルール ................................................................................................... 518
RMI ファンクションフラグ ......................................................................................... 519
例 ............................................................................................................................ 519
物理 ......................................................................................................................................... 521
ジオメトリ ....................................................................................................................... 521
ジオメトリ管理関数 ................................................................................................... 522
物理的なエンティティ ........................................................................................................ 523
エンティティの作成と管理 .......................................................................................... 523
エンティティ構造の関数 ..................................................................................................... 526
共通関数 .................................................................................................................. 526
生きているエンティティ専用の機能 .............................................................................. 528
パーティクルのエンティティ固有の関数 ....................................................................... 530
連結型エンティティ固有の関数 .................................................................................... 530
ロープのエンティティ固有の関数 ................................................................................. 532
ソフトエンティティ固有の関数 .................................................................................... 533
Collision クラス ................................................................................................................. 533
設定 ......................................................................................................................... 534
コード ..................................................................................................................... 534
Types] ..................................................................................................................... 535
衝突のフィルタリング ................................................................................................ 535
インターフェイス ...................................................................................................... 536
世界エンティティに対する関数 ............................................................................................ 536
物理世界の時間状態を進める ...................................................................................... 536
重複する境界ダイアログボックス持つエンティティを返す ............................................... 537
環境での射線のキャスト ............................................................................................. 538
爆発の作成 ............................................................................................................... 539
プロファイラー ......................................................................................................................... 540
プロファイラーのチュートリアル ......................................................................................... 540
アプリケーションの登録 ............................................................................................. 541
プロファイラーの起動 ................................................................................................ 541
データのキャプチャ ................................................................................................... 541
データの確認 ............................................................................................................ 543
データの再生 ............................................................................................................ 545
データのエクスポート ................................................................................................ 550
注釈の作成と使用 .............................................................................................................. 550
注釈の使用 .............................................................................................................. 551
注釈の作成 .............................................................................................................. 552
トレースメッセージプロファイラーでの注釈の表示 ....................................................... 553
ネットワーキング用プロファイラーの使用 ............................................................................ 554
前提条件 ................................................................................................................. 554
キャリアプロファイラー ............................................................................................. 554
レプリカアクティビティプロファイラー ....................................................................... 555
Version 1.6
xi
Lumberyard 開発者ガイド
CPU の利用率でのプロファイラーの使用 .............................................................................. 562
ツリービューについて ................................................................................................ 563
表示の制御 ............................................................................................................... 564
VRAM のプロファイラーの使用 ........................................................................................... 566
コメント .................................................................................................................. 566
採取されるデータについて .......................................................................................... 566
データの確認 ............................................................................................................ 567
GridHub の使用 ................................................................................................................. 569
GridHub へのアプリケーションの登録 .......................................................................... 569
GridHub の表示と設定 ............................................................................................... 569
GridHub のトラブルシューティング ............................................................................. 571
ScriptBind の参照 ...................................................................................................................... 572
ScriptBind エンジン関数 ..................................................................................................... 572
ScriptBind_AI ............................................................................................................ 572
ScriptBind_Entity ........................................................................................................ 642
ScriptBind_Movie ....................................................................................................... 696
ScriptBind_Particle ..................................................................................................... 698
ScriptBind_Physics ..................................................................................................... 701
ScriptBind_Script ....................................................................................................... 704
ScriptBind_Sound ...................................................................................................... 706
ScriptBind_System ..................................................................................................... 708
ScriptBind アクション関数 .................................................................................................. 735
ScriptBind_Action ....................................................................................................... 735
ScriptBind_ActionMapManager ..................................................................................... 749
ScriptBind_ActorSystem .............................................................................................. 752
ScriptBind_GameStatistics ........................................................................................... 752
ScriptBind_GameToken .............................................................................................. 754
ScriptBind_Inventory ................................................................................................... 755
ScriptBind_ItemSystem ............................................................................................... 757
ScriptBind_Network .................................................................................................... 760
ScriptBind_UIAction .................................................................................................... 760
ScriptBind_Vehicle ..................................................................................................... 772
ScriptBind_VehicleSeat ............................................................................................... 779
ScriptBind_VehicleSystem ........................................................................................... 781
ScriptBind_Boids ................................................................................................................ 782
CanPickup ................................................................................................................ 782
CreateBugsFlock ....................................................................................................... 782
CreateFishFlock ........................................................................................................ 782
CreateFlock .............................................................................................................. 783
EnableFlock .............................................................................................................. 783
GetUsableMessage .................................................................................................... 783
OnBoidHit ................................................................................................................. 783
OnPickup ................................................................................................................. 784
SetAttractionPoint ...................................................................................................... 784
SetFlockParams ........................................................................................................ 784
SetFlockPercentEnabled ............................................................................................. 785
システム .................................................................................................................................. 786
メモリ処理 ....................................................................................................................... 786
ハードウェアのメモリ制限 .......................................................................................... 786
ターゲットとするプラットフォームの選択 .................................................................... 786
予算 ......................................................................................................................... 787
複数のモジュールとスレッドによる割り当て戦略 ........................................................... 787
計算データのキャッシュ ............................................................................................. 787
圧縮 ......................................................................................................................... 787
ディスクのサイズ ...................................................................................................... 787
合計サイズ ............................................................................................................... 787
アドレス空間 ............................................................................................................ 788
帯域幅 ..................................................................................................................... 788
Version 1.6
xii
Lumberyard 開発者ガイド
レイテンシー ............................................................................................................
配置 .........................................................................................................................
仮想メモリ ...............................................................................................................
ストリーミング .........................................................................................................
ストリーミングシステム .....................................................................................................
低レベルストリーミングシステム .................................................................................
ストリーミングおよび Levelcache Pak ファイル ............................................................
単一スレッド IO アクセスおよび無効なファイルアクセス ................................................
高レベルストリーミングエンジンの使用 .......................................................................
テキストのローカリゼーションと Unicode のサポート ............................................................
用語 .........................................................................................................................
どのエンコードを使用すべきか ....................................................................................
コード作成時の影響 ...................................................................................................
テキストアセット処理時の影響 ....................................................................................
CryCommon で提供されるユーティリティ .....................................................................
詳細情報 ..................................................................................................................
CryLog .............................................................................................................................
CryLog ログ作成機能 .................................................................................................
詳細レベルと色 .........................................................................................................
ログファイル ............................................................................................................
コンソール変数 .........................................................................................................
CryConsole .......................................................................................................................
色コーディング .........................................................................................................
すべてのコンソールコマンドおよび変数のダンプ ...........................................................
コンソール変数 .........................................................................................................
新しいコンソールコマンドの追加 .................................................................................
コンソール変数グループ .............................................................................................
コマンドラインのコンソールコマンドの遅延実行 ...........................................................
CVar Turorial ............................................................................................................
Lumberyard ブログ、フォーラム、およびフィードバック ................................................................
Version 1.6
xiii
788
788
789
789
789
789
796
797
797
799
799
800
802
803
803
803
803
803
804
804
805
805
805
806
806
806
807
808
809
812
Lumberyard 開発者ガイド
プログラマー向け Lumberyard
Lumberyard 開発者ガイドは、プログラマーや、Lumberyard コードを直接操作する方を対象としてい
ます。
このガイドには、次のセクションが含まれています。
• AI (p. 4)
ナビゲーション、およびユーザーとグループのビヘイビアを処理するさまざまな AI 機能について、
またビジュアル AI デバッガー、行動ツリーのビジュアルエディタ、ビジュアルフローグラフエディ
タなどの便利なツールについて説明します。
• アニメーション (p. 99)
線形 (ビデオ) アニメーションとインタラクティブアニメーションの両方を作成するためのツールが
用意されています。インタラクティブアニメーションは、AI およびアバター (プレイヤー) の動作を
表現します。これらのアニメーションでは、ゲームプレイでのプレイヤーの選択に応じてシーケン
スが変化します。
• アセットビルダー API (p. 117)
アセットビルダー API を使用して、カスタムアセットビルダーを開発します。これはアセットタイ
プをいくつでも処理でき、出力を生成して、今後の処理に利用できる結果をアセットプロセッサー
に返します。カスタムビルダーは、カスタムアセットタイプを使用する大型プロジェクトに特に便
利です。
• アセットインポーター (p. 125)
新しい FBX Importer を使用すると、単一の静的 FBX メッシュと単一のマテリアルを Lumberyard
に導入でき、他の入力形式を受け入れるために拡張可能な抽象化レイヤーを提供します。
• AZ モジュール (プレビュー) (p. 130)
AZ モジュールは、Lumberyard ゲームやツールに接続するために Amazon が新しく作成したコード
ライブラリです。これらの AZ モジュールは、特定の初期化関数を実行します。Lumberyard アプリ
ケーションの起動時に各 AZ モジュールがロードされ、対応する初期化関数を呼び出します。
• コールバックのリファレンス (p. 184)
エンティティシステム (p. 391) スクリプトと GameRules スクリプトのコールバックについて説
明します。
• Cloud Canvas (p. 189)
Cloud Canvas は、ゲームをアマゾン ウェブ サービスに接続する Lumberyard の技術です。Cloud
Canvas を使用すると、AWS を使用してクラウドホスト型機能を実行し、非同期のマルチプレイ
Version 1.6
1
Lumberyard 開発者ガイド
ヤーゲームを作成することができます。AWS を使用すると、ホストサーバーを取得、構成、または
操作して接続されたゲームプレイを実行する必要がなくなります。
• コンポーネントエンティティシステム (p. 322)
コンポーネントエンティティシステムは、新しく Amazon が作成したコンポーネント作成の方
法で、レガシーシステムより優れています (いずれはこの方法に移行します) エンティティシステ
ム (p. 391)。
• コントローラデバイスとゲームの入力 (p. 335)
キーボード、マウス、ジョイスティックなどの入力デバイスに関する Lumberyard のサポートにつ
いて説明し、制御やアクションマップをセットアップする方法を示します。
• CryCommon (p. 345)
Lumberyard 機能を使い勝手のよい拡張機能にリファクタリングするために使用できる
CryExtension などのゲームエンジンインターフェイス、カスタムリファレンスカウントの文字列ク
ラス CryString、およびユーザーのシリアル化コードを実際のストレージ形式から分離してフォー
マットを簡単に変更できるシリアル化ライブラリについて説明します。
• デモと動画キャプチャ (p. 384)
Lumberyard エディタ の使用方法、またはベンチマークビデオを記録し、音声を取り込む
Lumberyard スタンドアロンランチャーについて説明します。
• エンティティシステム (p. 391)
プレイヤーが相互通信できるレベル内に配置されるオブジェクトとして、エンティティを作成およ
び管理する方法について説明します。このセクションには、新しいエンティティクラス、エンティ
ティプール、エンティティのスクリプティングの作成などのトピックが含まれます。
• イベントバス（EBus） (p. 415)
イベントバスは、メッセージを送信するための Lumberyard 汎用システムです。EBus はシステム
間のハードの依存関係を最小限に抑え、イベント駆動型 (ポーリングを削減) で、同時実行処理をス
ムーズに扱い、所定のバスのハンドラの順序付けをサポートして予測可能性を提供します。
• ファイルへのアクセス (p. 426)
ゲームの内容ファイルを圧縮し、ゲームのパフォーマンスを低下させる可能性のある、無効なファ
イルの読み込みを追跡する方法を説明します。
• グラフィックスとレンダリング (p. 437)
Lumberyard のシェーディングコアは、ハイエンドの映画用レンダリングパイプラインと同じ物理パ
ラメーターを使用します。このセクションでは、レンダリングノード、True Type フォントのレン
ダリング、空のレンダリングに使用される星のデータについて扱います。また、アンチエイリアシ
ングを制御して、シャープなイメージから柔らかいぼかしイメージのグラフィックを生成する方法
についても説明します。
• Lua スクリプト (p. 447)
Lua は Lumberyard のスクリプト言語です。このセクションでは Lua スクリプトリファレンスにつ
いて扱い、Lua スクリプトの使用方法、Lua と C++ の統合、Lua リモートデバッガー、および Lua
XML Loader をトピックとして取り上げます。
• ネットワークシステム (p. 481)
Lumberyard のネットワーキング サブシステム GridMate について説明し、マルチプレイヤーのセッ
トアップ、セッションサービス、帯域幅使用の制御、GridMate レプリカフレームワークを使用する
ゲーム状態の同期をトピックとして扱います。
• 物理 (p. 521)
Lumberyard 物理システムについて、および物理エンジンと連携する方法について説明します。この
セクションでは、物理世界のオブジェクトを作成する方法、世界をジオメトリと物理エンティティ
で埋める方法、および記述された関数でエンティティを制御する方法を説明します。
Version 1.6
2
Lumberyard 開発者ガイド
• プロファイラー (p. 540)
プロファイラーは、ネットワークや CPU、VRAM の使用統計を採取し、保存、分析するための
Lumberyard のツールです。保存されたデータを使用してフレーム単位のネットワークの使用量を
分析し、ネットワーク帯域幅の利用上の問題を修正して、ゲームのパフォーマンスを最適化できま
す。
• システム (p. 786)
メモリ処理、ストリーミング、ローカリゼーション、ログ、およびコンソールツールをトピックと
して扱います。
Version 1.6
3
Lumberyard 開発者ガイド
AIシステムの概念
AI
このセクションはAIシステムを説明します。このセクションは重要な概念の全般的な概要を含み、シ
ステムコンポーネントを説明し、AIスクリプトマニュアルを提供します。
このセクションでは、次のトピックについて説明します。
• AIシステムの概念 (p. 4)
• AIバブルシステム (p. 20)
• AI タクティカルポイントシステム (p. 21)
• ナビゲーションに関する Q & A (p. 33)
• 経路追従 (p. 33)
• 動作システム (p. 35)
• 自動無効化 (p. 36)
• AI スクリプト (p. 37)
AIシステムの概念
AIシステムの重要な機能には以下のものが含まれています:
Navigation
• 設計者からの助けがほとんどないナビゲーション
• マルチレイヤーナビゲーション (飛行、水泳、無重力) またはシンプルな2Dナビゲーション
• 特殊ナビゲーションとインタラクションのためのスマートオブジェクト
個別AI
• 使いやすい静的および動的(移動可能な乗り物の後ろなど) 隠れ場所
• ダイナミックで戦略的なポイント (カバー地点、伏せ地点、パトロールルート上の地点など)
• ブール型変数の値に基づく行動を選択するための行動ツリー
Version 1.6
4
Lumberyard 開発者ガイド
AI システム概要
• カスタマイズ可能な知覚（視覚、音、記憶、第六感など)
グループおよびグローバルAI
• グループ戦略を定義するグループ行動ツリー
• AIキャラクターを比較的整った形で移動するフォーメーション
• 派閥（仲間、中立、敵など)
• 再利用されたサブフローグラフのマクロノードを使ったゲームロジックの視覚フローグラフ
MMO装備済
• ストリーミング中の大きなマップのためのサポート
ユーザーに分かりやすい
• シグナル、行動変化、目標変更、ユーザコメントをログするためのビジュアルAIデバッガー
• 行動ツリーのビジュアルエディター
• ビジュアルフローグラフエディターおよびデバッガー（ビジュアルフロー伝播とブレークポイン
ト）
このセクションでは、次のトピックについて説明します。
• AI システム概要 (p. 5)
• パス探索コスト (p. 8)
• 感覚モデル (p. 11)
• 飛行 (p. 16)
• AI の C++ クラス階層 (p. 17)
• AI システムの概念の例 (p. 18)
AI システム概要
このセクションはAIシステムに関する基本的なコンセプトを概説します。
ナビゲーション
• デフォルトナビゲーションシステム
• トライアンギュレーション
• 2D 地形ベースドナビゲーション
• 円柱状のオブジェクト（木など）や禁止されたエリアを使用します
• ナビゲーションモディファイア
• ヒューマンウェイポイント– 手動で設置しなければいけませんが、コネクションは自動的につ
くられます。
• フライト– 飛行オブジェクトの操作可能なボリュームに関する情報
• ボリューム– 海などに使われるジェネラルボリュームナビゲーション
• マルチレイヤーナビゲーションシステム
• スマートオブジェクトシステム：AIエージェントに特別な動きができるように許可します
• AIテリトリー＆ウェーブ
• AIエージェントの (フローグラフロジックを通した)管理番号
Version 1.6
5
Lumberyard 開発者ガイド
AI システム概要
• シングルFGノードを使用しているテリトリーにアサインされたすべてのAIエージェントをアク
ティベート、ディスアクティベート、スパウンします
• AIウェーブはAIテリトリーに添付することができ、独立したAIアクティベーションを許可しま
す。
• AI ウェーブは、アサインされたAIエージェントの、ローディングやアンローディングなどのエン
ティティプールイシューを自動的に処理します
一般的に、検索はひとつのAIフレームにつき0.5 msを使用し、タイムスライスされます（コンソール
変数を使用して設定ai_PathfinderUpdateTime）。経路探索テクニックのオプションには高優先
度、ストレート、パーシャルがあります。ヒューマンウェイポイントの更新は重いですがタイムスラ
イスです。ナビゲーショングラフは能率的ですがメモリが必要です。ナビゲーションデータはオフラ
インだとEditorで生成されます。マルチレイヤーナビゲーションを使用すると、デザイナーがマップを
編集したときにナビゲーションメッシュが再生成されます。
意思決定
• ビヘイビアセレクションシステム – ビヘイビアツリーを使用してAIビヘイビアを選択します
• カバーシステム – AIエージェントに静的・動的なカバーを提供します
• スマートオブジェクトシステム– AIエージェントに環境との接触を許可します
• インタレストシステム– AIエージェントが警戒態勢にないときに知能的アクションをパフォームす
ることを許可します
タクティカル
• タクティカルポイントシステム(TPS) – AIエージェントに環境に対する知能的な質問をすることを許
可します (どこに隠れるべきか、どこを攻撃するか、など)
• ファクションシステム– AIエージェントどうしの敵対レベルを決定します
• グループコンディションシステム– コーディネーションセレクションツリーを使ってグループのビ
ヘイビアを選択します
• フォーメーションシステム – AIエージェントにフォーメーションにそって動くことを許可します
• クラスターディテクター– スペース上のポイントのクラスターを検出して具体的なプロパ
ティを満たす異なるグループに細分します（modified Kの使用はアルゴリズムを意味します);
AISquadManager を使用して異なるAIエージェントをダイナミック分隊にグループ分けします
ワールド・インターフェーシング
• シグナル – イベントを発生させ、ビヘイビアを変えます
• 知覚システム
• 知覚ハンドラー (遺産、通常1ゲームごと)
• ターゲットトラックシステム– 設定可能なADSRエンベロップを使用して次にくる刺激を表現しま
す
• コミュニケーションシステム– AI agentsに音声/アニメーションイベントをプレーすることを許可し
ます
開発環境
デザイン・開発環境は以下の要素を含みます：
• ゲームオブジェクトモデル– エンティティ、ムーブメントコントローラー、エクステンション
Version 1.6
6
Lumberyard 開発者ガイド
AI システム概要
• アクター& ヴィークルシステム– ヘルス、カメラ、IK、武器、アニメーションetc.
• フローグラフ– ゲームロジックのビジュアル定義
• AIデバッグレンダラ– HUD, 幾何プリミティブ、テキストラベル、グラフ etc.
• JSON テキストエディタ
• AI エンティティ – プロパティ、フローグラフ、スクリプト
• エンティティ原型– 個別AIエージェントのプロパティのテンプレート
• AI シェープ – AI テリトリー、AI経路、禁止エリア
• ナビゲーション – トライアンギュレーションではなくナビゲーションモディファイアを使用しま
す
• カバー表面– CoverSurfaceがカバーの場所を示すために固定されます
• ビジュアルAIデバッガー– AIのシグナル、アクティブビヘイビア、ゴール、刺激などを記録しま
す
• Luaでのスクリプティング
• エンティティ定義（エンティティフローグラフノード含む）
• AI ビヘイビア定義
• グループビヘイビア定義
• ライブラリまたは共有Luaコード（ゲームルール、基本エンティティ）
• ブラックボードを使用してグローバルに、もしくはグルーム内で情報を共有します
• AI ファンクショナリティの例はLuaで入手可能です:
• AI.Signal
• AI.FindObjectOfType
• AI.GetAttentionTargetType (Visual, Memory, Sound, None)
• AI.GetAttentionTargetAIType (Actor, Grenade, Car, etc.)
• AI.GetRefPointPosition
• AI.DistanceToGenericShape
• AI.SetBehaviorVariable (ビヘイビアを変更したいとき)
• AI.CanMelee
• AI.RecComment (Visual AI デバッガーにコメントする)
• XM1Lでのスクリプティング
• ビヘイビア/コーディネーションツリー
• AI コミュニケーションズ
• アイテム(例：武器)
• エンティティシステム
• 空間クエリ – GetPhysicalEntitiesInBox()
• AIエージェントとヴィークルはエンティティシステム内のエンティティです
• エンティティをスパウンするには、そのエンティティのエンティティクラスが必要です– [.ent ]
ファイル(Game\Entities内）を使用するか、ゲームコードのRegisterFactory() へのC++ コール
を通して定義できます
• エンティティプールはひとつひとつの特定のエンティティクラスごとのアクティブAIエージェン
トの数を制限するのに使用します。
• AI デバッガー とAIデバッガードロー
• AI デバッガー の使用アクティブビヘイビアを含む複数のフィーチャーを記録 受信シグナル、ア
テンションターゲット、コメントなど
• ai_DebugDraw
• 1 – AIエージェント上の基本情報（
ai_DrawAgentStats
によって選択)
Version
1.6
7
• 74 – すべてのナビゲーショングラフ (低速度の可能性あり)
• 79 – プレイヤー周辺の一部のナビゲーショングラフ
Lumberyard 開発者ガイド
パス探索コスト
• ai_statsTarget <AI name> – 特定のAIの詳細情報
• ai_DebugTargetTracksAgent <AI name> – 特定のAIの知覚情報
• ai_Recorder_Auto – AI デバッガーのEditorゲームモード内でのAIアクティビティを記録します
• ai_DebugTacticalPoints – TPSクリエのデバッグ
• ai_DrawPath <AI name> – 特定のAIの経路を描きます("all"ですべてのAI エージェントを選択す
ることも可能)
• ai_DrawPathFollower –実際に使われた経路を描きます
• ai_DrawSmartObjects – スマートオブジェクトとそのクラスと特徴を表示します
• ai_DebugDrawEnabledActors – 現在使用可能なAIエージェントをリストします。
実行コンテキスト
• AIアップデートは各フレームコールしますが、10Hzまでしか完全にアップデートされません
• 独立したタイムスライス（経路探索、タクティカルポイント、動的ウェイポイント更新、スマート
オブジェクト、インタレスト、死体除去）を使うAIサブシステムもあります
• ゲームコード（タクティカルポイントシステム（TPS）クリエなど）から同期的に発生するサービ
スもあります
パス探索コスト
エージェントがリアリティーのある動作をするには、現在の状態に応じたパスを見つけることが必要
です。これらのパスが最も直接的なルートになる場合もありますが、それ以外の場合は、道路、カ
バーその他の環境内の舞台装置を最大限に利用するため、パスは長くなります。また、これをサポー
トするために現在のシステムを拡張する必要があります。パス探索システムは、A*を使用して最小コ
ストのパスを見つけます。
パスのコストは、パスを構成するリンクのコストを合計することで算出されます。現在、ナビゲー
ショングラフのリンクを通過するコストは、単純にそのリンクの物理的な長さ（3D）です。ただ
し、A* の実装により、リクエスタは、シンプルなコードの変更によって現在のシステムを拡張し、こ
れらの距離ベースのコストを簡単に変更することができます。たとえば、2 つの道路ノードの間を移
動するコストを 0.1 の係数で増やすことで、道路間を移動するエージェントに、道路を使ったパスを
見つける動機付けを与えることができます。
2 つのグラフノードを接続するパスリンク残すとは、次の 2 つのプロパティのセットによって決定す
る必要があります。
• パスの長さを含むリンクプロパティ。
• リンクプロパティに関連するパス探索エージェントのプロパティ。たとえばステルスエージェント
は、道路を進むリンクよりも森の中を通過するリンクが、ユニットの長さあたりのコストが低いと
評価する場合があります。ただし一方で、車両を積んだトラックの集団をエージェントが率いてい
る場合は、違う結論に到達する可能性もあります。
一般的にリンクのコストは、「リンクの長さ x ユニットの長さあたりの相対的なコスト」という 2 つ
の係数によって生成されます。決定する必要があるのは後者です。
問題: 実行時のコスト計算
さまざまな種類のエージェントに対して同じナビゲーショングラフを使用する必要があります。つま
り、固有のリンクプロパティとエージェントプロパティを組み合わせ、リンクのコストを実行時に計
算する必要があります。
Version 1.6
8
Lumberyard 開発者ガイド
パス探索コスト
リンクプロパティ
これらのプロパティを各リンクに関連付けます。
Link.Length
リンクの長さ（メートル単位）。
Link.Resistance
リンクに設定される通過時の抵抗。たとえば、道路は 0 に近く、オフロードはそれよりも大きく
なり、泳がないと通過できない深い水の場合は 1 に近くなります。
Link.Exposure
リンクの露出度。大量の植物に覆われた森は 0 に近く、植物の背が低い場合はそれよりも大きく
なり、道路やオープンスペースの場合は 1 に近くになります。
Link.DeepWaterFraction
深い水（例: > 1.5m）を含むリンクの割合。
Link.DestinationDanger
ターゲットノードに関連付けられる、追加の「危険値」。たとえば、死体は 1 となります。この
値はターゲットノードに格納し、メモリを節約できます。
エージェントプロパティ
これらのプロパティを各エージェントに関連付けます（通常はエージェント作成時に設定します）。
Agent.CanTraverseTriangular
エージェントが三角形ノードを通過できるかどうかを決定する true/false インジケータ。
Agent.CanTraverseWaypoint
エージェントがウェイポイントノードを通過できるかどうかを決定する true/false インジケータ。
リンクの種類に対して適切な場合は、これらのプロパティをエージェントに関連付けます。
Agent.CanSwim
エージェントが泳げるかどうかを決定する true/false インジケータ。
パス探索リクエストのプロパティ
これらのプロパティを、エージェントのパス探索リクエストのそれぞれに関連付けます。
Agent.TriangularResistanceFactor
リンクの種類が Triangular で、抵抗が 1 の場合に追加されるリンクのコスト係数。
Agent.WaypointResistanceFactor
リンクの種類が Waypoint で、抵抗が 1 の場合に追加されるリンクのコスト係数。
Agent.RoadResistanceFactor
リンクの種類が Road で、抵抗が 1 の場合に追加されるリンクのコスト係数。
リンクの種類に対して適切な場合は、これらのプロパティをエージェントのパス探索リクエストに関
連付けます（注意: リンクの開始/終了ノードの種類が異なる場合、平均を計算することで結果が取得
されます）。
Agent.SwimResistanceFactor
リンクの深い水の割合が 1 の場合に追加されるリンクのコスト係数。
Agent.ExposureFactor
リンクの露出が 1 の場合に追加されるリンクのコスト係数。
Agent.DangerCost
リンクの危険値が 1 の場合に追加されるリンクのコスト係数。
Version 1.6
9
Lumberyard 開発者ガイド
パス探索コスト
Link.DestinationDanger を除くすべてのリンクプロパティは、三角形分割の生成時に計算され
ます。Link.DestinationDanger は最初は 0 に設定され、ゲームの進行に合わせて計算されま
す。たとえば、あるキャラクターが死亡した場合は常に、死亡ノードに移動する各リンクの
DestinationdangerCost が 1 増加します。これによって、Agent.DangerCost = 100 のエージェントに
は、この死亡ノードを回避するために、最大 100m まで長いパスを選択する動機が与えられます（そ
の他のパスコストが同じだと仮定した場合）。読み込み/保存をサポートするため、これらのリンクの
修正はシリアル化する必要があります。
また、実行時に追加コストを計算することができます。たとえば、エージェントがプレイヤーを回避
する必要がある場合に、露出に関連付けられた追加コストを追加できます。これは、コストを計算す
る A* のコールバック内でレイキャストを使用することで実現できます。
パス探索コストを決定する場合、次の 2 つの問題を解決する必要があります。
• リンクプロパティの計算方法
• 各グラフリンクの通過コストを数値化するための、リンクプロパティとエージェントプロパティの
組み合わせ方法
リンクプロパティは、リンクの長さに対する環境の平均を示していることに注意してください。リー
ジョンの三角形分割が適切に生成されていない場合、このことがパス探索の結果に悪影響を及ぼす可
能性があります。影響が非常に大きい場合は、三角形分割のポイントの追加が必要になることがあり
ます。
その他の考慮事項として、夜と日中、霧と晴天など可視性条件が異なる場合で、パス探索を区別する
かどうかという問題があります。区別する場合は、物理カバーとシャドウカバーから導き出される
それぞれの条件に、リンクの露出を分割することが必要になります。含まれるリンクの数を考慮する
と、このような情報が各リンクにあまりにも多く追加されることには注意が必要です。よりシンプル
なソリューションとしては、こうした条件の場合にステルスエージェントがステルスパスをリクエス
トする頻度を引き下げる、エージェントの ExposureFactor を低く設定するなどが考えられます。
ソリューション
リンクプロパティの計算
リンクの抵抗は、リンクに実際に含まれるノードの種類にのみ依存するため、検索テーブルに格納で
きます。それぞれのノードの種類の抵抗値の例を以下に示します。
ノードの種類
抵抗
Triangular-no-water
0.5
Triangular-water
1.0
Waypoint
0.6
Road
0
Flight/Volume
0
Note
• 水中の地形では Flight/Volume にそれぞれ別の抵抗を追加することを検討してください。
• 種類が異なるノード間のリンクでは、抵抗値を平均することができます。
リンクに格納される Link.Exposure 値は、リンクの長さからサンプリングされた環境内の舞台装
置によって決定されます。このサンプリングは、三角形、ウェイポイント、およびボリューム移
Version 1.6
10
Lumberyard 開発者ガイド
感覚モデル
動のリージョンでは、ポイントからリンクに沿って放射される光線によって実行できます（これ
には、IPhysicalWorld::RayWorldIntersection を使用して、HIT_COVER | HIT_SOFT_COVER と
COVER_OBJECT_TYPES を確認します）。実際には、最適化されたパスがリンクを直接たどること
はないため、取得する値の正確性を追求しすぎる必要はありません。
リンクプロパティとエージェントプロパティの組み合わせ
リンクコストには、リンクプロパティとエージェントプロパティの両方の条件が反映されている必要
があります。たとえば、あるリンクに深い水が含まれるというマークがあり、エージェントが泳げな
い場合、このリンクは通過できないものとして扱う必要があります。
さらに、移動の抵抗および露出に関連する追加コストを示す係数が計算されることで、合計のリンク
コストは次のように設定されます。
Cost = Link.DestinationDanger * Agent.DangerCost + (1 + Factor) *
Link.Length
where
Factor = Agent.[link-type]ResistanceFactor * Link. [link-type]Resistance +
Agent.ExposureFactor * Link.Exposure
次のようなシナリオを考えてみます: 露出/ターゲットのコストがなく、道路リンクが
Link.Resistance {{0}} で、オフロードのリンクが Link.Resistance {{0.5}} の場合、オフロー
ド移動の 10 倍強い動機を道路移動に与えるには（エージェントが自動車の場合など）、
エージェントの Agent.TriangularResistanceFactor の設定は {{(10-1)/0.5}}（つまり 18） と
し、Agent.RoadResistanceFactor は 0 に設定します。
エージェントが人間のキャラクターで、道路かどうかにかかわらず常に同じ速度で移動する場
合、Agent.TriangularResistanceFactor と Agent.RoadResistanceFactor の両方を 0 に設定できます。
エージェントが深い水を通過し、水の影響を受けない場合（ホバークラフトな
ど）、Agent.SwimResistanceFactor を 0 に設定できます。人間のエージェントの場合、この係数には
最大 3.0 を設定できます。こうすることで、川を泳いで渡ることを迂回路を使って回避する、強い動
機が与えられます。
感覚モデル
概要
このトピックでは、Lumberyard AI システムに実装されているセンサーのモデリングと基本的な操作
について説明します。これらには、視覚センサー、聴覚センサー、および汎用シグナリングメカニズ
ムが含まれます。
感覚情報は、個々の敵を完全に更新するときに処理されます (感覚イベントが受信された実際の時間
とは同期していません)。これらのセンサーは、敵が唯一持っている外界とのインターフェイスで、敵
が状況を評価して潜在的なターゲットを選択するときに使用するデータを提供します。いずれのセン
サーも詳細な設定が可能で、個々の敵についてランタイムでオン/オフを切り替えることができます。
視覚
視覚センサーモデルは、AI システムの心臓部です。視覚は、敵の最も重要な感覚です。このモデル
は、譲歩と最適化を織り交ぜて実行コストを抑えながら、視覚をできるだけリアルにシミュレートす
ることを目的としています。
システムは、個々の敵を完全に更新するときに、敵の視点から見えるすべての潜在的なターゲットを
詳細に検討し、それらのターゲットについてそれぞれ可視性判定ルーチンを実行します。このフィル
Version 1.6
11
Lumberyard 開発者ガイド
感覚モデル
タリング手順を生き残ったすべてのターゲットが可視リストに追加され、次回完全に更新するときま
で保持されます。ターゲットが "可視" として存続するには、完全に更新されるたびに可視性テストに
合格する必要があります。更新時に可視から不可視に変わったターゲットは、記憶ターゲットリスト
に移動されます。以前に見えていたターゲットが再度見えるようになると、記憶ターゲットリストか
ら元の可視リストに戻されます。敵がターゲットを "忘れる" ことをシミュレートするために、記憶
ターゲットには、有効期限が設けられています。この間隔は、ターゲットの脅威インデックスやター
ゲットが見えていた時間の長さなど、いくつかの要因によって決まります。脅威インデックスが高い
別のターゲットがいる場合でも、見えているターゲットに高い優先順位が付けられ、現在の注意ター
ゲットとなります。このアプローチは、記憶している (または聞こえる) ものより目に見えるものに対
して迅速に行動する人間の自然な傾向をシミュレートしています。
可視性の判定
可視性判定ルーチンは、ターゲットが敵に見えていると見なされるかどうかを判定します。このルー
チンは、完全な更新のときに、敵の潜在的なターゲットに対してそれぞれ実行されます。
ターゲットの識別
可視性の判定には、大量の CPU リソースが消費されることがあります。これを緩和するため、潜在
的なターゲットについてのみ可視性を評価します。AI オブジェクトを可視性の判定に含める必要が
あるオブジェクトとして登録するメカニズムが用意されています (ユーザー定義のオブジェクトを含
む)。これには、Lumberyard での手榴弾や懐中電灯などのオブジェクトが含まれます。属性と呼ばれ
る特殊なオブジェクトもあります。これらについては、このトピックの後半で詳しく説明します。
潜在的なターゲットと見なされるには、AI オブジェクトが次の条件を満たしている必要があります。
• 現在アクティブである。
• 敵と異なる種族である (敵は自分のチームのメンバーを追跡する必要はありません)。
加えて、プレーヤーが敵と同じ種族である場合でも、プレーヤーに対して自動的に可視性判定テスト
が実行されます。このルールによって、プレーヤーをオブジェクトタイプとして正確に指定すること
ができ、可視性をチェックするときに常にプレーヤーを考慮に入れることができます。
ゲーム開発者は、特定の AI オブジェクトタイプを指定して可視性を判定することもできます。こ
れらのユーザー定義のタイプは、可視性チェックに含めるオブジェクトタイプを識別する AI シス
テムによって管理されるリストに追加されます。オブジェクトは、このリストまたはスクリプトか
らでも、自由に追加または削除することができます。オブジェクトをリストに含めるには、目的の
オブジェクトタイプに適用する評価乗数を指定します。たとえば、/scripts ディレクトリにある
aiconfig.lua ファイルを参照します。評価乗数の詳細については、脅威の評価に関するトピックを
参照してください。
可視性のチェック
一連のテストを使用して、特定された潜在的なターゲットの可視性がそれぞれ評価されます。プレー
ヤーが 1 つの種族と対峙している場合、可視性の判定は、敵の AI オブジェクト間では行われず、プ
レーヤーに対してのみ行われます。可視性を判定する際の重要な測定単位には、次のようなものがあ
ります。
視界テスト
このチェックは、敵の視界に入っていないすべての AI オブジェクトを短時間かつ低コストで除外でき
るため、最初に行われます。このチェックは、敵からターゲットまでの距離と敵の視界値を比較する
ことで行われます。
敵の視界
敵がどこまで見ることができるかを決定する浮動小数点値です (メートル単位)。値は、敵を中心
とした球体の半径を表しています。
Version 1.6
12
Lumberyard 開発者ガイド
感覚モデル
視野テスト
敵の視界を表す球体の内側にあるオブジェクトについては、敵の視野 (FOV) の内側にあるかどうかも
確認されます。
敵の視野
敵の視円錐の角度を決定する浮動小数点値です (角度単位)。円錐は、頂点が敵の頭にあり、敵の
顔が向いている方向に外側に延びます。
FOV は、敵が現在の前方方向から左右のどこまでを見ることができるか (周辺視野の範囲) を決定する
角度です。たとえば、FOV を 180 度にすると、敵は自分の顔が現在向いている方向から左右 90 度の
範囲内にあるものすべてを見ることができます。FOV を 90 度にすると、敵は自分の現在の前方方向
から左右 45 度の範囲内にあるものを見ることができます。FOV チェックは、敵の方向ベクトルと、
潜在的なターゲットから敵までの位置の違いとして作成されたベクトルとの簡単なドット積を使用し
て行われます。計算されたスカラーが FOV 値と比較されます。FOV では、円錐が使用されているた
め、2D 表現に限定されません。
物理光線テスト
最初の 2 つのチェックに合格したオブジェクトは、非常に高い確率で見えている可能性があります。
次のチェックでは、ゲーム世界で実際の光線を追跡しますが、これはコストの高いプロセスです。す
べてのフレームにわたって AI システムの低層で分散して更新が行われるため、フレームあたりに大
量の光線を放射しなければならないことは滅多にありません。ただし、各種族に属するオブジェクト
の数が多いシーンや大規模な戦闘シーン (種族あたりの参加者が 20 人を超えるシーン) などは例外で
す。
敵とターゲットの間に物理的な障害物があるかどうかを判定するには、可視性物理光線を使用しま
す。この光線は、敵キャラクターの頭蓋骨 (敵にアニメーションキャラクターが設定されていない場
合はエンティティの位置 (多くの場合、地上の点)) から、ターゲットの頭蓋骨 (頭蓋骨がない場合はエ
ンティティの位置) に向けて放射されます。この可視性光線がパスを通過するときに何かに当たると、
ターゲットは見えないものと見なされます。光線が障害物に当たることなくターゲットに到達した場
合、そのターゲットはこのテストに合格です。この更新の可視リストにターゲットを追加することが
できます。
すべての障害物が同じであるわけではありません。物理光線テストでは、ハードカバー障害物とソフ
トカバー障害物が区別されます。カバーの種類が敵の行動にどのような影響を与えるかについては、
このトピックの後半のソフトカバーに関するセクションを参照してください。
認識テスト
このテストは、プレーヤーの AI オブジェクト (およびゲーム開発者によって定義されたその他の AI オ
ブジェクト) にのみ実行されます。プレーヤーが敵のすべての可視性テストに合格したら、この最終
テストによって、敵からプレーヤーオブジェクトが見えるかどうかが判定されます。個々の敵は、プ
レーヤーターゲットに対して認識度係数を計算します。この係数は、最終的に、敵からターゲットが
見えている確率を表しています。
認識度係数 (SOM 値)
ターゲットを実際に見るまでに敵がどれほど近づいているかを定義する浮動小数点値です (0 ～
10)。
認識度係数は、さまざまな要因 (敵からターゲットまでの距離、ターゲットの高さ、ターゲットが移
動しているかどうかなど) に基づいて計算されます。この値は、敵が確実な視覚刺激を受容する (つま
り、ターゲットを見る) 前に、最大値 (現時点は 10) に到達している必要があります。
認識度値の導出方法の詳細については、このトピックの後半の認識度の計算に関するセクションを参
照してください。
Version 1.6
13
Lumberyard 開発者ガイド
感覚モデル
ソフトカバーが可視性および動作に与える影響
物理光線テストでは、可視性を判定するときに、障害物の表面の種類も評価されます。AI システム
は、ソフトカバーとハードカバーの 2 種類の表面を区別することができます。物理的な感覚で大きく
異なる点として、ゲームプレーヤーはソフトカバーを通過することはできますが、ハードカバーを通
過することはできません。プレーヤーはソフトカバーのオブジェクトの背後に隠れることができます
が、ターゲットがソフトカバーのオブジェクトの背後にいる (ハードカバーのオブジェクトの背後ま
たは開けた場所ではなく) 場合、可視性の判定はわずかに "歪曲" されます。AI システムは、ソフトカ
バーの背後にいるターゲットの可視性を判定するときに、敵が既にターゲットを "生きている" ター
ゲットとして (記憶ではなく、ターゲットの音などにより) 識別しているかどうかを考慮に入れます。
敵が生きているターゲットを識別していない場合、ソフトカバーはハードカバーと同じように見なさ
れ、通常の可視性の判定が行われます。このことは、敵がアイドル状態にある場合や、敵が音の発生
源を探しており、まだ発生源を見つけていない場合などに起こります。
敵が既にターゲットを識別している場合は、動作がわずかに異なります。物理光線テスト時に敵と
ターゲットの間にソフトカバーのみが検出された場合は、ターゲットが短時間 (3 ～ 5 秒間) だけ見え
る状態になります。この間、ターゲットがソフトカバーの背後に留まり続けると、敵は最終的にター
ゲットを見失い、最後の既知の位置に記憶ターゲットを置きます。逆に、この間にターゲットがソフ
トカバーから離れると、タイマーがリセットされ、通常の可視性ルールが有効になります。
この動作は、ターゲットが茂みの中に走り込むのを兵士が認識した場合などをシミュレートしていま
す。その場合、茂みの中にいてもターゲットのシルエットを見分けることができるので、兵士はその
ことをすぐには忘れません。しかし、そのようにターゲットを追跡するのは時間と共に難しくなり、
しばらくすると兵士はターゲットを見失います。木材などの貫通可能なカバーで作られたカバーにつ
いても同じルールが適用されますが、その理由は少し異なります。ターゲットが薄い木製の壁の背後
に走り込んだ場合、銃弾が壁を貫通することを兵士はわかっており、しばらくの間はターゲットの位
置もわかるため、敵は壁を挟んでターゲットを撃ち続けます。これは、Lumberyard ゲームの非常に激
しい場面で役に立つことがあります。
このプロセスを合理的なクローズドシステムで機能させるには、ゲーム内のすべての表面を適切に物
理化する (木材、草、ガラスをソフトカバーにし、岩石、コンクリート、金属をハードカバーにする)
必要があります。この作業は Lumberyard で一貫して行われます。
認識度の計算
AI エージェント間の可視性とは異なり、Lumberyard では、敵の AI エージェントに対するプレーヤー
オブジェクトの可視性をオン/オフで切り替えることはできません。このようにさらに複雑にすること
で、ゲームのプレイスタイルにバリエーション (行動したり隠れたりなど) を持たせることができるよ
うになっています。認識度により、プレーヤーは、いくらか失敗をしても、そこから挽回することが
できます (これは、プレーヤーの AI オブジェクトが特別に AI システム階層の一番下の階層でも定義さ
れている理由の 1 つです)。(光線がターゲットの位置まで届くと、すぐにターゲットが見えるように
なる) "切り替え" 型の視覚を使用する、他の AI オブジェクトと一緒に使用することはできません。一
部の AI オブジェクトが認識度係数の使用をトリガーするように宣言することもできます。
特定のターゲットを実際に見るまでに敵がどれくらい近づいているかを示す認識度係数が敵に提供さ
れます。認識度係数の初期値は 0 ですが、この値は定義された一連のルールに基づいて増減します。
プレーヤーターゲットがそれまでのすべての可視性テストに合格すると、敵は認識度係数を適用し始
めます。最大値に到達すると、プレーヤーターゲットは敵に見えるようになります。これから次のこ
とが推察されます。
• 個々の敵は、処理しているそれぞれのプレーヤーターゲットに対して認識度係数を持っています。
• 個々の敵は、認識度係数が最大値に到達した後にのみ、プレーヤーターゲットが見えるようになっ
たという通知を受け取ります。
• プレーヤーターゲットが同じであっても、2 人の異なる敵の認識度係数は関連付けられません。
• ゲームレベルの認識度係数 (すべての敵がプレーヤーターゲットをどのように認識しているかを示す
値) はありません。ただし、この情報は、統計から導き出せることがあります。
Version 1.6
14
Lumberyard 開発者ガイド
感覚モデル
敵は、プレーヤーターゲットが可視性判定ルーチンに合格したという通知を受け取ると、認識度係数
を計算し始めます。その際、次の要因が評価されます。これらはいずれも係数の増加速度に影響を与
えます。認識度係数を適用する前に、プレーヤーターゲットが依然として可視性判定ルーチンのその
他のすべてのテストに合格している必要があることに注意してください。
距離
敵からプレーヤーターゲットまでの距離は、認識度に最も大きな影響を与えます。プレーヤー
ターゲットが敵に近いほど、係数は速く増加します。一方、距離が大きくなると、係数の増加は
緩やかになります。増加関数は、基本的な二次関数です。敵までの距離が非常に近いと、ほぼ一
瞬で最大認識度に到達し、ターゲットが瞬時に見えるようになります。それとは対照的に、認識
度値の増加が緩やかなときは、プレーヤーターゲットは、敵の視界の境界に沿ってより自由に動
くことができます。
地上からの高さ
この要因では、プレーヤーターゲットの地上からの距離が考慮に入れられます。この動作の理由
は、うつぶせのターゲットの方が直立しているターゲットよりもはるかに見つけるのが難しいこ
とにあります。AI システムは、AI オブジェクトの "目線の高さ" プロパティに基づいて地上から
ターゲットの距離を測定します。このプロパティは、AI オブジェクトを初期化したときに設定さ
れますが、ゲームの実行時にいつでも変更することができます。ゲームで敵とプレーヤーがアニ
メーションキャラクターによって表現されている場合、キャラクターの頭蓋骨の実際の高さを使
用して視線の高さが計算されます。この要因は、認識度係数の増加速度に影響を与えます。具体
的には、プレーヤーターゲットの地上からの高さが 1 m 未満である場合、距離による認識度係数
の増加速度が 50% 低下します。
ターゲットのモーション
認識度係数は、プレーヤーターゲットが動いているかどうかによっても影響されます。動くと目
立ちますが、じっとしていると見つかりにくくなります。この要因は、認識度係数の増加速度に
影響を与えます。具体的には、プレーヤーターゲットがじっと立っている場合、その他の要因に
よる認識度係数の増加速度がさらに 50% 低下します。
人為修飾子
付加的な値で認識度係数が増加する速度を定義することができます。これらの値は、ゲーム世界
のすべての敵に影響を与えることも、特定のターゲットにのみ影響を与えることもできます。す
べての敵に影響を与える修飾子の例として、コンソール変数 ai_SOM_SPEED があります。デフォ
ルト値はゲームの難易度によって変化しますが、このコンソール変数は、すべての敵に適用さ
れ、他のすべての計算よりも優先して適用される定数の乗数を提供します。それとは対照的に、
特定のプレーヤーターゲットにのみ使用されるオブジェクトタイプを指定し、それにカスタマイ
ズした乗数を設定することもできます。ただし、この設定は、AI システムの一番下の階層に制限
されるため、微調整に使用することはできません。
ターゲットが敵に見えていると見なされている間、認識度の効果は累積されます。上記の要因に基づ
いて浮動小数点値が計算され、敵が完全に更新されるたびに、その値が (更新された可視性判定と一緒
に) 認識度係数に追加されます。このため、たとえば、敵の視界の内側にいるプレーヤーターゲットで
も、しゃがんでいたり、じっとしていたりすれば、非常に長い間、敵に認識されずに済むことができ
る場合があります。
同時に、完全に更新されるたびに値が一貫して増加しない場合は、ゼロ以外の認識度係数が時間と共
にゼロに戻ることがあります。たとえば、プレーヤーターゲットが数秒見えて、係数が 5 まで増加し
たとします。しかし、その後、見えなくなりました。このシナリオの場合、係数はゼロまでゆっくり
減少します。このシナリオは、戦術的に前進し、その後、続行する前に一度立ち止まるプレーヤーに
対して見返りを与えるために実装されています。これにより、プレーヤーは、係数がゼロまで減少す
るのを待ってから忍び寄ることができます。
プレーヤーに対するすべての敵の認識度係数の統計概要を使用して、HUD ステルス O メーターが表
示されます。ステルス O メーターとは、HUD のレーダーサークルの左右に表示される小さなゲージ
のことです。このゲージには、現在プレーヤーを認識しているすべての敵のうち、最も高いプレー
ヤー認識度係数が示されます。言い換えるなら、これはプレーヤーを見つける可能性が最も高い敵の
認識度係数を示していると言えます。ステルス O メーターが最大になったからといって、すべての
敵からプレーヤーが見えているわけではありません。ただし、少なくとも 1 人の敵からは見えていま
Version 1.6
15
Lumberyard 開発者ガイド
飛行
す。ステルス O メーターが空になった場合は、現在プレーヤーを見ることができる敵が存在しないこ
とを示しています。
属性オブジェクト
属性オブジェクトは、完全な AI オブジェクトではありません。むしろ、既存の AI オブジェクトにた
どり着くための特別な助けと言えます。属性は、AI オブジェクトの特殊なクラスで、特別に AI シス
テムの一番下の階層で定義されています。すべての属性オブジェクトには、プリンシパルオブジェク
トを関連付ける必要があります。プリンシパルオブジェクトは任意のタイプのオブジェクト (パペッ
ト、車両、プレーヤーなど) にすることができます。ただし、属性にすることはできません。
属性は、可視性の判定に影響を与えることがあります。属性オブジェクトが見えると敵が判断する
と、システムによって属性がプリンシパルオブジェクトに切り替えられ、敵の可視リストに追加され
ます。このように、属性を見ている敵は、属性にアタッチされているプリンシパルオブジェクトを見
ているものと考えます。
基本的に、属性は、特定のイベントと単一のターゲットをつなぐための体系化された方法です。た
とえば、プレーヤーが懐中電灯を点灯し、その光が近くの壁に当たるとします。壁に当たる光によっ
て、プリンシパルオブジェクト (プレーヤー) に関連付けられた属性オブジェクトが作成されます。こ
のシナリオでは、プレーヤーは隠れていますが、敵は属性オブジェクト (壁に当てられた光) を見るこ
とで、実際にはプレーヤーを "見る" ことができます。その理由は、敵には光の発生源を推測するのに
十分な知性が備わっており、プレーヤーの位置を知ることができることにあります。
この機能は、岩石、手榴弾、ロケットなどに関しても使用されています。その他の機能をゲームに追
加して機能を拡張することができます。たとえば、ターゲットが時間と共に消える足跡を地面に残す
ことがあります。足跡によって属性オブジェクトが発生します。敵は、それを見ることで、その足跡
を残したターゲットの位置を認識することができます。別の応用例として、血痕を挙げることができ
るかもしれません。
属性オブジェクトが可視性の判定に含められるようにするには、属性オブジェクトに評価乗数が設定
されている必要があります。AI システムがどこで属性オブジェクトの乗数を定義しているかについて
は、Scripts\AI ディレクトリの aiconfig.lua を参照してください。
飛行
飛行体を制御するには、エンティティとともにこれらのアーキタイプとフローノードを使用します。
これらのアーキタイプはキャラクターアーキタイプライブラリにてご確認ください：
• CELL/ヘリコプターレギュラー
• Ceph/ドロップシップレギュラー
• Ceph/ガンシップレギュラー
これらのエンティティおよび以下に示されるフローノードは、ヘリコプターのカテゴリにあります。
フォローパス
現在飛行AIが使用する進路は、このフローノードにより設定されます。
• AIが戦闘モードでない場合。
• AIがフロ―ノード回路を巡回するように設定されている場合は、AIは現在の位置から最寄りの進
路に移動し、最後までこの進路を辿ります。AIが進路の最後まで達したことを示すノードアウト
プットは一度のみ送信されます。
• 巡回しない場合、AIは現在の場所から進路の最初に移動しようとし、その進路を最後まで進みま
す。
• AIが戦闘モードである場合。
Version 1.6
16
Lumberyard 開発者ガイド
AI の C++ クラス階層
• ターゲットが見える場合は、ターゲットを襲撃するために最適な場所にAIを配置するための進路
が使用されます。また進路のポジション間をナビゲートするために使用されます。
• ターゲットが見えない場合、進路はパトロールパスとして使用されます。可能な限り、戦闘モー
ドの進路が巡回設定できるように設定を簡素化します。
戦闘モード有効化
現在のターゲットと交戦し撃ち倒すため、このフローノードはAIの戦闘パス内の配置能力を有効また
は無効にします。デフォルトでは、AIは戦闘モードに入る明示的な許可がないと戦闘モードに入れま
せん。
• AIが戦闘モードにあり、ターゲットの場所を特定した場合、交戦するために現在のパス内の位置か
ら戦闘が可能な位置へ移動しようとします。
• 対立するグループのキャラクターは誰でも良いターゲットの候補となります。
発砲有効化
このフローノードは、AIが戦闘モードにあるとき、現在のターゲットへの発砲を有効又は無効にしま
す。デフォルトでは、AIが戦闘モードのときにはこのノードが無効化を明示するまでは発砲が可能で
す。
AI の C++ クラス階層
AI オブジェクトの C++ クラスは次のように構造化されています。
Version 1.6
17
Lumberyard 開発者ガイド
AI システムの概念の例
CAIObject
基本 AI オブジェクトのプロパティ (エンティティ ID、位置、方向、グループ ID、派閥、など) を
定義
CAIActor
基本パーセプションとナビゲーション、動作の選択、調整、ブラックボード、AI テリトリーの把
握、AI プロキシ
CAIPlayer
実際のゲームプレイヤの AI システムでの表現
CPuppet
照準、射撃、姿勢、射程、本格的な AI エージェント
CAIVehicle
車両固有のコード
AI システムの概念の例
このセクションでは、次のトピックについて説明します。
• AI 多層ナビゲーション (p. 18)
• 個々の AI: 動的カバー (p. 18)
• 個々の AI: タクティカルポイント (p. 18)
• グループおよびグローバル AI: ファクション (p. 19)
• グループおよびグローバル AI: フローグラフ (p. 20)
AI 多層ナビゲーション
AI の便利なデバッグ描画:
• ai_useMNM=1
• ai_DebugDraw=1
• ai_DebugDrawNavigation=1
• ai_DrawPath=all
• ai_DrawPathFollower=1
個々の AI: 動的カバー
例: CoverSurface と HMMWV
この例では、オフラインで生成され、実行時に調整される動的カバーの使用を示しています。
AI の便利なデバッグ描画:
• ai_DebugDraw=1
• ai_DebugDrawCover=2
• [AI/Physics] is on
個々の AI: タクティカルポイント
例: 常にプレイヤから隠れたい非常に内気な一般市民
• タクティカルポイントシステム (TPS) クエリ:
Version 1.6
18
Lumberyard 開発者ガイド
AI システムの概念の例
AI.RegisterTacticalPointQuery({
Name = "Civilian_HideFromEnemy",
{
Generation =
{
cover_from_attentionTarget_around_puppet = 25
},
Conditions =
{
reachable = true,
},
Weights =
{
distance_from_puppet = -1,
},
},
});
• AI の便利なデバッグ描画:
• ai_DebugTacticalPoints=1
• ai_StatsTarget=Grunt1
• ai_TacticalPointsDebugTime=10
• 現実性を向上させるには、goalop TacticalPos の前に次を追加します。
<Speed id="Sprint"/>
グループおよびグローバル AI: ファクション
例: さまざまなファクションの AI フォーメーション
マップに次のファクションの戦闘員 3 人を配置します。敵対関係に注意してください。
• 戦闘員
• 暗殺者
• 一般市民
以下に例を示します。
<Factions>
<Faction name = "Players">
<Reaction faction- "Grunts" reaction="hostile"/>
<Reaction faction- "Civilians" reaction="friendly"/>
<Reaction faction- "Assassins" reaction="hostile"/>
</Faction>
<Faction name="Civilians default="neutral"/>
...
</Factions>
(Game/Scripts/AI/Factions.xml を参照してください)
Version 1.6
19
Lumberyard 開発者ガイド
AIバブルシステム
グループおよびグローバル AI: フローグラフ
フローグラフ エディタを使用すると、プログラマーでなくてもグローバル AI ロジックを視覚的に構
築できます。信号伝達の強調表示やブレークポイントなど、フローグラフのデバッガー機能を試して
ください。
AIバブルシステム
AIバブルシステムは、レベルデザイナーが解決できるようにAIエラーメッセージを収集します。この
システムは、どのシステムが問題に関連しているか追跡するのを助けることで、デバッグプロセスを
簡素化します。AIバブルシステムを使用するには、プログラマーは、重要なメッセージをシステムに
プッシュする必要があり、そうすることでレベルデザイナーにいつ問題が発生するか通知します。
メッセージ表示タイプ
メッセージは一連の情報 (エージェント名、場所など) を含みます。標準的フローで何かが間違ってい
ることをデザイナーに理解させる手助けをするメッセージ通知は次のいずれの方法でも表示できます:
• AIエージェントにかぶる発言バブル
• コンソールのエラーメッセージ
• Windowsのメッセージボックスをブロックする
通知表示タイプを指定する
エラーメッセージの表示タイプを指定するために次のうちいずれか一つの方法を使用します:
コンソール
ai_BubblesSystem
AIバブルシステムを有効/無効にします。
ai_BubblesSystemDecayTime
次のメッセージが表示されるまでの発言バブルの画面残留秒数を指定します。
ai_BubblesSystemAlertnessFilter
デザイナーに表示する通知タイプを指定します:
• 通知タイプなし:
• 1 - コンソールのログのみ
• 2 - バブルのみ
•
•
•
•
•
3 - ログとバブル
4 - ポップアップのみをブロック
5 - ポップアップとログをブロック
6 - ポップアップとバブルをブロック
7 - すべての通知のタイプ
ai_BubblesSystemUseDepthTest
通知がワールドのジオメトリによって塞がれる必要があるかどうかを指定します。
ai_BubblesSystemFontSize
3D世界に表示される通知の文字サイズを指定します。
Version 1.6
20
Lumberyard 開発者ガイド
AI タクティカルポイントシステム
C++
C++では、AIQueueBubbleMessage () を使ってどのようにメッセージ通知を表示するか定義します。
Method Signature
bool AIQueueBubbleMessage(const char* messageName, const IAIObject*
pAIObject, const char* message, uint32 flags);
パラメーター:
messageName
メッセージを説明する文字列これは同じメッセージエラーを何度も出すために必要です。 (メッ
セージはキューから削除されたときにもう一度システムにプッシュすることができます)。
GET Object ACL
メッセージに接続されているAIオブジェクトへのポインター
メッセージ
表示するメッセージのテキスト。
flags
通知タイプ. このパラメータは一つ以上のフラグを含めることができ、複数のフラグはパイプ(|)を
使用することで分割できます。
• eBNS_Log
• eBNS_Balloon
• eBNS_BlockingPopup
例:
AIQueueBubbleMessage("COPStick::Execute PATHFINDER_NOPATH non continuous",
pPipeUser, "I cannot find a path.", eBNS_Log|eBNS_Balloon);
Luaスクリプト
local entityID = System.GetEntityIdByName("Grunt.AlienGrunt1");
AI.QueueBubbleMessage(entityID,"I cannot find a path.");
AI タクティカルポイントシステム
タクティカルポイントシステム (TPS) によって、AI システムは AI エージェント環境に対してクエリ
を強力に実行できます。これには GetHidespot 機能があり、"非表示の" goalop を拡張します。
TPS は、AI の世界のポイントの集合に対する構造化クエリ言語です。TPS を使用して、AI エージェ
ントは環境に関するインテリジェントな質問を尋ねて、隠れスポット、攻撃ポイント、およびナビ
ゲーション中間ポイントなどの関連する種類の点を発見することができます。TPS 言語は、単純で強
力であり、非常に読みやすくなるように設計されたものです。
たとえば、次のクエリは、次の条件に一致するすべてのポイントを要求します。
• 自分の注意ターゲットから隠れることができる現在の場所から 7 メートル以内の場所を生成しま
す。
• 注意ターゲットが到達する前に自分が到達できる、覆いの付いた場所のみを受け入れます。
• 自分に最も近い場所が望ましいです。
Version 1.6
21
Lumberyard 開発者ガイド
タクティカルポイントシステムの概要
hidespots_from_attentionTarget_around_puppet = 7
coverSuperior = true, canReachBefore_the_attentionTarget = true
distance_from_puppet = -1
TPS はポイントのランク付けを行う非常に効率的な方法を使用して、レイキャストおよびパス探索な
どのコストのかかるオペレーションを最小限に抑制します。クエリの最適化は自動的に行われます。
このセクションでは、次のトピックについて説明します。
• タクティカルポイントシステムの概要 (p. 22)
• TPS クエリ実行フロー (p. 23)
• C++ を使用した TPS のクエリ (p. 23)
• Lua を使用した TPS のクエリ (p. 25)
• TPSクエリ言語参照 (p. 26)
• ポイントの生成および評価 (p. 29)
• モジュラー動作ツリーシステムとの統合 (p. 31)
• 今後の計画と可能性 (p. 32)
タクティカルポイントシステムの概要
タクティカルポイントシステム (TPS) の主要機能には以下が含まれます。
• 構造化クエリ言語の使用
• C++ と Lua における強力かつ高速な変化
• オブジェクト背後に隠す場所といった従来の枠を超えた、さまざまなポイント特性に対するクエリ
サポート
• エンティティの位置に近いポイント
• 地形の特徴に沿ったポイント
• デザイナーが提案したポイント
• 公開された場所または地形上の近くのポイントの任意の解決法
• 次のようなクエリの組み合わせ
• 「自分の背後と左側で、ソフトカバーではない、自分の現在の位置以外のポイントを見つける」
• 「自分の注意ターゲットからは非表示で、仲間には表示されるポイントを見つける」
• 次のような優先する重み付け
• 指定したエンティティに最も近い (または最も遠い) ポイントを見つける
• エンティティに近いポイントとプレイヤから遠いポイントとの間でバランスを取る
• ソフトカバーよりも固いカバー上のポイントを優先する
• 次のようなクエリのフォールバックオプション
• 近くの良好なカバーを優先する (存在しない場合はソフトカバーに戻る)
• クエリの可視化
• 許容されるポイントと拒否されるポイント、およびその相対スコアを確認する
• クエリで使用されている高価なテストの数と、該当するポイントを確認する
• 自動クエリの最適化
• クエリで構成される個々の評価の相対コストを把握する
• 重み付け基準に従い、考えられる適合性に基づいてポイントを動的にソートする
• 高価なテストの使用を最小限に抑えるため、最初に「最も適合性の高い」ポイントから評価する
• 評価数をさらに減らすため、相対的な適合性に基づいて、超えられないポイントを識別する
• アーキテクチャ、レベル、またはロケールに特化した最適化をさらに実行するフレームワークを
指定する
Version 1.6
22
Lumberyard 開発者ガイド
TPS クエリ実行フロー
これらの主要機能から得られる利点に加えて、このフレームワークにはコーディングするうえで次の
ような利点があります。
• アクションからクエリを分離
• エージェントの状態を変えずに任意のクエリをいつでも実行できる
• クエリ言語は展開が容易
• タイムスライシングに簡単に対応 (基本的にマルチスレッディング)
• クエリを介した進行がきめ細かい
• 進行は状態として追跡されるため、簡単に一時停止、再開できる
• 生成されたポイントで必要になるまで高価な評価テストを遅らせるメカニズムを提供する
TPS クエリ実行フロー
以下のステップは、TPS クエリの定義と実行ステージをまとめたものです。パフォーマンスに大きく
影響するのは、ステージ 3 および 4 のみです。
1. クエリの解析:
• クエリの文字列と値を解析します。
• このステップは通常、1 回だけ実行され、キャッシュされます。
2. クエリリクエストの実行
• クエリは、C++、ScriptBind、goalops などで実行されます。
• クエリはステートレスです。動きのある操作を示すものではありません。
3. ポイントの生成:
• 一連の候補ポイントを作成します。
• ポイント候補は、クエリの Generation 基準に基づいています。
4. ポイントの評価 (これは圧倒的に負荷の高いステージです):
• Conditions 基準に基づき、ポイントを承認または拒否します。
• Weights 基準に基づき、相対スコアをポイントに割り当てます。
5. クエリフォールバックの検討:
• Conditions 基準に一致するポイントがない場合は、フォールバックオプションを検討します。
• フォールバックがある場合は、ステップ 3 に戻ります。
6. ポイントの視覚化:
• 視覚化が必要な場合は、すべてのポイントを画面に描画します。
• 承認/拒否のステータスや相対スコアなどのポイントデータを含めます。
7. 結果を返す:
• クエリ条件を満たすものがあれば、1 つ以上のポイントを返します。
• 各ポイントは、選択されたポイントを説明する構造体として返されます。
実行フローによっては、ある程度の最適化も可能です。たとえば、関連するクエリ結果をキャッシュ
しておき、次のフォールバッククエリで使用することができます。
C++ を使用した TPS のクエリ
これらの C++ インターフェイスを使用すると、他の C++ コードから、および goalops 内で TPS を使
用できます。Lua のクエリは変換されます。
次の 2 つの C++ インターフェイスがあります。
• 内部 - AI システム内でのみ使用
Version 1.6
23
Lumberyard 開発者ガイド
C++ を使用した TPS のクエリ
• CTacticalPointQuery オブジェクトを使用してクエリを構築
• クエリをオンザフライで作成または調整
• 関連する AI システムクラスへのアクセスが容易
• 外部 - あらゆるモジュールから使用
• DLL の境界を越える場合に最適
• よりシンプルで、オブジェクト指向ではなく、強力
• 保存されているクエリを使用して効率化
内部インターフェイスの構文
次の例では、いくつかの解析が明示的にここで行われています。これはほとんどのシステムで重要に
なります。
// Check for shooter near cover using TPS
static const char *sQueryName = "CHitMiss::GetAccuracy";
ITacticalPointSystem *pTPS = gEnv->pAISystem->GetTacticalPointSystem();
int iQueryId = pTPS->GetQueryID( sQueryName );
if ( iQueryId == 0 )
{
// Need to create query
iQueryId = pTPS->CreateQueryID( sQueryName );
pTPS->AddToGeneration( iQueryId,
"hidespots_from_attentionTarget_around_puppet", 3.0f);
pTPS->AddToWeights( iQueryId, "distance_from_puppet", -1.0f);
}
pTPS->Query( iQueryId, CastToIPuppetSafe( pShooter->GetAI() ),vHidePos,
bIsValidHidePos );
TPS の構文の例
次の例とその説明は、TPS のクエリ構文の使用方法を説明するものです。TPS クエリ言語の詳細な説
明については、TPS のクエリ言語の構文およびセマンティクスのトピックを参照してください。
option.AddToGeneration("hidespots_from_attTarget_around_puppet", 50.0)
このクエリリクエストは生成基準として表現され、距離を表す浮動小数点値を指定します。このクエ
リは 5 つの語に分かれます。
• 「hidespots」は、慣習的に、生成されたポイントが既知のカバーの背後に配置されることを表しま
す。
•
•
•
•
「from」と「around」は読みやすくするために接着剤の役目をする単語です。
「target」は、ポイントをオブジェクトから隠す場合のオブジェクトの名前を指定します。
「puppet」は、ポイントがその周囲に生成される中心の場所を指定します。
浮動小数点値は、中心の場所から測定した半径の距離を表し、その中にポイントが生成される領域
を定義します。
この段階ではレイキャストは実行されないことに注意してください。ここには非常に高い柔軟性があ
ります。たとえば、プレイヤから隠すことをどのように選択するかについては、(1) プレイヤの近くの
どこか、(2) 私たちの近くのどこか、(3)、友達の近くのどこか、から選択できます。また、想像した
プレイヤの位置など、隠れる際の全く異なるターゲットを指定できます。ポイントの生成段階に柔軟
性を持たせることにより、より強力なクエリをサポートでき、またユーザーが適切な領域での計算に
集中できるようになります。
option2.AddToConditions("visible_from_player",true)
Version 1.6
24
Lumberyard 開発者ガイド
Lua を使用した TPS のクエリ
このクエリリクエストは条件基準として表されるため、ブール値の結果を期待できます。クエリ
ではプレイヤに表示されるポイントを指定することができ、これは興味深く、非常に有効です。
「visible」という用語はレイテストを指定し、「player」は生成したポイントからレイキャストするオ
ブジェクトを指定します。
option2.AddToConditions("max_coverDensity",3.0)
このクエリは条件として表されるため、ブール値の結果を期待できます。「Max」という用語は、
結果の値を与えられた浮動小数点値と比較して、それよりも小さくなければならないことを指定し
ます。「coverDensity」という用語は、これを密度のクエリとして識別し (カバーやフレンドリな AI
エージェントなどのものの密度を測定します)、カバーの測定を指定します。
option1.AddToWeights("distance_from_puppet",-1.0)
このクエリはウエイトコンポーネントとして表されます。クエリの結果は 0 から 1 の範囲の値です
(必要に応じて正規化されます)。ブール型のクエリは設定 (セカンダリカバーの上のプライマリカバー
など) を表すことができます。false の場合は 0.0、true の場合は 1.0 の値を返します。
このクエリのコンポーネントは、オブジェクトに関連する特定の場所にあるポイントの設定を表しま
す。「distance」という用語はこれを距離クエリとして識別し、距離を表す浮動小数点値を指定しま
す。「puppet」という用語は、距離を測る際の出発点となるオブジェクトを表します。
Lua を使用した TPS のクエリ
Lua では、TPS を使用する 2 つの方法があります。
• Scriptbinds では Lua 動作から TPS クエリを使用し、副作用なしでテーブルとして結果を返すこと
ができます。これは、次のような高レベルの環境の論理に役立ちます。
• 環境が適しているかどうかに応じて動作を選択する (たとえば、多くのソフトカバーが利用できる
場合は、"sneaker" 動作のみを選択する)。
• 非常にあいまいなクエリを TPS システムに追加するのではなく、ポイントの短いリストで、最終
的で非常に具体的なテストを実行する。
• より大きな環境の認識を可能にする (たとえば、隠れる前に見ることができるように、近くの良い
隠れ場所を 3 つ教えてください)。
• 目標パイプにより、goalop を使用してポイントを選択し、事前定義された TPS テーブルを使用し
てそこに移動できます。
• 前の "hide" goalop と同等の "tacticalpos" goalop を使用します。
• フォールバッククエリを使用して、goalpipe のブランチのリストを回避します。
• さらに柔軟な goalop を提供して、移動からクエリを分離することができます。
両方の方法では、次の例に示すように同じテーブル構造を使用してクエリの指定を定義できます。
Hide_FindSoftNearby =
{
-- Find nearest soft cover hidespot at distance 5-15 meters,
-- biasing strongly towards cover density
{
Generation= {
hidespots_from_attentionTarget_around_puppet = 15 },
Conditions= {
coverSoft = true,
visible_from_player = false,
max_distance_from_puppet = 15,
min_distance_from_puppet = 5},
Weights =
{
distance_from_puppet = -1.0,
coverDensity = 2.0},
},
Version 1.6
25
Lumberyard 開発者ガイド
TPSクエリ言語参照
-- Or extend the range to 30 meters and just accept nearest
{
Generation ={
hidespots_from_attentionTarget_around_puppet = 30 },
Weights =
{
distance_from_puppet = -1.0}
}
}
AI.RegisterTacticalPointQuery( Hide_FindSoftNearby );
Note
クエリを登録すると、この保存されたクエリを参照するクエリ ID が返されます。
Scriptbind を使用したクエリ
次のスクリプトは、既存の指定を使ってクエリを実行します。詳細については、Scriptbind_AI.h
のコメントを参照してください。
AI.GetTacticalPoints( entityId, tacPointSpec, pointsTable, nPoints )
Goalop を使用したクエリ
次のスクリプトは既存のクエリを実行します。クエリにはフォールバックを組み込むことができるた
め、通常、ブランチの使用は不要です (ブランチテストは引き続きサポートされます)。
AI.PushGoal("tacticalpos",1, Hide_FindSoftNearby);
TPSクエリ言語参照
C++とLua(潜在的にXMLにおいても）におけるクエリの定義方法がありますが、同じコア・シンタッ
クスを使用します。このページでは、まずTPSクエリ言語をGeneration、ConditionsまたはWeightsで
表出されるクエリ構成要素によって定義し、またクエリ言語セマンティックについて議論します。
クエリシンタックス
Note
非終端記号は太文字です。シンボルは全て実行されませんが、イラストレーションのために
表示されます。
Generator ::= GenerationQuery '_' 'around' '_' Object
Condition ::= BoolQuery | (Limit '_' RealQuery)
Weight
::= BoolQuery | (Limit '_' RealQuery) | RealQuery
GenerationQuery ::= ( 'hidespots' '_' Glue '_' Object)
| 'grid' | 'indoor'
BoolQuery ::= BoolProperty | (Test '_' Glue '_' Object)
BoolProperty ::= 'coverSoft' | 'coverSuperior' | 'coverInferior' |
'currentlyUsedObject' | 'crossesLineOfFire'
Test ::= 'visible' | 'towards' | 'canReachBefore' | 'reachable'
RealQuery = ::= RealProperty | (Measure '_' Glue '_' Object)
RealProperty ::= 'coverRadius' | 'cameraVisibility' | 'cameraCenter'
Measure ::= 'distance' | 'changeInDistance' | 'distanceInDirection' |
'distanceLeft' | 'directness' | 'dot' | 'objectsDot' | 'hostilesDistance'
Glue ::= 'from' | 'to' | 'at' | 'the'
Limit ::= 'min' | 'max'
Object ::= 'puppet' | 'attentionTarget' | 'referencePoint' | 'player'
Version 1.6
26
Lumberyard 開発者ガイド
TPSクエリ言語参照
| 'currentFormationRef' | 'leader' | 'lastOp'
クエリ・セマンティック
Note
• ｢調整可能」は、使用された厳密値は事後の微調整または調節が可能であることを示しま
す。
• 「真値」は、浮動小数点値を返す（ブーリアン型ではなく）ことを意味しています。
オブジェクト
パペット
クエリを作成するAIエージェント
アテンション・ターゲット
AIエージェントの対象であるオブジェクト
レファレンス・ポイント
AIエージェントの参照点、展望
プレイヤー
人間のプレイヤー（主にデバッグや迅速なハッキングに対応）
グルー
from | to | at | the
クエリステートメントでの検索を可能にする単語の貼り付けをする各クエリーにはグルーワード
が必要ですが、アクティブ機能を持たず、さらにパーサーはそれらを区別しません。検索可能性
はデバッギングと長期的メンテナンスによって補完されることが望ましいです。
ジェネレーション
ハイドスポット
「～から」のつくオブジェクト（「オブジェクトから隠す」にあるような）についての可能なカ
バーオブジェクトのすぐ後ろにある個別の点典型的に、一つのカバーオブジェクトにひとつのポ
イントがあります。シンボルの使用は大きなカバーオブジェクトの後ろに複数のポイントを発生
させ、不規則に形成されたダイナミックなオブジェクトに対応します。
アラウンド
特殊な意味をもったグルーワードこの単語の後には、ジェネレーション半径を中央に、その周り
をとるオブジェクトの名前を置かなければなりません。
Conditions/Weight プロパティ（オブジェクトを使用しない）
これらのプロパティは特定のポイントと関連性を持ちます。
coverSoft
ブーリアン型プロパティ、特定されたポイントがソフトカバーを使用したハイドスポットであれ
ば、値は真となります。
coverSuperior
ブーリアン型プロパティ、特定されたポイントがスペリアーカバーを使用したハイドスポットで
あれば、値は真となります。
coverInferior
ブーリアン型プロパティ、特定されたポイントがインフェリアーカバーを使用したハイドスポッ
トであれば、値は真となります。
Version 1.6
27
Lumberyard 開発者ガイド
TPSクエリ言語参照
currentlyUsedObject
ブーリアン型プロパティ、特定されたポイントが、パペットが既に使っているオブジェクト（パ
ペットの現在のハイドオブジェクトなど）であれば値は真となります。
coverRadius
真（浮動）プロパティ、0.0もしくはあらゆる特定ポイントに関連付けられたカバーオブジェクト
のおおよその半径を表します。条件テストに使われる際には、メーターで表された絶対値に戻り
ます。重さとして使われた場合、標準化された値に戻り、[0.0-5.0m]から[0.0-1.0]の範囲のマッピ
ングをします。(調整可能)
coverDensity
リアルプロパティ、特定ポイントに近い潜在的なハイドポイントの数を表します。条件テストに
使われる場合、５メートル半径のサンプルを用いた１メートル平方あたりのハイドスポットの
数の見積もりを意味する絶対値に戻ります。重さとして使われた場合、標準化された値に戻り、
（０0.0-0.1）から[0.0-0.1]の範囲にマッピングします（１メートル平方あたりのハイドスポッ
ト）。(調整可能）
コンディション、重量テスト、測量（オブジェクトが必要）
これらのプロパティはdistance_to_attentionTargetやvisible_from_referencePointなどの特定のオブジェ
クトと関連しています。
距離
真（浮動）測定値、あるポイントから特定のオブジェクトまでの直線距離を表します。条件テス
トに使われる際には、メーターで表された絶対値に戻ります。重さとして用いられる場合は、標
準値に戻り、[0.0-50.0m] から [0.0-1.0]の範囲の値にマッピングします。調整可能
changeInDistance
真（浮動）測定値、あるポイントに移動した場合にパペットが特定のオブジェクトまでどのくら
い近づくかを表します。現在の位置から特定のオブジェクトまでの距離を測り、提案されてい
る新しい位置からそのオブジェクトまでの距離を引きます。条件テストに使われる際には、メー
ターで表された絶対値に戻ります。重さとして用いられる場合は、標準値に戻り、[0.0-50.0m] か
ら [0.0-1.0]の範囲の値にマッピングします。(調整可能)
distanceInDirection
真（浮動）測定値、ポイントから特定のオブジェクトまでの距離を表します。ポイントまでのパ
ペットからドットプロダクトまでのベクトルを取り、オブジェクトまでのパペットから標準化さ
れたベクトルを取ります。テストに使う場合、メーターで表した真値に戻ります。重さとして用
いられる場合は、標準値に戻り、[0.0-50.0m] から [0.0-1.0]の範囲の値にマッピングします。(調整
可能)
directness
真（浮動）測定値、あるポイントまでの動きが、特定のオブジェクトまでどの程度接近するかを
表します。オブジェクトまでの様々な距離をとり（changeInDistance）ポイントまでのパペット
からの距離で割ります。[-1.0 to 1.0]の範囲を必ず使います。1.0は完全に直接的なコースを意味
し、マイナスの値はオブジェクトから離れる動きを表します。
リミット
min | max
ブーリアン型をプロダクトするために、リミットは真値のテストに使うことができます。粗い重
量として使うことのできる条件などにも有用です。例えば、MAX_DISTANCE = 10 は１０より小
さい値が望ましく、一般的な意味でそれよりも近い距離のポイントであることを必要としない、
ということを表すのに使うことができます。
Failing クエリー
クエリーが失敗する理由はたくさんあり、各ケースがどのように扱われるかを理解することは重要で
す。
Version 1.6
28
Lumberyard 開発者ガイド
ポイントの生成および評価
• クエリの条件に合うポイントがありませんでした。これは妥当な結果で、失敗ではありません。AI
は、フォールバッククエリーへ戻るもしくは他の行動を試してみることができます。
• 個別のポイントの文脈ではクエリーは意味を成しません。時折、あるポイントやあ時間ではクエリ
は意味をなしません。このような場合には、クエリーは「最も驚かない」結果へ戻ろうとします。
例えば、オープンでじぇねレートされたポイントについてのクエリーは「これはソフトカバーです
か？」と聞きます。これはなんらのカバーでもないため、結果は「偽」となります。クエリーの名
前は混乱を避けるために慎重に選ばなければなりません。
• この時間のどこのポイントにおいても、クエリはパペットの文脈では意味をなしません。ポイント
文脈の問題については、クエリはもっとも「最も驚かない」結果に戻ろうとします。例えば、パ
ペットに関するクエリは「私は注目されたいターゲットに対して可視的ですか？」パペットに注目
対象がないときクエリは偽値に戻ることがあります。ただし、それはすべてのポイントを不適切化
させます。このケースは通常、パペットが最低限この時点で注目ターゲットを持っているべきなの
に持っていないというコードエラーを指します。注意:「注目ターゲットからハイドスポットを作
る」というクエリーの場合、 この状況はポイントジェネレーション段階における問題に似た問題を
引き起こします。これらの状況はコードエラーとしてフラグされます。
• コードエラーによりクエリーが失敗しました。TPSクエリーのエラーをテストし、その問題を挙げ
ることもできます。例えば、クエリーもしくはコンビネーションが完全に実行されていないか、も
しくは変数をテストするためにある種の検証の条件として使われています。
ポイントの生成および評価
AI エージェントは考慮対象とする一連のポイントを生成するために TPS ポイント生成クエリを行い
ます。各ポイントが生成されると、その位置と使用可能なメタデータに基づいて検証できます。
ポイントの生成
Input
ポイントを生成するには、以下の情報が必要になります。
• 生成するポイントの種類を定義する具体的な条件。
• ポイントが生成される中央または焦点位置。これは Puppet 自体の現在の位置、注意ターゲット、
またはその他の指定した位置にすることができます。
• クエリによっては非表示にするターゲットなどのセカンダリオブジェクトの位置になります。
複数のポイント生成基準セットを指定できます。たとえば、クエリは Puppet と注意ターゲットの両
方を中心にしたポイント生成をリクエストすることもできす。
Processing
TPS は、入力に基づいて評価するポイントの生成を開始します。すべてのポイントは主に 2 つのタイ
プに分類されます。
• 非表示ポイント。このポイントは次の計算に基づいて生成されます。
• 非表示可能なオブジェクト
• 非表示にする位置が指定された場合にのみ生成される
• 非表示ポイントは最終的な位置を表す (カバー背後の位置の計算など)
• オブジェクトおよび遅延を使用して実際のポイントを検索することも可能
• オープンポイント。これらはクエリの指定および次の計算に基づいて生成されます。
• 通常は地形 (表面などの場合もある)
• 解決法/パターン (1 メートル間隔の三角形など)
• より一般的なサンプリングを行って正確なポイントを見つけることもある (その場合でも最初の解
決法は必要)
Version 1.6
29
Lumberyard 開発者ガイド
ポイントの生成および評価
• 放射状/均等な分散
出力
ポイント生成クエリの結果はポイントオブジェクトのリストです。各ポイントオブジェクトには、ポ
イントの位置と、関連付けられた非表示オブジェクトなどの使用可能なメタデータが含まれます。
評価ポイント
生成クエリが一連のポイントを生成すると、評価することができます。ポイント評価は各ポイントの
「適合性」(指定した基準にポイントがどれだけ一致するか) を確立しようとします。目的は、1 つの
良好なポイント、または良好なポイントの最高 N 数を選択することです。
Input
ポイントを評価するには、以下のエレメントが必要になります。
• ポイントジェネレーターからのポイント候補のリスト
• ポイント評価の基準
• ブール値 – 他のポイントとは関係なく、ポイントを含めるか除外する基準として使われる条件
• 重み – 他のポイント (ブール値基準に含まれるもの) に相対した適合性の測定値を組み合わせて与
える基準
Processing
主な目的は、できるだけ早く十分に良好なポイントを見つけることです。「十分に良好」は「最適」
を指すこともありますが、ユーザーが指定する不確実性レベルが許容される場合、最適化から結果が
得られる可能性は大きくなります。
評価の順序はクエリの効率に大きく影響します。このため、コストがかかるオペレーションの数を最
小限に抑えるために、評価では次の戦略を使用します。
1. 安価なブール値 (1 つの関数呼び出し、またはいくつかのベクトル演算の順序で費用が発生)。こ
れを使用することで、多大なコストをかけずに、多数のポイントを完全に割り引くことができま
す。例: このポイントはプライマリまたはセカンダリの非表示スポットかどうか。このポイントか
らターゲットまでの距離は 5 メートル未満か。
2. 安価な重み付け (安価なブール値と同様の費用)。これを使用することで、可能性が高いポイントに
焦点を当てて、特定のポイントが最終的に最適な選択肢となる可能性を測定し、高価なテストの数
を減らすことができます。例: closeness_to_player * 3 + leftness * 2
3. 高価なブール値 (およそ 100 倍 コストがかかる)。これらは解答するのに高価な計算を要するイエ
ス/ノーの質問形式ですが、競合からポイントをさらに除外します。たとえば、このポイントはプレ
イヤに表示されますか? という質問には高価なレイテストが必要になります。
4. 高価な重み付け (高価なブール値と同様の費用)。これらを使用して、残りのポイントをランク付け
することができます。例: nearby_hidepoint_density * 2
アルゴリズムの詳細
最終的な 2 つのステップを交互に配置し、評価の順序を完全に動的にすることで、処理はさらに進む
ことが分かります。条件 (ブール値) とは異なり、重み付けではそれ以降の評価からポイントを明示的
に割り引いて考慮しません。ただし、評価時にポイントの相対的な「適合性」を追跡すれば、重み付
けに次の 2 つの基本的な原則を採用することで、評価数を大幅に減らすことができます。
• 最大限可能な適合性の順にポイントを評価し、最適なポイントを最速で十分に評価します。
Version 1.6
30
Lumberyard 開発者ガイド
モジュラー動作ツリーシステムとの統合
• 最初の重み付け評価に基づいたポイントがそれ以外のポイントよりも良好な場合は、残りの条件に
対する評価を即座に終了します。ポイントがすべての条件基準を通過した場合、それが最適なポイ
ントであり、その他のポイントを評価する必要はありません。また、このポイントを残りの重み付
けで評価する必要もありません。
この実装は、最大限可能な適合性に応じてポイントを順序付けし、各ポイントの評価の進行状況を個
別に追跡するヒープ構造をベースとしています。各重み付けの評価はポイントに関する一部の不確実
性を折りたたみ、最小と最大の適合性の両方を調整します。重み付け評価によるスコアが高いと、最
大値が少し減少し、最小値が大きく増加します。スコアが低いと、最大値が大きく減少し、最小値が
少し増加します。
各イテレーションでは、ヒープ最上部のポイントで次に高価な評価を行ってから、必要に応じてポイ
ントが再ソートされます。ポイントですべての評価が完了した後の最大限可能な適合性が、最適なポ
イントとなるはずです。このアプローチは、その他すべてのポイントについての評価数が比較的少な
い最適なポイントの評価となる傾向があります。
出力
ポイント生成評価の結果は、単一ポイントまたは N 個のポイントのグループ、およびその選択肢に導
くすべてのメタデータをリクエストする機会です。その結果、動作はそれぞれのスタイルを適応し、
非表示ポイントが受け取った特性を反映させることができます。
モジュラー動作ツリーシステムとの統合
モジュラー動作ツリー (MBT) 内で <QueryTPS> ノードを使用して、事前定義された、名前による
TPS クエリを呼び出すことができます。<QueryTPS> ノードは成功または失敗を返します。
<QueryTPS> ノードに関して最もよく使用されるパターンとして、<Sequence> 内の
<Move> ノードと組み合わせて、指定した位置の状態を識別することがあります。次の例
は、SDKGrunt_TargetPositionOnNavMesh という事前定義された TPS クエリ (入力を想定) の呼び出
しを示しています。このクエリが成功すると、AI エージェントは照会した位置に移動します。
<Sequence>
<QueryTPS name="SDKGrunt_TargetPositionOnNavMesh" register="RefPoint"/>
<Move to="RefPoint" speed="Run" stance="Alerted" fireMode="Aim"
avoidDangers="0"/>
</Sequence>
事前定義されているクエリ SDKGrunt_TargetPositionOnNavMesh の定義は次のとおりです。
AI.RegisterTacticalPointQuery({
Name = "SDKGrunt_TargetPositionOnNavMesh",
{
Generation =
{
pointsInNavigationMesh_around_attentionTarget = 20.0
},
Conditions =
{
},
Weights =
{
distance_to_attentionTarget = -1.0
},
},
Version 1.6
31
Lumberyard 開発者ガイド
今後の計画と可能性
});
今後の計画と可能性
以下のトピックは、TPS 関連の開発が可能な領域を示します。
環境に対する高レベルの推測
1 つ考えられる TPS の用途として、単純にポイントの選択とそこまでの移動のために TPS を使用す
るだけではなく、クエリ結果に基づいて環境に対する有益な推測を得ることもできるという可能性が
あります。
たとえば、プレイヤーが角に沿って走り、AI Puppet がその後を追うとします。AI Puppet が角を曲が
るときには、プレイヤーが見えなくなっています。このとき Puppet は TPS に対し、自身から隠れる
ために選択されると思われる場所を問い合わせ、たとえば次のような結果を得ることができます。
• TPS は、1 つの隠れポイントが他のポイントよりずっと優れているという結果を返します。これ
は、空の部屋の中心に大きなボックスが 1 つあるからです。AI Puppet は、そこにプレイヤーがい
ると推測し、発砲しながらまっすぐボックスに突撃します。
• TPS は、隠れるのに適した場所がいくつかあるという結果を返します。これは、隠れ場所となる茂
みがあるからです。隠れポイントはすべてグループブラックボードに保存され、AI Puppet (または
グループ) はプレイヤーを見つけるために、次々に各地点に接近することができます。
このシナリオは、コードを少し追加すると実行可能ですが、TPS を土台にすることでずっと簡単にな
ります。
サンプリングメソッド
オープンスペースでポイントを生成する場合、ポイントはグリッド内に生成するか、オブジェクトの
周囲に放射状に生成します。このような場合は、基本的なサンプリングメソッドがサポートされま
す。領域のサンプリングが必要である場合、評価機能におけるなんらかの干渉性を想定できます。ま
た、代わりに適応サンプリングのアプローチを使用することもできます。
動的なコスト評価
TPS の最適化における重要な側面には、クエリの相対コスト機能の調整が伴います。評価のコストは
プラットフォーム、レベル、レベル内の場所によって異なり、時間の経過と共にコードが変更された
場合にも変化します。コストの低い評価よりコストの高い評価に有利になることを回避するには、評
価順序が正しいかどうかを確認することが重要です。あらゆる環境で評価機能のプロファイリングを
行う必要性があるということは、実行時の自動プロファイリングソリューションが役立つ可能性があ
ります。
さらに、重み付け基準の相対的な重みも考慮する必要があります。低コストのクエリであっても、最
終的な適合値に対する貢献度が 10% しかなければ、先に実行する価値がない可能性があります。これ
に対し、高コストであっても貢献度が 90% のクエリを実行すると、実際には他の評価を多数実行する
分のコストを節約できる可能性があります。
最適性制約の緩和
ポイントを評価する際には、すべてのステージで考えられる最大および最小の適合性が常に認識され
ています。これにより、エラーの範囲や、ポイントに関する不確実性の相対的な測定基準が提供され
ます。
適合性が著しく高い他のポイントはあり得ないと明らかになった場合は、最適性制約を緩和してポイ
ントを承認する方が良い場合もあります。たとえば、あるポイントについて考えられる最小適合性
が、次に最適なポイントについて考えられる最大適合性より、5% 未満下回るだけという可能性もあ
ります。この情報を使用すると、評価を早く停止し、パフォーマンスをさらに節約できる可能性があ
ります。
Version 1.6
32
Lumberyard 開発者ガイド
ナビゲーションに関する Q & A
ナビゲーションに関する Q & A
大きな三角形とその間にある小さいリンク
Q: 大きいフラットマップを作成し、その上に AI エージェントを配置して、AI ナビゲーションの三角
形分割を生成しました。しかし、AI エージェンがポイント A からポイント Ｂ まで最短の直線パスを
常に取るわけではないことに気が付きました。なぜでしょうか。
A: この問題を説明するために、次のツールを使用します。
• AI デバッグコンソール変数 ai_DebugDraw を "74" に設定します。この値は AI のナビゲーショ
ングラフを描出します (注: 値を 79 にすると実行速度は速くなりますが、プレイヤに近いエリ
ア (15 m) に結果が制限されます)。
• AI デバッグコンソール変数 ai_DrawPath を "all" に設定します。この変数はリンク (隣接する
三角形の間の通路) などの AI エージェントパスを描出します。
• エディターの [Ruler] ツールをパスの可視化に使用します。実験を行うためにマップ上で実際の
AI エージェントは必要ありません (注: このツールは [Snap Angle] と [Select Object(s)] の間に
配置されています)。
AI ナビゲーションの三角形分割は、小さいメモリ占有領域を使用して高速に実行することを意図
しています。これに関連する決定事項には、16 ビットの符号付き整数を使用して、隣接する 2 つ
三角形間の通路 (または "リンク") の半径測定を保存することも含まれます。単位にセンチメート
ルを使用するため、最大のリンク半径は 32,767 cm (327.67 m) になります。AI エージェントが別
の三角形に移動する際に通過できるのはこの通路のみとなるため、三角形のサイズが特大のまま
だと必然的に非常に狭くなります。2 * 327.67 = 655.34 m 未満の辺を使用した三角形ではこの問
題は発生しません。
この問題はマップ開発のごく初期段階でのみ発生します。禁止されたエリア、ツリー、その他の
マップの不規則性すべてによって三角形分割はさらに促進され、サイズの小さい三角形が増える
ことになります。その結果、この問題は解消されます。
パスの追従
Q: パスの追従は実際、どのように機能しますか。開始点はどこですか。
A: 詳細については、経路追従 (p. 33)を参照してください。
自動無効化
Q: プレイヤからの距離に関係なく常にパトロールをアクティブにするにはどうすればよいでしょう
か。
A: 詳細については、自動無効化 (p. 36)を参照してください。
経路追従
このトピックではどのようにしてLumberyard 内で経路追従が行われるかのハイレベルな使い方をいく
つか提供します。いくつかのコンセプトを説明するために、多くのAIテキストにみられる一般的な経
路追従をよく表しているRacing HMMWVsという比較的単純な例を使います。
Racing HMMWVsの経路追従は次のような手順を踏みます。
1. (AIエージェントに)最も近い経路上のポイントを獲得します。
2. このポイントの経路パラメーターを獲得します。経路は通常パラメトライゼーションのようなもの
ですt -> (x,y,z)。
Version 1.6
33
Lumberyard 開発者ガイド
Goalop "Followpath"
3. このパラメーターに、通常"lookahead"と呼ばれる特定の価値を加えます。
4. この新しいパラメーターに対応する経路ポイントを獲得します。これをルックアヘッドポジション
と呼びます。
5. このポジションをナビゲーションターゲットとして使用します。
6. もしヴィークルが詰まったときは、一番近い経路上のポイントに直接送信します。
Goalop "Followpath"
goalop followpath を使用してAIエージェントに経路を追従するように指示しま
す。COPFollowPath::Execute.へのコールの最初にブレイクポイントを設定することで、この手順を見
ることができます。Visual Studio内のコールスタックウィンドウ内で、AIシステムアップデート処理
の一部として呼ばれているすべての（アクティブ）AIエージェントのアップデートオペレーションを
見ることができます。それと引き換えに、このアクションはAIによって実行されていて現在アクティ
ブなgoalopsのオペレーション実行を呼び出します。
COPFollowPath::Execute は以下のタスクを遂行します：
• goalop pathfind を使って、経路の最初に導く経路を見つけます。オプショナルで、 followpath
goalopに渡されたパラメーターを使った経路上にある一番近くのポイントへの経路を見つけます。
• goalop traceを使用して経路を追従し、追跡します。
• "OnPathFollowingStuck"のシグナルを感知して、AIエージェントが詰まっていないことを確認しま
す。
goalops pathfind とtrace は通常[approach ]と [stick]を含んだナビゲーション機能のあるgoalopsのため
に使用されます。
COPTrace::ExecuteTrace と COPTrace::Execute
COPTrace::ExecuteTrace はエッジケースやスマートオブジェクトのような、経路追従に関する問題
を解決するために使います。このコールの主要事項は以下の通りです。
IPathFollower* pPathFollower = gAIEnv.CVars.PredictivePathFollowing ?
pPipeUser->GetPathFollower() : 0;
bTraceFinished = pPathFollower ? ExecutePathFollower(pPipeUser, bFullUpdate,
pPathFollower) : Execute2D(pPipeUser, bFullUpdate);
COPTrace::Execute では同じ作業に加えて少し他のこともできます。経路追従AIに関し
ては、ルックアヘッドポジションが経路の最終地点に達したとき、このオペレーション
が"OnEndWithinLookAheadDistance"のシグナルをAIに送信します。サンプルシナリオでは、racing
HMMWVs に、現在従っている経路内を移動しながら、ほかの新しい経路を探し始めるように許可し
ます。通常、経路追従プロセスが完了するとAIエージェントは動きを停止します。以下のLuaスクリプ
トも、動きを持続させるのに便利です：
AI.SetContinuousMotion(vehicle.id, true);
COPTrace::Execute2D
AIエージェント(少なくともCPipeUser)が従う経路を持っていない場合、このオペレーションはフォー
ルバックとして使用可能です。COPTrace::Execute2D は以下のタスクを遂行します：
• ルックアヘッド経路ポジションと、そのポジションにおける経路ディレクションを獲得します。
• 必要に応じて操作を実行します。例えば、Uターンをするために車を後進させます。
Version 1.6
34
Lumberyard 開発者ガイド
動作システム
• 以下のような点を考慮して、減速させることもできます：
• 現在の進行方向と望まれる進行方向（経路ディレクションに前述）との角度差。
• 経路のカーブの曲率。
• 経路の最終地点への接近。
• 丘の頂上への接近。
次に、後でゲームコードに追加されるAIエージェントのSOBJECTSTATE ストラクチャー
のfDesiredSpeed とvMoveDir を設定します。どのようにしてこのデータが実際のステアリングで使わ
れるかの例は、CVehicleMovementArcadeWheeled::ProcessAIを参照してください。
COPTrace::Execute2D だけがvMoveDirを設定するオペレーションではありませんのでご注意くださ
い。例えば、障害物回避コードは上書きができます。
動作システム
AI動作システムのキー優先度には次の機能があります。
• 剛性と予測可能性。ナビゲーションには不確実性があり、キャラクターがリクエストどおりの動作
を実行し、ご希望の最終仕向地に到着するかどうかの保証はありません。これは機構上の問題であ
り、明確な解決法がありません。AI動作システムは明確な情報と失敗の理由を提供し、この問題を
解決します。
• セントラルでクリアなオーナーシップと簡単なデバッグ作業。コンテキスト動作情報や、–、スタイ
ル、リクエスタなどを保持するのではなく、– は、行動切り替えが起きた際に特定のgoalopに関連
付けし、消滅します。Lumberyardは、この情報を中央のロケーションに管理し、goalopから分離し
ます。実際には、動作リクエストあらゆるところから送ることができ、動作システムが集中処理し
ます。goalopのリクエスタが権限を既に保持していない場合は、リクエストを単にキャンセルしま
す。これによって、キャラクターの動作が直ぐに停止してすべての情報が消失するわけではなく、
単にリクエストへの権限の期限が切れていることを意味します。
• 計画. In Lumberyardでは、ロジックは使いやすさと機構のためにブロック単位で処理します。動
作ブロックは、FollowPathLeaveCoverおよびUseSmartObjectといった各自単独のタスクを担いま
す。シーケンスにおけるブロックの集合体は、インプットとしての文字列パスを持つコントローラ
によって生成するプランを構成します。このタイプの機構は、今現在処理中の、そして次に起こる
プロセスについての概要を明確にしてくれます。
Note
このシステムは未だ構築段階にあり、その仕様は既存のコードベースとの重大な問題を解決
することを目的とされました。これは、すべてのゲームタイトルに当てはまるわけではあり
ません。
動作システムの利用について
動作システムの使用法は、至って分かりやすいです。仕向地、スタイルやコールバックについての情
報を持つMovementRequestオブジェクトを作成してください。動作システムにキューを行い、動作
リクエストIDを取得してください。リクエストをキャンセルしたいときも、そのIDを使用してくださ
い。動作システムがリクエストを処理するまでお待ちください。リクエストの処理が終了すると、
コールバックから通知されます。
以下に、リクエスト処理中に内部で行われていることを説明します。
1. 動作システムがリクエストを受理すると、MovementActorと呼ばれる内部のキャラクター代理を生
成します。これが、すべての内部のステートを内包するコンテイナーであり、キャラクターに関す
Version 1.6
35
Lumberyard 開発者ガイド
潜在的改善点
るすべての外部ステートやロジックに対するプロキシです。MovementControllerをMovementActor
に結合させます。現在使用可能なコントローラは、過去の処理結果である– GenericController
の一つのみとなっています。(「コントローラ」という名称は、ゲーム側でも使用されますが、
似て非なるオブジェクトに対して使用されています。そういったオブジェクトは今後統合さ
れ、Pinger、ScorcherまたはBipedCoverUsedといった複数タイプのコントローラが追加になるかも
しれません。
2. 動作システムは、処理を開始すべき新しいリクエストについてコントローラに通知しま
す。GenericControllerがパスファインダーを開始します。
3. パスファインダーの結果が出るとともに、GenericControllerは実行開始するためのプランを作成し
ます。
4. GenericControllerは計画の中の最終ブロックを終了すると、動作システムにタスクが完了したこと
を通知します。
5. 動作システムはリクエスト提出者に対して完了通知を出し、次のリクエストの処理に移ります。
潜在的改善点
以下の領域が、改善または強化の対象として検討中です。
• 変更リクエストの処理今、1件のリクエストキューが存在し、動作リクエストはFIFOルールに従っ
て1件ずつ処理されます。リクエストはイミュータブルであるので、キューに出された後リクエスト
を変更することはできません。よって、リクエストのキャンセルを行う唯一の方法は、新しいリク
エストをキューすることです。上記の問題は、リクエストキューを削除し、一度に1件のリクエスト
を処理させることで解決できます。リクエストがまだ1件処理中に新しく入力された場合、進行中の
リクエストを中断し、報告してください。
• アップデートを開始する前に、Pipeユーザーを認証してください。
• UseSmartObjectのブロックがSmartObject開始時に特定配置システムのキャラクター配置失敗を検
知した際には、エージェントのバブルとログで報告します。そして、SmartObjectの最後にキャラク
ターをテレポートすることで問題を解決し、プランにおける次のブロックに進みます。
• GenericControllerは、FollowPathブロックを実行中にのみ、新しいリクエストの処理を開始するこ
とができます。その後、Actorがプラン作成中にSmartObjectの中に自身を見出さないようにするた
め、すべての後続するブロックを削除します。こうすることで、コントローラがプランの一部を作
成し、次の処理に備え、また現在のプランで補完することができ、改善が可能となります。
• リクエストがキャンセルされたときは、プランは削除されません。「停止」「移動」リクエストが
キャンセル後に付帯するからです。しかし、このリクエストが受領されるまでは、コントローラは
処理内容を把握していない状態です。
• パスファインディングへのリクエストはPipeユーザーを介して通知され、結果もまたm_pathに保
管されると同時にPipeユーザーを通して返却されます。このパスは、その後MovementController
によって抽出されます。パスファインダーはMovementControllerが直接使用し、中間層のPipeユー
ザーを介さない方が望ましいです。
• MovementControllerコードは、キャラクターの生き方の情報がある場のゲーム側で、より良く適合
します。ゲーム側で処理される動作変遷に統合することも可能です。
• コントローラが常に既存のリクエストの処理を行っているという前提を信頼することができないた
め、いかなるときにも動作リクエストを取り出せることで、コードは多少なりとも複雑になりま
す。リクエストはそのまま維持し、キャンセルのフラグをつけてコールバックをクリアした方が良
いでしょう。
• プラン作成とプラン実行を一つではなく二つの異なるコードパスに分けることで、コードを改善す
ることができます。
自動無効化
離れた AI エージェントを更新しないことで CPU 時間を節約できます。自動無効化機能を使用し
て、AI ベースまたはグローバルに更新を管理します。
Version 1.6
36
Lumberyard 開発者ガイド
グローバルな自動無効化
グローバルな自動無効化
• すべての車両の自動無効化を制御するには: コンソール変数 v_autoDisable を使用します。
• すべての AI エージェントの自動無効化を制御するには、コンソール変数 ai_UpdateAllAlways を
使用します。
AI ごとの自動無効化
AI ごとの自動無効化は、エンティティプロパティ AutoDisable によって制御されます。AI および車両
エンティティの詳細については、『Lumberyard ユーザーガイド』を参照してください。また、ランタ
イムにこのプロパティ (および動作) を変更することもできます。
• C++: pAIActorProxy->UpdateMeAlways(true);
• Lua: AI.AutoDisable(entity.id, 1);
• フローグラフ Editor で、AI ごとに [AI:AutoDisable] をオンまたはオフに切り替えます。
AI スクリプト
トピックのこのコレクションでは、スクリプティングを使用して、主要な AI 機能を処理する方法につ
いて説明します。
このセクションでは、次のトピックについて説明します。
• コミュニケーションンシステム (p. 37)
• ファクション (p. 43)
• モジュラー動作ツリー (p. 44)
• Refpoint (p. 87)
• シグナル (p. 88)
コミュニケーションンシステム
AIコミュニケーションとはゲーム中に必要なときに音/や音声アニメーションを行うことです。
AIエージェントのコミュニケーションをセットアップするには次のステップが必要になります:
• 一般的なセットアップ
• コミュニケーションチャンネルを定義します。チャンネルはAIのコミュニケーションイベントの
ステータスをトラックするのに使用されます。
• コミュニケーションを定義する。コミュニケーションは、コミュニケーションが呼び出されると
きに、どのような（そしてどのように）アクティビティが発生するべきかを詳細に決定します。
コミュニケーションは様々な設定にグループ化されます。
• 音声ライブラリをセットアップする。音声ライブラリは、ローカライズダイアログ、字幕、リッ
プシンキングに重点を置いてしました。
• AIプロパティを使用するAIにコミュニケーションタイプを指定します:
• そのAIのコミュニケーションのセットを含めるコミュニケーション設定をAIのCommConfigのプ
ロパティに指定します。
• そのAIに使用する音声のライブラリをAIのesVoiceのプロパティを指定します。
• コミュニケーションイベントをトリガーします:
• イベントに関して通信チャンネルの名前を指定します。
• 発生する通信の名前を指定します。
Version 1.6
37
Lumberyard 開発者ガイド
コミュニケーションンシステム
コミュニケーション、チャンネル、音声ライブラリは、XMLファイル内で定義されます。ゲーム開始
時に、ディレクトリGame/Scripts/AI/Communicationとすべてのサブフォルダは、このような設
定を含むXMLファイルがあるかスキャンされます。
コミュニケーションチャンネルを定義します。
コミュニケーションチャンネルは使用状態において、指定された時刻にAIがコミュニケーションをプ
レイできるかどうかが決まります。チャンネルとは自己完結的な概念で、他のAIコミュニケーション
概念から独立しています。これらの唯一の目的は、「使用中」もしくは「使用可」のいずれの可能な
状態に落ち着くことです。
AIコミュニケーションはチャネルはGame/Scripts/AI/Communicationに収納されているXMLファ
イルで定義されます。SDKはChannelConfg.xmlと呼ばれるテンプレートチャンネル設定XMLファイ
ルを含みます。コミュニケーションチャネルは、親と子供のチャンネル階層関係で設定されます。階
層構造はチャンネルの使用中状態がどのように他のチャンネルのステータスに影響を与えるかを決定
します (例えば、使用中の子チャンネルときの親の状態) 。
チャンネルのエレメントと属性
通信チャンネルは次の属性要素<ChannelConfig>で定義されます:
name
チャンネル名。
優先度
minSilence
コミュニケーションが完了後チャネルが使用中状態であるべき最小時間 (秒単位) です。
flushSilence
フラッシュが完了した後のチャネルが使用中であるべき時間 (秒単位) 。この値は、コミュニケー
ションをプレイした後のサイレンス時間(minSilence) をオーバライドします。指定がない場合
は、minSilenceに設定された値が使用されます。
actorMinSilence
コミュニケーションを開始した後の音声ライブラリをAIエージェントがプレイすることを制限す
るための最低時間 (秒単位) です。
ignoreActorSilence
スクリプトからAIエージェントのコミュニケーションを制限することを示すフラグが無視される
べきです。
type
コミュニケーションチャンネルのタイプ。有効な値は「プライベート」、「グループ」または
「グローバル」です。
例
Game/Scripts/AI/Communication/ChannelConfig.xml
<Communications>
<ChannelConfig>
<Channel name="Global" minSilence="1.5" flushSilence="0.5"
type="global">
<Channel name="Group" minSilence="1.5" flushSilence="0.5"
type="group">
<Channel name="Search" minSilence="6.5" type="group"/>
<Channel name="Reaction" priority="2" minSilence="2"
flushSilence="0.5" type="group"/>
<Channel name="Threat" priority="4" minSilence="0.5"
flushSilence="0.5" type="group"/>
Version 1.6
38
Lumberyard 開発者ガイド
コミュニケーションンシステム
</Channel>
<Channel name="Personal" priority="1" minSilence="2"
actorMinSilence="3" type="personal"/>
</Channel>
</ChannelConfig>
</Communications>
AIコミュニケーションの設定
通信設定は、AIエージェントがどのような通信アクティビティを実行することが可能で、どのように
実現するかを決定します。特定のAIタイプのコミュニケーションは様々な設定にグループ化されま
す。例えば、ゲームには、各自の通信アクティビティをもつ人間や非人間のAIエージェントなどが存
在します。このシナリオでは、すべての人間コミュニケーションを「人間」と名前のついた設定オ
ブジェクトに分類し、非人間コミュニケーションを「非人間」設定に分類するかもしれません。特定
AIには、AIのCommConfigプロパティと使用するために設定を指定します。この設定構造を使用する
と、トリガーされた際コミュニケーションアクティビティが関連するAIに適合されるように、各設定
で様々なコミュニケーション（「surprise」など）の定義ができます。
各コミュニケーションについて、様々なバリエーションでアクションの意味を定義でき、どのように
バリエーションが使用されるか指定できます。
AIコミュニケーションチャンネルはGame/Scripts/AI/Communicationに収納されている１件以上
のXMLファイルで定義されます。SDKはBasicCommunications.xmlと呼ばれるテンプレートチャン
ネル設定XMLファイルを含みます。
通信エレメントと属性
コミュニケーションは次のエレメントと属性を使用して設定されます:
設定
通信設定は<Config>エレメントに分類され、次の属性を使います。各設定は少なくとも一つのコ
ミュニケーションを含める必要があります。
name
AIのCommConfigプロパティで参照できる設定名。
コミュニケーション
コミュニケーションは次の属性とともに<Communication>エレメントで定義されます。各コミュニ
ケーションは、少なくとも一つのバリエーションを含める必要があります。
name
コミュニケーション名
choiceMethod
バリエーションを選択するときに使用する方法。有効な値は「Random」、「Sequence」、
「RandomSequence」、「Match」などを含めます (最初のバリエーションのみを使用)。
responseName
responseChoiceMethod
choiceMethodと似ています。
forceAnimation
ブーリアン型フラグ。
バリエーション
各バリエーションは次の属性とともに<Variation>エレメントで定義されます。
Version 1.6
39
Lumberyard 開発者ガイド
コミュニケーションンシステム
animationName
グラフ アニメーション入力値。
soundName
voiceName
lookAtTarget
AIが通信中にターゲットを見るかどうかを示すブーリアン型フラグ。
finishMethod
コミュニケーションタイプの終了後やタイムインターバル後など、コミュニケーションがいつ
終了するかを判断する方法。有効な値は「animation」、「sound」、「voice」、「timeout」、
「all」などを含みます。
ブロック
通信中に無効にする AI 動作。有効な値は「movement」、「fire」、「all」、「none」を含みま
す。
animationType
有効な値には「signal」、「action」含みます。
timeout
例
Game/Scripts/AI/Communication/BasicCommunications.xml
<Communications>
<!--sound event example-->
<Config name="Welcome">
<Communication name="comm_welcome" finishMethod="sound"
blocking="none">
<Variation soundName="sounds/dialog:dialog:welcome" />
</Communication>
</Config>
<!--example showing combined animation + sound event (needs state using
action/signal in the animation graph)-->
<Config name="Surprise">
<Communication name="comm_anim" finishMethod="animation"
blocking="all" forceAnimation="1">
<Variation animationName="Surprise" soundName="sounds/
interface:player:heartbeat" />
</Communication>
</Config>
</Communications>
音声ライブラリのセットアップ
ローカライズダイアログ、字幕、リップシンキングをサポートするには、音声ライブラリを設定する
必要があります。一旦設定したら、AIのenVoiceプロパティを使ってボイスライブラリをAI（またはエ
ンティティアーケタイプ）に割り当てることができます。
音声ライブラリはGameSDK/Libs/Communication/Voiceに収納されている一連のXML Excelファイ
ル内で定義されます。SDKはGameSDK/Libs/Communication/Voice/npc_01_example.xmlのテ
ンプレート音声ライブラリファイルを含みます。
各音声のライブラリは、以下の情報を含める必要があります。
Version 1.6
40
Lumberyard 開発者ガイド
コミュニケーションンシステム
言語
このライブラリのローカリゼーションのタイプ。
ファイル パス
このライブラリのサウンドファイルを保存する場所。
通知
サウンドファイルに関連付けられるコミュニケーションの名前。
サウンド ファイル
信号によってリスト化されるサウンドファイルのファイル名。
例
サウンドファイルを記述または説明するのに使用するコメント欄。
例
GameSDK/Libs/Communication/Voice/npc_01_example.xml
言語
アメリカ英語
ファイル パス
languages/dialog/ai_npc_01/
通知
サウンド ファイル
SDK NPC 01 Example
see_player_00
見えたよ
see_player_01
いるじゃん
see_player_02
ずっと探してたよ
pain_01
痛い
pain_02
痛い
pain
痛い
death_01
あーーーーー
death_02
あーーーーー
death_03
あーーーーー
alerted_00
watch_out
alerted_01
気をつけて
alerted_02
何かある
「」を参照してください
pain
death
alerted
AIコミュニケーションの設定
AIコミュニケーションの方法はAIエージェントのプロパティを使用して設定されます。さまざまな方
法でAIプロパティを設定できます。Lumberyard エディタの使用してAIプロパティを設定するための情
Version 1.6
41
Lumberyard 開発者ガイド
コミュニケーションンシステム
報については、Lumberyardのユーザーガイドにある"Using Database View to Set AI Communication"
をご覧ください。
以下のパラメータを設定します。
• CommConfig – このAIに使用してほしいコミュニケーション設定の名前にこのプロパティ
を設定します。コミュニケーション設定はエレメントを使用してGame/Scripts/AI/
Communication<Config>のXMLファイル内で定義されます。
• esVoice – このAIに使用してほしい音声ライブラリを含むXMLファイル名にプロパティを設定しま
す。音声ライブラリはGameSDK/Libs/Communication/VoiceのXMLファイル内で定義されま
す。
アニメーションおよびボイスをオフにする
コミュニケーションアニメーションや音声は、エージェントのLuaスクリプト（下の例に示すよう
な）もしくはLumberyard エディタ エディターのエンティティプロパティを使用するAIエージェント
に対してオフにします。
例
Game/Scripts/Entities/AI/Shared/BasicAITable.lua
Readability =
{
bIgnoreAnimations = 0,
bIgnoreVoice = 0,
},
コミュニケーションイベントをトリガーする:
通信のイベントがトリガーするには、次の属性とともにgoalopcommunicateを使用します。AIが現在
スマートオブジェクトアクションをプレイしている場合、コミュニケーションアニメーションはプレ
イされないことに注意してください。
name
トリガーするコミュニケーションの名前 (音や音声やアニメーション) 。通信AIの名前は、このAI
のCommConfigのプロパティによって参照されるXMLファイル内で定義されます。
チャンネル
このAIによって使用されるコミュニケーションチャンネル。AIのコミュニケーションチャネル
はGame/Scripts/AI/CommunicationのXMLファイル内で定義されます。
有効期限(expiry)
コミュニケーションチャンネルが一時的に使用中のときにコミュニケーションをトリガーするの
に許容される最大遅滞。コミュニケーションがこの期間内にトリガーすることができない場合は
破棄されます。
フローグラフロジックを使用して通信をトリガーするには、フローグラフnodeAI:Communicationを使
用します。
例
<GoalPipe name="Cover2_Communicate">
<Communicate name="comm_welcome" channel="Search" expirity="0.5"/>
</GoalPipe>
Version 1.6
42
Lumberyard 開発者ガイド
ファクション
デバッグ
AIコミュニケーション問題のデバッグ情報を取得するには、以下のコンソール変数を使用します
(ai_DebugDraw「1」に設定する必要があります) :
• ai_DebugDrawCommunication
• ai_DebugDrawCommunicationHistoryDepth
• ai_RecordCommunicationStats
デバッグ出力はここに説明されるコンソールに示されます:
Playing communication: comm_welcome[3007966447] as playID[84]
CommunicationPlayer::PlayState: All finished! commID[-1287000849]
CommunicationManager::OnCommunicationFinished: comm_welcome[3007966447] as
playID[84]
CommunicationPlayer removed finished: comm_welcome[3007966447] as playID[84]
with listener[20788600]
トラブルシューティング
[Warning] Communicate(77) [Friendly.Norm_Rifle1] Communication failed to start
コミュニケーション設定が適切に設定されていないのにAIの行動ツリーがコミュニケーションをコー
ルしている場合は、このようなメッセージか類似したものを受け取ります。このメッセージ例では、
「77」はAI行動ツリースクリプトの77行目を示します (またはgoalopスクリプト) 。このラインはおそ
らくこのようなコミュニケーショントリガーです:
<Communicate name="TargetSpottedWhileSearching" channel="Reaction"
expirity="1.0" waitUntilFinished="0" />
確認すべき事項::
• 指定コミュニケーション名「TargetSpottedWhileSearching」はコミュニケーション設定ファイルに
存在しますか？(Game/Scripts/AI/Communication/内のXMLファイル)
• AIに対するCommConfig プロパティを確認します。これはコミュニケーション設定ファ
イルで定義された<Config>エレメントの名前ですか？その場合、コミュニケーション名
「TargetSpottedWhileSearching」はこの<Config>エレメント内で定義されましたか？AIに設定さ
れていないコミュニケーションへのコールの問題はよくあるエラーです。
• コミュニケーションのバリエーション定義を確認します。これは、存在するリソース (アニメーショ
ン、音) を指定しますか？音声のライブラリを使用している場合、有効なライブラリの音声ファイル
名を指定しますか。
ファクション
AI エージェントは、他の AI エージェントに遭遇したときの動作を決定するためにファクションを使
用します。動作のベースセット (中立、友好的、敵対など) があります。たとえば、"Grunt" 派閥の AI
が "プレイヤ" 派閥の AI に遭遇した場合、その遭遇は敵対になります。"一般市民" に遭遇したプレイ
ヤは「友好的」になります。
派閥情報をセットアップする方法
• ゲーム内のすべての派閥とそれらの相互の反応を定義する XML ファイルを作成します (例を参照)。
このファイルは \Games\Scripts\AI\ に配置する必要があります。SDK には派閥のテンプレート
XML ファイル Factions.xml が含まれています。
Version 1.6
43
Lumberyard 開発者ガイド
モジュラー動作ツリー
• すべての AI エージェントの派閥プロパティを、定義済みのいずれかの派閥に設定します。フローグ
ラフを使用して派閥を設定することもできます。
例: 派閥のセットアップ
Factions.xml
<Factions>
<Faction name="Players">
<Reaction faction="Grunts" reaction="hostile" />
<Reaction faction="Civilians" reaction="friendly" />
<Reaction faction="Assassins" reaction="hostile" />
</Faction>
<Faction name="Grunts">
<Reaction faction="Players" reaction="hostile" />
<Reaction faction="Civilians" reaction="neutral" />
<Reaction faction="Assassins" reaction="hostile" />
</Faction>
<Faction name="Assassins">
<Reaction faction="Players" reaction="hostile" />
<Reaction faction="Civilians" reaction="hostile" />
<Reaction faction="Grunts" reaction="hostile" />
</Faction>
<Faction name="HostileOnlyWithPlayers" default="neutral">
<Reaction faction="Players" reaction="hostile" />
</Faction>
<Faction name="Civilians" default="neutral" />
<Faction name="WildLife" default="neutral" />
</Factions>
モジュラー動作ツリー
モジュラー動作ツリー (MBT) は、ゲームで人工知能 (AI) エージェントの動作を作成する概念のコレク
ションです。MBT では、C++ やその他の汎用プログラミング言語で複雑なコードを記述する代わり
に、ポインター、メモリ、コンパイラーなどのしくみを考えることなく、高いレベルで AI の動作を記
述することができます。MBT の概念および実装は、迅速なイテレーションと再利用に最適化されてい
ます。
重要な概念
概念的には、MBT はノードおよびツリーという 2 つの主要オブジェクトに基づいています。
ノード
ノードは最も基本的な概念であり、その他の要素と組み合わせて動作を構築するための構成要素
です。ノードは単純なタスクを表すコードブロックで構成されます。すべてのノードには同じイ
ンターフェイスがあります。これらは、処理されるとタスクを実行し、成功または失敗します。
ノードはスタンドアロンノードとするか、子ノードを持つことができます。子ノードは親ノード
処理の一部として処理されます。親ノードが処理に成功するかどうかは、多くの場合、それぞれ
の子ノードの成功に依存します (ただし、常にそうであるとは限りません)。
ノードは、アクションノード、複合ノード、デコレータノードなど、いくつかの共通パターンに
従います。これらの共通ノードパターンについては、後で詳しく説明します。
ゲーム開発者は、ゲームに必要なノードを作成できます。また、Lumberyard には一般的に使用
できる一連の標準ノードが備わっています。これらには、AI、アニメーション、飛行、一般的な
ゲームのアクティビティに関連するタスクと、タイムアウトやルーピングタスクなど、動作を構
Version 1.6
44
Lumberyard 開発者ガイド
モジュラー動作ツリー
築するときに役立つ汎用ノードが含まれています。用意されているこれらのノードについては、
「モジュラー動作ツリーノードのリファレンス (p. 54)」で説明しています。
ツリー
動作は、リーフに伸びるブランチとともにルートとして位置付けられた場合に、入力に応じた AI
エージェントの動作を定義するノードのツリー、個別のタスクのコレクションによって構築され
ます。
一般的なノードパターン
アクションノード
アクションノードは、何らかのシンプルなアクションを表します。たとえば、アクションノードに
よって AI エージェントは話す、アニメーションを再生する、別の場所に移動することができます。
複合ノード
複合ノードは、特定の順序で実行する一連のアクションを表します。複合ノードは親ノードと複数の
子ノードで構成されます。子ノードが処理されるかどうか (およびその順序) を、前に処理されたノー
ドの成功または失敗に応じて決定することができます。一般的な複合パターンには、シーケンシャ
ル、セレクタ、および並列があります。
シーケンシャルノード
この複合パターンは、指定されたシーケンスで連続して処理される子ノードを示します。すべて
の子ノードは、前の子ノードが成功したか失敗したかに関係なく処理されます。たとえば、シー
ケンシャルノードで、AI モンスターはプレーヤーを指さし、吠え、プレーヤーに向かって走り出
すとします。このパターンでは、次の子ノードが処理を開始するには、シーケンスのそれぞれの
子ノードが成功する必要があります。いずれかの子ノードが失敗した場合、親ノードはすぐに失
敗し、処理は停止します。
セレクタノード
この複合パターンは、連続して処理され、1 つが成功するまで順に処理される子ノードを示しま
す。1 つの子ノードが成功するとすぐに親ノードが成功し、子ノードの処理を停止します。すべ
ての子ノードを試み、すべてが失敗した場合、親ノードは失敗します。このパターンは、複数の
異なる方法を試みるよう AI エージェントを設定するか、予期しない結果を処理するフォールバッ
ク動作を作成する場合に役立ちます。
たとえば、AI モンスターがプレーヤーを追いかけたが追い付けない場合に「私と勝負しろ、この
臆病者!」と叫ぶようにするとします。このシナリオを実装するには、セレクタ親ノードを 2 つの
子とともに (可能なアクションごとに 1 つずつ) 設定します。親ノードは最初に "chase player" 子
ノードを処理します。それが成功すると、セレクタノードがそこで停止します。ただし、"chase
player" ノードが失敗すると、親ノードは続行し、"taunt player" 子ノードを処理します。
Version 1.6
45
Lumberyard 開発者ガイド
モジュラー動作ツリー
並列ノード
この複合パターンは、同時に処理される子ノードを示します。このシナリオでは、AI モンスター
が交互にではなく、叫ぶと同時にプレーヤーを追いかけるとします。
デコレータノード
デコレータノードは、別のノードに追加し、他のノードの動作や処理にかかわらず動作できる何らか
の機能を表します。一般的なデコレータ機能には、ルーピングおよび同時制限の機能が含まれます。
ループ
ループ機能は、他のノードを複数回処理するために使用できます。タスクを繰り返すたびに毎回
カスタムノードを作成するのではなく、親ループデコレータノードで、任意のノードをラップで
きます。ループノードのパラメーターを設定することにより、子ノードを処理する回数を指定で
きます。子ノードが成功するたびに、ループノードのカウントは更新され、子ノードが再処理さ
れます。ループカウントが設定されたパラメーターを満たすと、ノードループは成功します。
同時ユーザーの制限
この機能では、指定したノードを何人のユーザーが同時に使用することができるかを指定できま
す。これは。AI エージェントのグループ内で動作のバリエーションを確実にするための良い方法
です。この機能について説明する一般的なシナリオは次のとおりです。プレーヤーは 3 匹のモン
スターのグループによって発見されます。1 匹のモンスターがアラーム音を鳴らし、2 匹のモンス
ターがプレーヤーを追いかけるとします。
同時ユーザーの制限は、1 つが成功するまで子ノードのシーケンスを進むセレクターノードで機
能します。制限デコレータノードでセレクタノードの子ノードの 1 つをラップすることで、子
ノードは同時ユーザーにより失敗し、それによりセレクタノードは次の子に移動することができ
ます。
説明したシナリオに対応するため、セレクタノードは 2 つの子ノード "sound alarm" と "chase
player" を持ちます。"sound alarm" ノードは制限ノードでラップされ、ユーザー制限は 1 に設定
されます。モンスター #1 はセレクタノードから制限ノードに移ります。"sound alarm" ノードを
同時に使用しているモンスターがいないため、モンスター #1 がこのアクションを実行します。1
つの AI エージェントが子ノードを処理中であることを制限ノードが記録するため、そのドアを
実質的にロックします。モンスター #2 と #3 も、セレクタノードから制限ノードに移りますが、
制限ノードがユーザーの制限に達したため、失敗が報告されます。その結果、セレクタノードは
Version 1.6
46
Lumberyard 開発者ガイド
モジュラー動作ツリー
シーケンスの次の子ノード ("chase player") に移行します。したがって、モンスター #2 と #3 が
プレーヤーを追いかけます。
XML での動作ツリーの記述
動作ツリーは、XML Markup Language を使用して記述します。動作ツリーは、エディタでユーザー
がゲームにジャンプするたびにホットロードされます。
次の XML の例は、モンスターのグループの動作ツリーを示しています。この例では、一度に 1 匹の
モンスターのみがプレーヤーを追いかけることができます。残りのモンスターは何もせずに立ってい
て、プレーヤーをなじります。
<BehaviorTree>
<Root>
<Selector>
<LimitConcurrentUsers max=”1”>
<ChasePlayer />
</LimitConcurrentUsers>
<TauntPlayer />
</Selector>
</Root>
</BehaviorTree>
C++ の実装
すべての MBT コードは、BehaviorTree 名前空間にカプセル化されています。
メモリモデルについて
MBT のメモリフットプリントは比較的小さくなっています。これは、(1) ツリーのインスタンス間の
変更不可能な (読み取り専用) データの共有、および (2) 現在の状況で必要なもののみへのメモリの割
り当てによって達成されます。
メモリは 2 つのカテゴリ (設定データおよびランタイムデータ) に分類されます。さらに、MBT はス
マートポインタを使用します。
設定データ
次の例のような動作ツリーをロードすると、例に示すようなすべての設定データを保持する動作ツ
リーテンプレートが作成されます。これには 4 つの子ノードを持つシーケンスノードが含まれます (2
つの通信ノード、アニメーションノード、および待機ノード)。設定データはアニメーション名、期間
などで、このデータは変更されません。
<Sequence>
<Communicate name=”Hello” />
<Animate name=”LookAround” />
<Wait duration=”2.0” />
<Communicate name=”WeShouldGetSomeFood” />
</Sequence>
Version 1.6
47
Lumberyard 開発者ガイド
モジュラー動作ツリー
設定データのメモリはレベルヒープから割り当てられます。ランチャーを介してゲームを実行する
場合、このメモリはレベルのアンロードで解放されます。または、プレーヤーがゲームモードを終了
し、Lumberyard Editor で編集モードに戻ると解放されます。
ランタイムデータ
動作ツリーを使用して AI エージェントをスポーンすると、運用ツリーインスタンスが作成され、エー
ジェントと関連付けられます。インスタンスは標準設定データについて動作ツリーテンプレートを指
します。つまり、インスタンスには変数やタイムスタンプなどインスタンス固有のデータのみが含ま
れます。
AI エージェントについてツリーインスタンスがアクセスされると、シーケンスノードを実行して開始
されます。コアシステムにより、これがこの AI エージェントに対して実行された最初の動作であるこ
とが検出されると、このノードおよびエージェント用にランタイムデータオブジェクトが割り当てら
れます。つまり、動作ツリーノードを実行するときに、すべての AI エージェントが独自のランタイ
ムデータオブジェクトを取得します。ランタイムデータオブジェクトは、AI エージェントがノードを
実行している限り保持されますが (これは複数のフレームである場合があります)、AI エージェントが
ノードを離れると解放されます。
ランタイムデータのメモリは、バケットアロケーターから割り当てられます。この設計によりメモリ
の断片化が最小化されます。メモリの断片化が発生するのは、通常ランタイムデータはわずか数バイ
トで、頻繁に割り当てられ、解放されることが原因です。バケットアロケーターはレベルのアンロー
ド時にクリーンアップされます。
スマートポインタ
MBT は Boost スマートポインタを使用してデータを安全に引き渡し、可能な限り raw ポインタを避
けます。メモリ管理システムはコアシステムによって処理されます (C++11 の unique_ptr が適してい
る状況もありますが、Lumberyard では互換性の理由から Boost の shared_ptr が使用されます)。
MBT ノードの実装
C++ で新しい MBT ノードを実装するには、次のタスクを実行する必要があります。
• ノードを作成します
• ノードファクトリにノードを公開します
• ノードのエラーレポートを設定します
ノードの作成
次のコード例は、動作ツリーノードをプログラムで作成する方法を示しています。新規ノードに名前
を付ける場合は、「推奨の命名方法 (p. 54)」を参照してください。
#include <BehaviorTree/Node.h>
class MyNode : public BehaviorTree::Node
{
typedef BehaviorTree::Node BaseClass;
public:
// Every instance of a node in a tree for an AI agent will have a
// runtime data object. This data persists from when the node
// is visited until it is left.
//
// If this struct is left out, the code won't compile.
// This would contain variables like 'bestPostureID', 'shotsFired' etc.
struct RuntimeData
{
};
Version 1.6
48
Lumberyard 開発者ガイド
モジュラー動作ツリー
MyNode() : m_speed(0.0f)
{
}
// This is where you'll load the configuration data from the XML file
// into members of the node. They can only be written to during the
loading phase
// and are conceptually immutable (read-only) once the game is running.
virtual LoadResult LoadFromXml(const XmlNodeRef& xml, const LoadContext&
context)
{
if (BaseClass::LoadFromXml(xml, context) == LoadFailure)
return LoadFailure;
xml->getAttr("speed", m_speed);
return LoadSuccess;
}
protected:
// Called right before the first update
virtual void OnInitialize(const UpdateContext& context)
{
BaseClass::OnInitialize(context);
// Optional: access runtime data like this
RuntimeData& runtimeData = GetRuntimeData<RuntimeData>(context);
}
// Called when the node is terminated
virtual void OnTerminate(const UpdateContext& context)
{
BaseClass::OnTerminate(context);
// Optional: access runtime data like this
RuntimeData& runtimeData = GetRuntimeData<RuntimeData>(context);
}
virtual Status Update(const UpdateContext& context)
{
// Perform your update code and report back whether the
// node succeeded, failed or is running and needs more
// time to carry out its task.
// Optional: access runtime data like this
RuntimeData& runtimeData = GetRuntimeData<RuntimeData>(context);
return Success;
}
// Handle any incoming events sent to this node
virtual void HandleEvent(const EventContext& context, const Event& event)
{
// Optional: access runtime data like this
RuntimeData& runtimeData = GetRuntimeData<RuntimeData>(context);
}
private:
// Store any configuration data for the node right here.
// This would be immutable things like 'maxSpeed', 'duration',
// 'threshold', 'impulsePower', 'soundName', etc.
Version 1.6
49
Lumberyard 開発者ガイド
モジュラー動作ツリー
float m_speed;
};
// Generate an object specialized to create a node of your type upon
// request by the node factory. The macro drops a global variable here.
GenerateBehaviorTreeNodeCreator(MyNode);
ノードの公開
新しく作成したノードを使用するには、次のコードスニペットに示すように、ノードファクトリに公
開する必要があります。
BehaviorTree::INodeFactory& factory = gEnv->pAISystem>GetIBehaviorTreeManager()->GetNodeFactory();
ExposeBehaviorTreeNodeToFactory(factory, MyNode);
エラーレポートの設定
クラス ErrorReporter を使用して、新しいノードのエラーと警告を報告します。これは printf 形式
のメッセージを記録し、XML の行番号、ツリー名、ノードタイプなど、ノードに関して利用できる情
報を自動的に含めます。
ErrorReporter(*this, context).LogError("Failed to compile Lua code '%s'",
code.c_str());
変数
XML で変数が静的に宣言され、AI エージェントからのシグナルに応じてどのように変わるかに関する
情報が含まれます (AI システム内の名前付きテキストメッセージ)。
次のコードスニペットは、AI システムから入力を受け取る変数の使用を示しています。この例で
は、AI エージェントはターゲットが「見える」かどうかに応じてアクションを実行します。
<BehaviorTree>
<Variables>
<Variable name="TargetVisible" />
</Variables>
<SignalVariables>
<Signal name="OnEnemySeen" variable="TargetVisible" value="true" />
<Signal name="OnLostSightOfTarget" variable="TargetVisible"
value="false" />
</SignalVariables>
<Root>
<Selector>
<IfCondition condition=”TargetVisible”>
<Move to=”Target” />
</IfCondition>
<Animate name=”LookAroundForTarget” />
</Selector>
</Root>
</BehaviorTree>
Lua スクリプト
Lua コードは動作ツリーに埋め込み、ツリーノードで実行できます。これは、ファイアアンドフォー
ゲットコードを実行したり、ツリーの流れを制御したりするために役立ちます。また、新しいノード
を作成することなく機能を作成または拡張するために有効です。
Version 1.6
50
Lumberyard 開発者ガイド
モジュラー動作ツリー
コードは、純粋なゲームでレベルがロードされるとコンパイルされ、断片化を減らします。そのレベ
ルで実際に使用される動作ツリーのコードのみがコンパイルされます。
すべての Lua ノードでは entity 変数へのアクセスが許可されます。
• ExecuteLua は Lua コードを実行し、常に成功します。
<ExecuteLua code=”DoSomething()” />
• LuaWrapper は実行中の子ノードの前後に Lua コードを挿入します。ノード後のコードは、子ノー
ドが成功したか失敗したかに関係なく実行されます。
<LuaWrapper onEnter=”StartParticleEffect()” onExit=”StopParticleEffect()”>
<Move to=”Cover” />
</LuaWrapper>
• LuaGate は Lua コードを使用して、子ノードを実行するかどうかを制御します。Lua コードが true
を返す場合、子ノードが実行され、LuaGate は子ノードのステータス (成功または失敗) を返しま
す。コードが false を返すか実行に失敗した場合、子ノードは実行されず、LuaGate は失敗を返し
ます。
<LuaGate code=”return IsAppleGreen()”>
<EatApple />
</LuaGate>
• AssertLua では、ステートメントを作成することができます。ステートメントが true の場合は
ノードが成功し、false の場合はノードが失敗します。
<Sequence>
<AssertLua code=”return entity.someCounter == 75” />
<AssertCondition condition=”TargetVisible” />
<Move to=”Target” />
</Sequence>
タイムスタンプ
タイムスタンプは、イベントが発生した時点を識別します。多くの AI の動作は特定のイベントのタイ
ムスタンプの追跡に依存し、それらの時点からの時間を測定します。たとえば、AI エージェントが最
後に打たれてからの時間、プレーヤーを最後に見てから経過した時間、現在のカバー場所に移動して
からの時間などに動作を結び付ける場合に便利です。
タイムスタンプは、相互に排他的であると宣言できます。この場合、両方のタイムスタンプが同時に
同じ値を持つことはできません。たとえば、AI エージェントがプレーヤーを見ることができず、同時
にプレーヤーがいなくなったと考えるため、TargetSpotted と TargetLost の両方が値を持つこと
ができます。専用タイムスタンプの場合、1 つのタイムスタンプに値が書き込まれた場合、もう 1 つ
のタイムスタンプは自動的にクリアされます。
次のコードスニペットは、タイムスタンプの使用を示しています。
<BehaviorTree>
<Timestamps>
<Timestamp name="TargetSpotted" setOnEvent="OnEnemySeen" />
<Timestamp name="ReceivedDamage" setOnEvent="OnEnemyDamage" />
<Timestamp name="GroupMemberDied" setOnEvent="GroupMemberDied" />
</Timestamps>
<Root>
Version 1.6
51
Lumberyard 開発者ガイド
モジュラー動作ツリー
<Sequence>
<WaitUntilTime since=”ReceivedDamage” isMoreThan=”5”
orNeverBeenSet=”1” />
<Selector>
<IfTime since="GroupMemberDied" isLessThan=”10”>
<MoveCautiouslyTowardsTarget />
</IfTime>
<MoveConfidentallyTowardsTarget />
</Selector>
</Sequence>
</Root>
</BehaviorTree>
イベント
AI エージェントとの通信は AI シグナルを使用して行われます。これは基本的に名前が付けられたテ
キストメッセージです。OnBulletRain や OnEnemySeen などのシグナルは特定のイベントを伝えま
す。これは、他の AI エージェントにブロードキャストされた場合、各 AI エージェントの動作ツリー
に基づいて対応できます。この設計により、AI シグナルに疎結合された AI 動作のみが残ることがで
きます。AI シグナルは取得され MBT イベントに変換されてから、ルートノードにディスパッチされ
ます。ルートノードにより、シグナルはツリーで実行中のノードに渡されます。
<Sequence>
<WaitForEvent name=”OnEnemySeen” />
<Communicate name=”ThereHeIs” />
</Sequence>
デバッグおよびツリーの視覚化
このセクションでは、デバッグ中にツリーの視覚化ビューを提供して、動作ツリーのデバッグを支援
します。このビューでは、ゲームの進行状況としてツリーを介して AI エージェントの進行状況を追跡
できます。
エージェントの「スラッシュ」
この機能では、特定の AI エージェントの動作ツリーを DebugDraw で表示できます。この機能を有効
にするには:
1. ai_DebugDraw を 0 または 1 に設定します (デフォルトは -1)。
2. 動作ツリーを表示する AI エージェントを選択します。
• 選択された AI エージェントをカメラビューの中央に置き、テンキーの / キーを押します。
• "ai_DebugAgent closest" を呼び出して、カメラに最も近いエージェントを選択します。
• "ai_DebugAgent centerview" を呼び出して、カメラビューの中央に最も近いエージェントを選択
します (スラッシュと同じ)。
• "ai_DebugAgent <AgentName>" を呼び出して、名前で特定のエージェントを選択します。
• パラメーターなしで "ai_DebugAgent" を呼び出して、ツリーの視覚化を削除します。
ツリーの視覚化で、画面の上部に AI エージェントの名前が表示され、小さい緑の点によって画面
でエージェントが識別されます。ツリーノードは次のように表示され、カラーコーディングされま
す。XML ファイルの行番号が左に表示されます。
• 白 – カスタムデータを持つノード
• 青 – デバッグ時にしばしば特殊な重み付けを持つリーフノード
• グレー – 他のすべてのノード
Version 1.6
52
Lumberyard 開発者ガイド
モジュラー動作ツリー
カスタムデバッグテキストの追加
ツリーの視覚化はカスタムノード情報をサポートします。これにより、動作ツリーで現在実行中の部
分をより詳細に表示することができます。たとえば、WaitForEvent ノードが待機中のイベント名、
タイムアウトまでに Timeout が実行される時間などを表示できます。
この機能を使用するには、次のように GetDebugTextForVisualizer を上書きします。
#ifdef STORE_INFORMATION_FOR_BEHAVIOR_TREE_VISUALIZER
virtual void GetDebugTextForVisualizer(
const UpdateContext& updateContext,
stack_string& debugText) const
{
debugText.Format("Speed %f", m_speed);
}
#endif
ログと追跡
ログメッセージの追跡は、問題を診断するための重要なツールです。Lumberyard は、次のコードスニ
ペットに示すように、ログ作成のネイティブサポートを提供します。
<Sequence>
<QueryTPS name="CoverFromTarget" _startLog="Finding cover"
_failureLog="Failed to find cover" />
<Move to="Cover" _startLog="Advancing" _failureLog="Failed to advance"
_successLog="Advanced" />
</Sequence>
(予約属性 _startLog、_successLog、_failureLog は自動的に読み込まれます。)
ログメッセージは、BehaviorTree::ILogRouter インターフェイスから生成されるオブジェクトを
介してルーティングされます。これにより、ログメッセージが終了する場所を判断できます。たとえ
ば、1 つのオプションとして、個人ログに情報をルーティングし、各 AI エージェントのログメッセー
ジの短い履歴を保存します。この方法では、AI エージェントのツリーの視覚化の一部としてデバッグ
するときに、ログメッセージを表示できます。
AI Recorder はすべてのログメッセージも保持します、このツールを使用して、イベントのシーケンス
を調べます。
デバッグ情報を使用したコンパイル
デバッグ情報を使用してゲームをコンパイルするには、DEBUG_MODULAR_BEHAVIOR_TREE を定
義する必要があります。
#if !defined(_RELEASE) && (defined(WIN32) || defined(WIN64))
# define DEBUG_MODULAR_BEHAVIOR_TREE
#endif
完了したツリーの表示
動作ツリーが実行を終了すると (ルートノード全体を通じた失敗または成功)、最近アクセスしたノー
ドと行番号のリストとともにコンソールウィンドウに通知が表示されます。
[Error] Modular Behavior Tree: The root node for entity 'HumanSoldier' FAILED. Rebooting the tree
next frame. (124) Move. (122) Selector. (121) Sequence.
Version 1.6
53
Lumberyard 開発者ガイド
モジュラー動作ツリー
上記の例で、ツリーは次のフレームで再起動されることに注意してください。これは、動作ツリーが
この時点でエラーを処理するように設計されていないことを示します。
推奨の命名方法
次の推奨事項は、コードの明快さと開発チームのコミュニケーションを合理化するうえで有効です。
ノードの命名
アクションノードの場合、ノードで実行するアクションを識別する名前を使用します。通常、これら
はアクション動詞です。
良い
• Loop
• Animate
• LimitConcurrentUsers
• ExecuteLua
• Shoot
• AdjustCoverStance
不良
• 高速
• PathPredictor
• バナナ
• Script
• ActivationProcess
タイムスタンプの命名
タイムスタンプは、関連するイベントに基づいて命名します。タイムスタンプはすでに発生している
イベントを示すため、過去形 (TargetSpots ではなく TargetSpotted) を使用します。
• TargetSpotted
• ReceivedDamage
• GroupMemberDied
モジュラー動作ツリーノードのリファレンス
このセクションには、モジュラー動作ツリー (MBT) ノードタイプのリファレンス情報が含まれていま
す。MBT ノードタイプは、定義されているシステムに基づいてここにまとめています。
MBT ノードは Lumberyard コードのどこからでも公開できます。ノードは、その実行の動作を設定
するパラメータを持つことができます。無効な値がノードに渡されると、そのノードでの解析が失敗
し、Editor.log または Game.log にエラーメッセージが書き込まれます。
ノードインデックス
汎用ノード (p. 56)
• Loop (p. 56)
• LoopUntilSuccess (p. 57)
Version 1.6
54
Lumberyard 開発者ガイド
モジュラー動作ツリー
• Parallel (p. 57)
• Selector (p. 58)
• Sequence (p. 58)
• StateMachine (p. 58)
• State & Transitions (p. 59)
• SuppressFailure (p. 60)
• タイムアウト (p. 60)
• Wait (p. 60)
AIノード (p. 61)
• アジャストカバースタンス (p. 61)
• 目的 (p. 61)
• マシンガンを使用し、周りを狙う (p. 62)
• アニメ化 (p. 62)
• アニメーションタグラッパー (p. 62)
• アサートコンディション (p. 63)
• アサートLua (p. 63)
• アサート時間 (p. 63)
• バブル (p. 64)
• ターゲットへ到達できるかの確認 (p. 64)
• クリアターゲット (p. 65)
• コミュニケート (p. 65)
• Luaを実行する (p. 66)
• グループスコープ (p. 66)
• コンディションの場合 (p. 66)
• 時間の場合 (p. 67)
• ログ (p. 67)
• 見る (p. 67)
• Luaゲート (p. 68)
• Luaラッパー (p. 68)
• モニターコンディション (p. 69)
• 移動 (p. 69)
• 優先順位とケース (p. 70)
• 脅威レベルの引き下げ (p. 71)
• クエリTPS (p. 71)
• ランダムゲート (p. 72)
• トランジション信号の送信 (p. 72)
• 警戒度の設定 (p. 72)
• 銃撃 (p. 73)
• 隠れ場所からの銃撃 (p. 74)
• 通知 (p. 74)
• スマートオブジェクト状態ラッパー (p. 75)
• 体勢 (p. 75)
• 動き停止 (p. 75)
• テレポート (p. 76)
Version 1.6
55
Lumberyard 開発者ガイド
モジュラー動作ツリー
• 手榴弾を投げる (p. 76)
• 時間まで待機 (p. 77)
CryAction ノード (p. 77)
• AnimateFragment (p. 77)
ゲームノード (p. 78)
• InflateAgentCollisionRadiusUsingPhysicsTrick (p. 78)
• KeepTargetAtADistance (p. 78)
• 近接攻撃 (p. 79)
• ScorcherDeploy (p. 80)
• SuppressHitReactions (p. 81)
飛行ノード (p. 82)
• Hover (p. 82)
• FlyShoot (p. 82)
• WaitAlignedWithAttentionTarget (p. 82)
• Fly (p. 83)
• FlyForceAttentionTarget (p. 84)
• FlyAimAtCombatTarget (p. 84)
• HeavyShootMortar (p. 85)
• SquadScope (p. 85)
• SendSquadEvent (p. 86)
• IfSquadCount (p. 86)
汎用ノード
これらのノードは、MBT の基本的な機能を提供します。
Loop
単一の子ノードを指定された回数実行するか、失敗するまで実行します。
パラメーター
count
子ノードを実行する最大回数です。空白のままにすると、無限と仮定され、失敗するまでノード
が連続して実行されます。
成功/失敗
最大回数まで繰り返すことができれば、ノードは成功です。子ノードが失敗すると、ノードは失敗で
す。
例
<Loop count="3">
<SomeChildNode />
Version 1.6
56
Lumberyard 開発者ガイド
モジュラー動作ツリー
</Loop>
LoopUntilSuccess
子ノードを指定された回数実行するか、子ノードが成功するまで実行します。
パラメーター
attemptCount
子ノードを実行する最大回数です。空白のまま、または <=0 以下の値に設定すると、無限と仮定
され、成功するまでノードが連続して実行されます。
成功/失敗
子ノードが成功すれば、ノードは成功です。最大許容試行回数まで到達すると、ノードは失敗です。
例
<LoopUntilSuccess attemptCount="5">
<SomeChildNode />
</LoopUntilSuccess>
Parallel
子ノードを並列に実行します。
Note
• 最大 32 個の子ノードを実行できます。
• 成功および失敗限度に同時に到達した場合は、ノードは成功します。
パラメーター
failureMode
ノードがいつ失敗したかを評価する場合に使用する方法です。許容値は、"any" または "all" で
す。デフォルトは "any" です。
successMode
ノードがいつ成功したかを評価する場合に使用する方法です。許容値は、"any" または "all" で
す。デフォルトは "all" です。
成功/失敗
successMode が "all" に設定されている場合、すべての子ノードが成功すれば、ノードは成功です。
successMode が "any" に設定されている場合、いずれかの子ノードが成功すれば、ノードは成功で
す。
failureMode が "any" に設定されている場合、いずれかの子ノードが失敗すると、ノードは失敗で
す。
failureMode が "all" に設定されている場合、すべての子ノードが失敗すると、ノードは失敗です。
例
<Parallel successMode="any" failureMode="all">
<SomeChildNode1 />
Version 1.6
57
Lumberyard 開発者ガイド
モジュラー動作ツリー
<SomeChildNode2 />
<SomeChildNode3 />
</Parallel>
Selector
子ノードを一度に 1 つずつ連続して実行し、最初に成功したところで停止します。
パラメーター
なし.
成功/失敗
ノードが子ノードを順番に実行し、いずれかの子ノードが成功した時点で、ノードは成功です。ノー
ドが成功すると、それ以降の子ノードは実行されません。すべての子ノードが失敗すると、ノードは
失敗です。
例
<Selector>
<SomeChildNode1 />
<SomeChildNode2ToExecuteIfSomeChildNode1Fails />
<SomeChildNode3ToExecuteIfSomeChildNode2Fails />
</Selector>
Sequence
子ノードを一度に 1 つずつ順番に実行します。
Note
最大 255 個の子ノードを実行できます。
パラメーター
なし.
成功/失敗
すべての子ノードが成功すれば、ノードは成功です。いずれかの子ノードが失敗すると、ノードは失
敗です。
例
<Sequence>
<SomeChildNode1 />
<SomeChildNode2 />
<SomeChildNode3 />
</Sequence>
StateMachine
State タイプの子ノードを一度に 1 つずつ実行します。定義された最初の子ノードが最初に実行され
ます。StateMachine ノードの現在の状態は、現在実行されている子ノードの状態と同じになります。
パラメーター
なし.
Version 1.6
58
Lumberyard 開発者ガイド
モジュラー動作ツリー
成功/失敗
現在の状態の子ノードが成功すれば、ノードは成功です。現在の状態の子ノードが失敗すると、ノー
ドは失敗です。
例
<StateMachine>
<State />
<State name="State1" />
<State name="State2" />
</StateMachine>
State & Transitions
BehaviorTree ノードのコンテンツを実行します。このノードは、別の状態 (または元の状態) に移行で
きます。実行中、元の状態に移行するように命令された場合、State ノードは、終了し、初期化され、
再度更新されます。
State ノードには、次の特徴があります。
• StateMachine ノードの基本ブロックです。
• BehaviorTree ノードが必要です。
• Transitions 要素が含まれる場合があります。
Transitions
Transitions 要素は、State ノードで記述される要素で、必要な数だけ移行の定義を含めることができ
ます。Transitions 要素は、MBT ノードではありません。存在しない状態が移行先の状態として指定さ
れている場合、MBT ノードを解析するときにエラーメッセージが表示されます。
パラメーター
<State /> 要素には、次のパラメーターを含める必要があります。
name
状態の名前です。所属する StateMachine の範囲で一意である必要があります。
<Transition /> 要素には、次のパラメーターを含める必要があります。
onEvent
移行を引き起こす可能性があるイベントの名前です。これらのイベントのタイプは AISignal で
す。
先
移行先の状態の名前です。
成功/失敗
BehaviorTree ノードのコンテンツが成功すれば、ノードは成功です。
BehaviorTree ノードのコンテンツが失敗すると、ノードは失敗です。
例
<State name="StateName">
<Transitions>
<Transition onEvent="EventOrTransitionSignalName" to="OtherStateName" />
Version 1.6
59
Lumberyard 開発者ガイド
モジュラー動作ツリー
</Transitions>
<BehaviorTree>
<SomeChildNode />
</BehaviorTree>
</State>
SuppressFailure
1 つの子ノードを所有および実行します。このノードは、子ノードが成功したかどうかに関係なく成
功します。
パラメーター
なし.
成功/失敗
子ノードが実行されれば、常にノードは成功です。
例
<SuppressFailure>
<SomeChildThatCanFail />
</SuppressFailure>
タイムアウト
指定された時間が経過すると、ノードは失敗です。
パラメーター
duration
失敗となるまでの時間 (秒単位) です。
成功/失敗
実行時間が duration パラメーターで指定された時間を超えると、ノードは失敗です。
例
<Timeout duration=5" />
Wait
指定された時間が経過すると、ノードは成功です。
パラメーター
duration
リクエストが成功となるまでの時間 (秒単位) です。
variation (バリエーション)
duration 値にランダムに追加することができる最大追加時間 ([0, variation] の範囲) です。こ
の値を設定すると、ノードを実行するたびに待機時間がランダムに変更されます。
成功/失敗
実行時間が指定された時間 (+ ランダムに追加される時間) になれば、ノードは成功です。
Version 1.6
60
Lumberyard 開発者ガイド
モジュラー動作ツリー
例
<Wait duration="5" variation="1" />
AIノード
これらのノードはAIシステムのMBT機能を提供します。
アジャストカバースタンス
現在有効なカバーの最大の高さに基づいてAIエージェントのカバースタンスを更新します。
パラメーター
duration
(オプションで)時間で(秒単位)ノードが実行します。無制限の期間を指定するには###
#continuous#を設定します。
variation (バリエーション)
[0 variation] の範囲内で、durationへランダムに追加できる値の(任意) 最大追加時間 (秒単
位)。この値を設定すると、ノードを実行するたびに待機時間がランダムに変更されます。
成功/失敗
子が指定された期間の長さを実行したらノードは成功です。子がカバーしていない場合は、ノードは
失敗です。
例
<AdjustCoverStance duration="5.0" variation="1.0"/>
目的
AIエージェントが目的とする場所を設定し、ノードが実行を停止した場合、場所を指定をクリアにし
ます。
パラメーター
目的とする場所。使用できる値は次のとおりです。
• 参考ポイント
• ターゲット
angleThreshold
(オプション) 狙いを撃つ正確さと耐性の角度。
境界値内の一度の機関
(オプション) 続けて狙うための時間 (秒単位) 。
成功/失敗
場所が無効な場合やタイムアウトが経過した場合に、指定された場所に指定された期間内に狙いを定
めるとノードは成功です。
例
<Aim at="Target" durationOnceWithinThreshold="2.0" />
Version 1.6
61
Lumberyard 開発者ガイド
モジュラー動作ツリー
マシンガンを使用し、周りを狙う
搭載されたマシンガンを使用すると、AIエージェントの狙い方向が更新されます。
パラメーター
最高角度範囲
(オプション) 元の方向から逸脱する最大角度。
更新頻度の最小秒数
(オプション) 更新の間隔遅延の最小時間 (秒単位) 。
参照ポイントを使用して初期方向とピボット位置を決定する
Boolean.
成功/失敗
ノードは成功も失敗もしません。
例
<AimAroundWhileUsingAMachingGun minSecondsBeweenUpdates="2.5"
maxAngleRange="30" useReferencePointForInitialDirectionAndPivotPosition="1"/
>
アニメ化
アニメーションを再生できるようにAIエージェントを設定します。
パラメーター
name
再生させるアニメーション。
緊急
(オプション)アニメーションに緊急のフラグを追加するかどうかブールが示します。
ループ
(オプション)アニメーションにループフラグを追加するかどうかブールが示します。
対象となるターゲットにボディ方向を設定する
(オプション) AIボディの方向を対象ターゲットに向けるよう変更するかどうかブールが示しま
す。
成功/失敗
アニメーションの再生が終了した際、またはアニメーションが初期化されない場合ノードは成功しま
す。
例
<Animate name="LookAround" loop="1" />
アニメーションタグラッパー
子ノードの実行のためアニメーションタグを追加し、最後に取り除きます。
パラメーター
name
設定するアニメーションタグ。
Version 1.6
62
Lumberyard 開発者ガイド
モジュラー動作ツリー
成功/失敗
子ノードの実行の結果をノードが返します。
例
<AnimationTagWrapper name="ShootFromHip">
<Shoot at="Target" stance="Stand" duration="5" fireMode="Burst" />
</AnimationTagWrapper>
アサートコンディション
指定されたコンディションが満たされたかどうか確認します。
パラメーター
Condition
確認するコンディション
成功/失敗
コンディションが正しければノードは成功し、その他の場合は失敗します。
例
<AssertCondition condition="HasTarget" />
アサートLua
正誤を返すLuaスクリプトを実行し、成功/失敗の値を変換します。この結果はMBTの前提条件を構築
するのに使用できます。
パラメーター
コード
実行するLuaスクリプト。
成功/失敗
Luaスクリプトが正しい値を返せばノードは成功で、その他の場合は失敗します。
例
<AssertLua code="return entity:IsClosestToTargetInGroup()" />
アサート時間
指定されたコンディションが満たされたかどうか確認します。
パラメーター
以来
コンディションがあるか確認するタイムスタンプの名称。
以上
タイムスタンプに指定された値以上があるかテストするコンディションステートメント。このパ
ラメータisLessThanでは使用できません。
Version 1.6
63
Lumberyard 開発者ガイド
モジュラー動作ツリー
未満
タイムスタンプが指定された値より小さいかどうかテストするコンディションステートメント。
このパラメータisMoreThanでは使用できません。
または1度も設定されたことがない
(オプション)タイムスタンプが1度も設定されていない場合、ノードを成功させるよう設定するか
どうかを示すブール。
成功/失敗
時間のコンディションが正の場合ノードは成功し、誤の場合は失敗します。指定されたタイムスタン
プが事前に設定されていない場合、そのノードは失敗しますが、パラメータorNeverBeenSetが正し
い場合に限り成功します。
例
<AssertTime since="GroupLostSightOfTarget" isLessThan="10"
orNeverBeenSet="1" />
バブル
AIエージェント上にスピーチバブルのメッセージを表示します。「AIバブルシステム (p. 20)」を参
照してください。
パラメーター
メッセージ
メッセージバブルに表示するメッセージ文字列。
duration
メッセージを表示する秒数。デフォルトは0.0です。
バルーン
AIエージェント上のバルーンのメッセージを表示するかどうかをブールが示します。デフォルト
は true です。
ログ
汎用ログにメッセージを作成するかどうかをブールが示します。デフォルトは true です。
成功/失敗
表示するメッセージをキューに入れた直後にノードが成功します。
例
<Bubble message="MessageToBeDisplayedAndOrLogged" duration="5.0"
balloon="true" log="true" />
ターゲットへ到達できるかの確認
AIエージェントがターゲットに到達できるかどうか確認します。
パラメーター
mode
確認するターゲット。使用できる値は次のとおりです。
• ライブターゲットの使用
• 対象ターゲットの使用
Version 1.6
64
Lumberyard 開発者ガイド
モジュラー動作ツリー
成功/失敗
ターゲットへ到達することができればノードは成功､できなければ失敗します。
例
<CheckIfTargetCanBeReached mode="UseLiveTarget" />
クリアターゲット
AIエージェントのターゲット情報が消去されます。
パラメーター
なし.
成功/失敗
Nodeは必ず成功します。
例
<ClearTargets />
コミュニケート
AIエージェントのコミュニケーションとしてコミュニケーションマネージャーにリクエストを送信し
ます。「コミュニケーションンシステム (p. 37)」を参照してください。
パラメーター
name
再生されるコミュニケーションの名前。
チャネル
コミュニケーションが設定されるチャネル。
完了するまで待つ
(オプション)実行を終了する前にコミュニケーションを待つべきかどうかを指定します。
timeout
(オプション)ノードが待機する最大秒数を定義する閾値。
有効期限
(オプション) コミュニケーションがチャネルがクリアになるまで待機する最大秒数。
minSilence
(オプション)コミュニケーションが再生されたあとチャネルがミュートになるまでの秒数。
音を無視
(オプション)コミュニケーションを無視するようにサウンドコンポーネントを設定します。
アニメーションを無視
(オプション)コミュニケーションを無視するようアニメーションコンポーネントを設定します。
成功/失敗
ノードが待機状態に設定されている場合、コミュニケーションが完了するとノードは成功します。そ
うでなければ、タイムアウトが経過した後に成功します。
例
<Communicate name="Advancing" channel="Tactic" expiry="1.0"
waitUntilFinished="0" />
Version 1.6
65
Lumberyard 開発者ガイド
モジュラー動作ツリー
Luaを実行する
Luaスクリプトを実行します。
パラメーター
コード
実行するスクリプト。
成功/失敗
Nodeは必ず成功します。
例
<ExecuteLua code="entity:SetEyeColor(entity.EyeColors.Relaxed)" />
グループスコープ
グループスコープの中にあるAIエージェントを入力することを条件に、子nodeが実行されます。グ
ループは限定数の同時ユーザーを許可します。
パラメーター
name
入力するグループスコープの名前。
許可された同時ユーザー
(オプション)指定されたグループスコープに認められた同時ユーザの最大数。
成功/失敗
AIエージェントがグループスコープを入力出来ない場合ノードは失敗します。それ以外の場合、子
ノードを実行した結果を返します。
例
<GroupScope name="DeadBodyInvestigator" allowedConcurrentUsers="1">
<SendTransitionSignal name="GoToPrepareToInvestigateDeadBody" />
</GroupScope>
コンディションの場合
指定されたコンディションを満たす場合、子ノードを実行します。
パラメーター
Condition
確認するコンディションステートメント。
成功/失敗
コンディションが満たされた場合、ノードは子ノードを実行した結果を返します。コンディションが
満たされない場合、そのノードは失敗します。
例
<IfCondition condition="TargetVisible">
Version 1.6
66
Lumberyard 開発者ガイド
モジュラー動作ツリー
<Communicate name="AttackNoise" channel="BattleChatter" expiry="2.0"
waitUntilFinished="1" />
</IfCondition>
時間の場合
タイムコンディションが満たされた場合、子ノードを実行します。
パラメーター
以来
コンディションがあるか確認するタイムスタンプの名称。
以上
タイムスタンプに指定された値以上あるかテストするコンディションステートメント。このパラ
メータisLessThanでは使用できません。
未満
タイムスタンプ指定された値未満であるかをテストするコンディションステートメント。このパ
ラメータisMoreThanでは使用できません。
または1度も設定されたことがない
(オプション)タイムスタンプが1度も設定されていない場合、ノードを成功させるよう設定するか
どうかを示すブール。
成功/失敗
タイムコンディションが正しい場合、ノードは子ノードを実行した結果を返します。タイムコンディ
ションが誤っている場合、失敗します。指定されたタイムスタンプが事前に設定されていない場合、
そのノードは失敗しますが、パラメータorNeverBeenSetが正しい場合に限り成功します。
例
<IfTime since="FragGrenadeThrownInGroup" isMoreThan="5.0" orNeverBeenSet="1">
<ThrowGrenade type="frag" />
</IfTime>
ログ
AIエージェントのパーソナルログにメッセージを追加します。
パラメーター
メッセージ
記録するメッセージ。
成功/失敗
Nodeは必ず成功します。
例
<Log message="Investigating suspicious activity." />
見る
AIエージェントが見る場所を追加し、ノードの実行が停止した場合消去します。
Version 1.6
67
Lumberyard 開発者ガイド
モジュラー動作ツリー
パラメーター
見る場所。許可された値は次のとおりです:
• 最も親しいグループメンバー
• 参照ポイント
• ターゲット
成功/失敗
このノードは成功も失敗もしません。
例
<Look at="ClosestGroupMember" />
Luaゲート
Luaスクリプトを実行した結果が正である場合のみ、子ノードを実行します。
パラメーター
コード
実行するLuaスクリプト。
成功/失敗
ノードはLuaスクリプトの結果が正であれば成功し、正でなければ失敗します。成功した場合は、
ノードが子ノードの実行結果を返します。
例
<LuaGate code="return AI.GetGroupScopeUserCount(entity.id,
'DeadBodyInvestigator') == 0">
<Animate name="AI_SearchLookAround" />
</LuaGate>
Luaラッパー
子ノードを実行する前後両方もしくはどちらかでLuaスクリプトを実行します。
パラメーター
エンター
(オプション) 最初に実行するスクリプト
エグジット
(オプション) 最後に実行するスクリプト。
成功/失敗
ノードが子ノードの実行結果を返します。
例
<LuaWrapper onEnter="entity:EnableSearchModule()"
onExit="entity:DisableSearchModule()">
Version 1.6
68
Lumberyard 開発者ガイド
モジュラー動作ツリー
<Animate name="AI_SearchLookAround" />
</LuaWrapper>
モニターコンディション
指定条件の状態を継続的にチェックします。
パラメーター
Condition
確認する条件を指定します。
成功/失敗
ノードは条件が満たされると成功します。
例
<MonitorCondition condition="TargetVisible" />
移動
現在の位置から指定した場所にAIエージェントを移動します。指定した場所がターゲットで、エンド
ポジションがターゲット移動後に届かない場合は、エンドポジションが更新されます。「動作システ
ム (p. 35)」を参照してください。
パラメーター
速度
移動速度。使用できる値は次のとおりです。
• 歩行
• 走行
• 全力疾走
体勢
移動時の体勢使用できる値は次のとおりです。
• リラックスする
• 警戒する
• 直立 (デフォルト)
ボディオリエンテーション
AIエージェントのボディが向くべき方向使用できる値は次のとおりです。
• 完全に進行方向を向く
• 完全に標的と向きあうまたは標的を見る
• 標的に向き合うもしくは見る途中 (デフォルト)
カバーするための移動
AIエージェントがカバーするために移動中であるかどうかをブールで示します。デフォルトは
false です。
x移動前に進行方向に向かってターンする
AIエージェントが実際に移動するために、事前に進行方向へのターンが必要かどうかをブールが
指示します。デフォルトは false です。
機銃掃射
ブールがAIエージェントに機銃掃射を許可するかどうかを指示します。デフォルトは false です。
進行方向を一瞥する
ブールがAIエージェントが進行方向を一瞥できるかどうかを指示します。偽の場合は、AIエー
ジェントが必ずルックアットターゲットを確認します。デフォルトは false です。
Version 1.6
69
Lumberyard 開発者ガイド
モジュラー動作ツリー
先
移動先使用できる値は次のとおりです。
• ターゲット - 現在注意を向けているターゲット
• 隠れ場所-現在のカバー位置。
• 参照ポイント - 現在の参照位置。
• 前回のオペレーション-直近で成功した場所関連オペレーションの位置。
一定距離内で停止
AIエージェントが動きを停止できるターゲットからの間隔。デフォルトは0.0です。
停止距離のバリエーション
stopDistanceVariationの値に[0, stopDistanceVariation]の範囲内で無作為に追加される
最大距離。この値を設定すると、ノードの異なる実行間で停止間隔が無作為に異なるようになり
ます。デフォルトは0.0です。
射撃モード
移動中の攻撃スタイル。許可される値は銃撃 (p. 73)ノードに表示されます。
リスク回避
移動中、AIエージェントがリスクを回避するべきかどうかをブールが指示します。デフォルトは
true です。
グループメイト回避
移動中、AIエージェントがグループメイトを回避するべきかどうかをブールが指示します。デ
フォルトは true です。
アクターを障害物として認識
AIエージェントのパスファインダが路上にいるアクターを回避するべきかどうかをブールが指示
します。デフォルトは false です。
進路の終わりからカットする長さ
パスファインダの進路からカットされるべき距離。進路の末尾からカットする場合正の値を、進
路初めからカットする場合には負の値を使用します。デフォルトは0.0です。
成功/失敗
目的地に到達すると、ノードが成功します。目的地へ到達不可能と判断された場合は、ノードが失敗
します。
例
<Move to="Target" stance="Alerted" fireMode="Aim" speed="Run"
stopWithinDistance="3" />
優先順位とケース
実行する一連の子ノードから順位を選択します。ノード<Priority>内では、各子ノードは条件項目
を定義するノード<Case>内に表示されます。子ノードは (1)条件を満たす最初の子ノード (2)同順位の
場合は、子ノードが表示されている順序を基に選択・実行されます。ただし、最後を除くすべての子
ノードは、条件項目が必要です。 最後にリストされている子ノードはデフォルトのケースなので、そ
の条件は常に真である必要があります。
パラメーター
<Priority>ノードにはパラメータがありません。
<Case>ノードには以下のパラメータがあります。
Condition
子ノードの優先順位をつけるのに使用するコンディションステートメント。
Version 1.6
70
Lumberyard 開発者ガイド
モジュラー動作ツリー
成功/失敗
ノードが実行済み子ノードの結果を返します。
例
<Priority>
<Case condition="TargetInCloseRange and TargetVisible">
<Melee target="AttentionTarget" />
</Case>
<Case>
<Look at="Target" />
</Case>
</Priority>
脅威レベルの引き下げ
AIエージェントのターゲット脅威認識を引き下げます。
パラメーター
先
成功/失敗
Nodeは必ず成功します。
例
<PullDownThreatLevel to="Suspect" />
クエリTPS
TPSクエリを行いAIエージェントのタクティカルポジションを特定し、結果を待機します。「AI タク
ティカルポイントシステム (p. 21)」を参照してください。
パラメーター
name
実行するTPSクエリの名前。
登録
TPSクエリの結果を保存する場所。使用できる値は次のとおりです。
• 参照ポイント
• 隠れ場所 (デフォルト)
成功/失敗
TPSがタクティカルポジションを戻すとノードは成功し、タクティカルポジションを特定できない場
合失敗します。
例
<QueryTPS name="queryName" register="Cover" />
Version 1.6
71
Lumberyard 開発者ガイド
モジュラー動作ツリー
ランダムゲート
無作為のに子ノードを実行（または非実行）します。
パラメーター
確率により開く
子ノードを実行するかを決定するのに使用する可能性。許可される値は浮動小数点0.0から1.0で
す。
成功/失敗
子ノードが実行されないとノードは失敗します。子ノードが実行されると、ノードは成功し、その子
ノードの実行結果を返します。
例
<RandomGate opensWithChance="0.5">
<ThrowGrenade type="frag" />
</RandomGate>
トランジション信号の送信
状態の変更を発生させる明示的な意図のもと、動作ツリー上の状態マシンノードに送信します。
パラメーター
name
送信される信号の名前。
成功/失敗
このノードは成功も失敗もしません。
例
<SendTransitionSignal name="LeaveSearch" />
警戒度の設定
AIエージェントの警戒レベルを設定します。
パラメーター
value
警戒レベル。許可される値は0から2までの整数です。
成功/失敗
Nodeは必ず成功します。
例
<SetAlertness value="1" />
Version 1.6
72
Lumberyard 開発者ガイド
モジュラー動作ツリー
銃撃
AIエージェントがターゲットもしくは指定された場所を撃つように設定します。
パラメーター
duration
AIエージェントが撃ち続けることのできる時間 (秒単位) 。
銃撃する場所。使用できる値は次のとおりです。
• 対象ターゲット
• 参照ポイント
• ローカルスペースポジション
攻撃モード
射撃スタイル。使用できる値は次のとおりです。
• オフ - 射撃しない（デフォルト）。
• バースト - 生きているターゲットのみを対象として爆破攻撃を行います。
• 継続的（Continuous）-生きているターゲットのみを対象に継続的に射撃します。
• フォース - どんなターゲットにも継続的に射撃します。
• エイム - 標的としたターゲットにのみ攻撃します。
• セカンダリ - 補助火器 (手榴弾など)で攻撃します。
• セカンダリスモーク - 発煙手榴弾で攻撃。
• ミリー - 乱闘。
• キル - AIエージェントの攻撃力/攻撃範囲/正確さの設定に関わらず、ターゲットを100％の命中
率で射撃します。
• 移動中バースト -移動中に遠距離にいるターゲットに攻撃します。
• パニックスプレッド - ターゲットめがけて無作為に攻撃します。
• バーストドローファイア - 敵の砲火を引くのを目的に爆破攻撃をします。
• ミリ―フォース - 距離制御のない乱闘です。
• バーストスワイプ - ヘッドショットを狙った爆破攻撃です。
• エイムスイープ - ターゲットへの照準を維持しますが、攻撃はしません。
• バーストワンス - 単発の爆撃を撃ちます。
体勢
銃撃中の体勢使用できる値は次のとおりです。
• リラックスする
• 警戒
• かがむ
• 直立
position
(ターゲットがローカルスペースポジションの場合必要) ターゲットとして利用するローカルス
ペースポジション。
急傾斜に使用する体勢
(オプション) 斜面が一定の傾度を超えるときに使用される体勢。許可される値はstanceに使われ
るものと同じです。
高角度から許可されたスロープノーマル偏差
(オプション) 基本体勢を設定するための最大傾斜許可値（水平線上からの傾斜度）この傾度を超
えると、代替体勢が使用されます。
標的遮断タイムアウト
(オプション)ノードに障害が発生する前に、AIエージェントの標的を遮断することができる時間
(秒単位) 。
Version 1.6
73
Lumberyard 開発者ガイド
モジュラー動作ツリー
成功/失敗
指定した時間持続的に実行されるとノードは成功します。標的が指定した時間よりタイムアウトとな
り、遮断されるとノードは失敗します。
例
<Shoot at="Target" stance="Crouch" fireMode="Burst"
duration="5" allowedSlopeNormalDeviationFromUpInDegrees="30"
stanceToUseIfSlopeIsTooSteep="Stand" />
隠れ場所からの銃撃
AIエージェントを隠れ場所からターゲットを撃つように設定し、それに応じて体勢を調整します。
パラメーター
duration
ノードを実行することができる時間 (秒単位) 。
射撃モード
射撃スタイル。許可される値は銃撃 (p. 73)ノードに表示されます。
遮断タイムアウトをねらう
(オプション)ノードに障害が発生する前に、AIエージェントの標的を遮断することができる時間
(秒単位) 。
成功/失敗
指定した時間持続的に実行されるとノードは成功します。AIエージェントに隠れ場所がない場合、銃
撃姿勢にない場合、または指定した時間よりタイムアウトになり標的が遮断された場合、ノードは失
敗します。
例
<ShootFromCover duration="10" fireMode="Burst" aimObstructedTimeout="3" />
通知
AIシステムに信号を送信します。「シグナル (p. 88)」を参照してください。
パラメーター
name
送信される信号の名前。
フィルター
(オプション) どのAIエージェントが受信するかを決定する信号を送信するときに使用する信号
フィルタ。
成功/失敗
Nodeは必ず成功します。
例
<Signal name="StartedJumpAttack" />
Version 1.6
74
Lumberyard 開発者ガイド
モジュラー動作ツリー
スマートオブジェクト状態ラッパー
子ノードを実行する直前や後に、特定のスマートオブジェクトの状態を設定します。
パラメーター
エンター
(オプション) 開始時に設定するスマートオブジェクトの状態。
エグジット
(オプション) 終了時に設定するスマートオブジェクトの状態。
成功/失敗
ノードが子ノードの実行結果を返します。
例
<SmartObjectStatesWrapper onEnter="InSearch" onExit="-InSearch">
<Animate name="LookAround" />
</SmartObjectStatesWrapper>
体勢
AIエージェントの体勢を設定します。
パラメーター
name
基本体勢スタイル。使用できる値は次のとおりです。
• リラックスする
• 警戒
• かがむ
• 直立
急傾斜に使用する体勢
(オプション) 斜面が一定の傾度を超えるときに使用される体勢。許可される値はstanceに使われ
るものと同じです。
高角度から許可されたスロープノーマル偏差
(オプション) 基本体勢を設定するための最大傾斜許可値（水平線上からの傾斜度）この傾度を超
えると、代替体勢が使用されます。
成功/失敗
Nodeは必ず成功します。
例
<Stance name="Crouch" allowedSlopeNormalDeviationFromUpInDegrees="30"
stanceToUseIfSlopeIsTooSteep="Stand" />
動き停止
すべての動きを停止するよう移動システムにリクエストを送信します。「動作システム (p. 35)」を
参照してください。
Version 1.6
75
Lumberyard 開発者ガイド
モジュラー動作ツリー
Note
AIエージェントは即座に停止しない可能性があります。移動システムはアニメーションと、移
動の即時の停止よりも自然な停止を指令する物理に依存する可能性があるためです。
パラメーター
停止まで待機
移動システムがリクエスト処理を完了するまでノードが待機するべきかどうかをブールが指示し
ます。
アニメーション停止まで待機
Motion_Idleアニメーションのフラグメントがマネキンで実行を開始するまでノードが待機するべ
きかどうかをブールが指示します。
成功/失敗
ノードは停止リクエストが完了すると成功します。
例
<StopMovement waitUntilStopped="1" waitUntilIdleAnimation="0" />
テレポート
目的位置とソースポイント両方がカメラビューの外にあるとき、AIエージェントを移動します。
パラメーター
なし.
成功/失敗
Nodeは必ず成功します。
例
<Teleport />
手榴弾を投げる
AIエージェントが手榴弾を投げるようにトリガーします。
パラメーター
timeout
手榴弾が投げられるまでの待機時間の最長時間(秒単位) 。
type
使用する手榴弾のタイプ。使用できる値は次のとおりです。
• 電磁
• 破片
• 発煙
成功/失敗
タイムアウト前に手榴弾が投げられればノードは成功し、それ以外の場合は失敗します。
Version 1.6
76
Lumberyard 開発者ガイド
モジュラー動作ツリー
例
<ThrowGrenade type="emp" timeout="3" />
時間まで待機
時間の条件が満たされるまで実行されます。
パラメーター
以来
コンディションがあるか確認するタイムスタンプの名称。
以上
タイムスタンプに指定された値以上があるかテストするコンディションステートメント。このパ
ラメータisLessThanでは使用できません。
未満
タイムスタンプが指定された値より小さいかどうかテストするコンディションステートメント。
このパラメータisMoreThanでは使用できません。
未設定であれば成功
(オプション)タイムスタンプが1度も設定されていない場合、ノードを成功させるよう設定するか
どうかを示すブール。
成功/失敗
ノードは時間の条件が真であれば成功します。指定されたタイムスタンプが事前に設定されていない
場合、そのノードは失敗しますが、パラメータsucceedIfNeverBeenSetが真の場合に限り成功しま
す。
例
<WaitUntilTime since="BeingShotAt" isMoreThan="7" />
CryAction ノード
これらのノードは CryAction 機能に MBT 機能を提供します。
AnimateFragment
Mannequin アニメーションフラグメントを再生し、アニメーションが終了するまで待機します。
パラメーター
name
再生するアニメーションの名前。
成功/失敗
アニメーションが正しく再生される場合、または操作の必要がない場合、ノードは成功します。アニ
メーションリクエストをキューに入れようとしているときにエラーが発生した場合、ノードは失敗し
ます。
例
<AnimateFragment name="SomeFragmentName" />
Version 1.6
77
Lumberyard 開発者ガイド
モジュラー動作ツリー
ゲームノード
これらのノードにより、ゲーム固有の MBT 機能が提供されます。また、複数のキャラクタータイプ
が含まれるゲームで特定のロジックをトリガーしたり、各タイプの特性に関連するアクションを実行
したりできます。"一般的な使用" に適さないゲーム固有のノードについては、各ゲームでカスタマイ
ズする必要がある場合があります。
キャラクタータイプは、ゲームノードの設定テーブルが含まれる Lua ファイルで定義されます。
InflateAgentCollisionRadiusUsingPhysicsTrick
プレイヤと衝突する場合は、AI エージェントのカプセル半径を拡大します。このノードは物理システ
ムのトリックを使用して、エージェントとプレイヤが衝突する場合のカプセル半径を拡大しますが、
エージェントと世界の衝突の場合は、カプセル半径が変更されません。
Note
このトリックは、このノード内で完全に隔離されています。このノードはクリーンアップさ
れないため、ノードの使用後、カプセルが拡大されたままになります。
このトリックは、次のように機能します。
1. エージェントとプレイヤの衝突半径でプレイヤのディメンションを設定します。物理システムはマ
ルチスレッドのため、プレイヤのディメンションがコミットされるまで少し待機が発生します。
2. プレイヤのディメンションを定期的に検査し、エージェントとプレイヤの衝突半径が正常にコミッ
トされていることを確認します。AI エージェントが狭い場所にあって拡大できないときなど、場合
によっては、この機能が実行されないことがあります。
3. エージェントとプレイヤの半径がコミットされたら、ジオメトリに移動し、エージェントと世界の
半径を使用して、カプセルの半径を適切に設定します。この操作は、エージェントとプレイヤの
ディメンションに影響を及ぼしません。
パラメーター
radiusForAgentVsPlayer
AI エージェントとプレイヤの衝突を計算する際に使用するカプセルサイズです。
radiusForAgentVsWorld
AI エージェントと世界の衝突を計算する際に使用するカプセルサイズです。
成功/失敗
このノードは成功したり失敗したりしません。実行されると、実行されたノードの範囲外になるまで
実行が継続されます。
例
<InflateAgentCollisionRadiusUsingPhysicsTrick radiusForAgentVsPlayer="1.0"
radiusForAgentVsWorld="0.5" />
KeepTargetAtADistance
指定された距離の範囲内にライブターゲットが存在するときに、そのターゲットを物理的にプッシュ
することより、ターゲットを遠ざけます。プレイヤの近くに何らかのアクションがあるときに、カメ
ラを通じたクリッピングを避けたい場合には、このノードが便利です。このノードの使用は、AI エー
ジェントのカプセルサイズを拡大することよりも推奨されます。このカプセルサイズの拡大は、キャ
ラクターが狭い通路を通り抜ける方法にも影響を及ぼします。通常、このノードは、プレイヤが AI
エージェントに最接近できないときに実行する必要のある他のアクションと並行して使用されます。
Version 1.6
78
Lumberyard 開発者ガイド
モジュラー動作ツリー
たとえば、ロケーターを動かさずに AI エージェントを動かすことができる場所でアニメーションを再
生すると、カメラクリッピングが発生します。
パラメーター
distance
プレイヤと AI エージェントの間に許可される最小距離です。
impulsePower
プレイヤを最小距離よりも近い位置に近づけないようにするために使用するインパルスの量で
す。
成功/失敗
このノードは成功したり失敗したりしません。実行されると、実行されたノードの範囲外になるまで
実行が継続されます。
例
<KeepTargetAtADistance distance="1.8" impulsePower="1.5" />
近接攻撃
AI エージェントのターゲットに対して近接攻撃をトリガーします。次の条件が満たされると、近接攻
撃が実行されます。
• failIfTargetNotInNavigationMesh が設定された場合、ターゲットは歩いて行ける有効な位置
に存在している必要があります。一部の近接攻撃アニメーションでは、ナビゲーションメッシュの
外部にあるターゲットへの攻撃を試みたときに、ナビゲート可能な領域の外部にキャラクターを移
動できます。
• エンティティの Lua 値 melee.angleThreshold によって指定されたしきい値角度内にターゲット
が存在しない場合。
パラメーター
target
近接攻撃のターゲットです。このパラメーターは、AI エージェントの AttentionTarget または一般
的な RefPoint で設定される場合があります。
cylinderRadius
ヒットの衝突確認に使用されるシリンダーの半径です。
hitType
ゲームのルールに報告されるヒットのタイプです。デフォルト
は、CGameRules::EHitType::Melee です。
failIfTargetNotInNavigationMesh
ノードがナビゲーションメッシュの外部にあるターゲットへの攻撃を試みる必要があるかどうか
を示すブール値です。
materialEffect
近接攻撃がターゲットにヒットしたときに使用されるマテリアルエフェクトの名前です。
成功/失敗
このノードは、近接攻撃が実行されたかどうかに関係なく、実行された場合は、攻撃がターゲットに
ダメージを与えたかどうかに関係なく、成功します。その理由は、動作ツリーロジックにとっては、
このノードの失敗が重要ではないからです。ゲームがこの状況に対応することが重要な場合は、失敗
オプションを追加できます。
Version 1.6
79
Lumberyard 開発者ガイド
モジュラー動作ツリー
例
<Melee target="AttentionTarget" cylinderRadius="1.5" hitType="hitTypeName"
materialEffect="materialEffectName" />
Lua テーブルの設定
Lua テーブル melee には、次の設定が含まれます。
melee =
{
damage = 400,
hitRange = 1.8,
knockdownChance = 0.1,
impulse = 600,
angleThreshold = 180,
},
damage
近接攻撃がターゲットに及ぼしたダメージの量です。
hitRange
近接攻撃がターゲットにヒットしたかどうかを確認するために使用されるシリンダーの高さで
す。
knockdownChance
成功した近接攻撃がプレイヤを倒す可能性です。
impulse
近接攻撃が成功したときにプレイヤに適用されるインパルスの量です。
angleThreshold
AI エージェントの移動方向と、AI エージェントと試行される近接攻撃のターゲット間のパス方向
との間で許可される最大角度です。
ScorcherDeploy
シューティングフェーズの一部としてデプロイまたはデプロイ解除するときに、Scorcher キャラク
タータイプが特定のアクティビティを処理する方法を管理します。このノードは適切に動作するため
にいくつかの外部 Lua スクリプトとさまざまなシグナルに依存していますが、AI ライブラリの一般的
な機能を難読化するのに役立ちます。
ノード実行の前後に、Lua 関数 EnterScorchTargetPhase() および
LeaveScorchTargetPhase() が呼び出されます。ノードの実行が始まると、Mannequin によって
"ScorcherScorch" アニメーションタグがリクエストされます。ノードが停止するとき、それが正常に
停止する場合、"ScorcherNormal" タグが再度リクエストされます。ノードが処理の途中で終了した場
合は、"ScorcherTurtle" タグのリクエストなど、動作ツリースクリプトが適切な終了戦略を定義するこ
とが求められます。
アニメーションタグをリクエストするときに、ノードは次のアニメーションイベントの受信を待機し
ます（これにより、移行ブレンドアニメーションが中断されなくなります）。
1. "ScorcherDeployed" – scorcher が射撃を開始できる状態になったとき
2. "ScorcherUndeployed" – scorcher が再度歩き回れる状態になったとき
ノードは、子ノード RunWhileDeploying および RunWhileDeployed をカプセル化します。これら
の各子ノードには、厳密に 1 つの子ノードを含めることができます。
Version 1.6
80
Lumberyard 開発者ガイド
モジュラー動作ツリー
RunWhileDeploying
Scorcher のデプロイのプロセス中にアクティビティを発生させます。つまり、攻撃の準備が整いま
す。たとえば、実際に射撃を開始する前に、照準を制御するためにこのノードを使用します。
次のいずれかのイベントが発生するまで、ノードは実行を続けます。イベントが発生した後、ノード
は強制的に停止されます。
• ScorcherFriendlyFireWarningModule がエンティティ "OnScorchAreaClear" または
"OnScorchAreaNotClearTimeOut" にこれらのシグナルの 1 つを送信する
• Mannequin アニメーションシーケンスが "ScorcherDeployed" シグナルを送信する
• 内部タイムアウトが経過した
ノードはパラメーターをサポートしません。ノードの成功と失敗は、子ノードの成功と失敗に左右さ
れます。ノードは処理の途中で成功できます。
RunWhileDeployed
攻撃中の実際の照準と射撃を制御します。攻撃の長さと実行は、このノードによって制御されます。
ノードはパラメーターをサポートしません。ノードの成功と失敗は、子ノードの成功と失敗に左右さ
れます。ノードは処理の途中で成功できます。ノードが成功すると、親ノードがトリガーされ、シー
ケンスのデプロイ解除が開始されます。
パラメーター
maxDeployDuration
"RunWhileDeploying" 子ノードの実行が許可される時間 (秒単位) です。デフォルトは2.0です。
成功/失敗
デプロイおよびデプロイ解除シーケンス全体が完了すると、ノードは成功しま
す。RunWhileDeploying ノードまたは RunWhileDeployed ノードが失敗すると、ノードは失敗し
ます。
例
<ScorcherDeploy maxDeployDuration="1.0">
<RunWhileDeploying>
<SomeChildNode>
</RunWhileDeploying>
<RunWhileDeployed>
<SomeOtherChildNode>
</RunWhileDeployed>
</ScorcherDeploy>
SuppressHitReactions
AI エージェントの Hit Reaction システムを有効または無効にします。
パラメーター
なし.
成功/失敗
ノードは、その子ノードの成功または失敗に応じて成功または失敗します。
Version 1.6
81
Lumberyard 開発者ガイド
モジュラー動作ツリー
例
<SuppressHitReactions>
<SomeChildNode />
</SuppressHitReactions>
飛行ノード
これらのノードは、飛行する乗り物に関連する MBT 機能を提供します。
Hover
飛行する AI エージェントを現在の位置でホバリングさせます。
パラメーター
なし.
成功/失敗
このノードは成功したり失敗したりしません。実行すると、強制的に終了されるまで実行を続けま
す。
例
<Hover />
FlyShoot
可能な場合は、AI エージェントが現在の位置から注意ターゲットに向けて発砲することを許可しま
す。
AI エージェントの補助火器システムが使用されると、ターゲットが武器を命中させるのに十分に近い
距離にいる場合にのみ、このノードは射撃を開始します。そうでない場合は、通常の射撃ルールが適
用されます。
パラメーター
useSecondaryWeapon
補助火器システム (ロケットランチャーなど) が使用されるかどうかを示すブール値。デフォルト
は0です。
成功/失敗
このノードは成功したり失敗したりしません。実行すると、AI エージェントは強制的に終了されるま
で撃ち続けます。
例
<FlyShoot useSecondaryWeapon="1" />
WaitAlignedWithAttentionTarget
AI エージェントがその注意ターゲットと対面するまで待機します。
Version 1.6
82
Lumberyard 開発者ガイド
モジュラー動作ツリー
パラメーター
toleranceDegrees
注意ターゲットと AI エージェントの進行方向の間の、AI エージェントが注意ターゲットに「対
面している」と見なせる最大角度 (度数)。使用できる値の範囲は [0.0,180.0] です。デフォルトは
20.0です。
成功/失敗
AI エージェントの進行方向とその注意ターゲットの間の角度が許容範囲内の場合、ノードは成功しま
す。AI エージェントに注意ターゲットがない場合、ノードは失敗します。
例
<WaitAlignedWithAttentionTarget toleranceDegrees="40" />
Fly
AI エージェントが経路に従って飛行することを許可します。経路は フローグラフ を使用して AI エー
ジェントに割り当てることをお勧めします。
パラメーター
desiredSpeed
経路に沿って移動する場合、経路に沿った移動の速度 (メートル/秒)。デフォルトは15.0です。
pathRadius
経路の半径 (メートル)。飛行中、AI エージェントは経路の線分からこの距離内にとどまろうとし
ます。デフォルトは 1.0 です。
lookAheadDistance
「アトラクタポイント」が飛行する経路に沿って警戒する距離 (メートル)。デフォルトは3.0で
す。
decelerateDistance
AI エージェントが減速を始める、経路の終わりからの距離 (メートル)。デフォルトは10.0です。
maxStartDistanceAlongNonLoopingPath
別の経路につながる最も近いポイントまでの最大距離 (メートル)。このパラメータは、ループし
ていない経路とつなげるために使用します。たとえば、AI エージェントが近づいているように見
える新しい経路にスナップしないようにするには便利ですが、実際には U ターンした後に壁に隠
れます。デフォルトは 30.0 です。
loopAlongPath
AI エージェントが無限ループの経路をたどるかどうかを示すブール値。デフォルトは0です。
startPathFromClosestLocation
AI エージェントがたどる経路の始点を示すブール値。デフォルトは0です。
• 1 - 最も近い場所
• 2 - 経路の最初の中間地点
pathEndDistance
このノードが到着通知イベントの送信を始める、経路の終わりからの距離 (メートル)。デフォル
トは 1.0 です。
goToRefPoint
経路の終わりに現在の基準点を付加するかどうかを示すブール値。デフォルトは0です。
成功/失敗
AI エージェントが経路の終わりに達した場合、ノードは成功します。AI エージェントに有効な経路が
割り当てられていない場合、ノードは失敗します。
Version 1.6
83
Lumberyard 開発者ガイド
モジュラー動作ツリー
例
<Fly lookaheadDistance="25.0" pathRadius="10.0"
decelerateDistance="20.0" pathEndDistance="1" desiredSpeed="15"
maxStartDistanceAlongNonLoopingPath="30" loopAlongPath="0" goToRefPoint="1"
startPathFromClosestLocation="1" />
Lua テーブルの設定
AI エージェントの Lua スクリプトテーブルの次のプロパティは、デフォルトの XML タグをオーバー
ライドすることができます。これにより、(フローグラフ) スクリプトを使用して実行時に変更を加え
ることを許可します。
メトリック
Lua 変数
XML タグ
各ノードティッ
ク
Helicopter_Speed
desiredSpeed
ノードのアク
ティブ化
Helicopter_Loop
loopAlongPath
ノードのアク
ティブ化
Helicopter_StartFromClosestLocation
startPathFromClosestLocation
到着時に、次のイベントが出力されます。
• ArrivedCloseToPathEnd
• ArrivedAtPathEnd
FlyForceAttentionTarget
飛行する乗り物から注意ターゲットを強制的に外さないようにします。注意ターゲットは、ノードの
各ティック中に Helicopter_ForcedTargetIdLua スクリプト変数から取得されます。ノードが非
アクティブ化されると、ForceAttentionTargetFinished イベントが出力されます。
パラメーター
なし.
成功/失敗
このノードは成功したり失敗したりしません。実行すると、非アクティブ化までは注意ターゲットを
追い込み続けます。
例
<FlyForceAttentionTarget />
FlyAimAtCombatTarget
武器の特殊な照準調整を考慮に入れて、飛行中の AI エージェントの照準をそのターゲットに合わせま
す。
パラメーター
なし.
Version 1.6
84
Lumberyard 開発者ガイド
モジュラー動作ツリー
成功/失敗
このノードは成功したり失敗したりしません。実行すると、終了まで AI エージェントのボディを注意
ターゲットに向けて強制的に回転させ続けます。
例
<FlyAimAtCombatTarget />
HeavyShootMortar
迫撃砲 (Heavy X-Pak) 武器の発射を制御します。これは、武器の前提条件のチェックと初期化、およ
び主要武器の再選択の簡素化と一元管理を試みます。
パラメーター
先
(オプション) 射撃対象のターゲット。使用できる値は次のとおりです。
• Target (デフォルト)
• Refpoint
fireMode
(オプション) 射撃のタイプ。使用できる値は次のとおりです。
• Charge (デフォルト)
• BurstMortar
timeout
(オプション) 射撃の最大継続時間 (秒)。デフォルトは5.0です。
aimingTimeBeforeShooting
(オプション) 射撃を始める前に照準を合わせるのにかかる時間 (秒)。値はグローバルのタイムア
ウトより長い値である必要があります。デフォルトは1.0です。
minAllowedDistanceFromTarget
(オプション) 射撃を始めるのに必要な、ターゲットまでの最短距離 (メートル)。デフォルトは
10.0です。
成功/失敗
武器が minAllowedDistanceFromTarget の値よりもターゲットに近い場合、ノードは失敗しま
す。武器の前方 2 メートル未満に障害物がある場合、ノードは失敗します。これを回避するには、
シリンダーのチェックを行います。タイムアウトに達すると、ノードは失敗します。射撃が成功する
と、ノードは成功します。
例
<HeavyShootMortar to="RefPoint" fireMode="Charge"
aimingTimeBeforeShooting="2" timeout="7" />
SquadScope
分隊範囲に AI エージェントを追加することを条件として、子ノードを実行します。分隊では限られた
数の同時ユーザーが可能です。
Note
動的分隊システムは AI システムのクラスター探知機を使用します。このツールは、AI エー
ジェントを動的な分隊にグループ化するために AISquadManager と一緒に使用されます。
Version 1.6
85
Lumberyard 開発者ガイド
モジュラー動作ツリー
パラメーター
name
入力する分隊範囲の名前。
allowedConcurrentUsers
(オプション) 指定された分隊範囲内で許可される同時ユーザーの最大数。デフォルトは1です。
成功/失敗
子が成功すると、ノードは成功します。AI エージェントが分隊範囲を入力できない場合、または子が
失敗した場合、ノードは失敗します。
例
<SquadScope name="SomeScopeName" allowedConcurrentUsers="5">
<SomeChildNode />
</SquadScope>
SendSquadEvent
イベントを分隊の隊員のみに送信します。
Note
動的分隊システムは AI システムのクラスター探知機を使用します。このツールは、AI エー
ジェントを動的な分隊にグループ化するために AISquadManager と一緒に使用されます。
パラメーター
name
送信されるイベントの名前。
成功/失敗
イベントの送信後は、ノードは常に成功します。
例
<SendSquadEvent name="SomeEventName" />
IfSquadCount
分隊の隊員数が指定された条件を満たしているかどうかによって、子ノードを実行します。すべての
パラメータはオプションですが、少なくとも 1 つのパラメータを使用する必要があります。
Note
動的分隊システムは AI システムのクラスター探知機を使用します。このツールは、AI エー
ジェントを動的な分隊にグループ化するために AISquadManager と一緒に使用されます。
パラメーター
isGreaterThan
(オプション) 分隊の隊員数が指定された値を超えるかどうかをテストするために使用される条件
ステートメント。
Version 1.6
86
Lumberyard 開発者ガイド
Refpoint
isLesserThan
(オプション) 分隊の隊員数が指定された値より少ないかどうかをテストするために使用される条
件ステートメント。
が
(オプション) 分隊の隊員数が指定された値とまったく同じ数であるかどうかをテストするために
使用される条件ステートメント。
成功/失敗
ノードは、分隊の隊員数が指定された条件ステートメントを満たしている場合は成功し、そうでない
場合は失敗します。
例
<IfSquadCount isGreaterThan="1">
<SomeChildNode />
</IfSquadCount>
Refpoint
refpoint、つまり参照点は goalpipe によって使用される特別な AI オブジェクトです。refpoint は主に
位置を、必要に応じて方向を指定します。次の例では、refpoint の使用方法を説明します。
例 1: sub-goalpipe が含まれる refpoint の更新
この例では、refpoint の位置が設定され、3 つの goalop (Locate、Stick、Signal) を含む 1 つの
goalpipe が作成されます。refpoint を使用して、Locate は LASTOP という値を設定します。この値
は、送信先を指定するために Stick で使用されます。
goalop の Stick が "+stick" と定義されていることに注意してください。この定義によって、Stick は確
実に前の goalop (Locate) でグループ化されます。その結果、割り込みの goalpipe によって Stick が依
存している値 (LASTOP など) が影響を受ける場合、適切な goalop に戻り、依存値が更新されます。
ACT_GOTO = function(self, entity, sender, data)
if (data and data.point) then
AI.SetRefPointPosition(entity.id, data.point);
-- use dynamically created goal pipe to set approach distance
g_StringTemp1 = "action_goto"..data.fValue;
AI.CreateGoalPipe(g_StringTemp1);
AI.PushGoal(g_StringTemp1, "locate", 0, "refpoint");
AI.PushGoal(g_StringTemp1, "+stick", 1, data.point2.x,
AILASTOPRES_USE, 1, data.fValue); -- noncontinuous stick
AI.PushGoal(g_StringTemp1, "signal", 0, 1, "VEHICLE_GOTO_DONE",
SIGNALFILTER_SENDER);
entity:InsertSubpipe(AIGOALPIPE_SAMEPRIORITY, g_StringTemp1, nil,
data.iValue);
end
end,
例 2: AI アンカーを使用した refpoint の設定
この例では、スマートオブジェクトシステムが OnBiomassDetected を使用して関連する AI アン
カーを特定します。このアンカーは、refpoint の位置と方向の両方を設定するために使用されます。そ
Version 1.6
87
Lumberyard 開発者ガイド
シグナル
の結果、AI エージェントが refpoint に到達すると、指定された方向を向き、次の goalpipe を選択しま
す。
OnBiomassDetected = function(self, entity, sender, data)
entity:SetTargetBiomass(sender);
entity:SelectPipe(0, "AlienTick_ReachBiomass");
end,
function AlienTick_x:SetTargetBiomass(biomass)
self.AI.targetBiomassId = biomass.id;
AI.SetRefPointPosition(self.id, biomass:GetWorldPos());
AI.SetRefPointDirection(self.id, biomass:GetDirectionVector(1));
end
<GoalPipe name="AlienTick_ReachBiomass">
<Speed id="Walk"/>
<Locate name="refpoint"/>
<Stick distance="0.3" useLastOp="true"/>
<Signal name="OnBiomassReached"/>
</GoalPipe>
OnBiomassReached = function(self, entity)
entity.actor:SetForcedLookDir(AI.GetRefPointDirection(entity.id));
entity:SelectPipe(0, "AlienTick_CollectBiomass");
end,
Note
この例では、タグ <Group> は使用されていません。この特定の goalpipe の中断は想定されて
いないためです (一般的には該当しません)。
シグナル
Lumberyard の AI システムには、AI エンティティ間のやり取りを可能にするための、完全にカスタマ
イズ可能なシグナルシステムが含まれています。このやり取りは、AI エージェントから別のシグナル
エージェント (自身を含む) や、ゲーム内で現在アクティブな AI エージェントのグループに送信でき
る、シグナルイベントで構成されています。
このトピックでは、AI エージェント間でシグナルを送受信する方法を説明します。
シグナルのリファレンス (p. 91)
シグナルの送信
シグナルは、AI エージェントの動作から、メソッド AI:Signal() を使用して 1 つ以上の別の AI
エージェントに送信されます。
AI:Signal(Signal_filter, signal_type, *MySignalName*, sender_entity_id);
Signal_filter
シグナルを受け取る AI エージェントのグループ。使用できる値は次のとおりです。
• 0 – entity_id パラメーターで指定された AI エージェント (多くの場合は送信側自体)。
Version 1.6
88
Lumberyard 開発者ガイド
シグナル
• SIGNALFILTER_LASTOP – AI エージェントの直前の操作ターゲット (ある場合)。
• SIGNALFILTER_TARGET – AI エージェントの現在の注意ターゲット。
• SIGNALFILTER_GROUPONLY – 通信範囲に含まれる送信側グループ (同じグループ ID) 内のす
べての AI エージェント。
• SIGNALFILTER_SUPERGROUP – レベル全体に含まれる送信側グループ (同じグループ ID) 内
のすべての AI エージェント。
• SIGNALFILTER_SPECIESONLY – 通信範囲に含まれる送信側の種類のすべての AI エージェン
ト。
• SIGNALFILTER_SUPERSPECIES – レベル全体に含まれる送信側の種類のすべての AI エー
ジェント。
• SIGNALFILTER_HALFOFGROUP – 送信側グループ内の AI エージェントの半分 (ランダムに選
択)。
• SIGNALFILTER_NEARESTGROUP – 送信側グループ内で最も近い AI エージェント。
• SIGNALFILTER_NEARESTINCOMM – 通信範囲に含まれる送信側グループ内で最も近い AI
エージェント。
• SIGNALFILTER_ANYONEINCOMM – 通信範囲に含まれるすべての AI エージェント。
• SIGNALID_READIBILITY – 受信側にリーダビリティイベント (音声/アニメーション) を実行さ
せるときに使用される特殊なシグナル。
signal_type
受信側による処理方法を決定する、シグナルのタイプ。使用できる値は次のとおりです。
• 1 – 受信側では、受信側が有効であり "ignorant" に設定されていない場合のみ、そのシグナルを
処理します (「AI:MakePuppetIgnorant」を参照してください)。
• 0 – シグナルを受け取るエンティティが "ignorant" に設定されていない場合に、シグナルを処理
します。
• -1 – シグナルを受け取るエンティティは、無条件でシグナルを処理します。
MySignalName
シグナルの実際の識別子。空白ではない任意の文字列を指定できます。シグナル受信側が受け
取ったシグナルに反応するには、現在の動作、デフォルトの動作、Scripts/AI/Behaviors/
Default.lua スクリプトファイルのいずれかに、同じ名前の関数が存在する必要があります。
entity_id
シグナル受信側のエンティティ ID。通常、シグナルを送信側自身に送信するために entity.id (また
は、動作からではなくエンティティから呼び出される場合は self.id) を指定できますが、シグナル
を別のエンティティに送信するために別の ID を指定することもできます。
シグナルの受信
シグナルの受信時に実行するアクションは、関数内で次のように定義します。
MySignalName = function(self, entity, sender)
self
受信側エンティティの動作。
entity
受信側エンティティ。
sender
シグナルの送信側。
この関数は実際にはコールバックであり、システムイベントとまったく同じように、受信側エンティ
ティの現在の動作、デフォルトのアイドル動作 (現在の動作にない場合)、Scripts/AI/Behaviors/
Version 1.6
89
Lumberyard 開発者ガイド
シグナル
Default.lua スクリプトファイル (デフォルトのアイドル動作にない場合) のいずれかで定義できま
す。
システムイベントについては、次のようにキャラクターファイル内にコード行を追加すると、キャラ
クターに動作を変更させるためにシグナルを使用することもできます。
Behaviour1 = {
OnEnemySeen
= *Behaviour1*,
OnEnemyMemory = *Behaviour2*,
&#8230;
MySignalName = *MyNewBehaviour*,
}
つまり、キャラクターの現在の動作が Behaviour1 であり、シグナル MySignalName が渡される場
合、上のコールバック関数の実行後、キャラクターの動作は MyNewBehaviour に切り替わります。
シグナルの例
代表的な例は、プレイヤーの敵がプレイヤーに気付いた場合です。OnEnemySeen システムイベント
が呼び出されます。このとき、プレイヤーが仲間 (同じグループ ID の男性) に知らせたいとします。
プレイヤーのデフォルトのアイドル動作 (例: キャラクターが Cover の場合は CoverAttack.lua)
で、OnEnemySeen イベントを次のように変更します。
OnEnemySeen = function( self, entity, fDistance )
-- called when the enemy sees a living enemy
AI:Signal(SIGNALFILTER_GROUPONLY, 1, "ENEMY_SPOTTED",entity.id);
end,
ここでは ENEMY_SPOTTED という新しいシグナルを定義しました。
次のステップは、コールバック関数を定義することです。グループ内の他のメンバーも同じキャラク
ターであるとします。ここで、さきほど OnEnemySeen を変更した同じアイドル動作に、コールバッ
ク関数を追加します。
ENEMY_SPOTTED = function (self, entity, sender)
entity:Readability("FIRST_HOSTILE_CONTACT");
entity:InsertSubpipe(0, "DRAW_GUN");
End,
これにより、仲間の男性 (動作が同じである、シグナルの送信側自体を含みます) はアニメーションを
変え、ある種のアラート音 (リーダビリティ) を生成し、銃を抜きます。アイドル動作を変更すること
によって、キャラクターの動作に対して実行されるデフォルトのコールバックが作成される点に注意
してください。このコールバックは、後で他の動作の中でオーバーライドすることができます。たと
えば、アイドル動作の場合と攻撃動作の場合でキャラクターの反応を変えるには、次のコールバック
関数を CoverAttack.lua ファイルに追加します。
ENEMY_SPOTTED = function (self, entity, sender)
entity:SelectPipe(0, "cover_pindown");
End,
"cover_pindown" は、ターゲットに対して最も近い避難場所に男性を隠れさせる goalpipe です。
これを他のキャラクターに拡張することもできます。他のキャラクター (Scout、Rear など) のグルー
プメンバーがいるとします。これらのメンバーにも同様に反応させたい場合は、これらのメンバーの
Version 1.6
90
Lumberyard 開発者ガイド
シグナル
アイドル/攻撃動作にも、ENEMY_SPOTTED コールバックを追加する必要があります。最後に、敵に
遭遇した場合は、この男性の動作をアイドルから攻撃に切り替える必要があります。
次の行をキャラクター (この例では Scripts/AI/Characters/Personalities/Cover.lua) に追
加します。
CoverIdle = {
&#8230;
ENEMY_SPOTTED = *CoverAttack*,
},
動作の継承
特定のシグナルを複数の動作内で使用する場合は、継承のメカニズムがあります。動作のクラスは、
キーワード Base = [CRYENGINE:ParentBehaviorName] を使用して、より汎用的な実装を直接継
承することも、キャラクターのアイドル動作として間接的に継承することもできます。また、シグナ
ルが現在の動作に実装されていない場合は、デフォルト動作 (DEFAULT.lua に定義されています) が
フォールバック動作と見なされます。
シグナルのリファレンス
一般的なシグナルハンドラーは次のようになっています。
OnEnemySeen = function(self, entity, distance)
-- called when the AI sees a living enemy
end,
self パラメータ (動作テーブル) と entity パラメータ (エンティティテーブル) はすべてのシグナルに渡
されます。追加パラメータは使用するシグナルに固有です。
\Game\Scripts\AI\Behaviors\Template.lua も参照してください。
パーセプションシグナル
以下のシグナルは、注意ターゲットのパーセプションタイプが変更されたときに、その AI エージェン
トに送信されます。
AITHREAT_SUSPECT < AITHREAT_INTERESTING < AITHREAT_THREATENING <
AITHREAT_AGGRESSIVE。
ターゲットなし
名前
パラメーター
OnNoTarget
説明
注意ターゲットが消失した。
サウンド
サウンドあり (表示されるターゲットなし)。
名前
パラメーター
説明
OnSuspectedSoundHeard
脅威は AITHREAT_SUSPECT
OnInterestingSoundHeard
脅威は AITHREAT_INTERESTING
Version 1.6
91
Lumberyard 開発者ガイド
シグナル
名前
パラメーター
説明
OnThreateningSoundHeard
脅威は AITHREAT_THREATENING
OnEnemyHeard
脅威は AITHREAT_AGGRESSIVE
メモリ
ターゲットは非表示で、メモリにあります。
名前
パラメーター
説明
OnEnemyMemory
脅威は AITHREAT_THREATENING
OnLostSightOfTarget
脅威は AITHREAT_AGGRESSIVE
OnMemoryMoved
脅威は AITHREAT_AGGRESSIVE であり、その
場所または所有者が変更された
表示
ターゲットは表示されています。
名前
パラメーター
説明
OnSuspectedSeen
脅威は AITHREAT_SUSPECT
OnSomethingSeen
脅威は AITHREAT_INTERESTING
OnThreateningSeen
脅威は AITHREAT_THREATENING
OnEnemySeen
distance
脅威は AITHREAT_AGGRESSIVE
OnObjectSeen
distance、data
AI はこのシグナルが登録されているオブ
ジェクトを確認します。data.iValue = AI
object type (例: AIOBJECT_GRENADE または
AIOBJECT_RPG)
OnExposedToExplosion データ
AI は data.point での爆発の影響を受けます
OnExplosionDanger
破壊可能オブジェクトが爆発します
プレイヤの認識
名前
パラメーター
説明
OnPlayerLooking
sender、data
プレイヤは entity.Properties.awarenessOfPlayer
秒間 AI を見ています。data.fValue = プレイヤの
距離
OnPlayerSticking
支払人
プレイヤは
<entity.Properties.awarenessOfPlayer> 秒間以上
AI の近くにいます
OnPlayerLookingAway
支払人
プレイヤは停止して AI を見ています
OnPlayerGoingAway
支払人
プレイヤは停止して AI の近くにいます
Version 1.6
92
Lumberyard 開発者ガイド
シグナル
注意ターゲットの認識
名前
パラメーター
説明
OnTargetApproaching
OnTargetFleeing
OnNewAttentionTarget
OnAttentionTargetThreatChanged
OnNoTargetVisible
OnNoTargetAwareness
OnSeenByEnemy
支払人
AI は敵に確認されています
名前
パラメーター
説明
OnBulletRain
支払人
敵が射撃しています
OnDamage
sender、data
AI は別の友好的/未知の AI によって破損しまし
た。data.id = 損傷を与えた AI のエンティティ
ID
OnEnemyDamage
sender、data
AI は敵 AI によって破損しました。data.id = 損傷
を与えた敵のエンティティ ID
パラメーター
説明
武器による損傷
近接
名前
OnCloseContact
敵は AI に近い距離に近づいています (この AI の
Lua プロパティ "damageRadius" で定義されて
いる)
OnCloseCollision
車両
名前
パラメーター
説明
OnVehicleDanger
sender、data
車両は AI の方に向かっています。data.point =
車両の移動方向、data.point2 = 車両に対する AI
の方向
OnTargetTooClose
sender、data
注意ターゲットが現在の武器の射程範囲に対し
て近づき過ぎています (AI が車両の場合にのみ動
作します)
OnTargetTooFar
sender、data
注意ターゲットが現在の武器の射程範囲に対し
て近づき過ぎています (AI が車両の場合にのみ動
作します)
OnEndVehicleDanger
Version 1.6
93
Lumberyard 開発者ガイド
シグナル
名前
パラメーター
説明
OnTargetDead
ユーザー定義
注意ターゲットが特定の範囲を入ったり出たりしたときに、カスタムシグナルを送信できます。これ
は以下の Lua 関数を使用して設定されます。
AI.ResetRanges(entityID);
AI.AddRange(entityID,range, enterSignal, leaveSignal);
AI.GetRangeState(entityID, rangeID);
AI.ChangeRange(entityID, rangeID, distance);
武器関連のシグナル
名前
パラメーター
説明
OnLowAmmo
OnMeleeExecuted
OnOutOfAmmo
OnReload
AI のクリップ空になった後に、AI は自動再ロー
ドになっています
OnReloadDone
再ロードが完了しました
OnReloaded
ナビゲーションシグナル
経路探索
名前
パラメーター
説明
OnEndPathOffset
支払人
AI が経路をリクエストし、経路の終点が目的地
から離れています。
OnNoPathFound
支払人
AI が不可能な経路をリクエストしました
OnBackOffFailed
支払人
AI が "バックオフ" 目標の実行を試行しましたが
失敗しました
OnPathFound
支払人
AI が経路をリクエストし、それが正常に計算さ
れました
名前
パラメーター
説明
OnSteerFailed
OnPathFindAtStart
操縦
Version 1.6
94
Lumberyard 開発者ガイド
シグナル
スマートオブジェクト
名前
パラメーター
説明
OnEnterNavSO
OnLeaveNavSO
OnUseSmartObject
ナビゲーションシェイプ
名前
パラメーター
説明
OnShapeEnabled
OnShapeDisabled
戦略シグナル
タクティカルポイントシステム
名前
パラメーター
説明
OnTPSDestNotFound
OnTPSDestFound
OnTPSDestReached
名前
パラメーター
説明
OnHighCover
OnLowCover
OnMovingToCover
OnMovingInCover
OnLeaveCover
OnCoverCompromised
名前
パラメーター
説明
OnGroupChanged
OnGroupMemberMutilated OnGroupMemberDiedNearest
射程
OnEnterCover
グループシグナル
Version 1.6
95
Lumberyard 開発者ガイド
シグナル
フォーメーション
名前
パラメーター
説明
OnNoFormationPoint
支払人
AI はフォーメーションポイントを見つけること
ができませんでした
OnFormationPointReached
OnGetToFormationPointFailed
グループの調整
グループターゲットはグループの最大の脅威であるターゲットです。
名前
パラメーター
説明
OnGroupTargetNone
OnGroupTargetSound
OnGroupTargetMemory OnGroupTargetVisual
PerformingRole
フローグラフのシグナル
これらは、対応するフローグラフノードがアクティブ化されたときに送信されるシグナルです。
名前
パラメーター
説明
ACT_AIMAT
AI:AIShootAt
ACT_ALERTED
AI:AIAlertMe
ACT_ANIM
AI:AIAnim
ACT_ANIMEX
AI:AIAnimEx
ACT_CHASETARGET
Vehicle:ChaseTarget
ACT_DIALOG
AI:ReadabilityDialog (Dialog System でも送信)
ACT_DIALOG_OVER
Dialog System で送信
ACT_DUMMY
ACT_DROP_OBJECT
AI:AIDropObject
ACT_ENTERVEHICLE
Vehicle:Enter
ACT_EXECUTE
AI:AIExecute
ACT_EXITVEHICLE
Vehicle:Exit、Vehicle:Unload
ACT_FOLLOW
AI:AIFollow
ACT_FOLLOWPATH
AI:AIFollowPath、AI:AIFollowPathSpeedStance、Vehicle:FollowPath
Version 1.6
96
Lumberyard 開発者ガイド
シグナル
名前
パラメーター
説明
ACT_GRAB_OBJECT
AI:AIGrabObject
ACT_GOTO
ユーザーがマウスの中央ボタンクリックした場
合は、AI:AIGoto、AI:AIGotoSpeedStance、およ
び AI デバッガー。
ACT_JOINFORMATION AI:AIFormationJoin
ACT_SHOOTAT
AI:AIShootAt
ACT_USEOBJECT
AI:AIUseObject
ACT_VEHICLESTICKPATH
Vehicle:StickPath
ACT_WEAPONDRAW
AI:AIWeaponDraw
ACT_WEAPONHOLSTER AI:AIWeaponHolster
ACT_WEAPONSELECT AI:AIWeaponSelect
その他のシグナル
強制実行
名前
パラメーター
説明
OnForcedExecute
OnForcedExecuteComplete
アニメーション
名前
パラメーター
説明
AnimationCanceled
名前
パラメーター
説明
OnFallAndPlay
名前
パラメーター
説明
OnActorSitDown
アクターが車両に入り
ました
名前
パラメーター
説明
OnSomebodyDied
Game
車両関連
分隊
Version 1.6
97
Lumberyard 開発者ガイド
シグナル
名前
パラメーター
説明
OnBodyFallSound
OnBodyFallSound
OnUnitDied
OnSquadmateDied
OnPlayerTeamKill
OnUnitBusy
OnPlayerDied
名前
パラメーター
説明
OnFriendInWay
支払人
AI が射撃しようとしていますが、その射撃方向
に友好的な別の AI がいます
データ
このエージェントの AI アクションが完了しま
した。data.ObjectName はアクションの名前で
す。data.iValue の値は、アクションがキャンセ
ルされた場合は 0、正常に完了した場合は 1 で
す。data.id は AI アクションの "そのオブジェク
ト" のエンティティ ID です
URPRISE_ACTION
OnActionDone
Version 1.6
98
Lumberyard 開発者ガイド
アニメーションの概要
アニメーション
このセクションでは、Lumberyard のアニメーションシステムについて説明します。主要な概念につい
て説明し、プログラムによるシステムの操作に関する情報も提供します。
このセクションでは、次のトピックについて説明します。
• アニメーションの概要 (p. 99)
• アニメーションイベント (p. 102)
• Limb IK テクニカル (p. 103)
• アニメーションストリーミング (p. 103)
• アニメーションのデバッグ (p. 106)
• 落下と再生 (p. 111)
• アニメーションシステムにおける時間 (p. 112)
アニメーションの概要
Lumberyard で目指したのは、アニメーションの境界を広げ、すべてをリアルタイムでレンダリングす
ることです。Lumberyard には、線形アニメーションとインタラクティブアニメーションの両方を作成
するためのツールが用意されています。
• 線形アニメーションとは、動画やカットシーンなどに見られるアニメーションの種類のことで、ビ
デオとして再生されます。
• インタラクティブアニメーションは、AI およびアバター (プレーヤー) の動作を表現する場合に使用
されます。これらのアニメーションでは、ゲームプレイでのプレーヤーの選択に応じてシーケンス
が変化します。
プレーヤーにとっては、どちらもキャラクターが画面上を動いているようにしか見えないため、この
違いがよくわからないかもしれませんが、アニメーションの種類によってアニメーションをゲームに
組み込む方法は大きく異なります。その大きな違いは、意思決定プロセス (画面上のキャラクターが次
に何をするかを決定する人物) にあります。
線形アニメーション
線形アニメーションの場合、意思決定プロセスは、アニメーションを設計した人の頭の中で行われま
す。このプロセスでは、アニメーターは、すべてのキーフレームを細かく直接制御することができま
Version 1.6
99
Lumberyard 開発者ガイド
インタラクティブアニメーション
す。アニメーターは、衝突の検出、物理法則、パスの検索などを考える必要はありません。アニメー
ターが望まない限り、キャラクターが壁にぶつかったり、キャラクターどうしがぶつかったりするこ
とはありません。プレーヤーの動作に合わせて AI の動作を反応させる必要はありません。ストーリー
ボードを書いている人物がキャラクターの知能を決定することができます。キャラクターどうしのや
り取りを表示するには、役者にモーションキャプチャスーツを着させて、演技を記録することができ
ます。
線形アニメーションシーケンスでは、アニメーションの間、見る位置が変わらないため、1 つのカメ
ラアングルからアクションを表示する必要があります。その結果、アニメーターは、移行やモーショ
ンの組み合わせについて考える必要はなく、モーションクリップのすべての要素を制御することがで
きます。すべてが決まっており、予測可能なため、一貫したモーションの質を保証することができま
す。アニメーターは、いつでも戻ってシーンの詳細 (キーフレームを追加または削除したり、照明を調
整したり、カメラの位置を変更したりなど) を調整することができます。
線形アニメーションを作成するうえでの技術的な課題は、フレームレートの低下や顔と胴体のアニ
メーションのずれなど、主にレンダリングに関する問題と関係があります。
Lumberyard では、線形アニメーションは、すべて トラックビューエディタ を使用して作成します。
インタラクティブアニメーション
インタラクティブアニメーションを作成するには、非常に困難な課題に取り組む必要があります。ア
ニメーターやプログラマーは、画面上のキャラクターの動きを直接制御することはできません。意思
決定プロセスがどこでどのように行われるかがよくわからないこともあります。意思決定プロセスで
は、通常、AI システム、プレーヤーの入力、場合によってはコンテキストに依存する動作が複雑に絡
まり合っています。
定義によれば、インタラクティブアニメーションとは、応答することができるアニメーションのこと
です。個々のユーザーの入力に合わせて見た目を変化させ、画面上のアクションに自動的に順応す
ることができなければなりません。線形アニメーションからインタラクティブアニメーションに移行
するには、単に微調整をいくつか行ったり、少し複雑にしたりする以上のことが必要になります。そ
れには、まったく異なるテクノロジーを搭載する必要があります。インタラクティブアニメーション
では、アニメーターは、キャラクターの動作を正確に計画したりモデル化したりすることはできませ
ん。代わりに、アニメーターやプログラマーは、モーションを自動的に合成することができるシステ
ムを開発し、キャラクターの動作に関するルールを定義します。
自動モーション合成は、アニメーションをよりインタラクティブにするうえで重要な機能です。キャ
ラクターが取る可能性があるアクションのシーケンスを予測するのは難しく、各アクションが任意の
時点で開始されるため、モーションを合成するシステムには非常に高い柔軟性が求められます。
たとえば、キャラクターが屋外を移動している場面を想像してみてください。少なくとも、設計者
は、キャラクターの移動スタイル、移動速度、および移動方向を指定する必要があります。また、坂
道を走って上り下りするとき、体を傾けて角を走って曲がるとき、またはさまざまなサイズの荷物を
運んでいるときなど、モーションにバリエーションを持たせる必要もあります。たとえば、ピストル
を持っているときでは、ロケットランチャーを抱えているときに比べて速く走る必要があります。さ
らに、喜び、怒り、怖れ、疲れなどの感情を表す特徴をインタラクティブに制御する必要があるかも
しれません。加えて、キャラクターが複数のタスクを同時に行う必要がある場合があります。たとえ
ば、特定の方向に歩きながら、別の方向に飛ぶ鳥を振り返って目で追ったり、別の方向に動く物体に
銃を向けたりする必要がある場合があります。考えられるすべての組み合わせおよび自由度に対して
固有のアニメーションアセットを提供することはほぼ不可能です。もしできたとしても、膨大な量の
データが必要になります。アセットの数をできるだけ抑えるには、モーションを変更するメカニズム
が必要になります。
そのようなシステムを開発するには、プログラマー、アニメーター、および設計者が緊密に共同し、
意見を交わす必要があります。通常、動作および移動システム (応答性またはモーションの質) に関す
る問題については、多方面からアプローチする必要があります。
インタラクティブアニメーションは、アバターコントロールと AI コントロールの 2 つのカテゴリに分
類できます。いずれの場合も、キャラクターの次のアクションに関する意思決定は別のところで行わ
Version 1.6
100
Lumberyard 開発者ガイド
インタラクティブアニメーション
れるため、アニメーターおよびプログラマーはゲームプレイでの実際のキャラクターの動作を間接的
に制御することしかできません。ゲーム環境での状況を詳しく見てみましょう。
アバターコントロール
アバターキャラクターは、ゲームプレーヤーによって制御されます。アバターのすべてのアクション
は、プレーヤーの意思決定によって決定されます。移動システムは、プレーヤーの入力を取得し、(手
続き型およびデータ駆動型の方法によって) 瞬時にスケルトンの動作に変換します。アバターコント
ロールでは、応答性を高めることが最優先されますが、ゲームのルールによってモーションの質が制
限されることがあります。このため、アニメーションの見た目を良くするために多くのルールを念入
りに作成すると、ある種のゲームプレイに必要な応答性を実現できなくなります。
画面上で実行されるアニメーションの質は、キャラクターを操作している (アバターの次のアクション
を決定している) 各プレーヤーのスキルや意思決定に大きく依存します。プレーヤーのアクションは予
測できないため、予測に基づいてモーションを計画することはできません。複雑な感情を制御するこ
ともできません (おそらくその必要もありません)。できるとしても、優しく叩くか、力いっぱい叩く
かといった初歩的なレベルに限られます。ただし、プレーヤーがアバターの移動を制御できるように
したり、ゲームの状況に基づいて "付加的なアニメーション" をブレンドすることによってゲームコー
ドでアバターの感情的な動作を制御したりすることはできるかもしれません。
いずれのシーンでも、プレーヤーがゲームパッドを使用してキャラクターを操作します。アニメー
ターによって作成されたアニメーションアセットを使用して、キャラクターが画面に表現されます。
AI コントロール
AI キャラクターの場合、意思決定プロセスは、ゲームコードの内部で行われます。ゲーム開発者は、
動作を生成するシステムを設計します。このシステムは、ゲーム作成者とプレーヤーの間を仲介する
役割を果たします。システムがこのタスクを行うには、ゲーム設計者がキャラクターの種類ごとに動
作のルールを明確に定義するなど、動作に関する意思決定や AI キャラクターのパラメーターを明示
的に指定する必要があります。AI キャラクターのインタラクティブアニメーションを完成させるの
は、アバターのアニメーションを完成させるよりも大変ですが、モーションの質を向上させることが
できる場合が多々あります (ただし、必ずしもわかりやすい場合であるとは限りません)。応答性を高
めることが最優先されるのはもちろんですが、キャラクターの選択がゲームコードの内部で行われる
ため、状況によってはキャラクターのアクションを予測できる場合があります。AI キャラクターが次
に何を行おうとしているかを AI システムが把握できる場合、それらの情報をモーションの計画に組み
込むことができます。モーションを適切に計画することで、インタラクティブアニメーションにより
古典的な "優れた" アニメーションルールを適用できる場合があります。その結果、AI コントロールで
は、より複雑なテクノロジーを搭載する必要はありますが、アバターコントロールに比べてモーショ
ンの質をいくらか高めることができます。
それらの予測システムで不確実なのは、プレーヤーだけです。AI は、プレーヤーに合わせて反応する
ことはできますが、プレーヤーのアクションを予測することはできません。その結果、ゲームのすべ
ての状況に対して適切なアセットを作成することはほぼ不可能です。このため、一貫したモーション
の質を保証することもできません。インタラクティブアニメーションを作成するアニメーターにとっ
て、最終的なアニメーションを直接制御できない (いつ作業が終わるかはっきりしない) ことは、大き
な問題となることがあります。このことは、動画やカットシーンでは線形アニメーションが優れてお
り、インタラクティブアニメーションは面倒である場合がある理由の 1 つです。
Lumberyard では、インタラクティブアニメーションに伴う問題にさまざまなレベルで取り組んでいま
す。
• 低レベルの CryAnimation システムライブラリでは、エンジンによって、アニメーションクリップ、
アニメーションのパラメーター化、手続き型の姿勢変更がサポートされています。アニメーション
は、まとめてシーケンス化するか、階層型移行キューで階層状に重ねることができます。
• 高レベルの CryAction ライブラリでは、CryMannequin システムによって、複雑なアニメーション
のバリエーション、アニメーション間の移行、その他の多数のアニメーションから構築されたアニ
メーション、手続き型コードのシーケンス、ゲームコードへのリンクなどが管理しやすくなってい
ます。
Version 1.6
101
Lumberyard 開発者ガイド
スクリプトアニメーション
スクリプトアニメーション
インタラクティブアニメーションは線形アニメーションよりはるかに困難であるため、多くのゲーム
では、インタラクティブスクリプトシーケンスを使用して、カットシーンとゲームアクションの境界
を曖昧にさせています。
その場合、キャラクターは事前に定義されたパスに従って行動します。この種類のモーションでは、
質を大幅に向上させることができます。完全にインタラクティブではないため、アニメーターは、
モーション計画を手動で設計するように、シーケンス全体をより細かく制御することができます。
これらは、解決が困難なアニメーションの問題を克服するためのまったく合理的な "騙し" と言えま
す。AI シーケンス全体のスクリプトを作成し、カットシーンに劣らない質を実現することもできま
す。そのアクションは、インタラクティブなフィーリングとシネマティクスのような見た目ですが、
実際はインタラクティブのように見えているだけです。
Crysis では、Crytek の設計者が多くのシーンでスクリプトアニメーションを活用していま
す。"Sphere" カットシーンでは、ハンターが上り坂や下り坂を歩いたり、障害物をまたいだりしてい
るように見えます。これはスクリプトシーケンスで、平坦な地面を歩くアセットを作成し、CCD-IK
を使用してキャラクターの脚を起伏のある地形に順応させています。航空母艦の甲板にハンターが出
現する "Fleet" カットシーンでは、プレイしていない他のキャラクターとハンターが戦闘している間、
プレーヤーは動き回ることができます。
これらのシーンは、いずれも非常にインタラクティブな見た目とフィーリングですが、実際はそうで
はありません。ハンターはプレーヤーに応答しておらず、プレーヤーもハンターと戦闘することは
できません。これらのシーンは、スクリプトで決められた完全な線形アニメーションです。アニメー
ションであるだけで、基本的には背景グラフィックです。これらのシーケンスは、トラックビューエ
ディタ で作成されています。一部のシーケンスには、フローグラフ エディタが使用されています。
カットシーンが終了すると、ハンターは AI によって操作されるインタラクティブなキャラクターに変
わります。
アニメーションイベント
Lumberyard のアニメーションでは、アニメーションで特定の時間にカスタムイベントを送信するよ
うにマークアップできます。このマークアップは、時間整列ブレンドに使用されます (たとえば、ア
ニメーションのフットプリントに合わせるために)。アニメーションイベントのもうひとつの適用は、
ちょうど良いタイミングでパーティクル効果を出すことです。
これらのイベントは、近接システムとの組み合わせなどの所定のポイントにアニメーションがいつ到
達するかに関する情報を受信する必要があるさまざまなシステムでも使用できます。
イベントによるアニメーションのマークアップ
アニメーションのイベントは、キャラクターが登場したするときにロードされている XML ファイルに
格納されています。自動的にそうなるように、chrparams ファイルにデータベースを含めておく必要
があります。
ゲームコードでのアニメーションイベントの受信
アニメーションイベントがトリガーされると、そのイベントはゲームオブジェクトに渡されます。ア
クターとプレイヤの両方の実装で、これらアニメーションイベントが処理されます。この関数につい
ては、Actor.cpp または Player.cpp を参照してください。
void AnimationEvent(ICharacterInstance *pCharacter, const AnimEventInstance
&event)
Version 1.6
102
Lumberyard 開発者ガイド
Limb IK テクニカル
Limb IK テクニカル
Lumberyard のアニメーションシステムではキャラクターの IK チェーンをセットアップできます。
IK チェーンがアクティブな場合、エンドエフェクタ (通常、手または足) がターゲットの位置に到達す
るチェーンのジョイント角度を計算します。
セットアップ
IK チェーンは chrparams ファイルで定義されます。
コードからの LimbIK の使用
アニメーションシステム以外から Limb IK チェーンを有効にするには、ISkeletonPose インター
フェイスからアクセス可能な関数 SetHumanLimbIK を使用します。SetHumanLimbIK 関数は、
アクティブにする IK チェーンの各フレームで呼び出す必要があります。Limb IK チェーン名は
chrparams ファイル内で定義されます。
ISkeletonPose& skeletonPose = ...;
skeletonPose.SetHumanLimbIK(targetPositionWorldSpace, "RgtArm01");
アニメーションストリーミング
アニメーションはメモリを非常に大量に使用し、大量のリソースを使用しがちです。メモリの予算に
制限があり、アニメーション化されたジョイントの数が多くなり、高品質のアニメーションが要求
されることで、すべてのアニメーションをメモリ内に継続的にロードし続けることはプロジェクトに
とって無駄です。
Lumberyard のアニメーションシステムは、必要に応じてアニメーションリソース内 (ファイル単位の
レベル) でストリーミングを行い、それらが必要なくなったときにアンロードすることでこの問題を軽
減します。アセットファイルのストリーミングは DGLINK ストリーミングシステムの使用によって達
成されます。アセットの内側と外側でストリーミングを行うことで、必要なリソースのみをメモリ内
に保持できますが、こうすることで、アニメーションリソースの使用方法とそのタイミングを計画す
る必要があるため、複雑さという犠牲をはらうことになります。
アニメーションデータ
アニメーションデータの使用量は 2 つの主要なセクションに分割されます。
• ヘッダーセクションは、アニメーションの一般的な情報 (ファイル名、期間、フラグなど) を示しま
す。
• コントローラーセクションは、アニメーション曲線を示します。関連するジョイントについて、こ
のセクションにはジョイントがそのアニメーションを再生するために必要となるすべての位置と方
向の値に関する情報が含まれます。圧縮された場合でも、コントローラーデータは、アニメーショ
ンに必要な合計メモリの 95% 以上を簡単に使用します。
アニメーションのヘッダーデータ
アニメーションのヘッダーデータは CAF ファイルと animations.img ファイルに保存されます。
CAF ファイルには、1 つのアニメーションのヘッダー情報が含まれていますが、animations.img に
は、ビルド内のすべてのアニメーションのヘッダー情報が含まれています。animations.img は、す
べてのアニメーションをリソースコンパイラを使用して処理する結果として得られます。
Version 1.6
103
Lumberyard 開発者ガイド
アニメーションコントローラーデータ
エンジンは通常、すべてのアニメーションファイルのヘッダーを個別のファイルからロードするので
はなく animations.img ファイルからロードします (個別のファイルから情報を読み取ると、ロード
時間が大幅に長くなる可能性があります)。
コントローラーとヘッダーのサイズの差が激しいため、Lumberyard がメモリの内部と外部でストリー
ミングするのはコントローラーデータのみです。すべてのアニメーションのヘッダーデータは、その
情報をいつでも利用できるようにしておくことが実用的であるため、常にメモリ内に保持されます。
Note
開発中は (たとえばローカルアニメーションファイルを使用して作業している場
合)、animations.img を使用できないようにしておく必要があり、代わりにヘッダー情報を
個別の CAF ファイルからロードする必要があります。そのためには、エンジンが起動する前
に ca_UseIMG_CAF コンソール変数を 0 に設定します。
アニメーションコントローラーデータ
アニメーションのコントローラーデータは CAF ファイルまたは DBA ファイル。
• CAF ファイルには 1 つのアニメーションのコントローラー情報が含まれます。
• DBA ファイルにはアニメーションのグループのコントローラー情報が含まれます。
DBA がロードされると、その DBA に含まれるすべてのアニメーションのコントローラーは DBA がア
ンロードされるまで利用できます。そのため、同じ DBA でまとめて使用されるアニメーションをグ
ループ化すると便利です。同様のアニメーションをまとめて 1 つの DBA に追加することには、等し
いコントローラーが保存されるのが一度だけであるというさらなる利点があります。これにより、ア
ニメーションのメモリ使用量が減少します。
コントローラーデータのロード
アニメーションシステムがアニメーションを適切に再生するのは、コントローラーがメモリ内にある
場合のみです。
アセットの再生が要求されるときにコントローラーデータが利用できない場合、アニメーションシス
テムはコントローラーデータをディスクからストリーミングします。コントローラーデータのスト
リーミングは非同期で実行されます。つまり、アニメーションシステムはアセットの再生が要求され
るまで待機しません。これによって、システムの停止を回避できます。
高レベルのシステムが、コントローラーデータが必要であることをアニメーションシステムに通知で
きない場合 (事前ロード関数のセクションを参照)、アニメーションシステムはアセットの再生が要求
されるまでアセットが必要とされていることがわかりません。これは、コントローラーデータが必要
なタイミングに非常に近づいています。コントローラーデータが適時に利用できない場合、通常は、
たとえばアニメーションが初回のみ再生されるなどの時折みられる表示上の不具合の原因となりま
す。
したがって、アニメーションの再生が要求される前にコントローラーデータのストリーミングをして
おくことが重要です。こうすることで、アニメーションのストリーミングが終了するまで待機する間
に発生する、意図しない不具合を最小限に抑えられます。
ストリーミングの完了に必要な時間は、現在のシステムの負荷、ターゲットシステムのストリーミン
グ速度、ロードに必要なリソースのサイズなどの多くの要素によって異なります。
コントローラーデータのアンロード
アニメーションシステムは、現在使用中のコントローラーデータのアンロードを行いません。
Version 1.6
104
Lumberyard 開発者ガイド
アニメーションコントローラーデータ
ca_DisableAnimationUnloading を 1 に設定することで、アニメーションデータ全体のアンロー
ドを回避できます。
システムによって使用されなくなったことが検出されると、CAF ファイルのコントローラー
はアンロードされます。CAF ファイルのコントローラーがアンロードされないようにするに
は、ca_UnloadAnimationCAF を 0 に設定します。
DBA ファイル内のアニメーションが使用されてから一定の時間が経過するまで DBA ファイルのコン
トローラーはメモリ内に残ります。ただし、DBA がロックされている場合、ロックステータスが 0 に
戻されるまでコントローラーはアンロードされません。
DBA ファイルのコントローラーをアンロードするまでアニメーションシステムが待機する時間を変更
するには、次の cvars を使用します。
• ca_DBAUnloadUnregisterTime – その DBA を使用するコントローラーとすべてのアニメーショ
ンの前回使用時以降のタイムアウト (秒単位)。このタイムアウトに達すると、DBA はコントロー
ラーデータを "unloaded" としてマークします。
• ca_DBAUnloadRemoveTime – DBA のコントローラーの前回使用時以降のタイムアウト (秒単
位)。このタイムアウトに達すると、DBA はメモリからの実際のアンロードを実行します。この値
は、ca_DBAUnloadUnregisterTime 以上にする必要があります。
以下のセクションでは、メモリ内の個々のリソースをロックしてシステムからアンロードされないよ
うにする方法について説明します。
メモリ内のコントローラーの事前ロードおよび保持
事前ロード関数は、アセットがいつ、どのようにアクセスされたかに関する情報の大半を含むため、
ハイレベルなシステムまたはユーザーコード (通常はゲームコード) によって実行されます。たとえ
ば、trackview は、表示されるアニメーションについてタイムラインの数秒後を検索して、事前ロード
関数を呼び出します。
DBA ファイルのコントローラーの事前ロード
DBA のストリーミングを事前ロードしてトリガーするには、次のように入力します。
gEnv->pCharacterManager->DBA_PreLoad(dbaFilename, priority);
DBA ファイルのストリーミングをトリガーし、Locked 状態 (メモリ内でロックすべきかどうかを指定)
への変更を要求するには、次のように入力します。
gEnv->pCharacterManager->DBA_LockStatus(dbaFilename, lockStatus, priority);
DBA 内のすべてのコントローラーデータをメモリからアンロードする (どのコントローラーも現在使
用されていない場合にのみデータをアンロードする) には、次のように入力します。
gEnv->pCharacterManager->DBA_Unload(dbaFilename);
Note
文字がロードされている間にシステムを自動的にロードして DBA ファイルをロックするに
は、chrparams ファイルの flags="persistent" を使用します。
CAF ファイルのコントローラーの事前ロード
CAF ファイルのリファレンス数を増加させるには、次のように入力します。
Version 1.6
105
Lumberyard 開発者ガイド
アニメーションのデバッグ
gEnv->pCharacterManager->CAF_AddRef(lowercaseAnimationPathCRC);
CAF ファイルのコントローラは、リファレンス数が 0 から 1 に変わるとストリーミングを開始しま
す。
CAF ファイルのリファレンス数を減少させるには、次のように入力します。
gEnv->pCharacterManager->CAF_Release(lowercaseAnimationPathCRC);
CAF ファイルのコントローラーは、リファレンス数が 0 に達して初めてアニメーションシステムに
よってアンロードされます (CAF ファイルの再生中にも、このリファレンス数はアニメーションシス
テムによって増加されるため、アニメーションは使用中にアンロードされません)。
CAF ファイルのコントローラがロードされるかどうかを確認するには、次のように入力します。
gEnv->pCharacterManager->CAF_IsLoaded(lowercaseAnimationPathCRC);
CAF ファイルのコントローラーを同期的にロードするには、次のように入力します。
gEnv->pCharacterManager->CAF_LoadSynchronously(lowercaseAnimationPathCRC);
CAF アセットを同期的にロードすると、結果的に停止することになりやすいため、絶対に必要とされ
る場合を除いてお勧めできません。
アニメーションのデバッグ
アニメーション問題をデバッグするためにいくつかのツールが利用可能です。
多層的移行のキューデバッギング
どのアニメーションが並べられてプレイ中であるかの画面上のデバッグ情報および適用されたポーズ
調整機能とIKの情報を有効にすることができます。
エンティティごとに示します。
指定エンティティのすべてのキャラクターインスタンスの移行キューを表示するためには:
es_debuganim <entityname> [0 | 1]
<entityName>
デバッグするエンティティの名前。一人プレーヤーのゲームで、プレーヤーは「dude」とよく呼
ばれます。 GameSDKの例のプレイヤーは、第一者と第三者のキャラクターインスタンスの両方
があります。
[0 | 1]
この特定のエンティティを有効にするために、１を指定するか、秒パラメーターを特定しないで
ください。それを無効にするには、0を指定します。
例
エンティティ名が「dude」のプレイヤーのデバッギングを有効にするには:
Version 1.6
106
Lumberyard 開発者ガイド
多層的移行のキューデバッギング
es_debuganim dude 1
エンティティ名が[npc_flanker_01」のデバッギングを有効にするには:
es_debuganim npc_flanker_01 0
CharacterInstanceごとに表示します。
すべてのキャラクターインスタンスもしくは特定のモデル名を使用しているインスタンスの移行
キューを表示できます。
ca_debugtext [<modelname-substring> | 1 | 0]
<modelname-substring>
モデル名が特定の文字列を含むすべてのキャラクターインスタンスに関する情報を示します。
[0 | 1]
1を指定した場合、すべての文字インスタンスが表示されます。0を指定すると、デバッグのテキ
ストは無効になります。
例
「プレイヤー」をモデル名に含むすべてのキャラクターインスタンスの情報を指定するには:
ca_debugtext player
すべての移行キュー情報を無効にするには:
ca_debugtext 0
出力を解釈する
移行キューの各アニメーションは次の例のように表示されます。この画面のキーエレメントは次の例
のように表示されます。
AnimInAFIFO 02: t:1043 _stand_tac_idle_scar_3p_01 ATime:0.84 (1.17s/1.40s)
ASpd:1.00 Flag:00000042 (----------I-K----) TTime:0.20 TWght:1.00 seg:00
inmem:1
(Try)UseAimIK: 1 AimIKBlend: 1.00 AimIKInfluence: 1.00 (Try)UseLookIK: 0
LookIKBlend: 0.00 LookIKInfluence: 0.00
MoveSpeed: 4.49 locked: 1
PM class: AnimationPoseModifier_OperatorQueue, name: Unknown
...
LayerBlendWeight: 1.00
...
ADIK Bip01 RHand2RiflePos_IKTarget: 0.24 Bip01 RHand2Aim_IKTarget: 1.00 Bip01
LHand2Aim_IKTarget: 0.00
文字色
• アニメーションはまだアクティブでない場合、黒か緑色になります。
• アニメーションがアクティブになったら、赤か黄色になります。
Version 1.6
107
Lumberyard 開発者ガイド
多層的移行のキューデバッギング
詳細しくは:
• レッドチャネル=アニメーションの重さ
• グリーンチャネル= (layerIndex > 0)
• アルファ チャネル= (+ 1) *0.5重み
AnimInAFIFO Line (アニメーションあたり1つ)
AnimInAFIFO 02: t:1043 _stand_tac_idle_scar_3p_01 ATime:0.84 (1.17s/1.40s)
ASpd:1.00 Flag:00000042 (----------I-K----) TTime:0.20 TWght:1.00 seg:00
inmem:1
AnimInAFIFO 02
範囲インデックス (小数点、ゼロベース)
t:1043
ユーザー トークン (小数点)
_stand_tac_idle_scar_3p_01
現在再生中のアニメーション名（機能名）、目標または確認ポーズもしくはbspace
ATime: 0.84 (1.17s/1.40s)
ATime: XXXX (YYYYs/ZZZZs)
• XXXX =現在のセグメント内の「標準化された時間」 (0.0…1.0）の現在時刻
• YYYY = 現在のセグメント内の現在の時刻 (秒)
• ZZZZ = 現在のセグメントで想定される所要時間 (秒)
ASpd: 1.00
現在のアニメーション速度 (1.0 =通常の速度)
Flag: 00000042 (----------I-K----)
アニメーションフラグ
Flag: XXXXXXXX (+ybVFx3nSIAKTRLM)
最初の数字は16進法で表したアニメーションのフラグです
括弧の間に個々のフラグが見えます:
char
flag
value
+
C
0 A_FORCE_TRANSITION_TO_ANIM
x
008000
yC
0 A_FULL_ROOT_PRIORITY
x
004000
bC
0 A_REMOVE_FROM_FIFO
x
002000
V
C
0x001000
A_TRACK_VIEW_EXCLUSIVE
F
C
0 A_FORCE_SKELETON_UPDATE
x
000800
Version 1.6
108
Lumberyard 開発者ガイド
多層的移行のキューデバッギング
char
flag
value
xC
0 A_DISABLE_MULTILAYER
x
000400
3C
0 A_KEYFRAME_SAMPLE_30Hz
x
000200
nC
0 A_ALLOW_ANIM_RESTART
x
000100
S
C
0 A-1
x
000080
IC
0 A-1
x
000040
A
C
0 A_START_AFTER
x
000020
K
CA_START_AT_KEYTIME
0
USD
x
000010
T
C
0 A_TRANSITION_TIMEWARPING
x
000008
R
C
0 A_REPEAT_LAST_KEY
x
000004
LC
0 A_LOOP_ANIMATION
x
000002
M
C
0 A_MANUAL_UPDATE
x
000001
TTime: 0.20
移行時間
秒で表したこのアニメーションへの移行の合計時間 (これはアニメーションを押したあと固定的で
す)
TWght:1.00
移行ウェイト
移行内の (0 =まだフェードインしていない、1 =完全フェードイン) このアニメーションの現在の
ウェイト
seg
現在のセグメントインデックス (ゼロベース)
Version 1.6
109
Lumberyard 開発者ガイド
多層的移行のキューデバッギング
inmem: 1
アニメーションがメモリーにあるかどうか (0 は基本的にまだストリームインしていないことを意
味する)
Aim/Look-IK Line
(Try)UseAimIK: 1 AimIKBlend: 1.00 AimIKInfluence: 1.00 (Try)UseLookIK: 0
LookIKBlend: 0.00 LookIKInfluence: 0.00
(Try)UseAimIK: 1
Aim IKが有効にするかどうか（PoseBlenderAim::SetStateを使用して設定)
AimIKBlend: 1.00
Aim IKへリクエストされたウェイト値 (フェードタイムによって上下することがある、他)
AimIKInfluence: 1.00
AimIKの最終的な影響ウェイト値 (== smoothed(clamped(AimIKBlend)) * weightOfAllAimPoses)
(Try)UseLookIK: 0
Look IKが有効か無効か
LookIKBlend: 0.00
Look IKへリクエストされたウェイト値 (フェードタイムによって上下することがある、他)
LookIKInfluence: 0.00
LookIKの最終的な影響ウェイト値 (== smoothed(clamped(LookIKBlend)) * weightOfAllLookPoses)
パラメーターライン(ブレンドスペースに対してのみ)
MoveSpeed: 4.500000 locked: 1
TravelAngle: 0.000000 locked: 0
MoveSpeed: 4.500000
指定されたブレンドスペースパラメーターの値(この場合MoveSpeed)
ロック済み：１
パラメータが固定するかいなか (=最初に設定されたら変更はできない)
PoseModifier Lines (実行している場合）
PM class: AnimationPoseModifier_OperatorQueue, name: Unknown
このレイヤーでどのポーズ調整機能が実行中かを表示しますクラスおよび名前を表示します (使用可能
な場合)。
LayerBlendWeight Line (レイヤー0ではない)
LayerBlendWeight: 1.00
このレイヤーのウェイト(0.00 - 1.00)
ADIK Line (アニメーション駆動型IKが適用されている場合にのみ)
ADIK Bip01 RHand2RiflePos_IKTarget: 0.24 Bip01 RHand2Aim_IKTarget: 1.00 Bip01
LHand2Aim_IKTarget: 0.00
Version 1.6
110
Lumberyard 開発者ガイド
CommandBufferのデバッギング
アニメーション駆動型IKターゲットとそれらの現在のウェイトを表示します。さらに詳細な場所・更
新情報については、別個のcvar使用しますca_debugadiktargets 1。
CommandBufferのデバッギング
最低レベルで、アニメーションシステムは最終的な骨組のポーズを組み立てるためのシンプルなコマ
ンドリストを実行します。
例えば、「ample animation x at time t, and add the result with weight w to the pose」のコマンドで
す。または「clear the pose」など。
何がコマンドバッファー（すべてのキャラクター0）に対して押されているのかを確認するための画面
上のデバッグ情報を有効にするには、次のコマンドのデバッグを使用してください:
ca_debugcommandbuffer [0 | 1]
警告レベル
いつアニメーションシステムがca_animWarningLevelを使用して警告を出すかをコントロールするに
は:
ca_animWarningLevel [0 | 1 | 2 | 3]
0
1
非致命的警告はオフです
違法行為の警告をする。
例えば、無効なインデックスを使用してアニメーションを再生するリクエスト等。
2
また、「パフォーマンスの問題」などの内容についても警告します。
例えば、アニメーションキューがいっぱいになること。この警告は、問題発生時に山のようなア
ニメーションキューをコンソールに送信するスパムのような働きにもなります。
3 (デフォルト)
すべての警告はオンです。これは重要性の非常に低い警告も含みます。例えば、圧縮されていな
いアニメーションデータを再生するときの警告です。
落下と再生
"落下と再生" は、キャラクターが 0 より大きい硬さでラグドール化されるときにアクティブ化され
ます (インターフェイスレベルでは RelinquishCharacterPhysics と呼ばれます)。これにより、
現在のアニメーションフレームで指定されている角度にジョイントを合わせようとする物理的なラグ
ドールにおいて、角度ばねがアクティブ化されます。キャラクターも現在の落下と再生のステージに
基づいて、アニメーションの選択を内部的に試みます。物理的な接触がない、またはほとんどない場
合、落下アニメーションになります。そうでない場合は、現在の身体方向に対応した、最初のフレー
ム (スタンドアップアニメーション) になります。
スタンドアップアニメーションは、落下と再生の関数を使用して、アニメーションシステム外から開
始されます。スタンドアップアニメーションの間、キャラクターの物理特性はアライブモードに切り
替えられ、最終的な物理姿勢は対応するスタンドアップアニメーションにブレンドされます。ここで
も、この姿勢に最適なアニメーションがスタンドアップアニメーションのリストから選択されます。
Version 1.6
111
Lumberyard 開発者ガイド
アニメーションシステムにおける時間
スタンドアップアニメーションのファイル名変換: アニメーション名が "standup" で始まっている場
合、スタンドアップアニメーションとして登録されます。また、スタンドアップアニメーションを
"standup_" およびいくつかのキーワード ("back"、"stomach"、"side") の文字列で分類するタイプのシ
ステムも存在します。CSkeletonPose::SetFnPAnimGroup() メソッドで使用するタイプを制御で
きます。実行時に、エンジンは横たわっている現在の姿勢に登録されているスタンドアップアニメー
ションのうち、最も類似性の高いものを確認し、ブレンドします。
ファイル名の例:
• standUp_toCombat_nw_back_01
• standUp_toCombat_nw_stomach_01
キャラクターがラグドールのままでも、GoLimp メソッドを使用して硬さをオフにすることもできま
す。
アニメーションシステムにおける時間
アニメーションシステムでは、システムに応じて異なる "時間" 単位が使用されます。これらの時間単
位の違いを説明するには、例を示すのが一番です。
"フレーム" の定義: アニメーションシステムでは、30 フレーム/秒 (fps) の固定レートが使用されしま
す。もちろん、より高いフレームレートでゲームを実行することもできますが、エディタの一部の操
作では "フレーム" の概念が使用され、アニメーションの長さが "1 フレーム" に固定されていることが
あります。この場合、フレームレートは 30 fps であると想定されます。
たとえば、長さが 1.5 秒のアニメーションがあるとします。つまり、このアニメーションには 46 フ
レームが含まれています。実時間の場合、アニメーションは時間 0 から開始され、セグメント化され
ておらず、標準の速度で再生されると見なされます。ただし、アニメーションシステムでは、実時間
ではなく正規化されたアニメーション時間が使用されるのが一般的です。実時間との比較を次の表に
示します。
フレームインデックス
実時間 (秒)*
正規化されたアニメーション時
間**
0
0.0 s
0.0
1
0.033.. s = 1/30 s
0.022.. = 1/45
..
..
..
30
1.0 s
0.666.. = 30/45
..
..
..
44
1.466.. s = 44/30 s
0.977.. = 44/45
45
1.5 s = 45/30 s
1.0
* 実時間は時間長を定義するために使われます:
• Duration = lastFrame.realTime - firstFrame.realTime。この例では 1.5 秒です。
• IAnimationSet::GetDuration_sec() は、アニメーションの長さを返します。
注意: パラメトリックアニメーションでは、大まかな概算としてすべての標本の平均時間長が返され
るだけで、パラメーターや速度のスケーリングは無視されます。
Version 1.6
112
Lumberyard 開発者ガイド
セグメント化
• CAnimation::GetExpectedTotalDurationSeconds() 現在再生中のアニメーションの長さを
返します。
注意: パラメトリックアニメーションでは、現在設定されているパラメーターがアニメーション全体
を通して変わらないと想定した場合の大まかな概算が返されるだけです。
• アニメーションの実時間を返す関数はありません。これを計算するには、正規化されたアニメー
ション時間に手動で長さを乗算する必要があります。
** 正規化されたアニメーション時間:
• アニメーション全体の長さに対する相対的な時間。
• アニメーションの先頭が開始位置 0 となり、1 (= RealTime/Duration = Keytime/LastKeyTime) で終
了します。
• ISkeletonAnim::GetAnimationNormalizedTime() や
ISkeletonAnim::SetAnimationNormalizedTime() などの関数で使用されます。
• セグメント数が異なる標本を含むパラメトリックアニメーションの場合、正確ではありません。詳
細については、次の「セグメント化」セクションを参照してください。
セグメント化
実際には、正規化されたアニメーション時間はアニメーションシステムで使用されません。この用語
は導入部をわかりやすくするために使用したものです。通常使用されるのは、正規化されたセグメン
ト時間です。正規化されたセグメント時間について理解するには、まずセグメント化について理解す
る必要があります。
アニメーションは、タイムワープ (位相整合) の目的で複数のセグメントに分割できます。たとえ
ば、2 サイクルの歩くアニメーションから 1 サイクルの歩くアニメーションにタイムワープするに
は、最初のアニメーションにアノテーションを付け、2 つに分割する必要があります (これらがセグメ
ントです)。このセグメント化を行うには、サイクル間の境界に segment1 アニメーションイベントを
追加する必要があります。
Note
セグメント化されていないアニメーションは、最初から最後までを含む 1 つのセグメントだ
けから成ります。
セグメント化により、正規化されたセグメント時間という新しい時間単位が導入されます。これは、
現在のセグメントの長さに対する相対的な時間を表します。
これまでの例を拡張して、1.0 秒の位置に segment1 アニメーションイベントを追加し、アニメーショ
ンを 2 つのセグメントに分割したらどうなるかを見てみましょう。
フレームイン
デックス
実時間
0
AnimEvents
正規化された セグメントイ
(アニメーショ ンデックス*
ン) 時間
正規化された
セグメント時
間**
0.0 s
0.0
0
0.0
1
0.033.. s
0.022..
0
0.033.. = 1/30
..
..
..
..
..
30
1.0 s
0.666..
1
0.0
..
..
..
..
..
segment1
Version 1.6
113
Lumberyard 開発者ガイド
再生速度
フレームイン
デックス
実時間
44
45
AnimEvents
正規化された セグメントイ
(アニメーショ ンデックス*
ン) 時間
正規化された
セグメント時
間**
1.466.. s
0.977..
1
0.933.. = 14/15
1.5 s
1.0
1
1.0
* セグメントインデックス:
• 現在のセグメントを識別します。 値の範囲は、0 からセグメントの総数 - 1 までです。
• アニメーションの再生中に CAnimation::GetCurrentSegmentIndex() を使用して取得できま
す。
• ca_debugtext または es_debuganim の使用時には、このインデックスは "seg:" に続けて表示されま
す。
** 正規化されたセグメント時間:
• 現在のセグメントの長さに対して相対的な時間。
• セグメントの先頭は 0、末尾は 1 (表に示されているように、最終セグメントは 1 のみ)。
• アニメーションの再生中に CAnimation::Get/SetCurrentSegmentNormalizedTime() を使用
すると、正規化されたセグメント時間を取得できます。
• 名前が示すとおり、CAnimation::GetCurrentSegmentIndex() は現在のセグメントインデック
スを取得し、CAnimation::GetCurrentSegmentExpectedDurationSecondsx() は現在のセグ
メントの長さを取得します。
• パラメトリックアニメーション内の時間を表す場合は、正規化されたアニメーション時間を使用す
るよりも、正規化されたセグメント時間を使用する方が便利です。このため、実行時には正規化さ
れたセグメント時間が使用されます。
• AnimEvent の時間は、正規化されたアニメーション時間を使用して指定されます (ただし、パラメ
トリックアニメーションは特殊なケースとして例外です。次のセクションを参照してください)。
• ca_debugtext または es_debuganim の使用時には、正規化されたセグメント時間は "ATime:" に
続けて表示されます。さらに続けて、かっこ内にセグメント内の実時間とセグメントの長さが表示
されます。
再生速度
再生速度は、CAnimation::GetExpectedTotalDurationSeconds() や
ISkeletonAnim::CalculateCompleteBlendSpaceDuration() など、再生するアニメーション
の長さを計算する関数には影響を与えません。
セグメント化されたパラメトリックアニメーション
セグメント化されたパラメトリックアニメーションでは、正規化されたアニメーション時間、セグメ
ントインデックス、時間長はいずれもあいまいになります。これは、パラメトリックアニメーション
内の各標本アニメーションが、独自の数のセグメントを含んでいる可能性があるためです。あいまい
さを回避するために、セグメント化されたパラメトリックアニメーション内のアニメーションイベン
トでは、正規化されたセグメント時間が使用されます。その結果、アニメーションイベントは、アニ
メーション中に複数回 (セグメントごとに 1 回) 発生します。
• ISkeletonAnim::GetAnimationNormalizedTime() が使用するヒューリスティックでは、一
般に、セグメント数が最大の標本アニメーションが検索され、その標本内の正規化されたアニメー
ション時間が返されます。
Version 1.6
114
Lumberyard 開発者ガイド
キーが 1 つだけのアニメーション
• ISkeletonAnim::GetCurrentSegmentIndex() では別のヒューリスティックが使用され、一般
に、標本アニメーション内でリストの先頭にあるセグメントインデックスが返されます。
これを踏まえて、上記の状況は、"パラメトリックアニメーション内のセグメントの合計数は、繰り返
しが開始されるまでのセグメント数として定義される" という所見に基づいて見直すことができます。
ここで、2 つの標本を含むパラメトリックアニメーションがあるとします。1 つは 2 セグメントで、
もう 1 つは 3 セグメントです。この場合、6 セグメント (2 と 3 の最小公倍数) の後に繰り返しが開始
されます。ただし、0 ～ 5 の数値を使用すると、可能性のあるセグメントの組み合わせをそれぞれ一
意に識別できます。
Character Tool では、この方法を使用して時間長を明確に定義していま
す。ISkeletonAnim::CalculateCompleteBlendSpaceDuration() 関数は、パラメトリックア
ニメーションで繰り返しが開始されるまで長さを計算します (パラメーターは固定と見なされます)。
非パラメトリックアニメーションでは標準の GetExpectedTotalDurationSeconds() の実装に戻
るため、一般的な状況でも同じ関数を使用できます。
キーが 1 つだけのアニメーション
通常、アニメーションには少なくとも 2 つのキーがあります。ただし、これらを付加的アニメーショ
ンに変換すると、最初のフレームは付加部分を計算するベースとして解釈され、付加的アニメーショ
ンには 1 フレームだけが残ります (つまり、アセットに関しては、アセットの開始時間と終了時間が
どちらも 1/30 秒に設定されることになります)。
このアニメーション全体の長さを取得する関数は 0.0 を返します (たとえ
ば、IAnimationSet::GetDuration_sec()、ISkeletonAnim::CalculateCompleteBlendSpaceDuration()、C
があります)。
ただし、アニメーションシステムによる再生時には、これらのアニメーションの
長さが 1/30 秒であるかのように処理されます。たとえば、正規化されたアニメー
ション時間は 0 から 1 まで進み、実時間は 0 から1/30 秒まで進みます。この場
合、CAnimation::GetCurrentSegmentExpectedDurationSecondsx() も 1/30 秒を返します。
時間の方向
通常、アニメーションの再生中に時間を巻き戻すことはできません。時間を巻
き戻すことができるのは、アニメーションに CA_MANUAL_UPDATE フラグを設定
し、CAnimation::SetCurrentSegmentNormalizedTime を使用して手動で戻す場合だけで
す。DGLINK の例の CProceduralClipManualUpdateList::UpdateLayerTimes() を参照してく
ださい。
コントローラー内部の時間
実際のキーデータを含み、アニメーションのサンプリングに使われるコントローラーでは、異なる単
位が使用されます。
フレームインデックス
実時間
I_CAF ティック*
キータイム**
0
0.0 s
0
0.0
1
0.033.. s
160
1.0
..
..
..
..
30
1.0 s
4800
30.0
Version 1.6
115
Lumberyard 開発者ガイド
コントローラー内部の時間
フレームインデックス
実時間
I_CAF ティック*
キータイム**
..
..
..
..
44
1.466.. s
7040
44.0
45
1.5 s
7200
45.0
* I_CAF ティック:
• I_CAF ファイル内で時間を表すために使用されます。
• 1 秒あたりの I_CAF ティックは 4800 です (これは現在、Controller.h に TICKS_CONVERT = 160
が定義され、30 キー/秒であるためです)。
** キータイム
• 実行時に、アニメーションのサンプリングを行うコントローラーに時間を渡すために使用されま
す。
• CAF ファイル内で時間を表すために使用されます。
• "フレームインデックス" の浮動小数点バージョンです。
• フレーム間の時間を表すことができます。
• 正規化されたアニメーション時間から Keytime に変換するに
は、GlobalAnimationHeaderCAF::NTime2KTime() を使用します。
• Keytime は、ランタイムのすべてのアニメーションコントローラーで使用されます。
アニメーションアセットでは、StartTime が 0.0 秒以外の場合もあります。この場合はやや複雑になり
ますが、影響を受けるのはコントローラーだけです。通常、コントローラー以外の場所であれば、時
間は StartTime に対して相対的に表されます。
Version 1.6
116
Lumberyard 開発者ガイド
ビルダーモジュール
アセットビルダー API
アセットビルダー API およびビルダー SDK は Lumberyard 1.5 向けのプレビューリリースであり、
改善の過程で変更になる場合があります。
アセットビルダー API を使用してカスタムアセットビルダーを開発し、独自のアセットタイプを作成
できます。アセットビルダーではアセットタイプをいくつでも処理できます。出力を生成してアセッ
トプロセッサーに結果を返し、今後の処理に利用できます。これは、カスタムのあアセットタイプを
使用する大型プロジェクトでは特に便利です。
ビルダーモジュール
ビルダーモジュールは、ライフサイクルコンポーネントと 1 つ以上のビルダーを含む .dll モジュー
ルです。ライフサイクルコンポーネントは AZ::Component から取得されます。ビルダーはどのよう
なタイプでもよく、特定の基本クラス要件はありません。
ライフサイクルコンポーネントの役割は、Activate() の呼び出し中にビルダーを登録
し、Deactivate および Destructor を呼び出したときに使用していないリソースを確実に削除する
ことです。
Version 1.6
117
Lumberyard 開発者ガイド
ビルダーモジュールの作成
ビルダーモジュールの作成
ビルダーモジュールを作成するには、次のステップを実行する必要があります。
• エクスポートされた .dll のエントリポイント関数を作成し、エントリポイント関数の事前宣言を
作成する REGISTER_ASSETBUILDER マクロを呼び出します。
• ライフサイクルコンポーネントの Descriptor を登録します。
• ライフサイクルコンポーネントを Builder エンティティに追加します。
• ライフサイクルコンポーネントの Activate() 関数が呼び出されたときにビルダーのインスタンス
を登録します。
• 安全にシャットダウンします
Note
ビルダーモジュールの全サンプルは、Lumberyard の dev\Code\tools\AssetProcessor
\Builders ディレクトリにあります。このドキュメントを読むときに言及されたサンプルに
従うことをお勧めします。アセットビルダー SDK は、Lumberyard のディレクトリの \dev
\Code\Tools\AssetProcessor\AssetBuilderSDK\AssetBuilderSDK にあります。
メインエントリポイント
以下のコードは、アセットビルダーモジュールの main.cpp ファイルの例です。
#include <AssetBuilderSDK/AssetBuilderSDK.h>
#include <AssetBuilderSDK/AssetBuilderBusses.h>
// Use the following macro to register this module as an asset builder.
// The macro creates forward declarations of all of the exported entry points
for you.
REGISTER_ASSETBUILDER
void BuilderOnInit()
{
// Perform any initialization steps that you want here. For example, you
might start a third party library.
}
void BuilderRegisterDescriptors()
{
// Register your lifecycle component types here.
// You can register as many components as you want, but you need at least
one component to handle the lifecycle.
EBUS_EVENT(AssetBuilderSDK::AssetBuilderBus, RegisterComponentDescriptor,
ExampleBuilder::BuilderPluginComponent::CreateDescriptor());
// You can also register other descriptors for other types of components
that you might need.
}
void BuilderAddComponents(AZ::Entity* entity)
{
// You can attach any components that you want to this entity, including
management components. This is your builder entity.
// You need at least one component that is the lifecycle component.
entity->CreateComponentIfReady<ExampleBuilder::BuilderPluginComponent>();
Version 1.6
118
Lumberyard 開発者ガイド
ライフサイクルコンポーネント
}
void BuilderDestroy()
{
// By the time you leave this function, all memory must have been cleaned
up and all objects destroyed.
// If you have a persistent third party library, you could destroy it
here.
}
ライフサイクルコンポーネント
ライフサイクルコンポーネントは、シリアル化するタイプを反映して、Activate() 関数の呼び出し
中にビルダーをモジュールに登録します。
以下はライフサイクルコンポーネントのコード例です。
//! This is an example of the lifecycle component that you must implement.
//! You must have at least one component to handle your module's lifecycle.
//! You can also make this component a builder by having it register itself
as a builder and
//! making it listen to the builder bus. In this example it is just a
lifecycle component for the purposes of clarity.
class BuilderPluginComponent
: public AZ::Component
{
public:
AZ_COMPONENT(BuilderPluginComponent, "{8872211E-F704-48A9B7EB-7B80596D871D}")
static void Reflect(AZ::ReflectContext* context);
BuilderPluginComponent(); // Avoid initializing here.
//////////////////////////////////////////////////////////////////////////
// AZ::Component
virtual void Init(); // Create objects, allocate memory and initialize
without reaching out to the outside world.
virtual void Activate(); // Reach out to the outside world and connect to
and register resources, etc.
virtual void Deactivate(); // Unregister things, disconnect from the
outside world.
//////////////////////////////////////////////////////////////////////////
virtual ~BuilderPluginComponent(); // free memory and uninitialize
yourself.
private:
ExampleBuilderWorker m_exampleBuilder;
};
次の例では、Activate() 関数でビルダーを登録し、ビルダーの記述子を作成してから、ビルダーの
詳細を提供します。
void BuilderPluginComponent::Activate()
Version 1.6
119
Lumberyard 開発者ガイド
ビルダーの作成
{
// Activate is where you perform registration with other objects and
systems.
// Register your builder here:
AssetBuilderSDK::AssetBuilderDesc builderDescriptor;
builderDescriptor.m_name = "Example Worker Builder";
builderDescriptor.m_patterns.push_back(AssetBuilderSDK::AssetBuilderPattern("*.example",
AssetBuilderSDK::AssetBuilderPattern::PatternType::Wildcard));
builderDescriptor.m_createJobFunction =
AZStd::bind(&ExampleBuilderWorker::CreateJobs, &m_exampleBuilder,
AZStd::placeholders::_1, AZStd::placeholders::_2);
builderDescriptor.m_processJobFunction =
AZStd::bind(&ExampleBuilderWorker::ProcessJob, &m_exampleBuilder,
AZStd::placeholders::_1, AZStd::placeholders::_2);
builderDescriptor.m_busId = ExampleBuilderWorker::GetUUID(); // Shutdown
is communicated on this bus address.
m_exampleBuilder.BusConnect(builderDescriptor.m_busId); // You can use a
global listener for shutdown instead of
// for each
builder; it's up to you.
EBUS_EVENT(AssetBuilderSDK::AssetBuilderBus, RegisterBuilderInformation,
builderDescriptor);
}
注
• 例ではイベントバスを呼び出してビルダーを登録します。ビルダーを登録すると、そのビルダーは
2 つの登録済みコールバック関数からアセットに対するリクエストを受け取ります。
• アプリケーションをシャットダウンする必要がある場合は、登録されたビルダーの UUID のアドレ
スを使用して、アセットプロセッサーから Shutdown() メッセージがビルダーバスにブロードキャ
ストされます。
• ビルダーには、ジョブを作成しそのジョブを処理する以上の関数は必要ありません。ただし、ビル
ダーで Shutdown() メッセージをリッスンする場合は、バスに接続するリスナーが必要です。
ビルダーの作成
次のステップはビルダーを作成することです。ビルダーの数はいくつでもよく、すべてのビルダー
をモジュール内に登録することもできます。前のセクションで説明したとおりにビルダーを登録した
後、CreateJobFunction と ProcessJobFunction という 2 つのコールバックを実装します。
次のコード例では、ビルダークラスが宣言されます。
#include <AssetBuilderSDK/AssetBuilderSDK.h>
class ExampleBuilderWorker : public
AssetBuilderSDK::AssetBuilderCommandBus::Handler // This handler delivers
the "shut down!"
// message on another thread.
{
public:
ExampleBuilderWorker();
Version 1.6
120
Lumberyard 開発者ガイド
ビルダーの作成
~ExampleBuilderWorker();
//! Asset Builder Callback Functions
void CreateJobs(const AssetBuilderSDK::CreateJobsRequest& request,
AssetBuilderSDK::CreateJobsResponse& response);
void ProcessJob(const AssetBuilderSDK::ProcessJobRequest& request,
AssetBuilderSDK::ProcessJobResponse& response);
//////////////////////////////////////////////////////////////////////////
//!AssetBuilderSDK::AssetBuilderCommandBus interface
void ShutDown() override; // When this is received, you must fail all
existing jobs and return.
//////////////////////////////////////////////////////////////////////////
static AZ::Uuid GetUUID();
private:
bool m_isShuttingDown = false;
};
アセットプロセッサーは Shutdown() 関数を呼び出してシャットダウン信号を送信します。この時点
で、ビルダーはすべてのタスクを停止し、アセットプロセッサーに制御を戻します。
注
• アセットプロセッサーがシャットダウンして再起動するときに速やかに停止できなかった場合は、
ハングが発生することがあります。シャットダウンメッセージは ProcessJob() スレッド以外のス
レッドに基づいています。
• アセットプロセッサーにビルダーで処理するアセットタイプのジョブがある場合
は、CreateJobs(const CreateJobsRequest& request, CreateJobsResponse& response)
関数が呼び出されます。作業が必要ない場合、CreateJobsRequest に応じてジョブを作成する必
要はありませんが、実装動作は一貫している必要があります。
• 古い製品を削除するため、起動したジョブは同じ入力、プラットフォーム、ジョブキー操作で最後
に起動されたジョブと比較されます。
• ジョブを処理する必要があるかどうかを確認する必要はありません。代わりに、イテレーションご
とに、特定のプラットフォームの特定の入力アセットに対して可能なすべてのジョブを発行しま
す。
• 一般的に、CreateJobs 関数では、発行するジョブごとにジョブの記述子を作成し、応答用のジョ
ブ記述子のリストにジョブを追加します。
CreateJobs 関数のコード例を以下に示します。
// This function runs early in the file scanning pass.
// This function should always create the same jobs, and should not check
whether the job is up to date.
void ExampleBuilderWorker::CreateJobs(const
AssetBuilderSDK::CreateJobsRequest& request,
AssetBuilderSDK::CreateJobsResponse& response)
{
// The following example creates one job descriptor for the PC platform.
// Normally, you create a job for each platform that you can make assets
for.
if (request.m_platformFlags & AssetBuilderSDK::Platform_PC)
Version 1.6
121
Lumberyard 開発者ガイド
ビルダーの作成
{
AssetBuilderSDK::JobDescriptor descriptor;
descriptor.m_jobKey = "Compile Example";
descriptor.m_platform = AssetBuilderSDK::Platform_PC;
// You can also place whatever parameters you want to save for later
into this map:
descriptor.m_jobParameters[AZ_CRC("hello")] = "World";
response.m_createJobOutputs.push_back(descriptor);
response.m_result = AssetBuilderSDK::CreateJobsResultCode::Success;
}
}
ビルダーが処理を開始するジョブがある場合、アセットプロセッサーは ProcessJob 関数を呼び出し
ます。
ProcessJob(const AssetBuilderSDK::ProcessJobRequest& request,
AssetBuilderSDK::ProcessJobResponse& response)
CreateJobs が発行した完全ジョブ記述子を含むジョブリクエストが、作業用の一時ディレクトリな
どの情報とともに ProcessJob に提供されます。
このメッセージはワーカースレッドで送信されるため、ビルダーで作業用のスレッドを起動する必要
はありません。ただし、この呼び出し中に他のスレッドと通信しないように注意してください。
Warning
ProcessJob の実行中は、一時ディレクトリのファイル以外のファイルを変更しないでく
ださい。ジョブが正常に完了後、アセットプロセッサーによって登録された製品がアセット
キャッシュにコピーされるため、キャッシュに書き込まないようにしてください。一時ディ
レクトリは好きなように使用していただけます。
ビルダーでアセットの処理が完了した後、レスポンス構造で作成したアセットがすべてリストされま
す。リストされたアセットのみがキャッシュに追加されるため、一時ディレクトリを処理のスクラッ
チ容量として使用できます。
ProcessJob 関数のコード例を以下に示します。
// This function is called for jobs that need processing.
// The request contains the CreateJobResponse you constructed earlier,
including the
// keys and values you placed into the hash table.
void ExampleBuilderWorker::ProcessJob(const
AssetBuilderSDK::ProcessJobRequest& request,
AssetBuilderSDK::ProcessJobResponse& response)
{
AZ_TracePrintf(AssetBuilderSDK::InfoWindow, "Starting Job.");
AZStd::string fileName;
AzFramework::StringFunc::Path::GetFullFileName(request.m_fullPath.c_str(),
fileName);
AzFramework::StringFunc::Path::ReplaceExtension(fileName, "example1");
AZStd::string destPath;
Version 1.6
122
Lumberyard 開発者ガイド
ビルダーの作成
// Do all of your work inside the tempDirPath.
// Do not write outside of this path
AzFramework::StringFunc::Path::ConstructFull(request.m_tempDirPath.c_str(),
fileName.c_str(), destPath, true);
// Use AZ_TracePrintF to communicate job details. The logging system
automatically places the
// text in the appropriate log file and category.
AZ::IO::LocalFileIO fileIO;
if (!m_isShuttingDown && fileIO.Copy(request.m_fullPath.c_str(),
destPath.c_str()) == AZ::IO::ResultCode::Success)
{
// If assets were successfully built into the temporary directory,
push them back into the response's product list.
// The assets that you created in your temporary path can be
specified using paths relative to the temporary path.
// It is assumed that your code writes to the temporary path.
AZStd::string relPath = destPath;
response.m_resultCode = AssetBuilderSDK::ProcessJobResult_Success;
AssetBuilderSDK::JobProduct jobProduct(fileName);
response.m_outputProducts.push_back(jobProduct);
}
else
{
if (m_isShuttingDown)
{
AZ_TracePrintf(AssetBuilderSDK::ErrorWindow, "Cancelled job %s
because shutdown was requested", request.m_fullPath.c_str());
response.m_resultCode =
AssetBuilderSDK::ProcessJobResult_Cancelled;
}
else
{
AZ_TracePrintf(AssetBuilderSDK::ErrorWindow, "Error during
processing job %s.", request.m_fullPath.c_str());
response.m_resultCode = AssetBuilderSDK::ProcessJobResult_Failed;
}
}
}
注
• 重要なファイルを失くさないように、すべてのジョブが作成されるまでエディタはブロック
されています。このため、できるだけ早く CreateJobs のコードを実行する必要がありま
す。CreateJobs ではコードで最小限の処理を行い、思い処理は ProcessJob に回すことをお勧め
します。
• CreateJobs で、記述子の m_jobParameters フィールドに任意のキーと値のペアを配置できま
す。キーと値のペアは ProcessJob の実行時にコピーバックされるため、再度追加する必要があり
ません。
• ジョブのすべて出力は、一時ワークスペースに配置されます。 ただし、アセットのキャッシュに
ジョブの一部として既存のファイルをコピーする必要があるだけの場合は、一時ディレクトリにま
ずコピーしないで、製品としてファイルのソースの完全パスを実行できます。 その後アセットプロ
セッサーによってファイルがキャッシュにコピーされ、ジョブ出力の一部として登録されます。他
のファイルは、ジョブが正常に完了した場合にキャッシュの自動更新を実行するために、一時ディ
レクトリからアセットキャッシュに移されます。
Version 1.6
123
Lumberyard 開発者ガイド
メッセージのログ記録
メッセージのログ記録
BuilderLog(AZ:Uuid builderId, char* message, ...) を使用して、ビルダー関連の任意の
一般メッセージやエラーをログに記録できます。ただし、BuilderLog はジョブの処理中は使用でき
ません。
ジョブ関連メッセージについては、AZ_TracePrintf(window, msg) を使用します。この関数は自
動的にジョブのログファイルにメッセージを記録します。
Version 1.6
124
Lumberyard 開発者ガイド
アーキテクチャーとコンセプト
アセットインポーター（プレ
ビュー）テクニカルオーバービュー
Lumberyard アセットインポーターとFBX インポーター はプレビューリリース内にあり、変更する
ことがあります。
このトピックではLumberyardのハイレベルなテクニカルオーバービューを提供します。アセットイン
ポーターアーキテクチャーとそのコアライブラリ。アセットインポーターの特徴のプレビューリリー
ス：
• シングルスタティックFBXメッシュとシングルマテリアルのLumberyardへ搭載が簡単にできる新し
いFBX インポーター (完全手作り) 。 FBX インポーター ツールの使い方については、Lumberyard
エディタからご確認いただけます。[ FBX Importer ]が[ Amazon Lumberyard User Guide ]に載って
いるのでご参照ください。
• 他のインプットフォーマットの受け入れを拡張できる抽象化レイヤー。
抽象化レイヤーを使ってOBJやDAEなどの古いフォーマットへのサポートや、カスタムデータフォー
マットへのサポートを追加できます。[scene graph]と呼ばれるデータのジェネリックレイヤーは、以
下のセクションで説明されているように、この拡張性を可能にします。
アーキテクチャーとコンセプト
以下は、Lumberyard アセットインポーターにおいて大切なコンセプトと構成要素です。
FBX – オートデスクの filmbox ファイルフォーマットのファイル拡張。これはビデオゲーム開発に広
く使われるデータの多様なタイプのための一般使用コンテイナーファイルです。多くのモデリング
パッケージはFBXファイルフォーマットを自然にエクスポートすることができます。Lumberyard ア
セットインポーターのプレビューリリースはこのフォーマットをサポートします。
インポートデータを取り込むインポーター – コードはそのデータからscene graph (Lumberyard'の
ジェネリックツリーベースのデータ表示) または scene manifest を作成します。たとえば、FBXファ
Version 1.6
125
Lumberyard 開発者ガイド
アーキテクチャーとコンセプト
イルからシーングラフを構成できる FbxSceneGraphImporter を実行することもできます。ほかに
も、JSONファイルからシーンマニフェステーションを構成するJsonManifestImporter を実行で
きます。
シーン – これはシーングラフツリーデータストラクチャとシーンマニフェストを搭載しています。
シーンマニフェストはシーングラフのメタデータを含みます。
シーングラフ– ジェネリックツリーベースのデータ表示。シーングラフは（FBXのような）インター
ミディエイト3Dアセット、 Lumberyard エンジン間のデータのレイヤーのことです。シーングラフは
オプショナルでscene nodesで内部的に構成されています。これには、data objectの形式のデータが含
まれます。
シーンノード – データオブジェクト形式のデータを含むもしくはヒエラルキカルな理由のみに
よって存在しているシーングラフ内のノード。ノードの名前は、シーングラフ内ですべての親
ノードを結合し、'.'でその範囲を定めることで固有のものとなります。たとえば、rootという
名前のノードがchild1とchild2という2つの子ノードを持っていた場合、フルノードの名前
はroot、root.child1、そしてroot.child2となります。仮に他のノードがchild2という名前の
子ノードを持っていたとしても、階層があるためフルネームは一意になります。
データオブジェクト – RTTI （実行時型情報）をサポートし、その AZ_RTTIシステムをキャストする
データのジェネリックコンテナこれはSceneManifestキー値ペアディクショナリーとSceneNode内
部データペイロード 両方に使用されるストレージの基本単位です。DataObjectクラスは、制限さ
れた リフレクション サポートを編集のために提供しますが、ファイルのシリアライズは提供しませ
ん。
シーンマニフェスト – これはシーングラフに関するメタデータのフラットディクショナリーです。こ
のメタデータの大部分は グループ と ルール の形式に入りますが、ユーザーによって提供されたジェ
ネリックや匿名データのサポートも行います。すべてのデータは文字列となっているキーを含むキー
値ペア、そしてDataObjectとなっている値として保存されます。
グループ – シーンマニフェストによってマネージされているこれらの構造は、ゲームデータファイ
ルが生成できるようにするためにシーングラフデータを処理する方法を明示するルールを含んでいま
す。アセットインポーターの現在のバージョンはCGFファイルとMTLファイルを生成できるメッシュ
グループをサポートします。
ルール – これらのグループ内に包含された構造は、アセット処理またはメタデータやユーザーコメン
トのようなディスプレイ情報の操作を特殊化します。たとえば、ビット数をインデックス作成する頂
点を変えるためのルールや、出力ファイル内の位置オフセットまたはローテーションオフセットを提
供するルールをつくることができます。アセットインポーターの現在のバージョンは オリジン 、 ア
ドバンスメッシュ 、 素材、 コメント のルールタイプをサポートします。
エクスポーター – シーングラフまたはシーンマニフェストからデータを引き抜き、他のデータフォー
マットに変更するコードです。たとえば、CgfSceneExporter という シーンマニフェストからの
指示を使ってシーングラフをCContentCGF メモリ内のストラクチャにエクスポートするコードを
所有している可能性があります。ジオメトリファイルの作成を許可するCgfExporterを使用するこ
ともできます。シーンマニフェストに入っているデータをディスク上のJSONファイルに書き込む
JsonManifestExporter も使用可能です。
次の図は説明されたコンポーネント間の関係を表しています。
Version 1.6
126
Lumberyard 開発者ガイド
他のコンポーネント
他のコンポーネント
アセットプロセッサー – を使用するアセットインポーター Lumberyard アセットプロセッサー .ア
セットプロセッサーはFBXファイルのようなソースデータまたは のようなメタデータ内の変更を探す
バックグラウンド内で実行します。##### ファイル。ソースデータまたはメタデータが追加、削除、
もしくは変更されたとき、アセットプロセッサーが自動的にソースデータを 再処理し、キャッシュ
ディレクトリ―にゲームデータを出力します。
リフレクション – Lumberyard エンジンは のシステムAZ_RTTI上で作られる頑丈でパフォーマンス性
の高いリフレクションシステムをサポートしますAzCore。アセットインポーターとそれに連結したシ
ステムは Lumberyard ReflectedPropertyGrid AzToolsFrameworkの一部であるUIシステムを通
してデータを表示します。 AzToolsFramework は、クラスデータを表示、編集するための一般的な
UIフレームワークです。
Core Libraries
以下が、アセットインポーターのコアライブラリです。ライブラリの名前は、括弧内に書かれている
それぞれのディレクトリの場所の前に表示されます。
シーンコア (\dev\Code\Tools\SceneAPI\SceneCore) – このライブラリには一般的なデータスト
レージ構造が含まれます。具体的には：SceneSceneGraphSceneManifestおよびDataObject現在
サポートされているデータタイプ Group、 Ruleおよび SceneNode のためのインターフェースも含
まれます。SceneGraph または SceneManifest データを通して簡単に繰り返し使うことのできる
ベーシックイテレータが含まれます。最後に、すべての使用ケースに共通であるベーシックインポー
ターとエクスポーターが含まれます。
Fbxシーンビルダー (\dev\Code\Tools\SceneAPI\FbxSceneBuilder) – このライブラリ
で、FBXデータのローディングと データへの変換が可能ですSceneGraph。便宜上、軽量パスス
Version 1.6
127
Lumberyard 開発者ガイド
FBX インポーター ワークフローの例
ルーFBXSdkWrapperの全ソースが含まれています。FBXSdkWrapper にはSceneCore がFBX SDKへ
の依存を必要としないように、FBXデータ用のインポーターが含まれています。特殊なライブラリに
依存性があるファイルフォーマットをサポートするためにSceneAPI コードベースを拡張したい場合
のモデル案はこちらです。
シーンデータ (\dev\Code\Tools\SceneAPI\SceneData) – このライブラリには 、 Group Rule お
よびSceneNodeのデータタイプ用にLumberyard アセットインポーターに提供されている具体的な実
装が含まれています。これらの実装はSceneCoreライブラリで設定したルールの拡張または実行の仕
方を説明する異なるライブラリ内で提供されます。SceneData ライブラリには、他のタイプのデータ
を生成するファクトリも含まれます。
エディターアセットインポーター (\dev\Code\Sandbox\Plugins\EditorAssetImporter) –
Lumberyard シーンマニフェストの編集を許可するエディタープラグインです。FbxSceneBuilder
および SceneCore ライブラリを使用し、 SceneData ライブラリでディスクに定義されたデータを
読み書きし、ユーザーのリクエストに応じます。現在、 EditorAssetImporter は.fbx ファイル拡
張を持つファイルのみサポートしています。他の SceneBuilder 実装で異なるファイルタイプをサ
ポートできるものもあります。
リソースコンパイラシーン (\dev\Code\Tools\rc\ResourceCompilerScene) – リソースコンパ
イラ (rc.exe) プラグインは からの指示を使用して SceneManifestを処理SceneGraphし、ゲーム
データを生成します。リソースコンパイラは FbxSceneBuilder および SceneCore ライブラリを使
用して SceneData ライブラリで定義されたフォーマット内のデータの読み込み、書き込み、保存を
行います。リソースコンパイラは現在 .fbx ファイル拡張と連結しています。ほかのインポーターが
実行されると、FBXでないソースから SceneGraph データへと翻訳されます。
FBXSdkラッパー (\dev\Code\Tools\SceneAPI\FBXSdkWrapper) – 名前の通り、便宜上またテス
トの関係上提供されるFBX SDK周辺のラッパーです。内部FBXシリアライゼーションとストレージ
モデルをお持ちであれば、このライブラリを使用してAutodesk FBX SDKと置き換えることができま
す。
FBX インポーター ワークフローの例
次のワークフローはこれらのライブラリがプロダクション環境でどのように動作するかを説明しま
す。
1. Lumberyard エディタ を開いて FBX インポーターを起動します。インポーターが
EditorAssetImporter.dll Lumberyard エディタ プラグインをロードします。 FBX インポー
ター, の使い方についてははこちらを参照してください。 FBX インポーター.
2. FBX インポーター ファイルブラウザを使用して、モデリングパッケージから出力されたFBXファ
イルを選択します。 FBX インポーター (FbxSceneBuilderに含まれる特殊インポーター) は
SceneGraphを作成し、これは .fbx ファイル内のデータと同等です。
3. .fbx ファイルを初めてインポートする場合は、空の SceneManifest も一緒に作成されます。
ファイルのインポートが完了すると、JsonManifestImporter が対応する##### ファイルを同じ
ディレクトリからロードし、新しいSceneManifestを作成します。
4. アセットインポーターUIを使用して、Lumberyard アセットインポーターが作成する出力ファイル
を定義するグループを作成します。グループは、出力ファイル用のデータを生成するSceneGraph
内の出力ファイルとターゲットノードの名前を特定します。出力ファイルの処理方法を変更する
ルールを作成します。
5. 作成したいシーングラフのグループとルールの作成が完了したら、をクリックしてをインポートし
ます。###### ファイルを.fbx ファイルをロードしたのと同じ場所に保存することで、シーンマ
ニフェストの作成、上書きをします。たとえば、 ######.fbx をロードする場合、 ##########
# ファイルが同じディレクトリに作成されます。JsonManifestExporterこのオペレーションを
実行します。MTLファイルが存在しない場合は、MaterialExporter がデフォルトのMTLファイ
ルを生成します。
6. アセットプロセッサーは .##### ファイルの作成、または変更を検知し、リソースコンパイラ
(rc.exe) を呼び出して.fbx ファイルが再処理されるようにします。
Version 1.6
128
Lumberyard 開発者ガイド
可能なアセットインポーターのカスタマイズ
7. リソースコンパイラは .fbx ファイルタイプを検知し、ResourceCompilerScene プラグインモ
ジュールを所有していることを認識します。このモジュールは.fbx ファイルを処理し、プラグイ
ンを実行します。
8. ResourceCompilerScene プラグインはシーングラフとシーンマニフェストを作成し、これ
は.fbx ファイル内のデータと同等です。プラグインはSceneManifest内のグループおよびルール
をパースし、ゲームデータファイルにシーングラフを書くためのこれらのグループとルールを使用
する特殊エクスポーターを呼び出します。
9. リソースコンパイラが完了すると、モデル用のMLTおよびCGFファイルは正しいロケーションに配
置され、ゲーム内で使える状態になります。
可能なアセットインポーターのカスタマイズ
SceneGraph および SceneManifest はフレキシブルかつ拡張可能な構成なため、追加のデータタイ
プにも簡単にご使用いただけます。任意データのRTTIベースのハンドリングを許可するDataObject
構造がこのフレキシビリティの鍵となります。以下でカスタマイズの例をいくつかご紹介します。
• 入力ファイルの種類: FBX以外ファイルタイプを処理するには、任意のデータのフォーマット
をSceneGraph生成するには新しい輸入業者を実行します。
• Input File Data:SceneNode （SceneGraph内）がDataObject構造を可能にしたRTTIフォーム内で
任意のデータペイロードを受け入れるため、 SceneGraph構造を構築して特殊または匿名データを
チームに合わせて処理できます。
• 手順:カスタム資産を処理する GroupRule純粋な仮想インターフェイスとして簡単にカスタマイズ
できますプロジェクトに特定の手順によりそのコンポーネントが実行されているためです。
• SceneManifest は文字列や数字のような匿名データをサポートするため、プロトタイピングに
必要なコードは最小限に抑えられます。
• チームに沿ったアセットプロセシングの要件を達成するために、SceneDataライブラリの基本的
かつ具体的な実行を拡張または置き換えします。
Version 1.6
129
Lumberyard 開発者ガイド
AZ モジュールとレガシーモジュールの比較
AZ モジュール (プレビュー)
AZ モジュールはプレビューリリースにあり、変更される可能性があります。
AZ モジュールは、Lumberyard のゲームやツールに接続するために設計されたコードライブラリで
す。AZ モジュールは、特定の初期化関数を実装する、静的または動的ライブラリとして構築された
C++ コードのコレクション (.lib または .dll ファイル) です。Lumberyard アプリケーションが起
動すると、各モジュールをロードし、次の初期化関数を呼び出します。これらの初期化関数を使用し
て、モジュールをリフレクション、シリアル化、イベントバス (p. 415)、および「コンポーネントエ
ンティティシステム (p. 322)」などのコアテクノロジーに接続できます。
モジュールは Lumberyard では新しい概念ではありません。実は、Lumberyard のゲームエンジンは旧
式モジュールのコレクションです。これらのレガシーモジュールはゲームエンジンでうまく機能しま
したが、次のセクションで説明するように、AZ モジュールによって対処できる多数の欠点がありま
す。
Lumberyard は現在レガシーモジュールと AZ モジュールの両方をサポートしますが、今後は AZ モ
ジュールを使用します。Lumberyard 1.5 から、Gem を AZ モジュールコードに含めることができま
す。新しい Gem を作成するのが、新しい AZ モジュールを立ち上げて実行する最も簡単な方法です。
Note
AZ は AZ モジュールを構築する AZCore C++ ライブラリの名前空間です。「AZ」という文字
は Amazon を表します。この用語は Amazon アベイラビリティーゾーンとはまったく関係が
ないプレビューの名前で、変更される可能性があります。
AZ モジュールとレガシーモジュールの比較
次の表に示すように、AZ モジュールには、レガシーモジュールにはない重要な利点があります。
トピック
レガシーモジュール
AZ モジュール
互換性
モジュールは機能を失うことな
く AZ モジュールに変換するこ
とができます。
レガシーモジュールで行うこと
ができるすべてのことは AZ モ
ジュールでもできます。ほとん
どの AZ モジュールのコードは
レガシーモジュール内で使用で
きますが、レガシーモジュール
は今後の AZ モジュールベース
Version 1.6
130
Lumberyard 開発者ガイド
AZ モジュールとレガシーモジュールの比較
の Lumberyard ツールとは互換
性がない可能性があります。
モジュールにサービス (シング
ルトンクラス) を追加できるこ
と
サービスを追加する場合、通
常、CryCommon でのファイル
の編集が必要です。シングルト
ンのクラスのインターフェイス
向けのファイルは CryCommon
ディレクトリになければなら
ず、シングルトンを gEnv に保
持する変数がなければなりませ
ん。
モジュールはコンポーネントを
作成し、システムエンティティ
にアタッチします。ゲームエン
ジンファイルの編集は必要あり
ません。
低レベルのアプリケーション機
能での使いやすさ
モジュールではロードに時間が
かかるため、アプリケーション
に対する低レベルの機能の提供
を防止します。すべての重要な
機能は、他のモジュールより
も前にロードされる 1 つのモ
ジュールに含まれている必要が
あります。
モジュールはアプリケーション
の起動シーケンスでは早くロー
ドされ、個別の段階で初期化
されます。これにより、すべて
のモジュールで、他のモジュー
ルがあとで利用できる低レベル
の機能を早い段階で提供できる
ようにします。
プロパティの公開
モジュールには、ユーザーに
サービスの設定を制御させる統
一された方法はありません。一
部のサービスでは、手動で編集
する必要のあるアセットディレ
クトリの xml ファイルから設
定を読み込みます。
AZ モジュールは、システムコ
ンポーネントのプロパティを
Lumberyard リフレクションシ
ステムに公開します。リフレク
ション システムは、他のすべて
のコンポーネントでこれらのプ
ロパティについての情報が使用
できるようにします。
ゲームエンジンの依存関係
モジュールはゲームエンジン
で実行する必要があり、ゲー
ムコードがないツールに使用す
るために拡張することは困難で
す。
モジュールはゲームエンジンに
特有ではないので、その外部で
使用できます。
初期化関数
関数パラメーターは CryEngine
に固有です。
関数パラメーターは AZ フレー
ムワークに固有です。詳細につ
いては、以下のセクションを参
照してください。
初期化の順序
シングルトンコードは、多くの
場合、他のシングルトンによっ
て提供されるサービスによって
異なりますので、モジュールは
特定の順序で初期化する必要が
あります。ただし、その順序
は明らかではありません。モ
ジュールのコードがよくわから
ない場合、ロードの順序の確認
は困難です。
各モジュールはシステムコン
ポーネントに対する依存関係を
明示的に示します。すべてのシ
ステムコンポーネントが検証さ
れたあと、これらの依存関係に
従ってソートされ、適切な順番
で初期化されます。各モジュー
ルは第 1 クラスの市民です。
Version 1.6
131
Lumberyard 開発者ガイド
初期化の自動認識方法
初期化の自動認識方法
レガシーモジュールは、特定の順序でロードされます。CrySystem はゲームモジュールの前にロー
ドされ、初期化されるため、ログ記録やファイル I/O など、後続のモジュールが依存する可能性があ
るすべての低レベルシステムを提供する必要があります。ゲームモジュール自体は、初期化が遅いた
め、このような低レベルシステムを提供できません。
一方、AZ モジュールは可能な限り迅速にロードされ、ステージで初期化されます。各モジュールは明
示的にシステムコンポーネントとの依存関係を宣言するため、すべてのシステムコンポーネントを事
前に検証し、依存関係に従ってソートし、適切な順序で初期化 (p. 138)できます。こうすることで、
低レベル機能 (カスタムロギングシステムのような) をゲームモジュールから実装できます。コンポー
ネントの初期化順序について詳しくは、「AZ ブートストラップのプロセス (p. 150)」を参照してく
ださい。
AZ フレームワークとの関係
AZ モジュールは、リフレクション、シリアル化、イベントバス (p. 415)、コンポーネントエンティ
ティシステムのような Lumberyard テクノロジーのコレクションである AZ フレームワークと連動す
るように設計されています。AZ フレームワークはゲームの開発をサポートしますが、外部でも使用で
きます。たとえば、セットアップアシスタント、アセットプロセッサ、コンポーネントエンティティ
システムのような Lumberyard ツールは AZ フレームワークおよび AZ モジュールを使用しますが、
ゲームコードは含まれていません。リソースコンパイラがスライスを構築するときに、AZ モジュール
がロードされ、その中にあるコンポーネントについてのリフレクション情報を取得します。
AZ モジュールは AZ フレームワークを使用するように構築されたコードライブラリです。AZ フレー
ムワークアプリケーションが AZ モジュールをロードすると、ライブラリ内で定義されたデータ型に
関するリフレクション情報の収集などのタスクの実行方法を、AZ モジュールが認識します。
よりスマートなシングルトン
AZ モジュールは、Lumberyard がゲーム内のエンティティを構築するために使用している同じコン
ポーネントエンティティシステムを使用して、サービス (シングルトンクラス) を構築します。モ
ジュールは単にシステムエンティティにシステムコンポーネントを配置するだけです。これにより、
レガシーモジュールのシングルトンに関連付けられる問題の多くが解決されます。
Lumberyard エディタ の GUI は、リフレクションシステムを使用して、エンティティ (ゲームプレイ
コンポーネント) のプロパティを設計者に公開します。同様に、Lumberyard は、設定を特定のゲーム
用にカスタマイズできるように、リフレクションシステムを使用してシステムコンポーネントのプロ
パティを公開します。システムコンポーネントはゲームプレイコンポーネントと実際に異なることは
ないので、ゲームの内部コンポーネントのプロパティを編集するのと同様に、プロジェクトコンフィ
ギュレーターを使用してシステムコンポーネントのプロパティを編集 (p. 145)できます。
現在の Lumberyard AZ モジュール
Lumberyard とともに提供される gem (p. 140) は、すべて AZ モジュールとして構築されています。
また、Gem として構築されていない AZ モジュールが 2 つあります。
LmbrCentral
LmbrCentral には、レガシーモジュールからの機能をラップするコンポーネントが含まれます。た
とえば、MeshComponent は内部で IRenderNode を利用します。LmbrCentral はゲームのアプリ
ケーションで使用されます。
Version 1.6
132
Lumberyard 開発者ガイド
LmbrCentralEditor
LmbrCentralEditor
コンポーネントには、ゲームのランタイム環境では使用できないテクノロジーを組み込んだ
エディタ固有の実装を作成できます。したがって、Lumberyard エディタ では別のモジュール
LmbrCentralEditor が使用されます。このモジュールには、LmbrCentral のすべてのコードに加
えて、ツールでのみ使用するコードが含まれています。LmbrCentralEditor モジュールは、スタン
ドアロンのゲームアプリケーションで使用するものではありません。
AZ モジュールのパーツ、説明
AZ モジュールはプレビューリリースにあり、変更される可能性があります。
AZ モジュールには 3 つの主要なコンポーネントがあります。AZ::Module を継承するクラス、1 つ以
上のパブリック側イベントバス、システムコンポーネントクラスです。
このページでは、モジュールの初期化、システムコンポーネントのシングルトンとしての使用、イベ
ントバス呼び出しがこのシングルトンと通信する方法、およびモジュール作成後にそれを外部で呼び
出す方法を説明します。
モジュールのクラス
各 AZ モジュールには、AZ::Module から継承されたクラスを含める必要があります。モジュールが
アプリケーションによってロードされると、クラスのインスタンスはアプリケーション運用中のかな
り早いタイミングで作成され、仮想関数はアプリケーションがブートストラップ処理 (p. 150)を行っ
ている間の適切なタイミングで呼び出されます。このクラスはモジュールで宣言しているコンポーネ
ントを反映 (p. 325)し、システムエンティティに重要なコンポーネントを追加します。
以下のスケルトンコードは、AZ::Module クラスの基本構造を示します。
namespace AZ
{
/**
* AZ::Module enables static and dynamic modules (aka LIBs and DLLs) to
* connect with the running \ref AZ::ComponentApplication.
*
* Each module should contain a class which inherits from AZ::Module.
* This class must perform tasks such as reflecting the classes within
* the module and adding critical components to the system entity.
*/
class Module
{
public:
Module();
virtual ~Module();
/// Override to require specific components on the system entity.
virtual ComponentTypeList GetRequiredSystemComponents() const;
};
}
AZ::Module クラスでは、仮想関数として AZ フレームワークと統合するすべてのポイントが公開
されます。これらの統合ポイントは、初期化コードが静的ライブラリと動的ライブラリのどちら
Version 1.6
133
Lumberyard 開発者ガイド
モジュールのクラス
にあってもできるかぎり同じ方法で書き込まれるように、クラスの仮想関数として作成されます。
一番最初の実際の初期化呼び出しは、静的ライブラリとも動的ライブラリとも異なる必要があり
ます。Lumberyard では、この重要ではないグルーコードを定義するマクロを提供して、お客様が
AZ::Module クラスに重要な初期化コードを書くことができるようにしています。
AZ::Module クラスに含める実装コードはできるだけ少なくすることをお勧めします。AZ::Module
クラスが作成されると、アプリケーションが起動を開始し、多くのシステムが使用不可になりま
す。AZ::Module クラスがシングルトンまたはマネージャークラスをスポーンさせた場合、このシン
グルトンが依存するシステムが使用可能になる保証がありません。代わりに、初期化順序を制御でき
る Lumberyard システムコンポーネント (p. 138)としてシングルトンをビルドする必要があります。
Lumberyard 1.5 から、gem は AZ モジュールを使用してビルドされています。次の例で
は、「HelloWorld」 AZ モジュールが新しい gem の作成で作成されています。この例の
CryHooksModule クラスは、AZ::Module のヘルパーラッパーであり、モジュール全体の gEnv への
アクセスを提供します。
// dev/Gems/HelloWorld/Code/Source/HelloWorldModule.cpp
#include "StdAfx.h"
#include <platform_impl.h>
#include "HelloWorldSystemComponent.h"
#include <IGem.h>
namespace HelloWorld
{
class HelloWorldModule
: public CryHooksModule
{
public:
AZ_RTTI(HelloWorldModule, "{39C21561-D456-413F-8C83-4214F6DBC5A5}",
CryHooksModule);
HelloWorldModule()
: CryHooksModule()
{
// Create descriptors for components declared within this module.
m_descriptors.insert(m_descriptors.end(), {
HelloWorldSystemComponent::CreateDescriptor(),
});
}
// Add required system components to the system entity.
AZ::ComponentTypeList GetRequiredSystemComponents() const override
{
return AZ::ComponentTypeList{
azrtti_typeid<HelloWorldSystemComponent>(),
};
}
};
}
// DO NOT MODIFY THIS LINE UNLESS YOU RENAME THE GEM
// The first parameter should be GemName_GemIdLower
// The second should be the fully qualified name of the class above
AZ_DECLARE_MODULE_CLASS(HelloWorld_010c14ae7f0f4eb1939405d439a9481a,
HelloWorld::HelloWorldModule)
Version 1.6
134
Lumberyard 開発者ガイド
イベントバス
イベントバス
外部コードはモジュールの公開イベントバス (p. 415) (EBus) を使用して、モジュールに呼び出した
り、モジュールからのイベントを受信したりできます。イベントバスを使用して、異なるコードのモ
ジュール間で簡単で安全な関数呼び出しができます。
新しい gem には、次の例に示すように、デフォルトで 1 つのイベントバスが付属しています。
// dev/Gems/HelloWorld/Code/Include/HelloWorld/HelloWorldBus.h
#pragma once
#include <AzCore/EBus/EBus.h>
namespace HelloWorld
{
class HelloWorldRequests
: public AZ::EBusTraits
{
public:
//////////////////////////////////////////////////////////////////////////
// EBusTraits overrides
// These settings are for a "singleton" pattern.
// A single handler can connect to the EBus.
static const AZ::EBusHandlerPolicy HandlerPolicy =
AZ::EBusHandlerPolicy::Single;
// A single address exists on the EBus.
static const AZ::EBusAddressPolicy AddressPolicy =
AZ::EBusAddressPolicy::Single;
//////////////////////////////////////////////////////////////////////////
// Put your public methods here
virtual void SayHello(const char* name) = 0;
};
using HelloWorldRequestBus = AZ::EBus<HelloWorldRequests>;
} // namespace HelloWorld
このイベントバスの呼び出しは、次のセクションで説明するようにシステムコンポーネントで処理さ
れます。
システムコンポーネントのクラス
シングルトンを必要とするモジュールの主要システムは、システムコンポーネントとして構成する必
要があります。システムコンポーネントには新しい gem がデフォルトで付属しています。システムコ
ンポーネントのクラスはアプリケーションの起動中に作成され、システムエンティティにアタッチさ
れます (HelloWorldModule.cpp の GetRequiredSystemComponents() を参照)。
現在の例では、システムコンポーネントのクラスが HelloWorldBus.h で宣言されている公開イベン
トバスの呼び出しを処理します。 次のコードは、HelloWorldSystemComponent クラスを示してい
ます。
// dev/Gems/HelloWorld/Code/Source/HelloWorldSystemComponent.h
#pragma once
#include <AzCore/Component/Component.h>
#include <HelloWorld/HelloWorldBus.h>
namespace HelloWorld
{
Version 1.6
135
Lumberyard 開発者ガイド
システムコンポーネントのクラス
// The HelloWorldSystemComponent is placed on the system entity
// and handles calls to the HelloWorldRequestBus.
class HelloWorldSystemComponent
: public AZ::Component
, protected HelloWorldRequestBus::Handler
{
public:
// Every component definition must contain the AZ_COMPONENT macro,
// specifying the type name and a unique UUID.
AZ_COMPONENT(HelloWorldSystemComponent,
"{72DFB0EE-7422-4CEB-9A40-426F26530A92}");
static void Reflect(AZ::ReflectContext* context);
static void
GetProvidedServices(AZ::ComponentDescriptor::DependencyArrayType& provided);
static void
GetIncompatibleServices(AZ::ComponentDescriptor::DependencyArrayType&
incompatible);
static void
GetRequiredServices(AZ::ComponentDescriptor::DependencyArrayType& required);
static void
GetDependentServices(AZ::ComponentDescriptor::DependencyArrayType&
dependent);
protected:
////////////////////////////////////////////////////////////////////////
// AZ::Component interface implementation
void Init() override;
void Activate() override;
void Deactivate() override;
////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////
// HelloWorldRequestBus interface implementation
void SayHello(const char* name) override;
////////////////////////////////////////////////////////////////////////
};
}
// dev/Gems/HelloWorld/Code/Source/HelloWorldSystemComponent.cpp
#include "StdAfx.h"
#include <AzCore/Serialization/SerializeContext.h>
#include <AzCore/Serialization/EditContext.h>
#include "HelloWorldSystemComponent.h"
namespace HelloWorld
{
void HelloWorldSystemComponent::Reflect(AZ::ReflectContext* context)
{
// Reflect properties that developers may want to customize.
if (AZ::SerializeContext* serialize =
azrtti_cast<AZ::SerializeContext*>(context))
{
serialize->Class<HelloWorldSystemComponent, AZ::Component>()
->Version(0)
Version 1.6
136
Lumberyard 開発者ガイド
システムコンポーネントのクラス
->SerializerForEmptyClass();
if (AZ::EditContext* ec = serialize->GetEditContext())
{
ec->Class<HelloWorldSystemComponent>("HelloWorld", "Says
hello")
->ClassElement(AZ::Edit::ClassElements::EditorData, "")
>Attribute(AZ::Edit::Attributes::AppearsInAddComponentMenu, AZ_CRC("System"))
->Attribute(AZ::Edit::Attributes::AutoExpand, true)
;
}
}
}
void
HelloWorldSystemComponent::GetProvidedServices(AZ::ComponentDescriptor::DependencyArrayType
provided)
{
provided.push_back(AZ_CRC("HelloWorldService"));
}
void
HelloWorldSystemComponent::GetIncompatibleServices(AZ::ComponentDescriptor::DependencyArray
incompatible)
{
// Enforce singleton behavior by forbidding further components
// which provide this same service from being added to an entity.
incompatible.push_back(AZ_CRC("HelloWorldService"));
}
void
HelloWorldSystemComponent::GetRequiredServices(AZ::ComponentDescriptor::DependencyArrayType
required)
{
// This component does not depend upon any other services.
(void)required;
}
void
HelloWorldSystemComponent::GetDependentServices(AZ::ComponentDescriptor::DependencyArrayTyp
dependent)
{
// This component does not depend upon any other services.
(void)dependent;
}
void HelloWorldSystemComponent::Init()
{
}
void HelloWorldSystemComponent::Activate()
{
// Activate() is where the component "turns on".
// Begin handling calls to HelloWorldRequestBus
HelloWorldRequestBus::Handler::BusConnect();
}
void HelloWorldSystemComponent::Deactivate()
Version 1.6
137
Lumberyard 開発者ガイド
外部コードからのモジュール呼び出し
{
// Deactivate() is where the component "turns off".
// Stop handling calls to HelloWorldRequestBus
HelloWorldRequestBus::Handler::BusDisconnect();
}
void HelloWorldSystemComponent::SayHello(const char* name)
{
AZ_Printf("HelloWorld", "Hello %s, you certainly look smashing
tonight.", name);
}
}
システムコンポーネントの詳細については、「システムコンポーネント (p. 138)」を参照してくださ
い。
外部コードからのモジュール呼び出し
モジュールを呼び出すには、イベントバスで公開関数を呼び出します。この例では、SayHello 関数
を使用します。
#include <HelloWorld/HelloWorldBus.h>
void InSomeFunctionSomewhere()
{
// ...
// Invoke the call through EBus.
EBUS_EVENT(HelloWorld::HelloWorldRequestBus, SayHello, "Bruce");
// ...
}
システムコンポーネント
AZ モジュールはプレビューリリースにあり、変更される可能性があります。
従来のゲームエンジンには多数のシングルトンクラスがあり、主要システムで個別に管理してい
ます。 Lumberyard の場合、これらのシングルトンはゲームプレイエンティティを強力に後押しす
る同一のコンポーネントエンティティシステムを使用してビルドされています。アプリケーション
が起動すると、システムエンティティが作成されます。このエンティティに配置されるあらゆる
コンポーネントが、システムコンポーネントと呼ばれます。システムエンティティには、常に ID
AZ::SystemEntityId (0) があります。
シングルトンを Lumberyard システムコンポーネントとしてビルドする際は、確立されたパターンで
問題解決を支援する相補技術の強力なスイートを使用しています。このトピックでは、システムコン
ポーネントを詳しく説明します。
スマート初期化の順序
ゲームエンジンのサイズが大きくなるにつれて、多数のシングルトンクラスが開発される傾向があり
ます。シングルトンクラスが機能するには、他のシングルトンと通信する必要がある場合が多くあり
ます。つまり、シングルトンが初期化される順序が非常に重要です。Lumberyard では、シングルトン
をコンポーネントとしてビルドすることでこれを解決します。
Version 1.6
138
Lumberyard 開発者ガイド
簡単に設定可能なコンポーネント
コンポーネントでは、どのサービスを提供するか、それが他のどのサービスに依存するかを宣言でき
ます。コンポーネントがアクティブ化されると、宣言された依存関係に従って並べ替えられ、適切な
初期化順序になります。
以下は、Lumberyard が初期化を指示した 2 つのコンポーネントの例です。
class AssetDatabaseComponent : public Component
{
...
static void GetProvidedServices(ComponentDescriptor::DependencyArrayType&
provided)
{
provided.push_back(AZ_CRC("AssetDatabaseService"));
}
...
};
class AssetCatalogComponent : public AZ::Component
{
...
static void
GetRequiredServices(AZ::ComponentDescriptor::DependencyArrayType& required)
{
required.push_back(AZ_CRC("AssetDatabaseService"));
}
...
};
例では、AssetCatalogComponent の前に AssetDatabaseComponent がどのようにアクティ
ブ化するかを示しています。AssetDatabaseComponent クラスで、GetProvidedServices
関数によってクラスが AssetDatabaseService というサービスを提供することが明らか
にされます。AssetCatalogComponentクラスで、GetRequiredServices 関数によって
AssetCatalogComponent が AssetDatabaseService に依存することが明らかにされま
す。Lumberyard はこの依存性を理解し、それに応じて初期化の順序を指示します。
コンポーネントの初期化順序について詳しくは、「AZ ブートストラップのプロセス (p. 150)」を参
照してください。
簡単に設定可能なコンポーネント
多くの場合、シングルトンにはゲームごとに設定可能な設定があります。低レベルシングルトンで
は、設定データを処理するシステムがまだ起動していないためデータにアクセスできない場合があり
ます。したがって、低レベルシングルトンの多くはコマンドラインパーサーや .ini ファイルなど簡
単なデータソースを使用しています。
システムコンポーネントは AZ リフレクションを通じて設定を表示できます。プロジェクトコンフィ
ギュレーターの [Advanced Settings] ダイアログボックス (p. 145)は、この機能を使用してゲームご
とのシステムコンポーネントの設定を可能にします。プロジェクトコンフィギュレーターでは、各シ
ステムコンポーネントの設定を含むアプリケーション記述子ファイル (p. 149)を保存します。この
ファイルは、アプリケーションをブートストラップし各コンポーネントをアクティブ化前に設定する
ために使用されます。これは、Lumberyard エディタ でエンティティインスペクターによってゲーム
プレイエンティティを設定するために使用されている技術と同じものです。詳細については、「シス
テムエンティティの設定 (p. 145)」を参照してください。
Version 1.6
139
Lumberyard 開発者ガイド
システムコンポーネントの作成
システムコンポーネントの作成
コンポーネントをゲームプレイコンポーネントではなくシステムコンポーネントとして指定するに
は、EditContext に反映させるときに AppearsInAddComponentMenu フィールドを System に設
定する必要があります。
次のコード例は、MemoryComponent をシステムコンポーネントとして指定します。
void MemoryComponent::Reflect(ReflectContext* context)
{
if (SerializeContext* serializeContext =
azrtti_cast<SerializeContext*>(context))
{
...
if (EditContext* editContext = serializeContext->GetEditContext())
{
editContext->Class<MemoryComponent>("Memory System", "Manages
memory allocators")
->ClassElement(AZ::Edit::ClassElements::EditorData, "")
>Attribute(AZ::Edit::Attributes::AppearsInAddComponentMenu, AZ_CRC("System"))
...
}
}
}
必須のシステムコンポーネント
多くの場合、モジュールにはシステムコンポーネントが必須です。この要件はモジュールの
GetRequiredSystemComponents() 関数によって確立できます。ここで宣言されているコンポーネ
ントタイプは、アプリケーションの開始時に存在が保証されます。
次の例では、OculusDevice コンポーネントが Oculus Gem に必要です。
GetRequiredSystemComponents()
AZ::ComponentTypeList OculusGem::GetRequiredSystemComponents() const override
{
return AZ::ComponentTypeList{
azrtti_typeid<OculusDevice>(),
};
}
システムコンポーネントは任意の場合は、プロジェクトコンフィギュレーターの詳細設定 (p. 145)か
ら追加できます。
gem と AZ モジュール
AZ モジュールはプレビューリリースにあり、変更される可能性があります。
gem システムはプロジェクト間のコード共有を容易にするために開発されました。Gem
は、Lumberyard のゲームに簡単に追加または削除できるモジュールコードやアセットの再利用可能な
Version 1.6
140
Lumberyard 開発者ガイド
gem の構造
パッケージです。また、gem はレガシーライブラリよりもモジュラーな方法でコードの作成を支援し
ます。たとえば、各 gem にはそれぞれ、パブリックインターフェイスコードファイル用のフォルダが
含まれています。また gem には、セマンティックバージョニングや他の gem の依存関係を示す機能
などの、パッケージ管理メタデータが付属しています。
gem の構造
gem のディレクトリの内容は次のように整理されています。
GemDirectory/
Assets/
(assets usable to projects)
Code/
Include/
(public interface code files)
Source/
(private implementation code files)
Tests/
(code files for tests)
wscript (waf build info)
gem.json (gem metadata)
Waf の統合
各ゲームプロジェクトでは、使用する gem を明示的にリストする必要があります。Waf ビルドシ
ステムを実行すると、アクティブに使用する gem のみがビルドされます。Waf ではまた、gem の
include/ ディレクトリがその gem に明示的に依存するゲームまたはプロジェクトにアクセスできる
ようにします。
AZ モジュールとしてビルドされる gem
Lumberyard 1.5 から、Lumberyard に同梱するすべての gem を AZ モジュールとして構築する必要が
あります。gem を AZ モジュールとしてビルドする場合、gem では AZ フレームワークで指定される
初期化関数が使用されます。AZ モジュールの gem には、イベントバス (p. 415)であり新しいコン
ポーネントエンティティシステムによりよく統合されるパブリックインターフェイスがあります。レ
ガシー gem のサポートも継続されますが、今後は AZ モジュールに基づいた gem を使用することを
強く推奨します。レガシー gem の移行については、Gem の変換を参照してください。
プロジェクトコンフィギュレーターを使用して gem を有効または無効にすると、それに伴い
Lumberyard でアプリケーション記述子ファイル (p. 149)が更新され、すべての AZ モジュールを確
実に参照するようにします。手動で dev\<project_asset_directory>\gems.json の gem のリ
ストを編集した場合は、以下のコマンドを使用してアプリケーション記述子ファイルを最新にできま
す。
dev\Bin64\lmbr.exe projects populate-appdescriptors
Gem のバージョニングについて
GemFormatVersion 値は gem 構築のバージョニングです。0.1.0 のような Gem のバージョン番号
は、gem の API バージョンを参照しています。
Lumberyard 1.4 以前の gem (レガシー gem) ではすべて GemFormatVersion 値は 2 で
す。Lumberyard 1.5 からは、Lumberyard に含まれるすべての gem は AZ モジュールであ
り、GemFormatVersion の値は 3 です。これにより、Lumberyard に gem が AZ モジュールである
ことおよびそれに従ってロードする必要があることがわかります。
Version 1.6
141
Lumberyard 開発者ガイド
gem ではない AZ モジュールの作成
Gem には、0.1.0 のような API バージョン番号がついている場合もあります。これ
は、GemFormatVersion とは別のものです。API バージョンは API の変更をユーザーに警告し
ます。API バージョン番号が変更されると、その gem のユーザーがコードを変更する必要がある
場合があります。たとえば、Rain Gem のバージョンは、API が変更されるまで 0.1.0 のままで
す。Lumberyard 1.4 の Rain Gem を使用している場合、Lumberyard 1.5 の Rain Gem もデータや
コードを変更せずに使用できます。
gem の詳細については、Amazon Lumberyard User Guide の Gem を参照してください。
gem ではない AZ モジュールの作成
AZ モジュールはプレビューリリースにあり、変更される可能性があります。
Lumberyard 1.5 から gem が AZ モジュールとなるため、AZ モジュールの構築方法としてお勧めなの
は、単純に新しい gem を作成することです。ただし、プロジェクトで gem として構築する必要のな
い AZ モジュールが必要な場合は、ここに示す手順に従ってください。
A. gem を使用して開始
gem には AZ モジュールに必要なすべてのコードが含まれているため、最初に gem を作成してから、
それを編集して gem 以外にする方法が簡単です。さらに、新しい gem はコードにわかりやすい方法
で名前を付けるため、便利です。新しい gem で取得できるコードの説明については、「AZ モジュー
ルのパーツ、説明 (p. 133)」を参照してください。
gem を作成してを変更するには
1.
2.
最初に、以下のステップを実行して gem を作成します。
a.
Lumberyard dev\Bin64\ ディレクトリーに移動して、ProjectConfigurator.exe を実行
します。
b.
プロジェクトを選択します (デフォルトは [SamplesProject] です)。
c.
[Enable Gems] をクリックします。
d.
[Create a New Gem] をクリックします。
e.
新しいモジュールの名前を入力します。(このページの例では、「HelloWorld」という名前を
使用します。)
f.
[OK] をクリックします。
新しい gem から目的の場所に code ディレクトリを移動し、名前を変更します。たとえば、次の
ようにディレクトリを移動します。
dev/Gems/HelloWorld/Code
先
dev/Code/<optional subfolder>/HelloWorld
3.
gem の残りのコード以外の部分を削除するには、ディレクトリ dev/Gems/HelloWorld を削除
します。
B. AZ モジュールの宣言の編集
gem ではない AZ モジュールは必ずしも名前の中に UUID が含まれているわけではないため、gem の
.cpp ファイルも変更する必要があります。
Version 1.6
142
Lumberyard 開発者ガイド
C. CryEngine 参照の削除 (オプション)
.cpp ファイルを変更するには
1.
以下のように見えるコードを削除します。
// DO NOT MODIFY THIS LINE UNLESS YOU RENAME THE GEM
// The first parameter should be GemName_GemIdLower
// The second should be the fully qualified name of the class above
AZ_DECLARE_MODULE_CLASS(HelloWorld_010c14ae7f0f4eb1939405d439a9481a,
HelloWorld::HelloWorldModule)
2.
AZ_DECLARE_MODULE_CLASS 宣言を、この構文に続く宣言に置き換えます。
AZ_DECLARE_MODULE_CLASS(HelloWorld, HelloWorld::HelloWorldModule)
最初の引数 (HelloWorld) は、project.json ファイルに含まれる一意の識別子であり、wscript
の target フィールドに一致する必要があります。これは後のステップで実行します。2 番目の
引数は、すでに .cpp ファイル内で定義されているクラスと同じ完全修飾名です。
C. CryEngine 参照の削除 (オプション)
モジュールが CryEngine からのコードにアクセスしない (たとえば、gEnv にアクセスしない) 場合
は、以下の追加ステップを実行します。
CryEngine 参照を削除するには
1.
2.
.cpp ファイル (この例では HelloWorldModule.cpp) に次の変更を加えます。
a.
削除 #include <platform_impl.h>
b.
削除 #include <IGem.h>
c.
追加 #include <AzCore/Module/Module.h>
d.
HelloWorldModule を、CryHooksModule からではなく、AZ::Module から直接継承する
ように変更します。
StdAfx.h ファイルから以下のインクルードステートメントを削除します。
#include <platform.h> // Many CryCommon files require that this be
included first.
D. Wscript および Waf Spec ファイルの変更
次に、デフォルトの wscript ファイルを変更して gem 固有コマンドを削除し、wscript ファイルにモ
ジュールディレクトリを追加して、モジュールを適切な waf spec ファイルに追加する必要がありま
す。
wscript および waf spec ファイルを変更するには
1.
次のように wscript の内容を変更します。
def build(bld):
bld.CryEngineModule(
target
=
vs_filter
=
file_list
=
platforms
=
'HelloWorld',
'Game', # visual studio filter path
'HelloWorld.waf_files',
['all'],
Version 1.6
143
Lumberyard 開発者ガイド
E. 新しいモジュールをロードす
るようにプロジェクトを設定する
configurations
pch
use
includes
=
=
=
=
['all'],
['source/StdAfx.h'],
['AzFramework'],
['include', 'source'],
)
2.
モジュールのディレクトリが waf で再帰的に処理されるように、親ディレクトリにあ
る wscript を次の例のように修正します。
# ...
SUBFOLDERS = [
# ...,
'HelloWorld'
]
# ...
3.
モジュールを waf でビルドするには、Lumberyard ディレクトリにある該当する waf spec ファイ
ル (dev\_WAF_\specs\*.json) に、次のようにモジュールを追加します。
{
// ...
"modules":
{
// ...
"HelloWorld"
}
// ...
}
E. 新しいモジュールをロードするようにプロジェク
トを設定する
プロジェクトを起動すると、dev/<project_assets>/Config/Game.xml ファイルにリストされた
モジュールがロードされます (Editor.xml ファイルは Lumberyard エディタ を起動したときに使用
されます)。これらのファイルは自動的に生成されるものであり、手動で編集してはいけません。
プロジェクトで AZ モジュールをロードするように設定する方法
1.
gem ではないモジュールをこの自動的に生成されるリストに含めるには、以下の行を
project.json ファイル (パス位置 dev/<project_asset_folder>/project.json) に追加
します。
{
// ...
"flavors": {
"Game": {
"modules": [
"LmbrCentral",
"HelloWorld"
]
},
"Editor": {
"modules": [
Version 1.6
144
Lumberyard 開発者ガイド
F. モジュールのパブリックインターフェイス
をプロジェクトのインクルードパスに追加する
"LmbrCentralEditor",
"HelloWorld"
]
}
}
}
Note
フレーバーセクションはプロジェクトにない場合があります。存在しない場
合、Lumberyard では LmbrCentral モジュールが Game に、LmbrCentralEditor モ
ジュールが Editor に使用されるとみなされます。
2.
dev ディレクトリから、コマンドプロンプトで以下のコマンドを実行します。
Bin64\lmbr.exe projects populate-appdescriptors
このコマンドは Game.xml および Editor.xml ファイルを変更して HelloWorld モジュールを
リストするようにします。
F. モジュールのパブリックインターフェイスをプロ
ジェクトのインクルードパスに追加する
最後に、AZ モジュールのパブリックインターフェイスをプロジェクトの他の部分で使用できるよう
に、モジュールの include ディレクトリのプロジェクトに通知する必要があります。
AZ モジュールのパブリックインターフェイスをプロジェクトで使用できるようにするには
•
プロジェクトの wscript ファイルで、プロジェクトの include ディレクトリを指すように
includes 行を次の例のように編集します。
# ...
includes = [..., bld.Path('Code/Engine/HelloWorld/include')],
# ...
システムエンティティの設定
AZ モジュールはプレビューリリースにあり、変更される可能性があります。
単一のシステムエンティティは、各 Lumberyard アプリケーションの中核をなすものです。システム
コンポーネント (p. 138)と呼ばれるこのエンティティのコンポーネントは、Lumberyard 内の主要シ
ステムの主力です。プロジェクトコンフィギュレーターの [Advanced Settings] ダイアログを使用し
て、プロジェクトのコンポーネントを選択し、編集できます。システムエンティティの編集は、エン
ティティインスペクターのエンティティの編集に似ています。
システムエンティティを設定するには
1.
プロジェクトのプロファイルビルドをコンパイルして、プロジェクトコンフィギュレーターでプ
ロジェクトのコンパイル済みコードをロードできるようにします。
2.
Lumberyard の \dev\Bin64\ ディレクトリに移動して、ProjectConfigurator.exe を起動し
ます。
Version 1.6
145
Lumberyard 開発者ガイド
システムエンティティの設定
3.
プロジェクトコンフィギュレーターで、プロジェクトを選択します。
4.
[Advanced Settings] をクリックします。
初めてシステムエンティティ設定がロードされたときは、システムエンティティに足りない必須
コンポーネントを追加するように求められます。
システムコンポーネントには省略可能なものも、必須なものもあります。プロジェクトで使用さ
れている Lumberyard エンジンおよび gem の両方で、特定のコンポーネントを必要とする場合が
あります。
5.
[Yes] をクリックします。拒否しても、必要なコンポーネントは実行時に作成されます。
6.
[Advanced Settings] ダイアログボックスの上部にある [Project] オプションを使用して、編集する
プロジェクトを選択します。[Configuration] オプションで、Game (ランチャー) システムエンティ
ティを変更する場合は [Game] を選択します。Editor システムエンティティを変更する場合は
[Editor] を選択します。
Version 1.6
146
Lumberyard 開発者ガイド
システムエンティティの設定
[System Entity] タブに、追加されたコンポーネントがリストされます。
7.
[Add Component] をクリックして、さまざまなコンポーネントから追加するものを選択します。
Version 1.6
147
Lumberyard 開発者ガイド
システムエンティティの設定
8.
コンポーネントを削除するには、リストのコンポーネントを右クリックして、[Remove
Component ”<ComponentName>"] を選択します。
9.
[Memory Settings] タブで、[System memory settings] を展開しシステムメモリのオプションを設
定します。
10. [Save] をクリックして変更をディスクに保存します。変更は、次に説明するアプリケーション記
述子ファイルに保存されます。
Version 1.6
148
Lumberyard 開発者ガイド
アプリケーション記述子ファイル
アプリケーション記述子ファイル
システムエンティティの設定をプロジェクトコンフィギュレーターの [Advanced Settings] ダイアログ
ボックスで編集した場合、実際はアプリケーション記述子ファイルを編集していることになります。
アプリケーション記述子ファイルは Lumberyard 1.5 で初めて使用されるもので、プロジェクトが使用
するすべてのモジュールをリストします。現状、各プロジェクトのアセットディレクトリに、2 つの
アプリケーション記述子ファイルが必要になります。
dev/<project_asset_directory>/Config/Game.xml
dev/<project_asset_directory>/Config/Editor.xml
プロジェクトコンフィギュレーターの [Advanced Settings] ダイアログボックスで、これらのファイル
は [Configuration] メニューの [Game] および [Editor] オプションに対応します。
以下の例は、Game.xml ファイルの冒頭部分です。Game.xml ファイルと Editor.xml ファイルは両
方とも同じ構造です。
<ObjectStream version="1">
<Class name="ComponentApplication::Descriptor"
type="{70277A3E-2AF5-4309-9BBF-6161AFBDE792}">
<Class name="bool" field="useExistingAllocator" value="false"
type="{A0CA880C-AFE4-43CB-926C-59AC48496112}"/>
<Class name="bool" field="grabAllMemory" value="false" type="{A0CA880CAFE4-43CB-926C-59AC48496112}"/>
<Class name="bool" field="allocationRecords" value="true"
type="{A0CA880C-AFE4-43CB-926C-59AC48496112}"/>
<Class name="bool" field="autoIntegrityCheck" value="false"
type="{A0CA880C-AFE4-43CB-926C-59AC48496112}"/>
<Class name="bool" field="markUnallocatedMemory" value="true"
type="{A0CA880C-AFE4-43CB-926C-59AC48496112}"/>
<Class name="bool" field="doNotUsePools" value="false" type="{A0CA880CAFE4-43CB-926C-59AC48496112}"/>
<Class name="bool" field="enableScriptReflection" value="true"
type="{A0CA880C-AFE4-43CB-926C-59AC48496112}"/>
<Class name="unsigned int" field="pageSize" value="65536"
type="{43DA906B-7DEF-4CA8-9790-854106D3F983}"/>
<Class name="unsigned int" field="poolPageSize" value="4096"
type="{43DA906B-7DEF-4CA8-9790-854106D3F983}"/>
<Class name="unsigned int" field="blockAlignment" value="65536"
type="{43DA906B-7DEF-4CA8-9790-854106D3F983}"/>
<Class name="AZ::u64" field="blockSize" value="0"
type="{D6597933-47CD-4FC8-B911-63F3E2B0993A}"/>
<Class name="AZ::u64" field="reservedOS" value="0"
type="{D6597933-47CD-4FC8-B911-63F3E2B0993A}"/>
<Class name="AZ::u64" field="reservedDebug" value="0"
type="{D6597933-47CD-4FC8-B911-63F3E2B0993A}"/>
<Class name="char" field="recordsMode" value="2" type="{3AB0037FAF8D-48CE-BCA0-A170D18B2C03}"/>
<Class name="unsigned char" field="stackRecordLevels" value="5"
type="{72B9409A-7D1A-4831-9CFE-FCB3FADD3426}"/>
<Class name="bool" field="enableDrilling" value="true" type="{A0CA880CAFE4-43CB-926C-59AC48496112}"/>
<Class name="AZStd::vector" field="modules" type="{2BADE35A-6F1B-4698B2BC-3373D010020C}">
<Class name="DynamicModuleDescriptor" field="element"
type="{D2932FA3-9942-4FD2-A703-2E750F57C003}">
Version 1.6
149
Lumberyard 開発者ガイド
AZ ブートストラップのプロセス
<Class name="AZStd::string" field="dynamicLibraryPath"
value="LmbrCentral" type="{EF8FF807-DDEE-4EB0-B678-4CA3A2C490A4}"/>
</Class>
[…]
アプリケーション記述子ファイルのシステムコンポーネントのリストは、[Advanced Settings] ダイア
ログボックスの [System Entity] タブのコンポーネントのリストに対応しています。各コンポーネン
トを、個別に設定でいます。アプリケーション記述子ファイルには、メモリを割り当てる方法を決定
するプロパティも含まれています。これらは、[Advanced Settings] ダイアログボックスの [Memory
Settings] タブの設定に対応します。
AZ ブートストラップのプロセス
AZ モジュールはプレビューリリースにあり、変更される可能性があります。
AZ フレームワークアプリケーションは、アプリケーション記述子ファイル (p. 149)にリストされた
動的ライブラリおよび CreateStaticModules() 関数から参照される静的ライブラリに基づいてモ
ジュールを初期化します。
AzFramework::Application が開始されると、以下の順序でイベントが配置されます。
1. 実行可能ファイルが開始されます。
2. AzFramework::Application クラスが初期化されます。アプリケーション記述子ファイルのパス
および性的ライブラリから AZ::Modules を作成する関数へのポインタが取得されます。
3. アプリケーションブートストラップだけでアプリケーション記述子ファイルを読み込むことができ
ます。
4. メモリ割り付け設定およびロードする動的ライブラリのリストを取得するためにアプリケーション
記述子ファイルが読み込まれます。Lumberyard はまだファイルからシステムエンティティを読み
込むことはできません。
5. Lumberyard でブートストラップされたシステムがシャットダウンされ、先ほどロードされた設定
に応じて設定され、これらのシステムのバックアップが開始されます。
6. 各動的ライブラリがロードされます。
7. 各動的ライブラリの InitializeDynamicModule() 関数が実行され、グローバル
AZ::Environment に DLL がアタッチされます。
8. ステップ 2 で渡された関数ポインタを使用して、各静的ライブラリの AZ::Module インスタンス
が作成されます。
9. 各動的ライブラリの AZ::Module インスタンスが CreateModuleClass() 関数によって作成され
ます。
10.各 AZ モジュールの RegisterComponentDescriptors() 関数が呼び出されます。これで、ライ
ブラリ内に定義されたコンポーネントをシリアル化する方法がアプリケーションで認識されます。
11.システムエンティティをそのコンポーネントおよび設定と併せて展開するために、アプリケーショ
ン記述子ファイルがもう一度読み込まれます。
12.各 AZ モジュールの GetRequiredSystemComponents() 関数が呼び出されます。システムエン
ティティから欠落しているコンポーネントがある場合は追加されます。
13.システムエンティティがアクティブ化され、そのすべてのシステムコンポーネントが適切な順序で
アクティブ化されます。
この時点で、初期化が完了し、ゲームが実行されます。
Version 1.6
150
Lumberyard 開発者ガイド
AZ コードジェネレーター
AZ コードジェネレーター
AZ コードロードジェネレーターは、特別にタグが付けられたソースコードからソースコード (または
データやテキスト) を生成するコマンドラインユーティリティです。これは、生成するコードの構造が
事前にわかっているため、そのテンプレートを用意できる場合に使用できます。たとえば、シリアル
化またはリフレクションの共通コードを生成できます。
AZ コードジェネレーターは、既存の C++ ソースファイルまたはヘッダーファイル、あるいはその
両方のリストを解析して、JSON 形式で中間データを生成します。また、一連のテンプレートに中間
データを渡します。
テンプレートは、生成されるコードの形式を提供します。テンプレートは、共通コードの自動更新を
有効にするため、コーディング効率の向上を可能にします。テンプレートを更新すると、関連するす
べての生成済みコードが次のビルドで再生成されます。これにより、グルーコードを手動で更新した
り、エラーの原因となる検索と置換のオペレーションを使用したりする必要がなくなります。
トピック
• ワークフローの概要 (p. 151)
• WAF (p. 152)
• Clang (p. 152)
• 中間の JSON データ (p. 152)
• AZ コードジェネレーターと Python (p. 153)
• テンプレートドライバーとテンプレートのレンダリング (p. 154)
• 生成されるファイル (p. 154)
• AZ コードジェネレーターと Waf の統合 (p. 156)
• AZ コードジェネレーターのパラメーター (p. 158)
• コード生成テンプレート (p. 162)
• テンプレートドライバー (p. 164)
• カスタムコードジェネレーターの注釈 (p. 169)
• AZ コードジェネレーターによる Waf のデバッグ (p. 173)
• テンプレートドライバーのデバッグ (p. 179)
• AZ コードジェネレーターユーティリティのデバッグ (p. 180)
• 中間 JSON データ形式 (p. 182)
ワークフローの概要
次のステップでは、AZ コードジェネレーターが Waf と連携してコードを生成する方法を説明しま
す。
1. Waf ビルドシステムは wscript ファイルで指定された .h および .cpp ソースファイル用に AZ
コードジェネレーターを呼び出します。
Version 1.6
151
Lumberyard 開発者ガイド
WAF
2. AZ コードジェネレーターは、指定されたファイルに対して 1 つまたは複数のパスを実行します。
3. 各パスには以下が含まれます。
a. AZ コードジェネレーターは、Clang フロントエンドコンパイラを使用して、提供された各ソー
スファイル用に抽象構文ツリー (AST) を作成します。Clang パーサーは入力のコンパイルを試み
ます。処理速度を高めるため、#include ステートメントに従わず、すべてのエラーを抑制する
よう Clang に指定できます。
b. AST は中間の JSON 形式に変換されます。
c. 中間 JSON オブジェクトは Python スクリプト形式でテンプレートドライバーに渡されてか
ら、Jinja2 テンプレートに渡されます。各ドライバーおよびテンプレートは、特定のコード生成
タスクを実装します。
d. テンプレートドライバーは、中間の JSON オブジェクトで必要な事前処理を実行します。
e. 次に、中間の JSON は Jinja2 テンプレートに渡されます。
f. 各テンプレートドライバーは、任意の数の出力ファイルに出力できる、任意の数のテンプレート
を持つことができます。テンプレートドライバー作成者の希望により、複数のテンプレートが同
じ出力ファイルを持つことも、異なる出力ファイルを持つこともできます。
4. AZ コードジェネレーターは生成されたファイルのリストを Waf ビルドシステムに返します。
5. Waf ビルドシステムは、ビルドで自動生成されたコードを含めて、ビルドプロセスを完了します。
次のセクションでは、このプロセスの詳細を示します。
WAF
AZ コードジェネレーターは Waf ビルドシステムに完全に統合されています。Waf の az_code_gen
機能を使用して、AZ コードジェネレーターを起動できます。コマンドラインではなく Waf を使用し
て AzCodeGenerator.exe ユーティリティを起動することをお勧めします。
Waf の統合に関する例と詳細については、「AZ コードジェネレーターと Waf の統合 (p. 156)」を
参照してください。
Clang
AZ コードジェネレーターのフロントエンドは、C++ ソースコード用の Clang パーサー/コンパイラで
す。AZ コードジェネレーターは Clang を使用してソースコードを解析し (ユーザー定義タグが含ま
れる場合があります)、中間の JSON データオブジェクトを生成します。AZ コードジェネレーターは
Clang のパーサーとコンパイルフェーズを完全に制御し、診断などの機能を選択的に抑制したり、有
効にしたりできます。これにより、それ以外の場合にコンパイルに失敗する可能性のあるソースコー
ドを無視し、それでも完全な中間のオブジェクトを生成する柔軟性が AZ コードジェネレーターに与
えられます。
中間の JSON データ
Clang フロントエンドコンパイラは、さらに処理するためにジェネレーターがテンプレートに渡す中
間の JSON データ構造を出力します。中間の JSON データオブジェクトの例を次に示します。
[
{
'name' : 'Component',
'qualified_name' : 'AZ::Component',
'fields' : [],
'bases' : [],
'meta' : {
'path' : 'D:\\Repo\\Ly\\branches\\AzComponents\\Code\\Tools\
\AzCodeGenerator\\CodeGenTest.h'
Version 1.6
152
Lumberyard 開発者ガイド
AZ コードジェネレーターと Python
},
'type' : 'class',
'annotations' : {},
'methods' : []
},
{
'name' : 'TestingClass',
'qualified_name' : 'TheNamespace::TestingClass',
'fields' : [
{
'type' : 'float',
'name' : 'm_field2',
'qualified_name' : 'TheNamespace::TestingClass::m_field2',
'annotations' : {}
}
],
'bases' : [
{
'name' : 'Component',
'qualified_name' : 'AZ::Component'
}
],
'meta' : {
'path' : 'D:\\Repo\\Ly\\branches\\AzComponents\\Code\\Tools\
\AzCodeGenerator\\CodeGenTest.h'
},
'type' : 'class',
'annotations' : {},
'methods' : [
{
'params' : ['type', 'int', 'name', 'version'],
'name' : 'CreateArgumentAnnotation',
'qualified_name' :
'TheNamespace::TestingClass::CreateArgumentAnnotation',
'annotations' : {}
}
]
}
]
中間の JSON データオブジェクトの完全な構文については、「中間 JSON データ形式 (p. 182)」を
参照してください。
AZ コードジェネレーターと Python
AZ コードジェネレーターは Python 2.7 を利用してテンプレートドライバーを実行し、Jinja テンプ
レートをレンダリングします。Python C API を使用して、テンプレートドライバーが依存関係、
エラー、および有用な情報の出力をレポートできる、azcg_extension モジュールのメソッドで
Python を拡張します。Windows では、Python 2.7 は Lumberyard の dev/Tools/Python ディレクト
リに含まれています。OS X で、AZ コードジェネレーターはオペレーティングシステムに含まれてい
るバージョンの Python を使用します。
Note
AZ コードジェネレーターを使用するときに Python C API コールをデバッグするに
は、CPython をダウンロードし、デバッグするプラットフォーム用のビルドを作成する必要
があります。
Version 1.6
153
Lumberyard 開発者ガイド
テンプレートドライバーとテンプレートのレンダリング
テンプレートドライバーとテンプレートのレンダリ
ング
Python で書かれたテンプレートドライバーを使用して、テンプレートエンジンに渡す前に中間データ
構造を変更できます。事前処理の後、テンプレートドライバーは Jinja2 テンプレートエンジンに対し
て、生成される必要なコードに応じて 1 つまたは複数のテンプレートのレンダリングを指示すること
ができます。
AZ コードジェネレーターは Jinja2 テンプレートエンジンを使用します。このエンジンは \dev
\Tools\Python\2.7.11\windows\Scripts ディレクトリの Python の easy_install スクリプ
トによってダウンロードされ、Lumberyard の 3rdParty\jinja2 ディレクトリにコピーされま
す。また、Lumberyard は jinja_extensions モジュールを提供します。これには、テンプレー
ト内で使用できるヘルパーメソッドが含まれています。これら拡張機能は dev/Code/Tools/
AzCodeGenerator/Scripts/jinja_extensions/ ディレクトリに保存されています。Jinja テン
プレートの例と詳細については、「コード生成テンプレート (p. 162)」を参照してください。
生成されるファイル
次のサンプル出力は、シリアル化テンプレートから生成されました。参照 JSON オブジェクトは読み
やすい形式にしてあります。
/////////////////////////////////////////////////////////
/////////////////////////////////////////////////////////
// THIS CODE IS AUTOGENERATED, DO NOT MODIFY
/////////////////////////////////////////////////////////
/////////////////////////////////////////////////////////
#include "stdafx.h"
#include <AZCore/Rtti/ReflectContext.h>
#include <AzCore/Rtti/Rtti.h>
#include <AzCore/Serialization/SerializeContext.h>
#include <AzCore/Math/Vector3.h>
#include "D:/Repo/Ly/branches/AzComponents/Code/Tools/AzCodeGenerator/
CodeGenTest.h"
namespace Components
{
void TestingClassReflect(AZ::ReflectContext* reflection)
{
AZ::SerializeContext* serializeContext =
azrtti_cast<AZ::SerializeContext*>(reflection);
if (serializeContext)
{
serializeContext->Class<TestingClass>()
->SerializerForEmptyClass()
;
}
}
}
///////////////////////////////////////////////////////////////
/*
// Reference JSON object
[{
'name':'Component',
'qualified_name':'AZ::Component',
'fields':[
],
'bases':[
Version 1.6
154
Lumberyard 開発者ガイド
生成されるファイル
],
'meta':{
'path':'D:\\Repo\\Ly\\branches\\AzComponents\\Code\\Tools\
\AzCodeGenerator\\CodeGenTest.h'
},
'type':'class',
'annotations':{
},
'methods':[
]
},
{
'name':'TestingClass',
'qualified_name':'TheNamespace::TestingClass',
'fields':[
{
'type':'float',
'name':'m_field2',
'qualified_name':'TheNamespace::TestingClass::m_field2',
'annotations':{
}
}
],
'bases':[
{
'name':'Component',
'qualified_name':'AZ::Component'
}
],
'meta':{
'path':'D:\\Repo\\Ly\\branches\\AzComponents\\Code\\Tools\
\AzCodeGenerator\\CodeGenTest.h'
},
'type':'class',
'annotations':{
},
'methods':[
{
'params':[
'type',
'int',
'name',
'version'
],
'name':'CreateArgumentAnnotation',
'qualified_name':'TheNamespace::TestingClass::CreateArgumentAnnotation',
'annotations':{
}
}
]
}]
*/
Version 1.6
155
Lumberyard 開発者ガイド
AZ コードジェネレーターと Waf の統合
AZ コードジェネレーターと Waf の統合
AZ コードジェネレーターは、Waf ターゲットから az_code_gen 機能としてフルアクセス可能で
す。dev/Code/Tools/waf-1.7.13/lmbrwaflib/az_code_generator.py ファイルには、Waf
統合の主要なコードが含まれます。また、wscript ファイルから使用できる az_code_gen 機能も含
まれます。
最低限必要な情報は、コードジェネレーターと 1 つ以上のテンプレートドライバーに渡すファイルの
リストです。このリストからコードジェネレーターにファイルが 1 つずつ渡され、ドライバーによっ
て指定されたテンプレートが呼び出されます。ドライバーからのファイル出力はビルドタスクの依存
関係として追加されます。出力ファイルには、コンパイル用に C++ ビルドに再挿入されるオプション
もあります。出力ファイルのパスは、現在のターゲットビルドと export_header エントリに使用す
るインクルードパスとして自動的に追加されます。これにより、記述したソースコードでは、内部と
外部の両方のターゲットから、生成されたソースコードを参照できます。
トピック
• 基本的な統合 (p. 156)
• 高度な統合 (p. 156)
• 入力ファイル (p. 157)
• テンプレートドライバー (p. 158)
• コマンドラインパラメーター (p. 158)
• Waf 固有のオプション (p. 158)
基本的な統合
生成されたコードを必要とするターゲットの wscript ファイルで、以下のように az_code_gen 機
能を追加します。
features = ['az_code_gen'],
次に、以下の例のように、コードジェネレーターへの入力として渡すファイルを指定します。
az_code_gen = [
{
'files' : ['MySourceFile.h'],
'scripts' : ['MyTemplateDriver.py']
}
],
指定したパスは、いずれの場合も、ターゲットパスに相対的です。
指定したターゲットがコンパイルされるたびに、コードジェネレーターに MySourceFile.h ファ
イルを渡し、MyTemplateDriver.py ファイルを呼び出して出力を制御する、コード生成タス
クが生成されます。テンプレートドライバーを記述する方法については、「テンプレートドライ
バー (p. 164)」を参照してください。
高度な統合
AZ コードジェネレーターの Waf 統合で、パスを使用して、ビルド時に実行されるコードジェネレー
タータスクを定義します。各パスによって、コードジェネレーターの実行に使用する一連のファイ
ル、ドライバー、環境設定が決まります。現在、すべてのパスは、パス間の依存性チェックなしで、
並列に実行されます。
Version 1.6
156
Lumberyard 開発者ガイド
AZ コードジェネレーターと Waf の統合
以下の例では、複数のパスの設定を示しています。
az_code_gen = [
{
'files' :
'scripts'
},
{
'files' :
'scripts'
}
],
['MyCode/MySourceFile.h'],
: ['MyCode/MyTemplateDriver.py']
['MyOtherCode/MyOtherSourceFile.h'],
: ['MyOtherCode/MyOtherTemplateDriver.py']
この例では、以下の 2 つのコード生成タスクを生成します。
1. コードジェネレーターに MyCode / MySourceFile.h ファイルを渡し、出力の制御用に MyCode/
MyTemplateDriver.py ファイルを呼び出します。
2. コードジェネレーターに MyOtherCode/MyOtherSourceFile.h を渡し、出力の制御用に
MyOtherCode/MyOtherTemplateDriver.py を呼び出します。
入力ファイル
各パスにより、コードジェネレーターへの入力として使用されるファイルのリストを渡します。この
リストには、文字列のパス、ノード、リストを含めることもできます。トップレベルの文字列のパス
とノードはコードジェネレーターに個別に渡されます。次の点に注意してください。
• リストを渡す場合、そのリストに含まれるすべてのファイルまたはノードは、コードジェネレー
ターによって同時に使用されます。これにより、柔軟性は最大になりますが、1 つのタスクにつき
1 つの入力というのが一般的な使用方法です。
• Waf タスクと AZ コードジェネレーターブートストラップのオーバーヘッドが重要になる場合があ
ります。パフォーマンスを向上させるために、複数の入力ファイルを 1 つのリストで渡すことがで
きます。
• コードジェネレーターによって入力ファイルごとに同じ Clang とテンプレートドライバーパイプラ
インが呼び出されます。
以下の例では、複数の入力ファイルを指定しています。
# Finds this file relative to the build context source node
'files' : [bld.srcnode.find_or_declare('Code/Framework/AzCore/Tests/
CodeGen.h')],
'files' : [
# Pass both MyClass.h and MyClass.cpp at the same time to code generator to
get more
# information about MyClass than just the header. Note the nested lists.
['MyClass.h', 'MyClass.cpp']
]
'files' : [
# Any and all variations are allowed, but because lists provide only one
layer of grouping,
# lists are allowed only at the top level.
'MySourceFile.h',
'MyOtherSourceFile.cpp',
bld.srcnode.find_or_declare('Code/Framework/AzCore/Tests/CodeGen.h'),
Version 1.6
157
Lumberyard 開発者ガイド
AZ コードジェネレーターのパラメーター
['MyClass.h', 'MyClass.cpp']
]
テンプレートドライバー
コード生成パスごとに使用するテンプレートドライバーを指定するには、以下の例のように、文字列
のパス (ターゲットパスに相対的) のリストを渡します。
'scripts' : [
'../../../Framework/AzFramework/CodeGen/AzClassCpp.py',
'../../../Framework/AzFramework/CodeGen/AzEBusInline.py',
'../../../Framework/AzFramework/CodeGen/AzReflectionCpp.py',
'../../../Framework/AzFramework/CodeGen/AzClassInline.py'
],
コマンドラインパラメーター
コード生成ユーティリティのすべてのコマンドラインパラメーターは、以下の例のように、引数のリ
ストを渡すことで、各コード生成パスで指定できます。
'arguments' : [
'-OnlyRunDiagnosticsOnMainFile=true',
'-SuppressDiagnostics=false',
'-SuppressErrorsAsWarnings=false',
'-output-redirection=file',
],
すべてのパラメーターのリストについては、「AZ コードジェネレーターのパラメーター (p. 158)」
を参照してください。
Waf 固有のオプション
Waf 統合には、以下の例のように、コード生成パスごとにリストで指定できる追加のオプションが用
意されています。
'options' : ['PrintOutputRedirectionFile'],
PrintOutputRedirectionFile - -output-redirection=file パラメーターと組み合わせて使用
すると、Waf から AZ コードジェネレーターに、コード生成時に追加の出力を保存するためのパスが
渡されます。ビルド時、エラーが発生した場合は、このファイルへのパスがタスクごとに表示されま
す。
AZ コードジェネレーターのパラメーター
最良の結果を得るには、AZ コードジェネレーターのオプションを Waf ビルドシステムに渡します。
ただし、コマンドラインで AzCodeGenerator.exe のパラメーターを指定することもできます。
トピック
• Waf のパラメーター (p. 159)
• Clang のコンパイルパラメーター (p. 159)
• 中間のデータ (p. 159)
• フロントエンド (p. 159)
• AZ コードジェネレーターパラメーターのリスト (p. 159)
Version 1.6
158
Lumberyard 開発者ガイド
AZ コードジェネレーターのパラメーター
Waf のパラメーター
AZ コードジェネレーターのほとんどのパラメーターは、Waf の統合によって指定されます。入力パ
ス、出力パス、インクルードパスなどのパラメーターは、自動的に検出され、転送されます。その他
の AZ コードジェネレーターのパラメーターは、ソースコードの入力と生成された中間データを AZ
コードジェネレーターがどのように処理するかを制御します。
wscript ファイルの az_code_gen パスの arguments セクションで、これらのいずれかのパラメー
ターを指定します。
Clang のコンパイルパラメーター
次の AzCodeGenerator.exe パラメーターは Clang のコンパイルに適用されます。
パラメーター
説明
コンパイル時に不明な #include ステートメントを抑制します。
SuppressIncludeNotFoundError
コンパイルに指定された主なファイルを除く、ビルドの警告とエラーを
OnlyRunDiagnosticsOnMainFile
すべて無視します。
SuppressDiagnostics
すべてのファイルでビルドの警告とエラーを無視します。
ビルドエラーを警告にダウングレードします。エラーが発生しても
SuppressErrorsAsWarnings
Clang の成功を許可します。
中間のデータ
中間の JSON データの入力ファイル外部に、コードに関する情報を含めるには、次のオプションを使
用します。
-inclusion-filter=<wildcard filter for files to allow>
フロントエンド
-Clang (デフォルト) または -JSON オプションを指定して、使用するフロントエンドを選択できま
す。
AZ コードジェネレーターパラメーターのリスト
次のリストに、すべての AZ コードジェネレーターのパラメーターを示します。
使用法: AzCodeGenerator.exe [options]
オプション
カテゴ
リ
説明
-Clang
全般
Clang コンパイラフロントエンドを使用します。
-clang-settingsfile=<string>
コード
解析
Clang 設定を含むファイルへのパス。
-codegenscript=<string>
Python
起動するコード生成スクリプトの絶対パスとファイル名。
Version 1.6
159
Lumberyard 開発者ガイド
AZ コードジェネレーターのパラメーター
オプション
カテゴ
リ
説明
-debug
全般
デバッグ出力を有効にします。
-debug-buffersize=<uint>
全般
プログラム終了まで、デバッグ出力の最後の n 文字をバッファし
ます。デフォルト値は 0 で、即時の出力が指定されます。
-debugonly=<debug
string>
全般
特定のタイプのデバッグ出力を有効にします。
-define=<string>
コード
解析
プリプロセッサ定義を指定します。
AST ト
DelayedTemplateParsing
ラバー
サル
変換単位の最後に解析するため、テンプレートトークンが消費お
よび保存されます。
AST ト 増分処理を有効にします。
EnableIncrementalProcessing
ラバー
サル
-forceinclude=<string>
コード
解析
Clang 解析に強制的に含めるヘッダーの一覧。
-help
全般
分類された形式で基本オプションを表示します。
-help-hidden
全般
分類された形式で、利用できるすべてのオプションを表示しま
す。
-help-list
全般
リスト形式で基本オプションを表示します。
-help-listhidden
全般
リスト形式で、利用できるすべてのオプションを表示します。
-includepath=<string>
コード
解析
ヘッダーのインクルードパス。
-inclusionfilter=<string>
コード
フィル
タリン
グ
ワイルドカードフィルタを指定し、input-files で指定された
以外のファイルが、Clang によって中間データに分析されるよう
にします。
-info-outputfile=<filename>
全般
-stats 出力を追加するファイル。
-inputfile=<string>
コード
解析
(必須) 値 input-path に対する相対的な入力ファイルのパス。
-inputpath=<string>
コード
解析
(必須) 入力フォルダーへの絶対パス。すべての input-file パス
はこのフォルダーに相対的である必要があります。
-intermediatefile=<string>
コード
解析
Clang 解析からの JSON AST を保存するファイルへのパス。
-JSON
全般
フロントエンドに raw JSON 入力を使用します。
-noscripts
全般
codegen スクリプトの実行を無効にします。
Version 1.6
160
Lumberyard 開発者ガイド
AZ コードジェネレーターのパラメーター
オプション
カテゴ
リ
説明
Clang
コンパイルされる主なファイルでのみ、診断 (エラーと警告の
OnlyRunDiagnosticsOnMainFile
コンパ
チェック) を実行します。他のすべてのファイルのエラーと警告を
イル
無視します。
-outputpath=<string>
コード
解析
(必須) 出力フォルダーへの絶対パス。
-outputredirection
出力
Clang および Python の内部ユーティリティからの出力とエラー
メッセージをリダイレクトします。
オプション:
=none – 出力はリダイレクトされません。Clang と Python は
stdout および stderr に出力されます。
=null – Clang および Python を null にリダイレクトし、実質的に
出力を抑制します。
=file – Clang および Python をディスクにリダイレクトしま
す。redirect-output-file を使用してパスを指定します。
-output-usingjson
出力
プレーンテキストの代わりに JSON オブジェクトを使用して出力
します。このオプションを使用して、呼び出し元アプリケーショ
ンの解析を容易にします。
-print-alloptions
全般
コマンドラインの解析後にすべてのオプション値を表示します。
-print-options
全般
コマンドラインの解析後にデフォルト以外のオプションを表示し
ます。
-python-debugpath=<string>
Python
デバッグで使用する AzCodeGenerator.exe 用の Python デバッ
グライブラリとスクリプトへのパス。
-pythonhome=<string>
Python
(必須) PYTHONHOME 環境変数に相当するもので、無視されます。
-python-homedebug=<string>
Python
デバッグ Python PYTHONHOME 環境変数と同じようなもので、無
視されます。
-pythonpath=<string>
Python
AzCodeGenerator.exe 用の Python ライブラリとスクリプトへ
のパス。
-redirectoutputfile=<string>
出力
リダイレクトされた出力のファイルパス。-outputredirection=file オプションと組み合わせて使用します。デ
フォルトのファイル名は output.log です。
-resourcedir=<string>
コード
解析
Clang のリソースディレクトリへのパス。
-stats
全般
プログラムから統計の出力を有効にします (アサーションで使用可
能)。-info-output-file=<filename> オプションを使用して
出力ファイルを指定します。
AST ト
SkipFunctionBodiesラバー
サル
関数の本文を走査しません。
Version 1.6
161
Lumberyard 開発者ガイド
コード生成テンプレート
オプション
カテゴ
リ
説明
Clang
SuppressDiagnostics
コンパ
イル
Clang のコンパイル診断情報を非表示にします。
Clang
SuppressErrorsAsWarnings
コンパ
イル
コンパイルのエラーを警告として報告することで、解析中のコン
パイルエラーを抑制します。
AST ト #include が見つからないエラーを抑制します。
SuppressIncludeNotFoundError
ラバー
サル
-track-memory
全般
-time-passes メモリ追跡を有効にします。このオプションを使
用すると、パフォーマンスが低下する可能性があります。
-v
全般
詳細なデバッグ情報を出力します。
-version
全般
AzCodeGenerator.exe のバージョンを表示します。
-view-background
全般
バックグラウンドでグラフビューアを実行します。このオプショ
ンでは、手動で削除する必要がある .tmp ファイルを作成しま
す。
コード生成テンプレート
AZ コードジェネレーターによって、Python の Jinja2 テンプレートエンジンが使用されて、その出力
がレンダリングされます。Jinja テンプレートエンジンによって、変数および論理ステートメントが組
み込まれたプレーンテキストが出力されます。
Jinja テンプレートは、非常に読みやすくなるように、かつ必要な出力の構造全体を模倣するように設
計されています。これらのテンプレートは上から下に処理されます。テンプレート内の制御ブロック
の外のテキストは出力に直接渡されます。
以下に示しているのは、いくつかのサンプルテンプレートです。Jinja テンプレートの作成の詳細につ
いては、Jinja Template Designer のドキュメントを参照してください。
トピック
• シンプルな例 (p. 162)
• 複雑な例 (p. 163)
• テンプレートのデータ (p. 164)
シンプルな例
Jinja テンプレートは、以下の例のように、テキスト変数を使用して、出力内の所定の位置にあるテキ
ストを置き換えます。
// Here's a {{ variable_name }} !!
int {{ variable_name }} = {{ variable_value }};
この例では、Jinja テンプレートに以下の入力を渡しています。
{
Version 1.6
162
Lumberyard 開発者ガイド
コード生成テンプレート
'variable_name' = 'foo',
'variable_value' = 42
}
出力結果は以下のようになります。
// Here's a foo !!
int foo = 42;
複雑な例
Jinja では、かなり複雑なロジック、制御構造の分岐とループが可能です。以下のサンプルテンプレー
トは、入力で指定されたパブリックおよびプライベート変数を使用するクラスを生成します。
// This class is auto-generated!
class {{ class.name }}
{
public:
virtual ~{{ class.name }}() = default;
{% if class.members is defined %}
{% for member_var in class.members if member_var.visibility is 'public' %}
{{ member_var.type }} m_{{ member_var.name }}{{ if member_var.value is
defined }} = {{ member_var.value }}{{ endif }};
{%- endfor %}
{% endif %}
private:
{% if class.members is defined %}
{% for member_var in class.members if member_var.visibility is 'private'
-%}
{{ member_var.type }} m_{{ member_var.name }}{{ if member_var.value is
defined }} = {{ member_var.value }}{{ endif }};
{%- endfor %}
{% endif %}
};
この例では、Jinja テンプレートに以下の入力を渡しています。
{
'class' : {
'name' : 'MyClass',
'members' : [
{
'name' : 'foo',
'type' : 'int',
'visibility' : 'public'
},
{
'name' : 'bar',
'type' : 'long',
'visibility' : 'public',
},
{
'name' : 'secretSauce',
'type' : 'float',
'visibility' : 'private',
Version 1.6
163
Lumberyard 開発者ガイド
テンプレートドライバー
'value' : '98.6f'
}
]
}
}
テンプレートによって以下の出力が生成されます。
// This class is auto-generated!
class MyClass
{
public:
virtual ~MyClass() = default;
int m_foo;
long m_bar;
private:
float m_secretSauce = 98.6f;
};
テンプレートのデータ
テンプレートに使用できるデータは Python テンプレートドライバー (p. 164)によって完全に制御さ
れます。
以下の表では、Jinja 環境に自動的に追加される変数を示しています。
可変
説明
extra_data
テンプレートドライバーの apply_transformations (p. 166) メソッドによって返さ
れるデータを含む Python オブジェクト。
extra_str
JSON 形式で extra_data の内容を含む文字列。
json_object テンプレートドライバーによって処理された後にデコードされた中間 JSON を含む
Python オブジェクト。
json_str
テンプレートドライバーによって処理された後にエンコードされた中間 JSON を含
む文字列。
中間出力の詳細については、「中間 JSON データ形式 (p. 182)」を参照してください。
Note
Jinja には、制限付きの機能がいくつか含まれているため、Jinja テンプレートで複雑なデータ
変換を実行しようとすると、非常に複雑で一般的に読めないテンプレートが生成されます。
この理由から、すべての主要なデータ操作をテンプレートドライバーで実行してから、Jinja
テンプレートエンジンに渡すことをお勧めします。詳細については、「テンプレートドライ
バー (p. 164)」を参照してください。
テンプレートドライバー
テンプレートドライバーは、中間 JSON データを処理して Jinja2 の出力テンプレートに配信する
Python スクリプトです。このスクリプトは Clang のフロントエンドからのデータを事前処理し、テン
プレートレンダリングを実行し、生成された出力をディスクのどこに書き込むかを制御します。
Version 1.6
164
Lumberyard 開発者ガイド
テンプレートドライバー
これらのスクリプトは通常、WAF の wscript ファイルの 1 つ以上のコード生成パスによって呼び出
されます。各 Python スクリプトは複数のテンプレートを参照できます。これにより、特に複数のテ
ンプレートが同じ事前処理済みデータに依存している場合は、非常に柔軟な実装が可能になります。
トピック
• Waf でドライバーを指定する (p. 165)
• Python でテンプレートドライバーを作成する (p. 165)
• 最小限のテンプレートドライバー (p. 167)
• レンダリングテンプレート (p. 167)
• 自動構築挿入を設定する (p. 168)
• 中間データを事前処理する (p. 168)
Waf でドライバーを指定する
ドライバーは各コード生成パス内のファイル名で指定されます。ファイルのパスは wscript ター
ゲットのルートからの相対です。すべてのドライバーは、各入力ファイルで呼び出されます。
次に、サンプルの Waf 項目の構造を示します。
'az_code_gen' = [
{
'files': [ <files to gen> ],
'scripts': [ <list of script file paths relative to current wscript
folder> ]
}
]
パスの指定方法の詳細については、「AZ コードジェネレーターと Waf の統合 (p. 156)」を参照し
てください。
Python でテンプレートドライバーを作成する
Python でテンプレートドライバーを作成するには、TemplateDriver 基本クラスをインポートし、
メソッドを上書きする必要があります。クラスのコードは dev/Code/Tools/AzCodeGenerator/
Scripts/az_code_gen/base.py ファイルにあります。
このクラスは AZ コードジェネレーターによって自動的に Python に挿入されますが、次の例のよう
に、az_code_gen.base としてインポートされる必要があります。
from az_code_gen.base import *
TemplateDriver クラスで上書きするメソッド
テンプレートドライバーを実装するには、TemplateDriver クラスの次のメソッドを上書きします。
add_dependency
add_dependency メソッドを呼び出して、Waf の az_code_gen タスクに依存関係を手動で追加しま
す。Waf では自動的に含められない依存関係をレンダリングテンプレートで追加して指定できるよう
に、ファイルパスは絶対パスで指定する必要があります。これらの依存関係には、テンプレートのレ
ンダリングに使用する外部データファイルであったり、入力データを生成するために使用されたファ
イルであることもあります。
構文
Version 1.6
165
Lumberyard 開発者ガイド
テンプレートドライバー
add_dependency(self, dependency_file)
apply_transformations
apply_transformations メソッドを上書きして、obj パラメーターとして渡された未加工の JSON
オブジェクトを操作します。処理がオブジェクトで実行されます。オブジェクトはその後パイプライ
ンを経由して転送され、最終的には render_templates の jinja_args に渡されます。このメソッ
ドで返されるオブジェクトはすべて、extra_data として Jinja 環境に提供されます。
構文
apply_transformations(self, obj)
このメソッドの例については、「中間データを事前処理する (p. 168)」を参照してください。
get_expected_tags
get_expected_tags メソッドを上書きして、すべての入力ファイルで見つける必要があるタグのリ
ストを返します。必要なタグがない場合、このドライバーはスキップされます。
Important
このメソッドは Lumberyard v1.6 までに廃止されます。Lumberyard v1.6 以降は、すべてのス
クリプトはタグの想定に関わらず処理され、get_expected_tags は呼び出されません。
構文
get_expected_tags(self)
render_template_to_file
テンプレートをディスクにレンダリングします。このメソッドでは output_file の値も Waf の
az_code_gen タスクの依存関係として追加されます。
構文
render_template_to_file(self, template_file, template_kwargs, output_file,
should_add_to_build=False)
パラメーター
パラメーター
説明
template_file
テンプレートへのパスを、テンプレートドライバーの .py ファイルを含むディ
レクトリからの相対で指定します。
template_kwargsJinja に渡すキーと値のペアのディクショナリを指定します。一般的に、これは
render_templates に指定された jinja_args のパススルー変数として扱わ
れますが、追加のキーと値のペアを追加できます。
output_file
レンダリングされた Jinja の出力の対象ファイルを指定します。パスは、対象出
力フォルダを基準とする相対パスです。
should_add_to_build
Waf が C++ 構築およびリンカーにこのファイルを追加するかどうかを指定する
ブール値。デフォルト: false。
Version 1.6
166
Lumberyard 開発者ガイド
テンプレートドライバー
render_templates
render_templates を上書きして、render_template_to_file を呼び出すことでテンプレートの
レンダリングを起動します。
構文
render_templates(self, input_file, **jinja_args)
パラメーター
パラメー
ター
説明
input_fileClang を起動するために使用される入力パスからの相対パス。
jinja_argsテンプレートドライバーがオブジェクトで事前処理を実行した後の中間 JSON オブジェ
クトからの未加工データ。
最小限のテンプレートドライバー
テンプレートドライバーに最小限必要なコードは、TemplateDriver 基本クラスから取得し、ファク
トリ関数を実装してテンプレートドライバーを作成するコードです。
from az_code_gen.base import *
class MyTemplateDriver(TemplateDriver):
pass
# Factory function - called from launcher
def create_drivers(env):
return [MyTemplateDriver(env)]
az_code_gen モジュールは AZ コードジェネレーターによって自動的に提供されます。これに
は、TemplateDriver および base.py ファイルからの役に立つメソッドが含まれています。
create_drivers 関数は、単純にレンダリングテンプレートで使用される Jinja 環境を転送します。
ただし、ドライバーをインスタンス化するときにこの関数を他の処理を実行する関数に変更できま
す。
Note
上記の基本実装は機能しますが、出力を何も生成しません。
レンダリングテンプレート
出力を生成するには、次の例のように、render_templates メソッドを実装する必要があります。
from az_code_gen.base import *
class MyTemplateDriver(TemplateDriver):
def render_templates(self, input_file, **jinja_args):
self.render_template_to_file("MyTemplate.tpl", jinja_args,
'GeneratedCode.cpp')
Version 1.6
167
Lumberyard 開発者ガイド
テンプレートドライバー
# Factory function - called from launcher
def create_drivers(env):
return [MyTemplateDriver(env)]
render_templates メソッドは input_file の相対パスと、AZCodeGenerator.exe ユー
ティリティから渡された引数を取ります。input_file パスには通常、Clang で作成された中間
json_object などの入力が含まれています。
テンプレートドライバーは apply_transformations メソッドを実行して、この情報を拡張できま
す。詳細については、「中間データを事前処理する (p. 168)」を参照してください。
render_template_to_file メソッドは、テンプレートファイルおよび引数のキーと値のペアを
取ってテンプレートエンジンに直接渡し、また出力パスを取ってテンプレートエンジンのレンダリン
グ出力をディスクに書き込みます。
自動構築挿入を設定する
この時点で、例では最低限の .cpp ファイルが生成されます。上記の例では、.cpp ファイルはコンパ
イルまたはリンクされません。これは、生成されたコードを #include を使用して手動で別のファイ
ルに含める場合は適しています。
生成されたファイルを自動的に挿入するには、should_add_to_build パラメーターを
render_template_to_file メソッドに追加し、パラメーターに true の値を渡しま
す。should_add_to_build パラメーターは、生成されたファイルを構築し現在のターゲットにリン
クする必要があることを Waf に通知します。
注意
should_add_to_build パラメーターの使用は、ヘッダーファイルや、コンパイルされリンクされる
必要がある C++ コードではない生成ファイルには推奨されません。
次の例では、構築が挿入された出力を示します。
from az_code_gen.base import *
class MyTemplateDriver(TemplateDriver):
def render_templates(self, input_file, **jinja_args):
self.render_template_to_file("MyTemplate.tpl", jinja_args,
'GeneratedCode.cpp', should_add_to_build=True)
# Factory function - called from launcher
def create_drivers(env):
return [MyTemplateDriver(env)]
中間データを事前処理する
テンプレートエンジンで実行しやすいように、中間データを事前処理する必要がある場合がありま
す。これを行うには、テンプレートドライバーで apply_transformations メソッドを実行しま
す。このメソッドを使用して、中間 JSON データオブジェクトが render_templates に渡される前
に直接アクセスできます。以下に例を示します。
from az_code_gen.base import *
class MyTemplateDriver(TemplateDriver):
def render_templates(self, input_file, **jinja_args):
self.render_template_to_file("MyTemplate.tpl", jinja_args,
'GeneratedCode.cpp')
Version 1.6
168
Lumberyard 開発者ガイド
カスタムコードジェネレーターの注釈
def apply_transformations(self, obj):
obj['my_custom_data'] = 42
# Factory function - called from launcher
def create_drivers(env):
return [MyTemplateDriver(env)]
obj 変数の内容の詳細については、「中間 JSON データ形式 (p. 182)」を参照してください。
カスタムコードジェネレーターの注釈
ソースコードに注釈とタグを添付することで、テンプレートドライバーに追加データを提供できま
す。
トピック
• 参照の注釈 (p. 169)
• ヘルパーマクロ (p. 169)
• 注釈の例 (p. 170)
参照の注釈
カスタムコードジェネレーターの注釈を作成する場合、dev/Code/Framework/AZCore/AZCore/
Preprocessor/CodeGen.h ファイルの既存の注釈を例として参照することをお勧めします。 既存の
注釈は、C++ に適切な注釈がないため、次善策としてマクロを大量に使用します。
Clang では、解析時間に読み込むことができる annotate 属性が提供されています。 以下の例のよう
に、提供されているヘルパーマクロを使用して新しい注釈を作成できます。
__attribute__((annotate("<Some string here>")))
この属性は、内容を AZ コードジェネレーターのユーティリティで解析できる文字列に変換するマク
ロとともにパッケージ化されます。
ヘルパーマクロ
AZ コードジェネレーターには、注釈用に CreateAnnotation と CreateArgumentAnnotation と
いう 2 つのヘルパーマクロがあります。
CreateAnnotation
CreateAnnotation は基盤となる Clang の annotate 属性を公開するコアマクロです。マクロ定義
は以下のとおりです。
#define CreateAnnotation(annotation) __attribute__((annotate(annotation)))
CreateAnnotation に渡される引数は文字列でなければなりません。
CreateArgumentAnnotation
CreateArgumentAnnotation マクロは注釈マクロによく使用されます。マクロ定義は以下のとおり
です。
#define CreateArgumentAnnotation(annotation_name, ...)
CreateAnnotation(AZ_STRINGIZE(annotation_name) "("
Version 1.6
169
Lumberyard 開発者ガイド
カスタムコードジェネレーターの注釈
AZ_MACRO_SPECIALIZE(AZ_SPACIZE_, AZ_VA_NUM_ARGS(__VA_ARGS__), (__VA_ARGS__))
")")
CreateArgumentAnnotation マクロは、annotation_name 引数といくつかの可変引数を取りま
す。可変引数に渡された値は、AZ コードジェネレーターでの解析用に単一の文字列にまとめられま
す。
注釈の例
このセクションでは、注釈の例を提供します。例の 1 つでは基盤となるマクロに引数を転送し、1 つ
はクラス内に注釈を配置し、1 つは元のファイルにコードを挿入します。
シンプルな注釈
次の例では、基盤マクロに引数を転送する AzExample という新しい注釈を作成します。
#define AzExample(...) CreateArgumentAnnotation(AzExample, __VA_ARGS__)
この例では、注釈のプライベート名とパブリック名は同じです。ただし、外部名と内部名が一致する
必要はありません。
次の例のように、C++ のほとんどの項目に、AzExample 注釈を添付できます。
class ExampleClass
{
AzExample(description("I am data!"))
int m_myData;
}
注釈内のタグは、以下の例のように、生成された中間データオブジェクトに JSON 形式で配置されま
す。読みやすくするため、データの一部を削除してあります。
{
"type": "class",
"name": " ExampleClass",
"annotations" : {},
"fields": [
{
"name": "m_myData",
"annotations" : {
"AzExample" : {
"description" : "I am data!"
}
}
}
]
}
クラスの注釈の例
次の例では、自由浮動型の注釈をクラスに添付するように AZ コードジェネレーターに指示します。
#define AzExampleClass(...) CreateArgumentAnnotation(AzExampleClass,
Class_Attribute, __VA_ARGS__) int AZ_JOIN(m_azCodeGenInternal, __COUNTER__);
Version 1.6
170
Lumberyard 開発者ガイド
カスタムコードジェネレーターの注釈
AzExampleClass – 注釈名 AzExampleClass を指定します (前の例の AzExample に代わるもので
す)。
Class_Attribute – AZ コードジェネレーターユーティリティに、注釈を含む属性をクラスに添付す
るように指定します。注釈はクラスオブジェクトの annotations プロパティに属します。
__VA_ARGS__ – 単一の文字列に変換されて AZ コードジェネレーターのユーティリティで解析される
追加パラメーターを指定します。
int AZ_JOIN(m_azCodeGenInternal, __COUNTER__) – AZ_JOIN は、2 つのマクロレベル項目
を取り、それらを文字列に変換せずに 1 つに結合するヘルパーマクロです。Clang では関数または変
数に添付する注釈属性が必要なため、この例では AZ_JOIN と一時的な整数のメンバー変数を使用し
てこれを行っています。一時的な整数のメンバー変数は、その後は無視されます。
前の例に新しい注釈を追加すると、以下のコードが作成されます。
//Class Annotation Example
class ExampleClass
{
AzExampleClass(description("I am an example class!"));
AzExample(description("I am data!"))
int m_myData;
}
これにより以下の中間 JSON オブジェクトが作成されます。判りやすくするため、データの一部を削
除してあります。
"type": "class",
"name": "SampleClass",
"annotations" : {
"AzExampleClass" : {
"description" : "I am an example class!"
}
},
"fields": [
{
"name": "m_myData",
"annotations" : {
"AzExample" : {
"description" : "I am data!"
}
}
}
]
生成されたコードの挿入例
次の例では、生成されたコードを自動的に元のファイルに挿入して戻す方法を示しています。例で
は、コードを例のクラスに挿入することで、前に作成した AzExampleClass 注釈を拡張していま
す。
#if defined(AZ_CODE_GENERATOR)
#
define AzExampleClass(ClassName, ...)
CreateArgumentAnnotation(AzExampleClass, Class_Attribute,
identifier(ClassName), __VA_ARGS__) int AZ_JOIN(m_azCodeGenInternal,
__COUNTER__);
#else
Version 1.6
171
Lumberyard 開発者ガイド
カスタムコードジェネレーターの注釈
#
define AzExampleClass(ClassName, ...)
AZ_JOIN(AZ_GENERATED_CODE_,ClassName)
#endif // AZ_CODE_GENERATOR
更新された注釈は、新しく必要になる ClassName というパラメーターを追加します。これはコード
を挿入するために使用される識別子です。この識別子が identifier(ClassName) として Clang に
渡され、データが中間 JSON に提供されます。
この時点までで、AZ_CODE_GENERATOR の外部にある注釈マクロは空白のままです。次のステッ
プでは、これをコードによって生成されたマクロの識別子まで拡張して、生成されたファイルが
#include ステートメントに置かれたときにマクロの注釈が生成されたコードに置き換えられるよう
にします。
これを実装するために、この例ではマクロが AZ_JOIN(AZ_GENERATED_,ClassName) になるように
設定します。前と同様に、この例の AZ_JOIN はこれを AZ_GENERATED_CODE_ExampleClass とし
てレンダリングします。ClassName パラメーターは生成されたマクロのコンパイル時に名前を指定し
ます。
Note
ClassName が、注釈が使用されるクラスの実際の名前である必要はありません。このメカニ
ズムを使用するその他の注釈では、一意の識別子だけが必要となります。
前のサンプルコードが更新されると、以下のコードが作成されます。
class ExampleClass
{
AzExampleClass(ExampleClass, description("I am an example class!"));
AzExample(description("I am data!"))
int m_myData;
}
このコードにより以下の中間 JSON が作成されます。クラスの新しい識別子の注釈をメモします。読
みやすくするため、データの一部を削除してあります。
"type": "class",
"name": "SampleClass",
"annotations" : {
"AzExampleClass" : {
"identifier" : "ExampleClass",
"description" : "I am an example class!"
}
},
"fields": [
{
"name": "m_myData",
"annotations" : {
"AzExample" : {
"description" : "I am data!"
}
}
}
]
この結果は、注釈とともに使用する以下のテンプレートコードが目的のマクロを作成するまでコンパ
イルしません。
Version 1.6
172
Lumberyard 開発者ガイド
AZ コードジェネレーターによる Waf のデバッグ
{% if class.annotations.identifier is defined %}
#define
AZ_GENERATED_CODE_{{ asStringIdentifier(class.annotations.identifier) }}\
public: \
{# This method is injected for all classes with the AzExampleClass annotation
#}
bool IsExampleClass(void) { return true; }
{% endif %}
このコードによって、挿入用の以下のコードが生成されます。
#define AZ_GENERATED_CODE_ExampleClass \
bool IsExampleClass(void) { return true; }
生成されたヘッダーが元のコードの #include ステートメントにある場合、このマクロのコードが
ExampleClass に挿入されます。
AZ コードジェネレーターによる Waf のデバッグ
PyCharm といくつかの重要なデバッグエントリポイントを使用して、Waf の Python スクリプトの統
合出力をデバッグできます。Waf 統合自体の詳細については、「AZ コードジェネレーターと Waf の
統合 (p. 156)」を参照してください。
トピック
• 前提条件 (p. 173)
• デバッグ出力の識別と設定 (p. 173)
• Waf のデバッグ用の PyCharm の設定 (p. 174)
前提条件 開始する前に、「Waf のデバッグ用の PyCharm の設定 (p. 174)」の手順に従います。続行する前
に、PyCharm デバッガーをデバッグ lmbr_waf に設定する必要があります。
デバッグ出力の識別と設定
すべての AZ コードジェネレーターの Waf の統合出力には az_code_gen プレフィックスが付いて
います。タスクの作成と実行の両方からの追加の出力を表示するには、Waf のコマンドラインに -zones=az_code_gen を追加します。これにより、AZ コードジェネレーターを起動するコマンド
と、AZ コードジェネレーターユーティリティ自体をデバッグするのに便利なコマンドが表示されま
す。詳細については、「AZ コードジェネレーターユーティリティのデバッグ (p. 180)」を参照して
ください。
Wscript 設定のデバッグ
ほとんどの設定の問題をデバッグするには、Code\Tools\waf-<version>\lmbrwaflib
\az_code_generator.py で create_code_generator_tasks メソッド内にブレークポイントを
設定するのが最も便利です。このメソッドは、az_code_gen 機能を使用する wscript ファイルご
とに呼び出されます。そのメソッドは直接、指定されたパスを解釈し、各パスの入力ファイルごとに
az_code_gen タスクを生成します。
az_code_gen
タスクの作成のデバッグ
create_az_code_generator_task 機能によって az_code_gen タスクが作成されます。この機能
によってほとんどの情報が収集され、そのタスクに挿入されます。各タスクは az_code_gen_group
Waf タスクに追加されて、他のタスクの前に実行されるようになります。
Version 1.6
173
Lumberyard 開発者ガイド
AZ コードジェネレーターによる Waf のデバッグ
az_code_gen タスクの実行のデバッグ
run および handle_code_generator_output コマンドはタスクの実行時の重要なポイントです。
run コマンドは、使用可能な情報を受け取り、@ プレフィックスが付いた Clang スタイルの引数ファ
イルを生成します。引数ファイルは、AZ コードジェネレーターユーティリティにコマンドラインで渡
されます。
handle_code_generator_output - AZ コードジェネレーターユーティリティ
は、handle_code_generator_output によって解析された 1 つ以上のエントリを含む、JSON オ
ブジェクトを返します。AZ コードジェネレーターユーティリティによって、実行時のエラーのため、
無効な非 JSON レスポンスが返された場合、Waf のタスクによって、エラーメッセージ No JSONObject could be decoded が返されます。処理できなかった戻り値を検出するには、Waf の外で
コマンドを実行します。
Waf のデバッグ用の PyCharm の設定
PyCharm は Python 用の統合開発環境であり、Waf のデバッグに便利なグラフィカルなデバッガーを
備えています。
Waf のデバッグ用に PyCharm を設定するには
1.
PyCharm Community Edition をダウンロードします。
2.
3.
PyCharm を起動します。
ウェルカム画面で、[Open Directory] を選択します。
4.
Lumberyard のルートディレクトリから、_WAF_ または dev ディレクトリが含まれるブランチに
移動します。 このフォルダーの下に wscript と waf_branch_spec.py という名前のファイル
があります。
5.
Python Interpreter を設定します。
a.
b.
[File]、[Settings]、[Project:dev]、[Project Interpreter] の順に選択して、Project Interpreter の
ページを開きます。
Project Interpreter の右側にある歯車のアイコンをクリックし、[Add Local] を選択します。
Version 1.6
174
Lumberyard 開発者ガイド
AZ コードジェネレーターによる Waf のデバッグ
c.
6.
python.exe があるフォルダーに移動します。 Python の実行可能ファイルはプロジェクト
と同じフォルダーにあることが必要です。それ以外の場所にあると、Waf の実行時に問題が
発生します。
Waf のデバッグプロファイルを設定します。
a.
デバッグ用に Waf を設定するには、左ペインでプロジェクトエクスプローラーを使用し
ます。 プロジェクトエクスプローラーが表示されていない場合は、Alt+1 を押します)。 Code/Tools/waf-<version> ノードに移動し、展開します。 このノード内に lmbr_waf
という名前のファイルがあります。
b.
[lmbr_waf] を右クリックし、[Create lmbr_waf] を選択します。
Note
オプションが表示される前に、[Indexing...] オペレーションが終了している必要があ
ります。下部のバーでステータスを確認できます。
Version 1.6
175
Lumberyard 開発者ガイド
AZ コードジェネレーターによる Waf のデバッグ
c.
[Create Run/Debug Configuration] ダイアログで、以下の値が正しく設定されていることを確
認します。
• [Single instance only] が選択されている。
• [Script Parameters] が実行/デバッグセッションで Waf を実行するコマンドになっている。
• Python Interpreter が先ほど指定したインタープリタになっている。
• [Working directory] がプロジェクトのルート (dev ディレクトリなど) になっている。
Version 1.6
176
Lumberyard 開発者ガイド
AZ コードジェネレーターによる Waf のデバッグ
次に、デバッグ可能 Python ファイルとして wscript ファイルを設定する必要がありま
す。Waf では、プロジェクトごとのビルドルールを定義する、wscript という名前のファイ
ルを使用します。 これらは、動的にロードされる Python モジュールであり、他の Python
モジュールのようにデバッグできます。
d.
[File]、[Settings]、[Editor]、[File Types]、[Python] の順に選択します。
e.
wscript の登録パターンを追加するには、[Recognized File Types] で [Python] を選択します。
Version 1.6
177
Lumberyard 開発者ガイド
AZ コードジェネレーターによる Waf のデバッグ
7.
8.
f.
[Registered Patterns] で、緑色のプラス記号 (+) をクリックします。
g.
[Add Wildcard] ダイアログボックスで、「wscript」と入力します。
[IncrediBuild] がオフになっていることを確認します。
a.
_WAF_/usersettings.options ファイルを開きます。
b.
use_incredibuild が、以下の例のように、false に設定されていることを確認しま
す。use_incredibuild = False
(オプション) ファイルのアウトラインを有効にします。
デフォルトでは、ファイルのアウトラインは PyCharm でオフになっています。この機能によ
り、以下の図に示すように、ソースファイル内の移動が容易になります。
Version 1.6
178
Lumberyard 開発者ガイド
テンプレートドライバーのデバッグ
ファイルのアウトラインを有効にするには、[Project] タブを右クリックし、[Show Members] を
選択します。
テンプレートドライバーのデバッグ
テンプレートドライバーが Python を使用して AZ コードジェネレーターの実行可能ファイルから実行
されているため、それらのドライバーを直接デバッグすることはできません。ただし、AZ コードジェ
ネレーターに含まれる debug.py ファイルを使用して、ドライバーとテンプレートのコードを (Jinja2
自体も) デバッグすることはできます。
PyCharm や Visual Studio のような Python デバッガーでテンプレートドライバーをデバッグ
するには
1.
Bin64\azcg\debug.py ファイルを実行するようにデバッガーを設定します。このファイルに
よって、入力 JSON を生成するユーティリティが起動され、Python でコード生成パスがエミュ
レートされるため、ユーティリティに接続しているかのようにデバッグできます。
2.
作業ディレクトリを Bin64\azcg に設定します。
3.
AzCodeGenerator.exe の引数を 1 行につき 1 つずつ指定してファイルに入力します。または、
「AZ コードジェネレーターによる Waf のデバッグ (p. 173)」で説明しているように、Waf に
よって生成される引数ファイルを使用します。
4.
@ プレフィックスを付けて引数ファイルをスクリプトの引数として設定します。
以下の引数が必要です。
• -codegen-script - デバッグするドライバースクリプトへの絶対パス。
• -input-path - ソースファイルのパスの基になっている絶対パス。このパスは通常、指定した
ターゲットの WScript の場所と同じです。
• -input-file - 入力に使用されるソースファイルへの入力パスからの相対パス。
• -output-file - 生成されたコードが書き込まれる絶対パス。
ここまでの手順を完了したら、デバッガーを起動してドライバースクリプトでブレークポイントを設
定できるようになっています。
Version 1.6
179
Lumberyard 開発者ガイド
AZ コードジェネレーターユーティリティのデバッグ
AZ コードジェネレーターのパラメーターの詳細については、「AZ コードジェネレーターのパラメー
ター (p. 158)」を参照してください。
AZ コードジェネレーターユーティリティのデバッ
グ
Waf と AZ コードジェネレーターユーティリティを使用するときは、Waf Python スクリプトのデバッ
グ (p. 173)とテンプレートドライバーのデバッグ (p. 179)が必要にあることがよくあります。それ
ほど頻繁ではありませんが、AZ コードジェネレーターユーティリティ自体のデバッグが必要にあるこ
ともあります。Windows で Visual Studio を、または OS X で Xcode を使用することで、AZ コード
ジェネレーターユーティリティをデバッグできます。
トピック
• 前提条件 (p. 180)
• Waf ビルドからの AZ コードジェネレーターユーティリティのデバッグ (p. 181)
• Visual Studio のデバッグ引数の設定 (p. 181)
• Xcode のデバッグ引数の設定 (p. 181)
前提条件
実行する必要のある準備手順は、オペレーティングシステムによって異なります。
Windows でのデバッグ
Windows で Visual Studio を使用して、AZ コードジェネレーターをデバッグするには、Visual Studio
の HostTools ソリューション (.sln) ファイルを生成する必要があります。
Visual Studio の HostTools ソリューションファイルを生成するには
1.
dev フォルダーから以下のコマンドラインを実行します。
lmbr_waf.bat configure --enabled-game-projects= --specs-to-include-inproject-generation=host_tools --visual-studio-solution-name=HostTools
2.
Visual Studio で、dev/Solutions/HostTools.sln ファイルを開きます。
OS X でのデバッグ
Xcode の Waf サポートを有効にするには、以下の手順を実行して、Xcode プロジェクトを生成しま
す。
Xcode プロジェクトを生成するには
1.
dev/_WAF_/specs/all.json ファイルを開きます。
2.
一時的に modules に AzCodeGenerator を追加します。
3.
./lmbr_waf.sh configure を実行して、Xcode プロジェクトを再生成します。
4.
dev/Solutions/LumberyardSDK.xcodeproj ファイルを開きます。
Version 1.6
180
Lumberyard 開発者ガイド
AZ コードジェネレーターユーティリティのデバッグ
Waf ビルドからの AZ コードジェネレーターユーティリティの
デバッグ
Waf ビルドから AZ コードジェネレーターユーティリティをデバッグするには、Waf によって生成さ
れた引数ファイルを見つける必要があります。
Waf は、コマンドラインパラメーターとして AZ コードジェネレーターに渡される引数ファイルを生
成します。AZ コードジェネレーター用の Waf のすべてのコマンドラインパラメーターは引数ファイ
ルに含まれます。このファイルは、特定の Waf AZ コードジェネレーターの呼び出しをデバッグする
のに便利です。使用する引数ファイルを Waf からアクセスできるようにするには、Waf のコマンドラ
インに --zones=az_code_gen オプションを追加します。
--zones=az_code_gen オプションを使用すると、出力は以下のようになります。
lmbr_waf build_win_x64_release -p all --zones=az_code_gen
[
1/3150] az_code_gen (win_x64|release): BinTemp\win_x64_release\Code
\Launcher\WindowsLauncher\GameSDKWindowsLauncherStaticModules.json
14:24:17 az_code_gen Invoking code generator with command:
g:\lyengine\Systems\dev\Bin64\azcg\AzCodeGenerator.exe @g:
\lyengine\Systems\dev\BinTemp\win_x64_release\CodeGenArguments
\arguments_file_ee625f9186107e30ab3126cc30cc9b49.args
この Waf の出力例で、以下に示しているのが、引数ファイルです。
@g:\lyengine\Systems\dev\BinTemp\win_x64_release\CodeGenArguments
\arguments_file_ee625f9186107e30ab3126cc30cc9b49.args
Visual Studio のデバッグ引数の設定
Visual Studio から AZ コードジェネレーターのデバッグを設定するには、以下の手順を実行します。
Visual Studio から AZ コードジェネレーターをデバッグするには
1.
「前提条件 (p. 180)」で説明しているように、Windows でのデバッグの設定手順を実行しま
す。
2.
Visual Studio Solution Explorer で、[AzCodeGenerator] を右クリックし、[Properties] を選択しま
す。
3.
[Debugging] で、引数ファイルへのパスを [Command Arguments] に貼り付けます。
4.
[OK] をクリックして、[Property] ウィンドウを閉じます。
5.
[AzCodeGenerator] を右クリックし、[Set as StartUp Project] をクリックします。
6.
F5 キーを押して、デバッガーを起動します。
Xcode のデバッグ引数の設定
Xcode から AZ コードジェネレーターのデバッグを設定するには、以下の手順を実行します。
Xcode から AZ コードジェネレーターをデバッグするには
1.
「前提条件 (p. 180)」で説明しているように、OS X でのデバッグの設定を実行します。
2.
Xcode の [Product] で、[Scheme] メニューから [AzCodeGenerator] を選択します。
3.
[Product] の下部で、[Scheme] メニューから [Edit Scheme] を選択します。
Version 1.6
181
Lumberyard 開発者ガイド
中間 JSON データ形式
4.
[Arguments] で、デバッグ引数を含む [Arguments Passed On Launch] に新しいエントリを追加し
ます。
5.
[Info] で、[Executable] ドロップダウンから [Other] を選択します。
a.
dev/BinMac64.Debug/azcg/AzCodeGenerator ディレクトリに移動します。
b.
[Choose] をクリックします。
6.
[Close] を選択して、スキームエディターを閉じます。
7.
[Product, Run] を選択して、デバッガーを起動します。
中間 JSON データ形式
次の JSON は、Jinja2 ユーザー定義テンプレートで実行される中間データ形式を示しています。
{
"meta": {
"path": "<Path/To/Code/Generator/Input/File.ext>"
},
"objects": [
{
"name": "<Name of class/struct>",
"qualified_name": "<Fully qualified name of class or struct>",
"fields": [
{
"type": "<member variable type>",
"canonical_type": "<member variable canonical type>",
"name": "<member variable name>",
"qualified_name": "<fully qualified member variable
name>",
"annotations": {
"<annotation name>": {
"<annotation variable name>": "<annotation
variable value (can be empty string)>",
...
},
...
}
},
...
],
"traits": {
"isAbstract": <true if abstract class, false if concrete>,
"isPOD": <true of plain old data type; otherwise, false>,
"isPolymorphic": <true if polymorphic type; otherwise, false>
},
"bases" : [
{
"name" : "<Base Class Name>",
"qualified_name" : "<Fully qualified name of base class>"
},
...
],
"meta": {
"path": "<Path/To/File/Containing/This/Object.ext>"
},
"type": <"class" or "struct">,
"annotations": {
Version 1.6
182
Lumberyard 開発者ガイド
中間 JSON データ形式
"<annotation name>": {
"<annotation variable name>": "<annotation variable value
(can be empty string)>",
...
},
...
},
"methods": [
{
"name" : "<method_name>",
"qualified_name": "<Fully qualified name of method>",
"is_virtual": <true if virtual method; otherwise, false>,
"annotations": {
"<annotation name>": {
"<annotation variable name>": "<annotation
variable value (can be empty string)>",
...
},
"access": "<Access level of method, one of: public,
private, protected>",
"params" : [
{
"type" : "<parameter type>",
"canonical_type" : "<parameter canonical type>",
"name" : "<parameter name>"
},
...
],
"uses_override": <true if override keyword is present;
otherwise, false>,
"return_type": "<return type of method>"
},
...
]
},
...
]
}
Version 1.6
183
Lumberyard 開発者ガイド
エンティティシステムスクリプトのコールバック
コールバックのリファレンス
このセクションでは、Entity システムとゲームルールのスクリプトコールバック情報を提供します。
このセクションでは、次のトピックについて説明します。
• エンティティシステムスクリプトのコールバック (p. 184)
• ゲームルールスクリプトのコールバック (p. 186)
エンティティシステムスクリプトのコールバック
このトピックでは、エンティティシステムのすべてのコールバックについて説明します。これらの
コールバック関数の使用は必須ではありませんが、Lumberyard エディタ におけるエンティティの正
常な動作が必要になる場合があります。たとえば、Lumberyard エディタ 内のゲームモードをユー
ザーが開始または終了した場合、クリーンな状態にするために OnReset コールバックを使用するこ
とが必要になります。
デフォルト状態の関数
コールバック関数
説明
OnSpawn
エンティティシステムによりエンティティが作成された後に呼び出されま
す。
OnDestroy
エンティティが破棄される（OnShutDown() が呼び出されるなど）と呼
び出されます。
OnInit
エンティティが ENTITY_EVENT_INIT により初期化され、エンティティ
の ScriptProxy が初期化されると呼び出されます。
OnShutDown
エンティティが破棄される（OnDestroy() が呼び出されるなど）と呼び
出されます。
OnReset
通常、エディターで状態のリセットが必要になると呼び出されます。
OnPropertyChange
ユーザーがいずれかのプロパティを 1 つ変更すると、Lumberyard エディ
タ により呼び出されます。
Version 1.6
184
Lumberyard 開発者ガイド
スクリプトの状態の関数
スクリプトの状態の関数
コールバック関数
説明
OnBeginState
状態が変更された後（以前の状態で OnEndState() が呼び出された
後）、Entity.GotoState() 内で呼び出されます。
OnBind
子エンティティがエンティティにアタッチされると呼び出されます。次の
パラメーターがあります。
• 子エンティティのスクリプトテーブル
OnCollision
あるエンティティとそれ以外の間で競合が発生すると呼び出されます。次
のパラメーターがあります。
• 競合に関する情報を含むスクリプトテーブル
OnEndState
以前の状態がまだアクティブなときに、新しい状態で OnBeginState()
が呼び出される前に Entity.GotoState() 内で呼び出されます。
OnEnterArea
エンティティがエリアまたはトリガーに完全に入ると呼び出されます。次
のパラメーターがあります。
• areaId (int)
• fade fraction (float) この値は、エンティティがエリアに完全に入った場
合は 1.0f、トリガーボックスの場合は 0.0f です。
OnEnterNearArea
エンティティがエリアの範囲に入ると呼び出されます。音量のエンティ
ティが接続されている場合に、Box-、Sphere-、および Shape- のエリア
と連携します。エンティティがエリアに近づいたかどうかは、サウンドエ
ンティティの OuterRadius で判断します。
OnLeaveArea
エンティティがエリアまたはトリガーから完全に出ると呼び出されます。
次のパラメーターがあります。
• areaId (int)
• fade fraction (float) この値は常に 0.0f です。
OnLeaveNearArea
エンティティがエリアの範囲から出ると呼び出されます。音量のエンティ
ティが接続されている場合に、Box-、Sphere-、および Shape- のエリア
と連携します。エンティティがエリアに近づいたかどうかは、サウンドエ
ンティティの OuterRadius で判断します。
OnMove
エンティティが世界を進む場合は常に呼び出されます。
OnMoveNearArea
エンティティが移動すると呼び出されます。音量のエンティティが接続
されている場合に、Box-、Sphere-、および Shape- のエリアと連携しま
す。エンティティがエリアに近づいたかどうかは、サウンドエンティティ
の OuterRadius で判断します。
OnProceedFadeArea
エンティティがエリアに入ったばかりで、フェードがまだ処理中の場合に
呼び出されます。次のパラメーターがあります。
• areaId (int)
• fade fraction (float)
OnSoundDone
サウンドが停止すると呼び出されます。次のパラメーターがあります。
Version 1.6
185
Lumberyard 開発者ガイド
ゲームルールスクリプトのコールバック
コールバック関数
説明
• soundId (int) サウンドの再生リクエストによって提供された、再生され
ているサウンドの ID です。
OnStartGame
ゲームが開始すると呼び出されます。
OnStartLevel
新しいレベルが開始すると呼び出されます。
OnTimer
タイマーが終了すると呼び出されます。次のパラメーターがあります。
• timerId (int) Entity.SetTimer() によって提供された時間の ID です。
• period (int) タイマーが作動する時間の長さ（ミリ秒）です。
OnUnBind
あるエンティティから子エンティティがデタッチされるときに呼び出され
ます。次のパラメーターがあります。
• 子エンティティのスクリプトテーブル
OnUpdate
エンティティの現在の状態のエンジンにより定期的に呼び出されます。コ
ンソール変数 es_UpdateScript が 1 に設定されていることを前提とし
ます。
ゲームルールスクリプトのコールバック
このトピックでは、GameRules スクリプトで使用されるコールバックのリファレンス情報について説
明します。
コールバック関数
説明
OnAddTaggedEntity
ミニマップでプレイヤがタグ付きプレイヤとして追加されたときに呼び出
されます。サーバーでのみ呼び出されます。
• shooterId – ターゲットプレイヤをタグ付けしたエンティティ。
• targetId – タグ付けされたプレイヤ。
OnClientConnect
プレイヤが接続したときに呼び出されます。サーバーでのみ呼び出されま
す。
• channelId
OnClientDisconnect
プレイヤが切断したときに呼び出されます。サーバーでのみ呼び出されま
す。
• channelId
OnClientEnteredGame
プレイヤがゲームを開始してゲームの世界の一部になったときに呼び出さ
れます。サーバーでのみ呼び出されます。
• channelId – プレイヤのチャネル ID。
• playerScriptTable – プレイヤのスクリプトテーブル。
• bReset – リセットリストからのチャネルかどうかを表すブール値。
• bLoadingSaveGame – 保存したゲームのロード中に行われた呼び出しか
どうかを表すブール値。
OnDisconnect
クライアント上でプレイヤが切断したときに呼び出されます。クライアン
トでのみ呼び出されます。
Version 1.6
186
Lumberyard 開発者ガイド
ゲームルールスクリプトのコールバック
コールバック関数
説明
• cause – 切断理由を識別する整数値。「EDisconnectionCause」を参
照してください。
• description – 切断理由の人間が読み取れる説明。
OnChangeSpectatorModeプレイヤが観客モードを変更したときに呼び出されます。サーバーでのみ
呼び出されます。
• entityId – 変更を行ったプレイヤ。
• mode – 新しい観客モード (1=固定、2=自由、3=追従)。
• targetId – 観覧可能なターゲットエンティティ。
• resetAll – インベントリなどのプレイヤ関連物をリセットするかどうか
を表すブール値。
OnChangeTeam
プレイヤがチームを切り替えたときに呼び出されます。サーバーでのみ呼
び出されます。
• entityId – チームを切り替えたプレイヤ。
• teamId – 新しいチーム ID。
Version 1.6
187
Lumberyard 開発者ガイド
ゲームルールスクリプトのコールバック
コールバック関数
説明
OnExplosion
爆発がシミュレートされたときに呼び出されます。サーバーおよびクライ
アントで呼び出されます。
• pos – ゲームの世界での爆発の位置。
• dir – 爆発の方向。
• shooterId
• weaponId
• shooter
• weapon
• materialId
• damage
• min_radius
• radius
• pressure
• hole_size
• effect
• effectScale
• effectClass
• typeId
• type
• angle
• impact
• impact_velocity
• impact_normal
• impact_targetId
• shakeMinR
• shakeMaxR
• shakeScale
• shakeRnd
• impact
• impact_velocity
• impact_normal
• impact_targetId
• AffectedEntities – 影響を受けるエンティティテーブル。
• AffectedEntitiesObstruction – 影響を受けるエンティティ障害テーブル。
Version 1.6
188
Lumberyard 開発者ガイド
特徴
Cloud Canvas
Cloud Canvasは、AWSサービスへの視覚スクリプティングインターフェイスです。Cloud Canvas
を使えば、Amazon DynamoDB、AWS Lambda、Amazon Simple Storage Service、 (Amazon
S3)、Amazon Cognito、Amazon Simple Notification Service (Amazon SNS)、Amazon Simple Queue
Service (Amazon SQS)を使った接続型ゲーム機能を構築することができます。Cloud Canvas を使え
ば、ログインボーナス、ゲーム内メッセージ、リーダーボード、通知、サーバー側のコンバットレゾ
リューション、非同期性の多人数型ゲームプレイ (カードゲーム、ワードゲーム、ゴーストレーサーな
ど) などのクラウドがホストする機能を作成することができます。Cloud Canvasは自身でホストサー
バーの獲得、コンフィギュア、または運営を可能にし、ゲームプレイ機能上でサーバーコードを入力
する手間を省きます。
特徴
Cloud Canvas は幅広い便利なコンポーネントを提供しています:
• チームがクラウド接続機能を備えたゲームを構築するためのツール。
• Amazon S3、Amazon DynamoDB、Amazon Cognito、AWS Lambda、Amazon SQS、Amazon
SNSなどの AWS サービス内のクライエントから直接コミュニケーションするためのフローグラフ
ノード
• AWSリソースを管理し、開発者とプレーヤーがどのようにしてAWSリソースへアクセスするかの決
定権の許可を管理するためのツール
• 開発、テスト、ライブのリソースが別々に維持管理されるようにするAWSデプロイの管理
• プレイヤーの認証方法（匿名および認証）。プレイヤーはさまざまなデバイスによって認証可能
で、Amazon、Facebook、Googleのアカウントへログインすることでゲーム データにアクセスでき
ます。
使用例
接続型ゲームのAmazon Web Servicesの様々な活用法を考えてみてください:
• プレイヤー状態、ハイスコア、世界のダイナミックなコンテンツなどのゲームデータを保存し、問
い合わせします：Amazon S3 および DynamoDB
Version 1.6
189
Lumberyard 開発者ガイド
ツール
• バックグラウンド処理のためのリアルタイムおよびキューデータのイベントをトリガーする:
Amazon SQS および Amazon SNS
• サーバーをセットアップもしくは管理せずにクラウド内のカスタムゲームロジックを実行します：
AWS Lambda
• ユーザーの訪問回数を記録し頻繁な訪問へのボーナスを設定するログインボーナスシステ
ムを設定する: Amazon CognitoAmazon S3、http://docs.aws.amazon.com/AmazonS3/latest/
dev/、DynamoDB,AWS Lambda
• その日のメッセージやゲーム内のイベント情報の更新を表示するニューステロップを表示します:
Amazon CognitoAmazon S3、http://docs.aws.amazon.com/AmazonS3/latest/dev/、AWS Lambda
サンプルプロジェクト内でCloud Canvasがどのように AWS サービスを使用するのかをみるに
は、Don't Die サンプルプロジェクト (p. 209)を参照してください。Cloud Canvasについてのチュー
トリアルは、Lumberyard のチュートリアルをご覧ください。
ツール
次のいずれかを使用してCloud Canvas機能にアクセスできます:
• Flow Nodes – デザイナーがAWSクラウドを活用する場合。Cloud Canvas フローグラフノードの詳
細については、「Cloud Canvas フローグラフ ノードのリファレンス (p. 257)」を参照してくださ
い。
• Cloud Canvas C++ APIs – ソフトウェア開発
• Cloud Canvas コマンドラインの使用 (p. 221) – 管理機能、マッピング、デプロイ、プロジェクト
です。
• Lumberyard エディタ の Cloud Canvas ツール (p. 216) – AWS リソース、デプロイ、および認証
情報を管理し、Cloud Canvas によってサポートされている AWS コンソールへ直接ナビゲートする
ため。
Don’t DieサンプルプロジェクトでAWSサービスがどのように利用されているかについて、こちらをご
参照くださいDon't Die サンプルプロジェクト (p. 209)。
前提知識
Cloud Canvasを活用するために次のことをする必要があります:
• AWS CloudFormation Templates– Cloud Canvas の理解には、AWS CloudFormationサー
ビスを使用し、AWSリソースを作成・管理します。当社の目標は、Cloud CanvasがAWS
CloudFormation、AWS について一般的に知るべきことを最大軽減することです。
• JSONのJSON – Cloud Canvasは、AWS CloudFormationテンプレートを含む設定データを保管する
ためJSONを活用する 。まずは、 Cloud Canvasリソース管理システムを使いこなすために、テキス
トフォーマットに慣れておく必要があります。JSONのチュートリアルはこちらでご覧いただけま
す。http://www.w3resource.com/JSON/introduction.php
トピック
• 料金表 (p. 191)
• Cloud Canvas の主要概念 (p. 191)
• Cloud Canvas Resource Manager の概要 (p. 196)
• チュートリアル: Cloud Canvas の開始方法 (p. 198)
Version 1.6
190
Lumberyard 開発者ガイド
料金表
• Don't Die サンプルプロジェクト (p. 209)
• Cloud Canvas の使用 (p. 215)
• Cloud Canvas フローグラフ ノードのリファレンス (p. 257)
• リソースの定義 (p. 280)
• リソースのデプロイ (p. 302)
• リソースマッピング (p. 304)
• カスタムリソース (p. 306)
• アクセスコントロールとプレイヤ ID (p. 310)
• AWS クライアント設定 (p. 319)
料金表
Cloud Canvas はAWS CloudFormationテンプレートを使ってAWS のリソースをアカウントにデプロ
イします。Cloud Canvasまたは AWS CloudFormationに対しての追加料金はありませんが、料金は関
連するAWSサービスを使うのに発生する場合もあります。AWS、Cloud Canvasによって作成された
リソースとAWS CloudFormation について、それらをマニュアルで支払うのと同様に支払えます。使
用した分だけをお支払いいただきます。最低料金や必須前払い義務はなく、ほとんどのサービスは無
料利用枠を含みます。
Cloud CanvasがサポートするAWS サービスについての料金情報は、次のリンクをご覧ください。
Amazon Cognito 料金表
Amazon DynamoDB 料金表
AWS Lambda 料金表
Amazon S3 料金表
Amazon SNS 料金表
Amazon SQS 料金表
すべての AWS サービスの価格については、次のクラウドサービス料金表ページをご覧ください。
Don’t Dieサンプルプロジェクトに使用されるAWSサービスについて見る場合は、こちらをご参照くだ
さいDon't Die サンプルプロジェクト (p. 209)。
Cloud Canvas の主要概念
Cloud Canvas を使うと、クラウドリソースを管理し、ゲームを AWS クラウドに接続できます。概念
を理解することで、クラウドに接続されたゲームのコンポーネントを操作するデザイナー、プログラ
マー、テスターなどのチーム全員に利点があります。
このセクションでは次の内容について説明します。
• Cloud Canvas の概要および AWS アカウントに関連付ける方法
• Cloud Canvas でサポートされる Amazon Web Services
• Cloud Canvas を使ってリソースを管理する方法
• フローグラフビジュアルスクリプティングシステムを介してゲームがクラウドと通信する方法
• チームがクラウド接続リソースグループを備えたゲームで共同作業する方法
Version 1.6
191
Lumberyard 開発者ガイド
前提条件
前提条件
このトピックをお読みになる前に、Lumberyard エンジンと フローグラフシステムについての基本的
な知識が必要です。
AWS、Cloud Canvas、および Lumberyard
Amazon Web Services (AWS) はクラウドベースのサービスの包括的かつ強力なコレクションです。こ
れらのサービスを使用して、ファイルのアップロードまたはダウンロード、データベースへのアクセ
ス、コードの実行をクラウド内で行えるほか、その他のさまざまな操作を実行することができます。
クラウドサービスを使用すると、依存しているインフラストラクチャを管理する必要がなくなりま
す。
クラウドベースのリソース
AWS クラウドサービスを使用する場合は、使用、ヘルプ、またはサポートで利用できるクラウドベー
スのリソースを介して行います。リソースには、データベース、ファイルの保存場所、サービスを実
行するコードなどが含まれます。
作成したリソースはクラウド内に存在しますが、そのリソースを使用したり、リソースのコンテンツ
を管理したりできます。また、リソースのアクセスまたは使用を許可するユーザーまたはグループを
指定することもできます。たとえば、すべてのユーザーにデータベースの読み取りを許可しても、書
き込みや変更は禁止することができます。
リソースグループ
ハイスコアテーブルなどの接続型ゲーム機能を作成するには、Cloud Canvas にリソースグループを作
成します。リソースグループは、機能に必要な AWS リソースを定義します。したがって、各接続型
ゲーム機能は Cloud Canvas のリソースグループとして実装されます。
AWS アカウント
リソースは AWS アカウントによって所有されます。AWS アカウントを使用して、ユーザーやチーム
で同じリソースへのアクセスを共有することができます。たとえば、ユーザー本人とチームメートが
同じデータベースで作業できるように、チームの AWS アカウントでデータベースリソースを所有で
きます。
ユーザー本人、またはチームのメンバーが管理者になります。管理者はチームの AWS アカウントを
作成し、アカウントのリソースへのアクセス権をチームの各メンバーに付与します。
Lumberyard、Cloud Canvas、およびフローグラフ
Cloud Canvas は Lumberyard ゲームと AWS リソースとの通信を有効にする Lumberyard Gem (拡張)
です。Amazon Web Services との通信を直接ゲームロジックに統合するには、Lumberyard のフロー
グラフビジュアルスクリプティングシステムを使用します。
作成するフローグラフノードは Cloud Canvas を使用してゲームから AWS リソースへの実際の呼び
出しを行います。たとえば、プレイヤのゲームの終了時に、クラウド内のハイスコアテーブルにプレ
イヤのスコアを送信するフローグラフノードを追加できます。後でフローグラフを使用してハイスコ
アテーブルを呼び出し、トップ 10 スコアをリクエストできます。
Cloud Canvas でサポートされる Amazon Web
Services
Cloud Canvas から利用できるいくつかの AWS サービスでゲームをさらに強化できます。
Version 1.6
192
Lumberyard 開発者ガイド
Cloud Canvas でサポートされる Amazon Web Services
クラウド内のファイルストレージ
クラウド内にファイルを保存するために、Cloud Canvas は Amazon Simple Storage Service (Amazon
S3) をサポートしています。Amazon S3 にはバケットと呼ばれるストレージリソースが用意されてお
り、これを大きなフォルダーと考えることができます。ローカルコンピューターのディレクトリと同
様に、Amazon S3 バケットにディレクトリ構造を構築できます。Amazon S3 バケットには、以下を
含めたゲームでのさまざまな用途があります。
• 保存したファイルをゲームでダウンロードできます。これらのファイルは、ゲームのレベル、キャ
ラクター、またはその他の拡張機能にすることができます。ゲームを発行した後に新しいファイル
を追加できます。ゲームはコンテンツのダウンロードと統合に Cloud Canvas を活用するため、顧
客が新しいクライアントをダウンロードする必要はありません。
• ゲームでユーザー生成コンテンツをアップロードできます。たとえば、プレイヤがラストボスを
倒すたびにスクリーンショットを取得するといった場合です。このスクリーンショットは Cloud
Canvas でバケットにアップロードされ、ゲームでスクリーンショットをウェブサイトで利用可能
にしたり、ゲームの他のプレイヤが使用できるようにします。
データベース
人の名前、電話番号、アドレスなどのデータをクラウド内に保存するために、Cloud Canvas は
Amazon DynamoDB データベースサービスをサポートしています。Amazon DynamoDB はテーブル
と呼ばれるリソースで管理されます。これらのテーブルはゲームを構築し、反復するごとに拡張およ
び適用されます。
次に、ゲームで Amazon DynamoDB テーブルリソースを活用する方法をいくつか示します。
• プレイヤのアカウント詳細と統計を追跡します。プレイヤのヒットポイント、インベントリ、ゴー
ルド、友だちを検索できるように、各プレイヤに一意の ID を割り当てます。
• ゲームの新リソースグループに対応するフィールドを追加または削除します。
• データ分析を実行します。たとえば、複雑なクエリを実行して特定の達成項目をロック解除したプ
レイヤの人数を確認できます。
• ハイスコアテーブルのクエリ実行やその日のメッセージの取得など、ゲーム全体のリソースグルー
プやイベントを管理します。
クラウドベースのロジックの実行
クラウド内でコードを実行するために、Cloud Canvas は AWS Lambda サービスをサポートしていま
す。AWS Lambda は関数というリソースを実行します。Lambda 関数のコードを指定すると、ゲーム
は Cloud Canvas から Lambda サービスを呼び出し、その関数を実行します。Lambda サービスは関
数からゲームにデータを返します。
Lambda 関数は、Amazon DynamoDB などのその他の Amazon Web Services を呼び出して、そのリ
ソースでオペレーションを実行することもできます。次に例をいくつか示します。
• ハイスコアの送信 – Lambda 関数はプレイヤ ID と新しいスコアを使用し、データベースでプレイヤ
ID を参照してそのスコアを既存のスコアと比較し、必要な場合は最も高いスコアに更新できます。
• データのサニタイズ – Lambda 関数は悪意ある入力や異常な入力がないかを確認できます。たとえ
ば、ベストプレイヤが 1,000 に到達できない場合に、あるプレイヤが 999,999,999 という新しいハ
イスコアをアップロードしようとすると、Lambda 関数はその送信をインターセプトして拒否する
か、レビュー用のフラグを付けることができます。
• サーバー側の権威アクションの実行 – Cloud Canvas はユーザーの Lambda 関数を呼び出して
ゲーム内のメリットを制御できます。たとえば、プレイヤがアイテムを購入しようとするとき
に、Lambda 関数はデータベースを確認し、プレイヤがそのアイテムに支払うだけの十分なお金が
Version 1.6
193
Lumberyard 開発者ガイド
Cloud Canvas リソース管理
あるかどうかを検証できます。次に、関数はプレイヤのアカウントから該当する金額を差し引き、
プレイヤのインベントリにそのアイテムを追加します。
ID およびアクセス許可
クラウド内でプレイヤの ID を管理し、AWS リソースへのアクセスを制御するために、Cloud Canvas
は Amazon Cognito サービスをサポートしています。
Amazon Cognito は特定のデバイスに関連付けられたユーザーに一意の匿名の ID を作成できます。ま
た、Amazon、Facebook、または Google といった認証プロバイダーの ID を認証できます。これによ
り、単一デバイスでの匿名の使用権限から複数のデバイスでの認証済み使用権限にシームレスに移行
できる、一貫したユーザー ID がゲームに提供されます。以下の例を検討してください。
• プレイヤは匿名でゲームのプレイを開始し、進捗状況を各自のデバイスにローカルに保存します。
後で経験を "アップグレード" し、前述のいずれかのログインプロバイダーを介した認証を依頼しま
す。プレイヤが認証 ID を指定すると、クラウド内に進捗状況を保存し、複数のデバイスからそれぞ
れの進捗状況にアクセスできます。
• アクセスが許可される AWS リソースプレイヤを指定できます。たとえば、ゲームだけでなく、外
部ウェブサイトなど誰でも呼び出せるように "Get the Latest High Scores" Lambda 関数を有効にす
ることができます。この場合でも、"Submit High Scores" 関数を呼び出せるのはゲームのプレイヤ
に限定できるため、ハイスコアテーブルをセキュアに保つことができます。これらのアクセス許可
は Cloud Canvas を使用して管理できます。
Cloud Canvas リソース管理
Amazon Web Services との通信に加えて、Cloud Canvas でリソースを管理することもできま
す。Amazon Web Services を使用すると、ゲームリソースグループに必要なあらゆるクラウドリソー
スを作成および管理できます。リソースグループを実装すると、Cloud Canvas デプロイを使用して
ゲームの開発、テスト、ライブバージョン用にリソースを管理できます。詳細については、「Cloud
Canvas Resource Manager の概要 (p. 196)」を参照してください。
リソースの定義
AWS CloudFormation テンプレートを使用して、クラウドリソースを作成できます。AWS
CloudFormation は、テンプレートを使用して計画に従い、再現性の高い方法で AWS リソースを定
義、作成、管理できるアマゾン ウェブ サービスです。テンプレートは、単一のユニット (スタック)
としてまとめて作成するリソースのコレクションを指定する際に使用する JSON 形式のテキストファ
イルです。
テンプレートの各リソースには専用の AWS CloudFormation 定義があり、この定義でリソースを制御
するパラメーターを指定します。AWS CloudFormation テンプレートはこのトピックでは取り上げま
せんが、現時点では、1 つの Amazon DynamoDB テーブルと 2 つの AWS Lambda 関数でテンプレー
トを定義できることなどを理解しておくだけで十分です。Amazon DynamoDB テーブルを作成する
AWS CloudFormation テンプレートの例については、AWS CloudFormation ユーザーガイドを参照し
てください。
デプロイ
新しいリソースグループで作業する場合、品質管理チームによるテストが必要になる場合がありま
す。独自のバージョンで作業を続行する間も、テストチームが使用できるリソースグループのバー
ジョンを提供する必要があります。対応するリソースの異なるバージョンを個々に保持するため
に、Cloud Canvas では個別にデプロイを作成することができます。デプロイは、製品の機能の個別の
インスタンスです。
前述のようなシナリオでは、開発チームに 1 つ、テストチームに 1 つ、ライブプレイヤに 1 つといっ
た、合計 3 つのデプロイを作成できます。各デプロイのリソースは互いに独立しており、(たとえば)
Version 1.6
194
Lumberyard 開発者ガイド
Cloud Canvas リソース管理
テストチームが入力したデータをプレイヤには表示すべきではない場合など、それぞれに異なるデー
タを格納できます。
Cloud Canvas を使えば、これらのデプロイを互いに独立して管理することも、デプロイ間で自由に切
り替えることもできます。変更を行った後は、Cloud Canvas を使って機能やデプロイを更新し、対応
する AWS リソースも更新できます。
デプロイを使用したチームワークフロー
以下のワークフロー例は、Cloud Canvas によるデプロイのしくみを示しています。
1. テストチームがバグを検出します。Lambda コード内のバグを修正します。
2. 開発デプロイに切り替え、Lambda 関数の新しいバージョンをアップロードします。テストデプロ
イとライブデプロイ内の Lambda コードは現時点では変更を加えず、そのままの機能を継続しま
す。
3. 修正したバグに問題がなければ、テストデプロイ内の Lambda コードを更新します。これで、テス
トチームは修正内容をテストできるようになります。ライブデプロイは変更なく継続されます。
4. テストチームが修正内容を承認した後、ライブデプロイを更新します。更新内容をライブプレイヤ
に反映します。ライブプレイヤがゲームの新しいバージョンをダウンロードする必要はありませ
ん。
フローグラフを使用したクラウドリソースとの通信
ゲームが AWS リソースと通信する際、Lumberyard のフローグラフシステムを使用してゲームと
AWS 間のやり取りを実装できます。Cloud Canvas 固有のフローグラフノードは他のフローグラフ
ノードと同じように機能しますが、AWS サービスの呼び出しも行います。たとえば、機能が異なる
状況において必要な 2 つの Lambda 関数を使用する場合、Lumberyard フローグラフシステムを使用
し、ゲームの適切な条件において呼び出される関数を指定できます。
また、フローグラフを使用して関数の成功または失敗に応じた適切なアクションを実行することもで
きます。たとえば、インターネット接続がない場合にエラーを返す関数や、リソースと接続するため
に十分な権限が関数にない場合にエラーを返すこともできます。ゲームはすべてのエラーを解析し、
ユーザーに再試行またはスキップを確認するなどの適切な操作を実行できます。
デプロイが複数ある場合、Cloud Canvas は AWS インスタンスに対する内部マッピングでわかりやす
い名前を適用し、使用する AWS リソースをゲームで識別しやすくします。Cloud Canvas は現在選択
しているデプロイを対応するリソースセットにマッピングします。
このため、ゲームを顧客にリリースする際、ライブプレイヤに明示的に確保しておいたデプロイを使
用します。1 つの機能の開発バージョンを使用している際にデプロイをテストに切り替える場合は、
ゲームはテストデプロイに関連付けられている Lambda 関数を呼び出します。
Cloud Canvas を使用したアクセス許可の管理
アクセス許可の管理はクラウドに接続された安全なゲームを構築するうえで重要な要素です。アクセ
ス許可を個別に管理することは、開発、テスト、本稼動の各段階で重要です。アクセス許可は、開発
およびテストチーム、ゲームで使用する AWS リソース、ゲームのプレイヤに割り当てることができ
ます。主な目的は、ゲームの AWS リソースをハッカーなどのあらゆる不正使用から保護することで
す。
アクセス許可を使用すれば、ゲームの一部である AWS リソースにアクセスできるユーザーと許可さ
れる操作を細かく指定できます。たとえば、スクリーンショットをアップロードするゲーム機能があ
る場合、スクリーンショットを保存する Amazon S3 バケットを作成できます。バケットへの書き込
み (ファイルの送信) を可能にしても、バケットから読み取ることはできないようにゲームのアクセス
許可を設定できます。こうしておくことで、アップロードしたファイルが好奇心にあふれるユーザー
によって調べられないようにします。その一方で、チームメンバーにはバケット内のファイルに対す
Version 1.6
195
Lumberyard 開発者ガイド
Cloud Canvas Resource Manager の概要
る読み取り権限を付与し、各メンバーがファイルを確認して承認できるように設定できます。Cloud
Canvas を使用すれば、個々のデプロイのアクセス許可も設定できます。たとえば、ライブデプロイ
とテストデプロイに異なるアクセス許可を設定できます。
機能と同様に、AWS CloudFormation テンプレートを使用してアクセス許可を定義できます。アクセ
ス許可は、Cloud Canvas リソース管理ツールを使用してクラウドリソースを更新するたびに適用され
ます。
詳細については、「アクセスコントロールとプレイヤ ID (p. 310)」を参照してください。
Cloud Canvas Resource Manager の概要
ゲーム開発は本来はローカルな作業です。ゲームコード、アセット、その他のリソースはローカルコ
ピーとして保管されます。ビルド、テスト、および微調整がローカルコンピュータ上で何度も行われ
ます。
クラウドはこれとは異なります。これは外部環境です。ゲームが依存するリソースは「外」に配置
されます。ただし、そのリソースは手元のコンピュータシステムには存在しません。クラウド内のリ
ソースを使用し変更するプロセスは、ローカルに存在するリソースとは異なります。
Cloud Canvas Resource Manager がこのギャップを埋めます。これにより、ゲームに必要なクラウド
内の AWS リソースのローカルな記述が得られ、AWS 内のそのリソースの実際のインスタンスを作成
し連係する手段が提供されます。リソースには、データベーステーブル、ファイルストレージバケッ
ト、イベントに応じて実行されるコードなどがあります。
チームで作業するプロジェクトでは、多くの場合、使用しているソースコードとアセットはソース管
理システムに存在しています。変更した内容は、そのソース管理システムを介してプロジェクトの他
の作業者と共有されます。各作業者は、他の作業者の妨げにならずに、異なるバージョンのコードや
アセットを使用して同時に作業できます。
AWS で、クラウドのリソースを使用するゲームを開発する時には、そのゲームに関して同時に作業
をしている別の作業者とでリソースが共有される可能性があります。時には、異なるバージョンのリ
ソースがクラウド内に必要な場合があります。この場合でも、ゲームを開発している作業者が、作業
中のコードやアセットのバージョンに対応するバージョンのリソースをクラウド内で使用することを
保証する必要があります。
ゲームがリリースされた後、プレイヤーは実稼働用コピーを使用しますが、開発チームはバグ修正や
新規コンテンツの作業のために、それとは別のプライベートコピーを使用します。
この時、以下が必要になる場合もあります。
• プレイヤーが開発バージョンのゲームリソースに確実にアクセスできなくする
Version 1.6
196
Lumberyard 開発者ガイド
AWS CloudFormation のロール
• 開発チームがリリース済みのゲームを破損する可能性のある変更を加えるのを防止する
• チームのメンバーによる不正アクセスから、電子メールアドレスといったプレイヤーの情報を保護
する
Cloud Canvas Resource Manager は、以下を行うのに必要なツールを提供します。
• ゲームが依存する AWS リソースの記述を保持する
• リリースと開発チームに必要な数の AWS リソースのコピーを作成する
• これらのリソースへの安全なアクセスを支援する
AWS CloudFormation のロール
Cloud Canvas Resource Manager は、AWS CloudFormation の使用を Lumberyard ゲーム開発環境に
統合します。AWS CloudFormation を使用すれば、必要な AWS リソースの記述がテキストファイル
テンプレート内に保持され、ソース管理システムで確認できます。この記述から派生品を作成して、
ゲームの他のコードやアセットとマージできます。AWS 内にリソースの実際のインスタンスを作成
する必要がある場合、Cloud Canvas Resource Manager がその記述を AWS CloudFormation に渡しま
す。AWS CloudFormation はテンプレートファイルを使用して、記述に合致するリソースを AWS 内
で作成、更新、または削除します。
リソースマネージャーを使用して、記述を任意の数のリソースグループに編成できます。各グループ
では、ハイスコアの追跡システムといったゲーム機能に必要なすべてリソースが記述できます。詳細
については、「リソースの定義」を参照してください。
リソースマネージャーを使用して、必要な数のリソースの記述を作成できます。開発チームへのデプ
ロイ用、QA チーム用、リリース済みゲーム用、その他必要に応じて自由に作成できます。各デプロ
イには、プロジェクトのすべてのリソースの完全かつ独立したインスタンスが含まれています。デプ
ロイは AWS CloudFormation stack リソースを使用して実装されます。詳細については、「リソース
のデプロイ」を参照してください。
使用するデプロイは Lumberyard エディタ で選択できます。たとえば、「QA」デプロイを作成し、こ
れを使用してゲームをテストする場合、Lumberyard エディタ は自動的にゲームコードのリソースに
リファレンスをマッピングし、そのリソースの「QA」インスタンスにフローグラフをマッピングしま
す。
同様にして、ゲームのリリースビルドに使用するデプロイも指定できます。詳細については、「リ
ソースマッピング」を参照してください。
各デプロイには、AWS 管理ポリシーと AWS のロールがあります。これらは、特定の AWS ユーザー
やグループにデプロイへのアクセスを許可するのに使用できます。たとえば、プレイヤーはデプロイ
Version 1.6
197
Lumberyard 開発者ガイド
チュートリアル: Cloud Canvas の開始方法
内の特定のリソースへのアクセスが許可されます。詳細については、「アクセスコントロールとプレ
イヤー ID」を参照してください。
チュートリアル: Cloud Canvas の開始方法
このチュートリアルでは、Cloud Canvas の使用を開始するための手順について説明します。たとえ
ば、Amazon Web Services（AWS）のアカウントへのサインアップ、AWS の認証情報の入力、コマ
ンドラインツールを使用した Cloud Canvas の初期化を取り上げます。チュートリアルの最後には、
AWS 認証情報を使用して、Cloud Canvas 対応の Lumberyard プロジェクトを管理できています。
具体的には、このチュートリアルでは次のタスクを説明していきます。
• Amazon Web Services アカウントを取得する
• AWS マネジメントコンソール を操作する
• Cloud Canvas プロジェクトを管理するのに適切な権限を持つ AWS Identity and Access
Management（IAM）ユーザーを作成する
• IAM ユーザーの認証情報を取得し、Cloud Canvas ツールに入力する
• コマンドラインツールを使用して、Cloud Canvas で使用する Lumberyard プロジェクトを初期化す
る
• Cloud Canvas で割り当てられた AWS の全リソースを削除して、プロジェクトを廃止する
前提条件
このチュートリアルを開始する前に、以下を完了する必要があります。
• Lumberyard エディタ の作業バージョンのインストールする
• Cloud Canvas Gem（拡張機能）を有効にして Lumberyard プロジェクトを設定する
• Cloud Canvas の概要と概念を理解する
ステップ 1: AWS にサインアップする
Amazon Web Services (AWS) にサインアップすると、すべてのクラウド機能にアクセスできま
す。Cloud Canvas でお客様の AWS にリソースが作成されることで、Lumberyard を介してこれら
サービスにアクセスできるようになります。料金が発生するのは、実際に使用したサービスの分のみ
です。AWS の新規のお客様の場合、無料で Cloud Canvas の使用を開始できます。詳細については、
「AWS 無料利用枠」を参照してください。
個人またはチームですでに AWS アカウントをお持ちの場合は、ステップ 2 (p. 199) に進みます。
AWS アカウントを作成するには
1.
https://aws.amazon.com/ を開き、[AWS アカウントの作成] を選択します。
2.
手順に従って新しいアカウントを作成します。
Note
• サインアップ手順の一環として、通話呼び出しを受け取り、電話で PIN を入力しま
す。
• アカウントを作成するには、お支払い方法を指定する必要があります。ここで示して
いるチュートリアルは、AWS 無料利用枠に含まれますが、優良なものもあるためご注
意ください。
Version 1.6
198
3.
4.
Lumberyard 開発者ガイド
ステップ 2: Cloud Canvas プロジェク
トを管理する AWS Identity and Access
Management (IAM) ユーザーを作成する
次のステップへ進む前に、ご自分のアカウントが作成されたことを確認するメールが届くまでお
待ちください。
AWS アカウント番号をメモしておいてください。次のステップで使用します。
これで、AWS アカウントを取得できました。AWS のアカウント番号を準備しておきます。
ステップ 2: Cloud Canvas プロジェクトを管理する
AWS Identity and Access Management (IAM) ユー
ザーを作成する
自分が AWS アカウントを持っていることを確認したら、Cloud Canvas プロジェクトを管理するた
めの適切な権限を持つ AWS Identity and Access Management (IAM) ユーザーが必要です。IAM で
は、AWS アカウントへのアクセスを管理できます。
AWS サービスにアクセスするときは、使用するための適切な権限を持っていることを確認するため
に、認証情報を求められます。これらの認証情報は、プロジェクト設定の一環として Lumberyard エ
ディタ に入力します。
作成する IAM は、Cloud Canvas リソースをインストールし Lumberyard を通してアクセス可能に
するための管理者権限を持つグループに属します。このグループの管理ユーザーは、通常の Cloud
Canvas ユーザーの範囲を超える特別な権限を持ちます。
チーム環境では、—管理者のグループのメンバーが—、自分のチームの各メンバー対する IAM ユー
ザーを作成します。IAM では、プロジェクトの各メンバーのロールに対して権限を設定できます。例
えば、デザイナーのみがデータベースを編集できるように指定したり、自分のプレーヤーがインタラ
クトするリソースへチームメンバーが誤って書き込むことを防いだりできます。
IAM と権限に関する詳細は、IAM ユーザーガイド をご覧ください。
このセクションでは、自分のアカウントへの IAM ユーザーの作成、管理者グループの作成、IAM ユー
ザーの管理者グループへの追加を行うことで、 IAM のベストプラクティスを説明します。
IAM ユーザーを作成する
ここで、IAM ユーザーを作成します。
IAM ユーザーをアカウントに作成するには
1.
AWS マネジメントコンソール にサインインして、https://console.aws.amazon.com/iam/ で IAM
コンソールを開きます。
2.
[Navigation] ペインで [Users] をクリックします。
3.
[Create New Users] をクリックします。
4.
[1] ボックスにユーザー名を入力します。このチュートリアルでは、名前に CloudCanvasAdmin
を使用します。
5.
[Generate an access key for each user] チェックボックスがオンになっていることを確認しま
す。
6.
[Create] をクリックします。IAM ユーザーが作成され、2 つの重要な認証情報であるアクセス
キーとシークレットアクセスキーが割り当てられます。これらの認証情報は、自分のプロジェク
トの AWS リソースにアクセスするために Cloud Canvas に登録する必要があります。
7.
セキュリティー証明書を確認するには、[Show User Security Credentials] をクリックするか、
[Download Credentials] をクリックして .csv ファイルでダウンロードしてください。 認証情報
は必ず安全な場所に保存してください。これ以降、AWS マネジメントコンソール からシーク
レットアクセスキーを表示することはできません。
Version 1.6
199
Important
Lumberyard 開発者ガイド
ステップ 2: Cloud Canvas プロジェク
トを管理する AWS Identity and Access
Management (IAM) ユーザーを作成する
認証情報を他者と共有しないでください。これらの認証情報にアクセスできる人はだれ
でも、AWS アカウントにアクセスし、料金の発生させた上で、悪意のある行為を行うこ
とができます。
8.
[Close] をクリックします。次に、ユーザーのパスワードを作成します。
9.
ユーザーのリストで、ユーザー名 CloudCanvasAdmin（または使用している名前）をクリック
します。
10. [Security Credentials] タブをクリックしてパスワードを作成してください。後でこのパスワード
を使用してサインインできます。
11. [Manage Password] をクリックします。
12. [Assign an auto-generated password] または [Assign a custom password] をクリックしてくださ
い。
13. 完了したら、[Apply] を選択します。
これで、IAM ユーザーを作成できました。次に、管理者グループを作成します。後
で、CloudCanvasAdmin ユーザーをこのグループに追加します。
管理者グループを作成するには
IAM グループによって、各個人を管理することなく大勢のユーザーの権限の管理を簡素化することが
できます。
Cloud Canvas 管理 IAM ユーザーのグループを作成するには
1.
IAM コンソールの左側のナビゲーションペインで [Groups] を選択します。
2.
[Create New Group（新しいグループの作成）] を選択します。
3.
グループに CloudCanvasAdministrators などの名前をつけます。
4.
[Next Step] をクリックします。
5.
[AdministratorAccess] ポリシーの横にあるチェックボックスを選択します。このポリシーに
は、Cloud Canvas プロジェクトを作成および管理するのに必要な権限が示されています。
Warning
AdministratorAccess ポリシーは、AWS アカウント内のほぼ全ての権限を付与するため、
アカウントの管理者にのみ帰属する必要があります。他のチームメンバーに付加してし
まうと、他のチームメンバーが行った操作により、AWS アカウントで不要な課金が発生
する可能性があります。
6.
[Next Step] をクリックします。
7.
作成候補となっているグループを確認します。
8.
[Create Group] をクリックします。
これで、管理者権限のあるグループが作成されました。
次に、前のステップで作成した CloudCanvasAdmin IAM ユーザーを、今作成した
CloudCanvasAdministrators グループに追加します。
管理者グループに IAM ユーザーを追加する
ユーザーを管理者グループに追加するのは、各 IAM ユーザーに個別に管理者権限のあるポリシーを付
加するよりも簡単でよりセキュアです。このチュートリアルでは、管理者グループに IAM ユーザーを
1人だけ追加しますが、必要に応じてさらに追加できます。
Version 1.6
200
Lumberyard 開発者ガイド
ステップ 3: IAM ユーザーとしてサインインする
CloudCanvasAdministrators グループに CloudCanvasAdmin IAM ユーザーを追加するには
1.
2.
3.
4.
5.
新規作成した CloudCanvasAdministrators グループの名前（チェックボックスではなく）を
クリックします。
[Users] タブで、[Add Users to Group] を選択します。
管理者グループに入れたい CloudCanvasAdmin IAM ユーザーの横にあるチェックボックスを選
択します。
[Add Users] をクリックします。CloudCanvasAdmin ユーザー名が
CloudCanvasAdministrators グループのユーザーリストに表示されます。
次のステップで CloudCanvasAdmin ユーザーとしてサインインするために、AWS マネジメント
コンソール からサインアウトします。
ステップ 3: IAM ユーザーとしてサインインする
新規ユーザーとして使用する準備ができました。
IAM ユーザーとしてサインインするには
1.
AWS アカウントを作成した時に受け取った、AWS アカウント ID を取得しま
す。CloudCanvasAdmin IAM ユーザーとしてサインインするには、この AWS アカウント ID を
使用します。
2.
Web ブラウザで、URL https://<your_aws_account_id>.signin.aws.amazon.com/
console/ を<your_aws_account_id> の部分にハイフンなしで自分の AWS
アカウント番号を入力します。例えば、お客様の AWS アカウント番号が
1234-5678-9012 の場合、AWS アカウント ID は、123456789012 、訪れるサイト
は、https://123456789012.signin.aws.amazon.com/console/ のようになります。
3.
4.
URL をブックマークに登録すると今後の利用の際に便利です。
前のステップで作成した、CloudCanvasAdmin IAM ユーザー名を入力します。
パスワードを入力して、[Sign In] を選択してください。
これで、AWS マネジメントコンソール にサインインしました。
Note
チュートリアルでは、最後まで AWS マネジメントコンソール にサインインしている必要が
あります。サインアウトした場合は、前のステップに戻って再度サインインしてください。
ステップ 4: Cloud Canvas Gem（拡張機
能）Package を有効にする
Cloud Canvas 機能は、Gem package を使用してLumberyard で有効になります。 Gam パッケージあ
るいは Gems は、Lumberyard プロジェクト内のコードやアセットを共有する拡張機能です。Gems
には、プロジェクトコンフィギュレータ を通してアクセスおよび管理します。
チュートリアルのこのセクションでは、SamplesProject の使い方、SamplesProject を使用していない
場合は、Cloud Canvas Gem パッケージを新規プロジェクトで有効にする方法を説明します。
SamplesProject の Cloud Canvas
デフォルトの SamplesProject は、すでに Cloud Canvas Gem パッケージを使用するための設定が
済んでいます。SamplesProject を使用している場合、追加のステップはありません。ステップ 5:
Lumberyard への管理者認証情報を追加する (p. 202)を参照してください。
Version 1.6
201
Lumberyard 開発者ガイド
ステップ 5: Lumberyard への管理者認証情報を追加する
新規プロジェクトで Cloud Canvas を有効にする
新しいプロジェクトで作業する場合は、以下の手順に従って Cloud Canvas 機能を有効にします。
Note
Cloud Canvas Gem パッケージをまだ設定されていないプロジェクトに追加する場合
は、Visual Studio でプロジェクトを再構築する必要があります。
新規プロジェクトで Cloud Canvas を有効にするには
1.
Lumberyard dev\Bin64\ バイナリディレクトリーから ProjectConfigurator.exe を起動し
ます。
2.
[Enable packages] をクリックして、Gems パッケージの画面に移動します。
3.
Cloud Canvas（AWS） Gem パッケージのチェックボックスがオンになっていることを確認して
ください。オンになっている場合は、ProjectConfigurator を閉じて、ステップ 5: Lumberyard へ
の管理者認証情報を追加する (p. 202) に進みます。
4.
[Save] をクリックして、ProjectConfigurator を閉じます。
5.
Cloud Canvas（AWS）Gem をプロジェクトに追加する必要がある場合は、コマンドライン画面
を開いて lmbr_waf configure を実行して新しいプロジェクトを設定します。
6.
生成された Visual Studio ソリューションファイルを再コンパイルし、構築します。Cloud
Canvas 用の Lumberyard プロジェクトが作成されました。
ステップ 5: Lumberyard への管理者認証情報を追加
する
Cloud Canvas プロジェクトの管理を始めるために、前の手順で作成した IAM ユーザー認証情報
を、Cloud Canvas が簡単に参照できるプロフィールに追加する必要があります。これを行うに
は、Lumberyard エディタ またはコマンドラインのプロンプトのいずれかを使用します。
Lumberyard エディタ に認証情報を入力するには
1.
Lumberyard エディタ で、[AWS]、[Credentials manager] の順にクリックします。
2.
[Credentials Manager] ダイアログで、[Add profile] をクリックします。
3.
[Add profile] ダイアログボックスで、要求された情報を入力します。[Profile name] に任意の名前
(たとえば、CloudCanvasAdminProfile) を入力します。[AWS access key] および [AWS secret
key] では、ステップ 2 (p. 199) で生成したシークレットキーおよびアクセスキーを入力しま
す。
Version 1.6
202
Lumberyard 開発者ガイド
ステップ 6: コマンドラインか
ら Cloud Canvas を開始する
4.
[Save] をクリックします。
5.
Credentials Manager で [OK] をクリックします。
コマンドラインを使用して認証情報を追加するには
1.
コマンドラインのウィンドウを開き、Lumberyard のルートディレクトリに移動します。ルート
ディレクトリは、Lumberyard のインストールディレクトリの dev サブディレクトリ (たとえば
C:\lumberyard\dev) です。
2.
以下のコマンドプロンプトを入力して、[Enter] をクリックします。<profile-name> を任意の
名前（例えば、 CloudCanvasAdminProfile）に変更します。<secret-key> と <accesskey> をステップ 2 (p. 199) で生成したシークレットキーとアクセスキーに置き換えます。
lmbr_aws add-profile --profile <profile-name> --make-default --aws-secretkey <secret-key> --aws-access-key <access-key>
プロファイル名が認証情報と関連付けられ、ローカルマシン上の AWS 認証情報ファイルに保存され
ました。このファイルは通常、C:\Users\<user name>\.aws\ ディレクトリに配置されます。利便
性を考慮して、AWS Command Line Interface や AWS Toolkit for Visual Studio などのその他のツール
もこれらの認証情報にアクセスできます。
プロファイルも Cloud Canvas 用にデフォルトプロファイルとして構築されています。このデフォル
トのプロファイルによって、Lumberyard エディタ を使用したり、lmbr_aws command を実行する度
にプロファイルを指定する必要がなくなります。
Important
これらの認証情報を他者と共有しないでください。また、ソース管理にチェックインしない
でください。これらの情報により、AWS アカウント内のほぼすべてのアクセス権限を持つこ
とができため、悪意のあるユーザーにより料金が発生する可能性があります。
これで、Cloud Canvas プロジェクトを管理するためのプロファイルが作成されました。
ステップ 6: コマンドラインから Cloud Canvas を開
始する
このステップでは、Cloud Canvas 機能を使用する Lumberyard プロジェクトを設定します。Cloud
Canvas で必要な初期 AWS リソース全てを設定します。どのプロジェクトでもこのステップを行うの
は 1 回だけです。
Cloud Canvas を初期化するには
1.
SamplesProject を使用していて、かつソース管理に Lumberyard をチェックインした場合
は、<root>\SamplesProject\AWS\project-settings.json ファイルがチェックアウトさ
Version 1.6
203
Lumberyard 開発者ガイド
ステップ 7: リソースグループを見つけて追加する
れていて書き込み可能になっていることを確認します。新しいプロジェクトを使用している場合
は、このファイルは、プロジェクトの AWS ディレクトリにあるその他のファイルと一緒に初期化
プロセスで作成されます。
2.
コマンドラインウィンドウを開き、Lumberyard \dev ディレクトリに移動します。
3.
AWS リソースが表示される領域を Cloud Canvas に与える必要があります。Cloud Canvas に
は、Amazon Cognito サービスでサポートされた領域を選択する必要があります。このサービ
スによって利用できるかどうかは、リージョン一覧 で確認できます。このチュートリアルで
は、Amazon Cognito をサポートする 米国東部（バージニア北部） へリソースを割り当てます。
次のコマンドを入力します。
lmbr_aws create-project-stack --region us-east-1
このコマンドは、<root>\<game>\AWS ディレクトリのコンテンツを初期化して、AWS アカウ
ントでプロジェクトを管理するために Cloud Canvas で必要なリソースを作成します。
続行する前に、初期化プロセスが完了するまでお待ちください。初期化プロセスには数分かかる
場合があります。
Note
この初期化プロセスは、1つの Lumberyard プロジェクトに対して1回のみ行う必要があ
ります。
4.
次のコマンドを入力すると、ご自分の AWS アカウントに作成したリソースを表示することがで
きます。
lmbr_aws list-resources
5.
ソースコントロールを使用している場合は、<root>\<game>\AWS ディレクトリのコンテンツを
チェックインするとチームの他のユーザーが AWS リソースにアクセスできるようになります。
これで、Lumberyard プロジェクトで Cloud Canvas を使用できるようになりました。
ステップ 7: リソースグループを見つけて追加する
Cloud Canvas では Lumberyard プロジェクトで必要な AWS リソースをいくつもの別個のリソースグ
ループに構成することができます。このステップでは、すでに SamplesProject により定義されている
DontDieAWS リソースグループを検索する方法を説明します。異なるプロジェクトを使用している場
合は、リソースグループの追加方法およびオプションでリソース例を追加する方法も説明します。
SamplesProject によって定義されているリソースグループを
検索する
SamplesProject は、「DontDieAWS」という単一のリソースグループを定義します。このリソー
スグループのリソース定義は、<root>\SamplesProject\AWS\resource-group\DontDieAWS
\resource-template.json ファイルにあります。このファイルは、AWS CloudFormation テンプ
レートです。これは、このチュートリアルの次のステップでSamplesProject に必要な AWS リソース
の作成に使用されます。
コマンドプロンプトで以下を入力して Enter を押すと、このリソースグループが SamplesProject の
一部であることが確認できます。
lmbr_aws list-resource-groups
Version 1.6
204
Lumberyard 開発者ガイド
ステップ 8: デプロイを作成する
新規プロジェクトにリソースグループを追加する
新規プロジェクトにリソースグループを追加するには
1.
ソース管理に Lumberyard プロジェクトをチェックインしている場合は、<root>\<game>\AWS
\deployment-template.json ファイルがチェックアウトされ、書き込み可能になっているこ
とを確認してください。
2.
以下のコマンドを入力して新しいリソースグループの定義を追加します。
lmbr_aws add-resource-group --resource-group Example --include-exampleresources
このコマンドを実行すると、このリソースグループのリソース定義を <root>\<game>\AWS
\resource-group\Example\resource-template.json ファイルで確認することができま
す。このファイルは、AWS CloudFormation テンプレートです。これは、このチュートリアルの
次のステップでプロジェクトに必要な AWS リソースの作成に使用されます。
3.
次のコマンドを入力すると、リソースグループが Lumberyard プロジェクトの一部として表示さ
れます。
lmbr_aws list-resource-groups
ステップ 8: デプロイを作成する
AWS アカウントでプロジェクトのリソースグループ用 AWS リソースを作成するには、Cloud
Canvas デプロイを作成します。Cloud Canvas ではデプロイをいくつでも作成できます。各デプロイ
には、Lumberyard プロジェクトで必要な、完全かつ独立した一連のリソースがあります。これは、
(たとえば) ゲームのデプロイ用、テスト用、本稼働用リソースを別個に用意する場合に便利です。こ
のステップでは、プロジェクトのデプロイを作成する方法を説明します。
Note
プロジェクト管理者 (AWS アカウントのアクセス権限を持つユーザー) のみがデプロイを追加
または削除することができます。
Cloud Canvas Resource Manager でデプロイを作成する
1.
ソース管理に Lumberyard プロジェクトをチェックインしている場合は、<root>\<game>\AWS
\project-settings.json ファイルがチェックアウトされ、書き込み可能になっていることを
確認してください。
2.
Lumberyard エディタ で、[AWS]、[Cloud Canvas]、[Cloud Canvas Resource Manager] の順にク
リックします。
3.
[Cloud Canvas configuration] ナビゲーションペインで、[Administration (advanced)]、
[Deployments] の順に選択します。
4.
詳細ペインで、[Create deployment] をクリックします。
Version 1.6
205
Lumberyard 開発者ガイド
ステップ 8: デプロイを作成する
5.
[Create deployment] ダイアログで、デプロイの名前を入力します。
Lumberyard では、入力した名前がプロジェクトのスタック名に付加され、デプロイ用の AWS
CloudFormation スタックが作成されます。
6.
デプロイの作成プロセスを開始するには、[OK] をクリックします。
Resource Manager のナビゲーションツリーでは、デプロイのノードが [Deployments] の下に表
示されます。詳細ペインについては、「Cloud Canvas の進行状況ログを表示 (p. 236)」で作成
プロセスの詳細を説明しています。
7.
デプロイをデフォルトにするには、「 デプロイをデフォルトにする (p. 240)」を参照してくだ
さい。
コマンドラインからデプロイを作成する
1.
ソース管理に Lumberyard プロジェクトをチェックインしている場合は、<root>\<game>\AWS
\project-settings.json ファイルがチェックアウトされ、書き込み可能になっていることを
確認してください。
2.
次のコマンドを入力して、デプロイを作成します。
lmbr_aws create-deployment --deployment TestDeployment
3.
次のコマンドを入力すると、デプロイが Lumberyard プロジェクトの一部として表示されます。
lmbr_aws list-deployments
4.
作成したデプロイを Lumberyard エディタ でデフォルトのデプロイにするには、次のコマンドを
入力します。
lmbr_aws default-deployment --set TestDeployment
5.
次のコマンドを入力すると、デプロイで作成されたリソースが表示されます。
Version 1.6
206
Lumberyard 開発者ガイド
ステップ 9: AWS でリソースを確認する
lmbr_aws list-resources --deployment TestDeployment
ステップ 9: AWS でリソースを確認する
このステップでは、このチュートリアルのこれまでのステップで作成した AWS CloudFormation ス
タックを確認します。
AWS でリソースを確認するには
1.
2.
ウェブブラウザーで、IAM の認証情報を使用して、AWS マネジメントコンソールにサインインし
ます（ステップ 3 (p. 201) を参照）。
コンソール画面の右上に表示される AWS リージョンが、ステップ 6 (p. 203) で Cloud Canvas
のリソースをデプロイしたときに指定したリージョンに設定されていることを確認します。この
チュートリアルでリージョンを選択した場合は、[N. Virginia] が表示されます。
3.
[Services]、[CloudFormation] の順にクリックします。
4.
これまでのチュートリアルステップにより、他のスタックも多数作成されていることに注意し
てください。スタックの更新オペレーションが進行中の場合、そのスタックのステータスは
UPDATE_IN_PROGRESS になります。それ以外の場合、ステータスには CREATE_COMPLETE
が示されます。[Refresh] をクリックして、ステータスを更新しなければならないこともありま
す。
次のステップでは、管理者として、チームメンバーに Cloud Canvas へのアクセスを付与する方法に
ついて説明します。
ステップ 10: IAM を使用して Cloud Canvas チーム
を管理する
このステップでは、チーム用の Cloud Canvas IAM ユーザーを作成し、ユーザーグループを作成し
たうえで、Cloud Canvas 管理ポリシーをそのグループにアタッチし、ユーザーを追加します。これ
は、AWS リソースへのユーザーアクセスを管理するのに役立ちます。
Cloud Canvas が IAM ユーザー向け作成するポリシーは、管理者向けのポリシーよりも制限がかなり
厳しくなっています。これは、チームメンバーに対して、管理者の承認のない不用意な課金が発生し
ないようにするためです。
プロジェクトに新しいリソースグループと AWS リソースを追加すると、こうした管理ポリシーが自
動的に更新され、最新のアクセス権限が反映されます。
IAM ユーザーを作成する
まず、IAM ユーザーを作成します。
IAM ユーザーを作成するには
1.
CloudCanvasAdmin 認証情報を使用して、AWS マネジメントコンソールにサインインします
（ステップ 3 (p. 201) を参照）。
2.
3.
4.
5.
6.
[Services]、[IAM] の順にクリックします。
[Navigation] ペインで [Users] をクリックします。
[Create New Users] をクリックします。
各チームメンバーの IAM ユーザー名を入力します。
[Generate an access key for each user] チェックボックスがオンになっていることを確認しま
す。
Version 1.6
207
Lumberyard 開発者ガイド
ステップ 10: IAM を使用して
Cloud Canvas チームを管理する
7.
[Create] をクリックします。
8.
ユーザーごとにアクセスキーとシークレットアクセスキーをダウンロードするオプションを選択
します。作成したすべてのユーザーのキーが、1 つの .csv ファイルでダウンロードされます。
認証情報は必ず安全な場所に保存してください。以降、シークレットアクセスキーは AWS マネ
ジメントコンソールから確認できなくなります。各ユーザーにそれぞれのキーを安全に配布する
必要があります。
9.
[Close] をクリックします。
グループを作成する
次に、新しく作成されたユーザーの IAM グループを作成します。
IAM ユーザーのグループを作成するには
1.
IAM コンソールの左のナビゲーションペインで、[Groups] をクリックします。
2.
[Create New Group] をクリックします。
3.
グループに名前を付けます。このチュートリアルでは、CloudCanvasDevelopers という名前を
使用します。
4.
[Next Step] をクリックします。
5.
Cloud Canvas によって作成された IAM 管理ポリシーを見つけるには、[Filter] の横にあるリンク
をクリックし、[Customer Managed Policies] をクリックします。
6.
プロジェクト名が含まれるポリシーの横にあるチェックボックスを選択します。SamplesProject
を使用している場合、名前は SamplesProject-DontDieDeploymentAccess で始まります。
7.
[Next Step] をクリックします。
8.
作成候補となっているグループを確認します。
9.
[Create Group] をクリックします。
IAM ユーザーをグループに追加する
最後に、IAM ユーザーを、作成したグループに追加します。
Cloud Canvas IAM ユーザーをグループに追加するには
1.
グループが選択されていない場合は、左のナビゲーションペインで [Group] をクリックします。
2.
新しく作成された CloudCanvasDevelopers グループの名前をクリックします（横にある
チェックボックスではありません）。
3.
ユーザーがまだアクティブになっていない場合は、[Users] タブをクリックします。
4.
[Add Users to Group] を選択します。
5.
CloudCanvasDevelopers グループに追加する IAM ユーザーの横にあるチェックボックスを選
択します。
6.
[Add Users] をクリックします。チームのユーザー名は、グループのユーザーのリストに表示され
ます。
7.
前にダウンロードした credentials.csv ファイルを開きます。シークレットおよびアクセス
キーをグループの各ユーザーに安全に配布します。その際、キーを安全に保管することと、他の
人と共有しないことを徹底させます。
8.
CloudCanvasDevelopers グループの各ユーザーに、次のステップを実行してもらいます。
a.
Lumberyard エディタ で、[AWS]、[Cloud Canvas]、[Permissions and Deployments] の順に
クリックします。
b.
新しいプロファイル名と、それぞれのアクセスキーおよびシークレットアクセスキーを入力
します。
Version 1.6
208
Lumberyard 開発者ガイド
ステップ 11: Cloud Canvas 機
能と AWS リソースを削除する
Important
チームと AWS アカウントのセキュリティを確保するのは管理者の責任です。Amazon の
「IAM ユーザーのアクセスキーの管理」ページでは、チームのアクセスキーを管理する方法
のベストプラクティスとオプションをいくつか紹介しています。このページはしっかりとお
読みください。
AWS アカウントのグループおよびユーザー数の制限については、『IAM ユーザーガイド』の「IAM
エンティティとオブジェクトに関する制限」を参照してください。
ステップ 11: Cloud Canvas 機能と AWS リソースを
削除する
プロジェクトから Cloud Canvas 機能と AWS リソースを削除するには、「Cloud Canvas デプロイと
そのリソースを削除する (p. 244)」を参照してください。
Don't Die サンプルプロジェクト
このサンプルプロジェクトは、AWS Cloud Canvas リソース管理システムと AWS Lambda をゲーム
で使用する方法を示します。Don't Die では プロジェクトコンフィギュレータ も使用します。これ
は、ビルドに含めるゲームプロジェクトとアセット (Gem) を Waf Build システムに指定する際に使用
する Lumberyard に含まれるスタンドアロンアプリケーションです。
Don't Die プロジェクトで使用する AWS リソースには個別の料金と追加の条件が適用される場合が
あります。このプロジェクトで使用するすべての AWS サービスに無料利用枠があります。このプロ
ジェクトで使用される AWS サービスの詳細については、このトピックの最後を参照してください。
設定
サンプルプロジェクトをセットアップするには、いくつかのタスクを行います。
AWS プロジェクトスタックの作成
DynamoDB テーブル、S3 バケット、Lambda などの Don't Die に関連付けられるすべての AWS リ
ソースは Cloud Canvas リソース管理システムを使って作成されます。High Score や Daily Gift など
のクラウドに接続された Don't Die の機能は、それぞれに関連付けられた AWS リソースをセットアッ
プするまでは動作しません。リソースをセットアップする前に次が必要になります。
• 管理者アクセス許可を持つ AWS アカウントを取得します。
• Lumberyard エディタ と Cloud Canvas コマンドラインを使用するための AWS アカウントを用意し
ます。以下のいずれかを実行します。
• Lumberyard エディタ Credentials Manager を使用して AWS プロファイルを追加します。詳細に
ついては、「Cloud Canvas プロファイルの管理 (p. 219)」を参照してください。
• コマンドラインプロンプトで Lumberyard \dev フォルダーに移動して、以下を入力します。
lmbr_aws add-profile --aws-access-key {accesskey} --aws-secretkey {secretkey} --profile {profilename} --make-default
{accesskey} キーと {secretkey} キーを AWS アカウントの対応するキーで置き換えま
す。{profilename} を選択したプロファイル名で置き換えます。--make-default引数 (任意)
Version 1.6
209
Lumberyard 開発者ガイド
設定
を指定すると、Cloud Canvas コマンドラインを使用する際にこの認証情報のセットをデフォルト
のプロファイルにすることができます。
Note
Credentials Manager を使用する場合は、指定したプロファイルがデフォルトになりま
す。
• プロジェクトコンフィギュレータ で SamplesProject が選択されていることを確認しま
す。&project-configurator は、Lumberyard フォルダー \dev\Bin64\ProjectConfigurator.exe
から実行できます。この構成により、必要な AWS リソースを作成するためのすべてのファイル、
テンプレート、プロジェクトコードが含まれる \SamplesProject\AWS を指すように AWS リソー
ス管理システムが設定されます。
• プロジェクトコンフィギュレータ で、Cloud Canvas Gem と Static Data Gem が有効になっている
ことを確認します。
• SamplesProject\AWS\project-settings.json ファイルが書き込み可能であることを確認し
ます。リソースのセットアッププロセスの間、AWS CloudFormation スタックの Amazon リソース
ネーム (ARN) がこのファイルに追加されます。
• AWS リソース存在する AWS リソースのリージョンを選択します。Don't Die はプレイヤ ID につい
て Amazon Cognito と呼ばれるサービスに依存します。これは現在、米国東部（バージニア北部）
(us-east-1)、欧州 (アイルランド) (eu-west-1)、およびアジアパシフィック (東京) (ap-northeast-1)
のリージョンでのみサポートされています。この例では、米国東部（バージニア北部） を使用しま
す。
プロジェクトスタックを作成するには
1.
コマンドラインプロンプトで Lumberyard の \dev フォルダーに移動し、次を入力します (この例
では米国東部リージョンを使用しているものとします)。
lmbr_aws create-project-stack --region us-east-1
スタックの作成には数分かかります。
次に、ゲームのクラウドリソースの完全なセットであるデプロイを作成します。リリースのさま
ざまな段階 (開発者の内部デプロイやプレイヤのリリースデプロイなど) に対応する個別のデプロ
イ (p. 302)を作成できます。プロジェクトを簡略化するために、デプロイを 1 つのみ作成しま
す。
2.
同じコマンドラインプロンプトに次を入力し、"DontDieDeployment" と呼ばれるデプロイを作成
します。
lmbr_aws create-deployment --deployment DontDieDeployment
ゲームのテスト
この時点で、ゲーム、および AWS に接続されたハイスコア機能をテストできます。ゲーム
は、Lumberyard エディタ またはスタンドアロンの SamplesProject ランチャーから実行できます。
Lumberyard エディタ からゲームを実行するには
1.
Lumberyard エディタ を開きます。
2.
[Welcome to the Lumberyard Editor] ダイアログで、[Open Level] をクリックします。
3.
[Open a Level] ダイアログで、[Levels]、[Samples]、[Dont_Die] の順に選択し、[Open] をクリッ
クします。
Version 1.6
210
Lumberyard 開発者ガイド
設定
4.
ゲーム用リソースをアップロードするには、次のいずれかを実行します。
• コマンドラインで、次のように入力します。
lmbr_aws upload-resources
• Lumberyard エディタ で、以下の手順を実行します。
1.
[AWS]、[Cloud Canvas]、[Cloud Canvas Resource Manager] の順にクリックします。
2.
[Resource Groups] で [Upload all resources] をクリックします。
3.
Lumberyard エディタ を終了して再起動します。
Version 1.6
211
Lumberyard 開発者ガイド
Visual Studio での Lambda コードの表示
Note
このステップと次のステップはバグの回避策です。このバグは以降のリリースで
修正されます。
4.
前述の手順に従って、Lumberyard エディタ で Dont_Die レベルを読み込みます。
5.
Lumberyard エディタ でゲームをするには、Ctrl-G を押します。
ハイスコアはクラウドに記録され、次回のプレイ時に表示されます。
SamplesProject のスタンドアロンランチャーからゲームを実行することもできますが、それにはいく
つか手順を追加する必要があります。
スタンドアロンランチャーからゲームを実行するには
1.
Lumberyard エディタ で、[File]、[Export to Engine] の順にクリックするか、Ctrl-E を押してレ
ベルをエクスポートします。
2.
Lumberyard エディタ で、[AWS]、[Cloud Canvas]、[Cloud Canvas Resource Manager] の順にク
リックします。
3.
[Cloud Canvas Resource Manager] ナビゲーションツリーで、[Administration (advanced)] を展開
し、project-settings.json を選択します。リソースマネージャを使用して JSON テキストを編集す
るか、dev\SamplesProject\AWS\project-settings.json ファイルをテキストエディタで
開いて編集します。
4.
次の行に移動します。
"DefaultDeployment": "DontDieDeployment",
直後に次の行を追加します。
"ReleaseDeployment": "DontDieDeployment",
5.
ファイルを保存します。
6.
コマンドラインプロンプトで、次のコマンドを実行します。
lmbr_aws update-mappings --release
7.
プログラム dev\Bin64\SamplesProjectLauncher.exe を実行します。
8.
~ (チルド) を入力して、SamplesProject ランチャーコンソールを開きます。
9.
コンソールで次のように入力します。
map dont_die
Enter キーを押します。
ゲームが SamplesProject ランチャー内に直接に開き、プレイできるようになります。ハイスコア
はクラウドに記録され、次回のプレイ時に表示されます。
Visual Studio での Lambda コードの表示
Don't Die プロジェクトの Lambda のソースコードは、Visual Studio 2013 で表示できます。ただし、
まず次のツールをインストールする必要があります。
Version 1.6
212
Lumberyard 開発者ガイド
Visual Studio での Lambda コードの表示
• AWS Toolkit for Visual Studio
• Node.js
• Node JS Tools for Visual Studio 2013
マッピングファイルの取得
Don't Die プロジェクト内の Lambda のコードはすべて "High Score Table" のようなわかりやすい名
前で AWS リソースを参照します。Lambda 関数はマッピングファイルを使用して、わかりやすい
名前をアカウント内で実際の AWS リソースの物理的な名前に変換します。このファイルは AWS リ
ソース管理システムによって生成されますが、システムがコードを AWS にアップロードする直前に
Lambda 関数に挿入されます。Lambda 関数を Visual Studio から実行するには、次のようにマッピン
グファイルをローカルにコピーします。
マッピングファイルを取得する
1.
https://console.aws.amazon.com/lambda/ にある AWS Lambda コンソールを開きます。
2.
[DontDie] でフィルタリングして、リストに表示されたいずれかの Lambda 関数のリンク名をク
リックします (名前に DontDieMain というテキストを含む関数があるはずです)。関数の詳細
ページが表示されます。
3.
[Actions] をクリックしてから、[Download function code] をクリックします。
4.
コンピューターに .zip ファイルをダウンロードします。
5.
.zip ファイルを開き、CloudCanvas ディレクトリとその中に含まれている settings.js ファ
イルを、\dev\SamplesProject\AWS\resource-group\DontDieAWS\lambda-functioncode\ ディレクトリに解凍します。このファイルにより、Visual Studio は Lambda 関数の正しい
リソースを見つけることができます。
6.
解答を見るには、Visual Studio で dev\SamplesProject\AWS\SamplesProjectAWS.sln ファ
イルを開きます。
Lambda コードの概要
Visual Studio プロジェクト内の apps フォルダーに、don't-die-main という名前のフォルダーがあ
ります。このフォルダーには、ゲーム全体で使用される dont-die-main Lambda 関数が含まれてい
ます。この関数は、クライアントから送信されてきた start-game、end-game、get-high-scoretable などのコマンドを実行して、実行結果を送り返します。コマンドをひとまとめにすることで、
他の AWS サービスに対する呼び出し回数を最小限に抑えることができます。たとえば、プレイヤー
テーブルを更新する 2 つのコマンドをいっしょに送信する場合、Lambda 関数は、それらのコマンド
を 1 つの DynamoDB 更新操作として結合します。
don’t-die-main フォルダーには、_sampleEvent.json、_testdriver.js、および app.js の
3 つのファイルが格納されています。最初の 2 つのファイルは AWS にはアップロードされず (アッ
プロードするかどうかは .ignore ファイルによって制御される)、ローカルでのテストのみに使用さ
れます。_sampleEvent.json ファイルには、クライアントから送信されるデータを表すテストデー
タが格納されています。_testdriver.js ファイルはローカルに Lambda コードを実行し、Lambda
関数を呼び出す AWS サービスをエミュレートします。この 2 つのファイルは AWS ツールキットに
よって生成されたものです (ただし、若干変更されています)。3 番目のファイル app.js には、この
サンプルの Lambda 関数 exports.handler のエントリポイントが含まれています。
特定の Lambda 関数をテストするには、_testdriver.js ファイルを右クリックし、[Set as Node.js
Startup File] を選択して、[Debug] > [Start Debugging] をクリックします。
Lambda 関数の一般的な動作は次のとおりです。
• Lambda 関数 dont-die-main が実行されるたびに、DontDie オブジェクトが作成され、そのオブ
ジェクトに対して Start が呼び出されます。
Version 1.6
213
Lumberyard 開発者ガイド
AWS プロジェクトスタックの削除
• DontDie オブジェクトは、systemModuleList 配列内の各ゲームシステムが初期化されるのを待
機します。
• ゲームシステムは、自分が依存している静的データのセットがある場合、そのデータをロードしよ
うとします。AWS は、Lambda 関数が最近使用されたコンピュータ上で Lambda 関数を実行する場
合、前回の実行時にロードされたデータを使用します。
• すべてのゲームシステムが初期化されると、クライアントによって送信されたコマンドが実行され
ます。このステップは、app.js ファイル内のコードに対応します。
• すべてのコマンドが順番に実行された後、DontDie オブジェクトに対して Finish が呼び出されま
す。これにより、状態が変更されている場合に、その変更内容を保存する機会が各ゲームシステム
に与えられます。たとえば、プレイヤーのデータが変更されている場合は、DynamoDB に保存され
ます。
AWS プロジェクトスタックの削除
Amazon S3 バケットが空であることを確認したら、デプロイ環境、リソース、およびプロジェクトス
タックを削除できます。
S3 バケットを空にする
Don't Die は Amazon S3 バケットを 1 つ作成します。プロジェクトスタックを削除する前に、この
S3 バケットが空であることを確認してください。空になっていないと AWS リソース管理システムは
S3 バケットを削除できず、それによりプロジェクトスタックの削除がブロックされます。
Note
以下の手順は、Don’t Die の mainbucket に手動でファイルを追加した場合のみ必要になりま
す。ファイルを追加しなかった場合、このステップは省略してかまいません。
S3 バケットを空にする
1.
AWS マネジメントコンソール にサインインし、Amazon S3 コンソール（https://
console.aws.amazon.com/s3/）を開きます。
2.
タイトル内に "mainbucket" が含まれる samplesproject バケットを見つけて、そのバケットをク
リックします。
3.
バケット内の各項目を選択し、[Actions]、[Delete] の順にクリックします。
Amazon S3 バケットが空になると、プロジェクトスタックを削除できます。
デプロイ環境とそのリソースの削除
デプロイ環境、リソース、およびプロジェクトスタックを削除するには、Cloud Canvas Resource
Manager または Cloud Canvas コマンドラインを使用して DontDieDeployment を削除します。手順に
ついては、「Cloud Canvas デプロイとそのリソースを削除する (p. 244)」を参照してください。
使用した AWS サービス
Don't Die サンプルプロジェクトはゲームのバックエンド機能を AWS に実装します。デフォルトで、
このプロジェクトは以下の表に示すサービスを使用します。サンプルプロジェクトで特定の機能を使
用するとき、その機能を動作させる AWS サービスを使用しています。テンプレートをカスタマイズ
するか、独自のテンプレートを作成し、その他のサービスを追加できます。
Don't Die サンプルプロジェクトを初期化すると、対象となる AWS CloudFormation テンプレートを使
用してアカウントに AWS サービスをデプロイするよう求められます。
Version 1.6
214
Lumberyard 開発者ガイド
Cloud Canvas の使用
Cloud Canvas は追加料金なしで使用できます。Don't Die に使用する AWS リソースには個別の料
金と追加の条件が適用される場合があります。Cloud Canvas を使用して作成された AWS リソース
(Lambda 関数、DynamoDB テーブル、IAM など) の支払いは、各リソースを手動で作成した場合と
同じ方法で行います。使用した分だけをお支払いいただきます。最低料金や前払いの義務はありませ
ん。ほとんどのサービスには無料利用枠が含まれます。
AWS サービステーブル
機能
使用した AWS サービス
設定
AWS CloudFormation、Lambda、DynamoDB、Amazon
S3、Amazon Cognito、IAM
Message of the Day の例
AWS CloudFormation、Lambda、DynamoDB
達成項目の例
AWS CloudFormation、Lambda、DynamoDB
ハイスコアの例
AWS CloudFormation、Lambda、DynamoDB、Amazon S3
Daily Gift の例
AWS CloudFormation、Lambda、DynamoDB
項目マネージャーの例
AWS CloudFormation、Lambda、DynamoDB
ミッションの例
AWS CloudFormation、Lambda、DynamoDB
Cloud Canvas の使用
Cloud Canvas では Lumberyard エディタ 用とコマンドライン用の豊富なツールが提供されていて、
それらを使用してゲームのクラウド接続機能を作成および管理できます。
それらのツールを使用すると、以下のタスクを含めて、Lumberyard プロジェクトで AWS リソースを
定義および管理できます。
• Cloud Canvas 機能を使用した Lumberyard プロジェクトの初期化 (p. 218)
• プロジェクトの リソースのデプロイ (p. 302)とリソース グループ (p. 192) (接続機能) の管理
• Lumberyard ゲームプロジェクトのコンテンツの更新
• ゲーム用の AWS リソースを定義 (p. 280)している AWS CloudFormation テンプレートのプレ
ビューと編集 (p. 216)
トピック
• Lumberyard エディタ の Cloud Canvas ツール (p. 216)
• Cloud Canvas ファイルを編集する (p. 216)
• Cloud Canvas Resource Manager を初期化する (p. 218)
• Cloud Canvas プロファイルの管理 (p. 219)
• リソースのステータスの説明について (p. 220)
• Cloud Canvas コマンドラインの使用 (p. 221)
• Cloud Canvas の進行状況ログを表示 (p. 236)
• デプロイでの作業 (p. 236)
• JSON ファイルでの作業 (p. 245)
• プロジェクトスタックの操作 (p. 246)
• リソースグループの使用 (p. 247)
Version 1.6
215
Lumberyard 開発者ガイド
Lumberyard エディタ の Cloud Canvas ツール
Lumberyard エディタ の Cloud Canvas ツール
Lumberyard エディタ には、ゲームを AWS に簡単に接続できるツールが用意されています。開始す
るには、Lumberyard エディタ ツールバーの [AWS] をクリックします。
AWS メニューには次のオプションがあります。
• Credentials manager – AWS アカウントにアクセスするために必要な認証情報を提供する 1 つ以上
の AWS プロファイルを選択または管理します。詳細については、「Cloud Canvas プロファイルの
管理 (p. 219)」を参照してください。
• GameLift – Amazon GameLift サービスを使用して、セッションベースのマルチプレイヤーゲーム
を初期費用なしで迅速にデプロイします。詳細については、Amazon GameLift を参照してくださ
い。GameLift メニュー自体にも他の情報へのリンクがあります。
• Cloud Canvas – Cloud Canvas メニューには以下のオプションがあります。
• Select a deployment – Lumberyard エディタ で作業するプロジェクトの AWS リソースセットを
指定します。詳細については、「Cloud Canvas デプロイをアクティブにする (p. 239)」を参照
してください。
• Cloud Canvas Resource Manager – Lumberyard プロジェクトの AWS リソースを定義および
管理します。リソースマネージャの概念については、「Cloud Canvas Resource Manager の概
要 (p. 196)」を参照してください。
• Open an AWS Console – メイン AWS マネジメントコンソール、および Amazon
Cognito、DynamoDB、Amazon S3、Lambda のコンソールに迅速にアクセスできるようになりま
す。
これらのリンクは、現在アクティブな AWS プロファイルを使用して AWS に接続します。「Cloud
Canvas プロファイルの管理 (p. 219)」でアクティブにするプロファイルを選択できます。
Cloud Canvas ファイルを編集する
Cloud Canvas Resource Manager ダイアログのナビゲーションペインには、ディスクに保存されてい
るテキストファイルを表す多数のノードが含まれています。resource-template.json (p. 245) ノード
は一例です。
Version 1.6
216
Lumberyard 開発者ガイド
Cloud Canvas ファイルを編集する
テンプレートファイルの子ノードは、それぞれ親ノードのテンプレートファイルの 1 つのセクション
を表します。これらの子ノードは、親ノードのテンプレートファイルのリソース定義セクションを検
索および編集するのに役立ちます。
内部エディタを使用する
ナビゲーションペインでテキストファイルノードを選択すると、ファイルのコンテンツとテキストを
編集するオプションが Cloud Canvas Resource Manager の詳細ペインに表示されます。詳細ペイン
を使用して、ファイルのコンテンツを表示および編集することができます。[Edit]、[Search] メニュー
項目を使用してテキストを検索し、[Previous] および [Next] ボタンを使用して、一致した結果から次
の結果へと移動します。ファイルを変更した後は、ツールバーで [Save] をクリックするか、[File]、
[Save] の順に選択するかして、ファイルを保存することができます。
Note
テンプレートファイルの子ノードで加えられた変更は、常に親ノードのテンプレートファイ
ルに保存されます。
外部エディタを使用する
Cloud Canvas Resource Manager の代わりに、外部スクリプトエディタを使用してファイルを編集す
ることもできます。Lumberyard エディタ でどのエディタを使用するか指定することができます。
外部スクリプトエディタを指定するには
•
Lumberyard エディタ で、[File]、[Global Preferences]、[Editor Settings]、[General Settings]、
[Files]、[External Editors]、[Scripts Editor] の順にクリックします。
外部スクリプトエディタでファイルを開くには
•
ナビゲーションペインでファイルを右クリックし、[Open in script editor] を選択します。
テンプレートファイルのパスをクリップボードにコピーするには、ナビゲーションペインでファイル
を右クリックし、[Copy path to clipboard] を選択します。
コメント
次の点に注意してください。
• スクリプトエディタでテンプレートファイルの子ノードを開くと、フル (親) ファイルが開いて編集
できるようになります。
• Lumberyard では、プロジェクトファイルがソース管理の対象となっている場合、まずファイルを
チェックアウトしなければ、編集することはできません。選択したファイルのソース管理のステー
タスは、ツールバーのソース管理アイコンに動的に表示されます。
Version 1.6
217
Lumberyard 開発者ガイド
Cloud Canvas Resource Manager を初期化する
• ファイルのコンテンツがディスクで変更され、エディタで変更が保存されていない場合、変更され
たコンテンツをディスクからロードして、エディタで変更を保存するように求められます。
Cloud Canvas Resource Manager を初期化する
AWS アカウントが必要なオペレーションを実行するときに、Lumberyard プロジェクトに関連付けら
れたアカウントがない場合は、Initialize Cloud Canvas Resource Manager ダイアログで、必要な情報
を入力するよう求められます。
Cloud Canvas Resource Manager を初期化するには
1.
Cloud Canvas Resource Manager を初期化するよう求められたら、次の情報を入力します。
• [Project stack name] で、これから作成する AWS CloudFormation スタックの名前を入力しま
す。スタックには、Cloud Canvas Resource Manager がプロジェクトに使用する AWS リソー
スが含まれます。Lumberyard では、デフォルトでプロジェクトの名前がスタック名に使用され
ます。選択したリージョンの AWS アカウントにすでにある名前をスタック名に指定すること
はできません。
• [AWS Credentials] で、使用可能なプロファイルのリストから選択するか、または新しくプロ
ファイルを作成します。お使いのコンピュータに AWS プロファイルがない場合は、AWS シー
クレットキーおよび AWS アクセスキーの入力を求められます。既存のプロファイルを編集す
ることもできます。
AWS で Lumberyard を使用するには、AWS アカウント用の管理用認証情報を直接入力する
か、AWS プロファイルに入力しておく必要があります。AWS からこれらの認証情報を取得す
る方法については、「チュートリアル: Cloud Canvas の開始方法」を参照してください。
• [AWS region] で、リソースが存在する AWS データセンターを指定します。ゲームで使用する
AWS サービスをすべてサポートしているリージョンを選択する必要があります。選択したリー
ジョンでは、Lumberyard がプレイヤー ID および AWS CloudFormation を確立するために使用
する Amazon Cognito サービスもサポートされている必要があります。AWS CloudFormation
は Lumberyard がリソースを作成および管理するために使用します。異なるリージョンの機能
の詳細については、「AWS のリージョンとエンドポイント」を参照してください。
2.
初期化プロセスを開始するには、[Create] をクリックします。ナビゲーションツリーでは プロ
ジェクトスタックの操作 (p. 246) ノードが選択され、詳細ペインではCloud Canvas の進行状
況ログを表示 (p. 236)に初期化の進行状況が表示されます。
Version 1.6
218
Lumberyard 開発者ガイド
Cloud Canvas プロファイルの管理
Cloud Canvas プロファイルの管理
Lumberyard エディタ の Credentials Manager またはコマンドラインを使用して、AWS アカウントへ
のアクセスに必要な認証情報を提供する 1 つ以上の AWS プロファイルを管理します。
プロファイルは、ローカルマシン上の AWS 認証情報ファイルに保存されます。このファイルは通
常、C:\Users\<user name>\.aws\ ディレクトリに配置されます。AWS Command Line Interface
および AWS Toolkit for Visual Studio でこれらの認証情報にアクセスできます。
Important
これらの認証情報を他者と共有しないでください。また、ソース管理にチェックインしない
でください。これらの情報により、AWS アカウント内のほぼすべてのアクセス権限を持つこ
とができため、悪意のあるユーザーにより料金が発生する可能性があります。
詳細については、「AWS セキュリティの認証情報」を参照してください。
Credentials Manager を開くには
•
Credentials Manager を開くには、次のいずれかを実行します。
• Lumberyard エディタ で、[AWS]、[Credentials manager] の順にクリックします。
• Cloud Canvas Resource Manager で、リソースマネージャーのツールバーから現在のプロファ
イルの名前をクリックします。
Credentials Manager を使用して既存の AWS プロファイルを選択、AWS プロファイルを編集、また
は新規 AWS プロファイルを追加できます。
既存の AWS プロファイルを編集するには、[Edited selected profile] をクリックします。AWS プロ
ファイルを追加するには、[Add profile] をクリックします。
Version 1.6
219
Lumberyard 開発者ガイド
リソースのステータスの説明について
プロファイルを追加または編集する場合は、次の項目を入力するよう求められます。
Profile name – プロファイルに使用する名前。
AWS Secret Key – アカウントにアクセスするために必要な AWS シークレットキー。
AWS Access Key – アカウントにアクセスするために必要な AWS アクセスキー。
コマンドラインを使用して認証情報を追加するには
1.
コマンドラインのウィンドウを開き、Lumberyard のルートディレクトリに移動します。ルート
ディレクトリは、Lumberyard のインストールディレクトリの dev サブディレクトリ (たとえば
C:\lumberyard\dev) です。
2.
以下のコマンドプロンプトを入力して、[Enter] をクリックします。<profile-name> を任意の
名前（例えば、 CloudCanvasAdminProfile）に変更します。<secret-key> と <accesskey> を AWS アカウントのシークレットキーとアクセスキーで置き換えます。
lmbr_aws add-profile --profile <profile-name> --make-default --aws-secretkey <secret-key> --aws-access-key <access-key>
--make-default オプションが、Cloud Canvas 用のデフォルトプロファイルとしてプロファ
イルを構築します。このデフォルトのプロファイルによって、Lumberyard エディタ を使用した
り、lmbr_aws command を実行する度にプロファイルを指定する必要がなくなります。
リソースのステータスの説明について
AWS リソースのステータスは、Cloud Canvas Resource Manager で進行状況ログなどに表示されま
す。次のリストでは、リソースのよく使用されるステータスコードについて説明します。リソースマ
ネージャーでステータステキストにマウスポインタを置くと、現在のステータスの理由を確認できま
す。
Create pending – リソースはローカル設定で定義されていますが、AWS には存在していません。
Create in progress – リソースは AWS で作成中です。
Create complete – リソースは AWS で作成が正常に完了しています。
Create failed – リソースは AWS で作成できませんでした。
Update in progress – リソースは AWS で更新中です。
Update complete – リソースは AWS で正常に更新されました。
Update failed – リソースは AWS で更新できませんでした。
Delete pending – リソースはローカル設定では定義されていませんが、AWS に存在しています。
Delete in progress – リソースは AWS で削除中です。
Delete complete – リソースは AWS で削除済みです。
Rollback in progress – 操作が失敗し、AWS CloudFormation がリソースの以前の状態への復元を試行
中です。
Rollback failed – ロールバックが失敗しました。CloudFormation スタックの AWS リソースがこのス
テータスである場合は、不整合な状態になっています。そのスタックを削除して再作成する必要があ
る可能性があります。
Version 1.6
220
Lumberyard 開発者ガイド
Cloud Canvas コマンドラインの使用
Cloud Canvas コマンドラインの使用
Cloud Canvas には AWS リソースを操作するための \dev\lmbr_aws.cmd コマンドラインツールが
あります。このツールは \dev\Tools\lmbr_aws ディレクトリにある Python コードを起動します。
構文
lmbr_aws {command} {command-arguments}
{command} は、以下の「コマンドの概要」セクションに挙げられているコマンドのいずれかで
す。{command-arguments} はコマンドによって受け入れられる引数です。ほとんどのコマンドに共
通する引数は、「共通の引数 (p. 221)」セクションに一覧しています。コマンド独自の引数は、その
コマンドの詳細のセクションに記載しています。
設定
ツールは AWS のデフォルト設定を AWS コマンドラインツールと同じ ~/.aws/credentials と
~/.aws/config ファイルから取得します (詳細については、AWS Command Line Interface の設定を
参照してください)。lmbr_aws ツールを使用する際に、AWS コマンドラインインターフェイスがイ
ンストールされている必要はありません。
Environment Variables
AWS コマンドラインツールと同様に、AWS のデフォルト設定は以下の環境変数を使用してオーバー
ライドできます。
• AWS_ACCESS_KEY_ID AWS アカウントのアクセスキー。
• AWS_SECRET_ACCESS_KEY AWS アカウントのシークレットキー。
• AWS_DEFAULT_REGION 使用するデフォルトのリージョン。たとえば、us-east-1。
• AWS_PROFILE 使用するデフォルトの認証情報と設定プロファイル (存在する場合)。
設定引数
次の引数は、他のあらゆるソースから AWS 設定を上書きするために使用できます。
• --profile {profile} 使用する AWS コマンドラインツールのプロファイル。
• --aws-access-key {access-key} 使用する AWS のAWSアクセスキー。
• --aws-secret-key {secret-key} 使用する AWS のシークレットキー。
共通の引数
lmbr_aws コマンドのほとんどは、独自の引数のほかに次の引数を受け入れます。
• -h または --help – コマンドのヘルプを表示します。
• --root-directory {root} – Lumberyard\dev ディレクトリを指定します。デフォルトは現在の
作業ディレクトリです。
• --aws-directory {aws} – 使用する {game}\AWS ディレクトリを指定します。デフォルトは
{root}\bootstrap.cfg から取得した sys_game_folder プロパティの値に AWS を追加したも
のです。
• --game-directory {directory} – ゲームプロジェクトディレクトリの場所。デフォ
ルトは {root}\{game} です。ここで {game} は {root}\bootstrap.cfg ファイルの
sys_game_folder 設定によって決まります。
Version 1.6
221
Lumberyard 開発者ガイド
Cloud Canvas コマンドラインの使用
• --user-directory {user} – ユーザーのキャッシュディレクトリの場所。デフォルトは
{root}\Cache\{game}\AWS です。ここで {game} は {root}\bootstrap.cfg ファイルの
sys_game_folder の設定によって決まります。
• --verbose – コマンドの実行時に追加の出力を表示します。
コマンドの概要
このトピックでは、以下のコマンドについて説明します。
• add-login-provider (p. 223) – プレイヤのログインプロバイダーを Amazon Cognito の ID プールの
設定に追加します。
• add-profile (p. 223)– AWS のプロファイルを AWS コマンドラインツールの設定に追加します。
• add-resource-group (p. 224) – 関連リソースのグループをプロジェクトに追加します。
• create-deployment (p. 224) – プロジェクトのリソースの独立コピーを作成します。
• create-project-stack (p. 225) – Lumberyard プロジェクトで必要な AWS リソースを作成しま
す。{game}\AWS ディレクトリにリソース定義がない場合は、デフォルトのリソース定義が作成さ
れます。
• default-deployment (p. 226) – デフォルトのデプロイを表示または設定します。
• default-profile (p. 226)– AWS コマンドラインツールの設定からデフォルトのプロファイルを設
定、クリア、または表示します。
• delete-deployment (p. 226) – プロジェクトのリソースの独立コピーを削除します。
delete-project-stack (p. 227) – プロジェクトスタックを削除します。このコマンドでは、デプロイ
があるプロジェクトは削除されません。
• import-resource (p. 227) – リソースをリソースグループにインポートします。
• list-deployments (p. 228)– ローカルプロジェクトのすべてのデプロイメントを一覧表示します。
• list-importable-resources (p. 228) – 現在 AWS に存在する、サポートされているすべてのリソース
のリストを取得します。
• list-mappings (p. 229)– 論理的リソースと物理的リソースの名前のマッピングを表示します。
• list-profiles (p. 229)– 設定されている AWS プロファイルを一覧表示します。
• list-resource-groups (p. 229) – プロジェクトのリソースグループのリストを取得します。
• list-resources (p. 229)– プロジェクトと関連付けられているリソースをすべて表示します。
• protect-deployment (p. 231) – デプロイを保護済みとしてマークします。
• remove-login-provider (p. 232) – プレイヤーのアクセステンプレートからログインプロバイダーを
削除します。
• remove-profile (p. 232)– AWS のプロファイルを AWS コマンドラインツールの設定から削除しま
す。
• remove-resource-group (p. 232) – プロジェクトからリソースグループを削除します。
• rename-profile (p. 232)– AWS コマンドラインツールの設定にある AWS のプロファイルの名前を
変更します。
• update-login-provider (p. 233) – アプリケーションを Amazon Cognito に接続できるように、プレ
イヤーのアクセステンプレートで既存のログインプロバイダーを更新します。
• update-mappings (p. 234) – 現在のデフォルトのデプロイを反映するように、論理リソース名から
物理リソース名へのマッピングを更新します。
• update-profile (p. 234)– AWS のプロファイルを更新します。
• update-project-stack (p. 235) – Lumberyard プロジェクトで使用されている AWS リソースを更新
します。
• upload-resources (p. 235) – ローカルの resource-template.json ファイルに加えられた変更
内容をアップロードして適用します。
Version 1.6
222
Lumberyard 開発者ガイド
Cloud Canvas コマンドラインの使用
コマンド
以下は、lmbr_aws コマンドの詳細です。
add-login-provider
プレイヤのログインプロバイダーを Amazon Cognito ID プールの設定に追加します。ログインプロバ
イダーは、ゲームのプレイヤを Facebook のようなソーシャルネットワークの ID や Amazon のユー
ザー ID を使用してログインさせることができます。詳細については、「アクセスコントロールとプレ
イヤ ID (p. 310)」を参照してください。
共通の引数 (p. 221) のほかに、add-login-provider サブコマンドは次の引数を受け入れます。
• --provider {provider-name}
必須プロバイダーの名前。この名前は amazon、google、または facebook であるか、一般的な
OpenID プロバイダーを使用している場合は選択した名前である必要があります。
• --app-id {application-id}
必須ログインプロバイダーからのアプリケーション ID (通常、これはクライアント ID とは別のもの
です)。
• --client-id {client-id}
必須ログイン プロバイダーに対する一意のアプリケーションクライアント ID。
• --client-secret {client-secret}
必須ログインプロバイダーで使用するシークレットキー。
• --redirect-uri {redirect-uri}
必須ログインプロバイダーで使用するリダイレクト URI。
• --provider-uri {provider-uri}
オプション。汎用的な OpenID Connect プロバイダーの URI。これは汎用的な OpenID プロバイ
ダーの場合にのみ使用します。
• --provider-port {provider-port}
オプション。プロバイダーが API のためにリッスンするポート。これは汎用的な OpenID プロバイ
ダーの場合にのみ使用します。
• --provider-path {provider-path}
オプション。プロバイダーの URI のパス部分。これは汎用的な OpenID プロバイダーの場合にのみ
使用します。
このコマンドによって設定がプロジェクトの設定バケット内にある /
player-access/auth-settings.json オブジェクトに保存されるた
め、ProjectPlayerAccessTokenExchangeHandler Lambda 関数からアクセスできるようにな
ります。
Note
このコマンドの実行後に lmbr_aws update-project-stack を実行
し、PlayerAccessIdentityPool リソース (p. 298) の設定を更新して変更を反映させる必要
があります。
add-profile
AWS プロファイルを AWS コマンドラインツールの設定に追加します。
Version 1.6
223
Lumberyard 開発者ガイド
Cloud Canvas コマンドラインの使用
共通の引数 (p. 221) のほかに、add-profile サブコマンドは次の引数を受け入れます。
• --aws-access-key{accesskey}
必須追加したプロファイルに関連付ける AWS アクセスキー。
• --aws-secret-key{secretkey}
必須追加したプロファイルに関連付ける AWS シークレットキー。
• --profile {profilename}
必須追加する AWS プロファイルの名前。
• --make-default
オプション。新しいプロファイルをデフォルトプロファイルにします。
add-resource-group
ResourceGroupConfiguration および AWS CloudFormation スタックリソースを deploymenttemplate.json ファイルに追加します。追加されたリソースは、サンプルの deploymenttemplate.json (p. 289) ファイルの HelloWorldConfiguration リソース (p. 291) および HelloWorld リ
ソース (p. 291) と同様になります。
このコマンドでは、{game}\resource-group\{resource-group-name} ディレクトリも作成され、そ
こには、デフォルトの resource-template.json ファイルと lambda-function-code サブディ
レクトリが置かれます。
共通の引数 (p. 221) のほかに、add-resource-group サブコマンドは次の引数を受け入れます。
• --resource-group {resource-group-name}
必須追加するリソースグループの名前。
• --include-example-resources
オプション。サンプルリソースの「Hello World」を含めます。
create-deployment
Lumberyard プロジェクトで必要なすべてのリソースの完全で独立したコピーを作成します。
共通の引数 (p. 221) のほかに、create-deployment サブコマンドは次の引数を受け入れます。
• --deployment {deployment-name}
必須作成するデプロイメントの名前。
• --enable-capability{capability}
オプション。AWS CloudFormation で特定のスタックを作成または更新する前に指定する必要があ
る機能の一覧。一部のスタックテンプレートには、AWS アカウントのアクセス許可に影響するリ
ソースが含まれる場合があります。このようなスタックの場合は、このパラメータを指定して、そ
れらの機能を明示的に認識する必要があります。指定できる値には、CAPABILITY_IAM などがあり
ます。
• --confirm-aws-usage
オプション。create-deployment コマンドによって、課金される可能性があり、また AWS アカ
ウントのアクセス許可に影響するアクションを実行する可能性がある AWS リソースが作成される
ことを理解済みであることを表します。指定しない場合は、確認が求められます。
Version 1.6
224
Lumberyard 開発者ガイド
Cloud Canvas コマンドラインの使用
create-project-stack
Lumberyard プロジェクトのための Cloud Canvas リソース管理を初期化します。これに
は、{root}\{game}\AWS ディレクトリでのデフォルトの リソースの定義 (p. 280) の作成
と、Cloud Canvas リソースマネージャーがゲームリソースを管理するために使用するリソースが含ま
れる AWS CloudFormation スタックの作成が含まれます。
共通の引数 (p. 221) のほかに、create-project-stack サブコマンドは次の引数を受け入れま
す。
• --stack {stack-name}
オプション。プロジェクトの AWS CloudFormation スタックに使用する名前。デフォルトは
{game} ディレクトリの名前です。
• --confirm-aws-usage
オプション。このコマンドによって、課金される可能性があり、また AWS アカウントのアクセス
許可に影響するアクションを実行する可能性がある AWS リソースが作成されることを理解済みで
あることを表します。またこのコマンドの実行時に確認プロンプトが表示されないようにします。
• --enable-capability {capability} [{capability} ...]
オプション。AWS CloudFormation で特定のスタックを作成または更新する前に指定する必要があ
る機能の一覧。一部のスタックテンプレートには、AWS アカウントのアクセス許可に影響するリ
ソースが含まれる場合があります。このようなスタックの場合は、このパラメータを指定して、そ
れらの機能を明示的に認識する必要があります。指定できる値には、CAPABILITY_IAM などがあり
ます。
• --files-only
オプション。{game}\AWS ディレクトリにデフォルト設定データを書き込み、終了します。この
ディレクトリは空であるか、存在していない必要があります。
• --region {region}
必須プロジェクトスタックが作成される AWS リージョン。
Note
region オプションを使用できるのは、create-project-stack コマンドと listimportable-resources コマンドだけです。
create-project-stack の仕組み
1. create-project-stack コマンドは、設定バケット (p. 303) リソースだけを定義するブートス
トラップテンプレートを使用して、プロジェクトの AWS CloudFormation スタックを作成します。
2. project-template.json (p. 284) ファイルと project-code サブディレクトリ (p. 298)の内容が zip
圧縮されたものが、設定バケット (p. 303)にアップロードされます。
3. AWS CloudFormation スタックの更新処理は、アップロードされた project-template.json
ファイルを使用して実行されます。project-code .zip ファイルは、project-template.json
ファイルで定義されている Lambda 関数リソースを作成するために使用されます。
Note
• {root}\{game}\AWS ディレクトリが空であるか、または存在しない場合は、必要に応じ
て create-project-stack によってこのディレクトリが作成され、このディレクトリに
{root}\Tools\lmbr_aws\AWSResourceManager\default-project-content ディレ
クトリの内容がコピーされます。
Version 1.6
225
Lumberyard 開発者ガイド
Cloud Canvas コマンドラインの使用
• 構成した AWS アカウントとリージョンに、指定した名前のスタックがすでに存在する場合
は、create-project-stack の処理は失敗します。この場合は、--stack オプションを
使用して、プロジェクトスタックに別の名前を指定することができます。
• {root}\{game}\AWS\project-settings.json ファイルに空でない ProjectStackId
プロパティが含まれている場合、create-project-stack の処理は失敗します。ステッ
プ 1 でプロジェクトスタックが作成された後、ProjectStackId プロパティがプロジェク
トの AWS CloudFormation スタック ID に設定されます。
• ステップ 2 のスタックの更新処理が最初の試みで失敗した場合は、update-projectstack コマンドを使用して再試行できます。
default-deployment
デフォルトデプロイメントを設定または表示します。
共通の引数 (p. 221) のほかに、default-deployment サブコマンドは次の引数を受け入れます。
• --set {deployment}
オプション。指定したデプロイメントの名前にデフォルトを設定します。
• --clear
オプション。デフォルトをクリアします。
• --show
オプション。デフォルトを表示します。
• --project
オプション。--set および --clear をユーザーのデフォルトではなくプロジェクトのデフォルト
に適用します。--show の場合は無視されます。
使用できる引数は、--set、--clear、--show のうちの 1 つだけです。
--set または --clear を指定すると、{root}\user\AWS\user-settings.json ファイルが更
新されます。--project を指定すると、{root}\{game}\AWS\project-settings.json ファ
イルが更新されます。
default-profile
AWS コマンドラインツール設定のデフォルトプロファイルを設定、クリア、または表示します。
共通の引数 (p. 221) のほかに、default-profile サブコマンドは次の引数を受け入れます。
• --set {deploymentname}
オプション。指定したデプロイメント名にデフォルトのプロファイルを設定します。
• --clear
オプション。デフォルトのプロファイルをクリアします。
• --show
オプション。デフォルトのプロファイルを表示します。
delete-deployment
Lumberyard プロジェクトで必要なすべてのリソースの完全で独立したコピーを削除します。
共通の引数 (p. 221) のほかに、delete-deployment サブコマンドは次の引数を受け入れます。
Version 1.6
226
Lumberyard 開発者ガイド
Cloud Canvas コマンドラインの使用
• --deployment {deployment-name}
必須削除するデプロイメントの名前。
• --enable-capability{capability}
オプション。AWS CloudFormation で特定のスタックを作成または更新する前に指定する必要があ
る機能の一覧。一部のスタックテンプレートには、AWS アカウントのアクセス許可に影響するリ
ソースが含まれる場合があります。このようなスタックの場合は、このパラメータを指定して、そ
れらの機能を明示的に認識する必要があります。指定できる値には、CAPABILITY_IAM などがあり
ます。
• --confirm-resource-deletion
オプション。このコマンドによって、指定デプロイに属するリソースが完全に削除されることを了
承します。これを指定しないと、削除の確認が求められます。
Note
AWS CloudFormation では、データを含む Amazon S3 バケットを定義するスタックは削除で
きません。プロジェクトスタックを削除できるようにするには、project-template.json
ファイルで設定バケットに対して Retain の DeletionPolicy を指定します。この指定に
よって、プロジェクトスタックを削除するときに AWS CloudFormation によってこのバケッ
トが削除されなくなります。プロジェクトのスタックを削除した後、このコマンドは設定バ
ケットに含まれるオブジェクトをすべて削除し、さらにそのバケットを削除します。
delete-project-stack
プロジェクトのリソースが含まれる AWS CloudFormation スタックを削除します。プロジェクトス
タックを削除する前に、そのプロジェクトのデプロイをすべて削除する必要があります。プロジェク
トスタックを削除した後は、新しいプロジェクトスタックを作成して、プロジェクトに対して AWS
CloudFormation リソースマネージャーを使用できるようにする必要があります。
共通の引数 (p. 221) のほかに、delete-project-stack サブコマンドは次の引数を受け入れま
す。
• --confirm-resource-deletion
オプション。このコマンドによって、ゲームの AWS リソースを管理する AWS CloudFormation リ
ソースマネージャーが使用している AWS リソースがすべて削除されることをユーザーに確認しま
す。またこのコマンドを実行する際のデフォルトの確認プロンプトを無効にします。
AWS CloudFormation では、データを含む Amazon S3 バケットを定義するスタックは削除できま
せん。プロジェクトスタックを削除できるようにするには、project-template.json ファイルで
設定バケットに対して Retain の DeletionPolicy を指定します。この指定によって、プロジェ
クトスタックを削除するときに AWS CloudFormation によってこのバケットが削除されなくなりま
す。プロジェクトのスタックを削除した後、このコマンドは設定バケットに含まれるオブジェクト
をすべて削除し、さらにそのバケットを削除します。
import-resource
リソースをリソースグループにインポートします。
共通の引数 (p. 221) のほかに、import-resource サブコマンドは次の引数を受け入れます。
• --type {dynamodb|s3|lambda|sns|sqs}
オプション。インポートする AWS リソースのタイプ。dynamodb、s3、lambda、sns または sqs
から選択します。
Version 1.6
227
Lumberyard 開発者ガイド
Cloud Canvas コマンドラインの使用
• --arn ARN
必須インポートする AWS リソースの ARN。
• --resource-name {resource-name}
必須インポートするリソースの名前。
• --resource-group {resource-group}
必須インポートするリソースグループの名前。
• --download
オプション。指定した場合、Amazon S3 バケットのコンテンツがダウンロードされます。
list-deployments
ローカルプロジェクトのすべてのデプロイメントを一覧表示します。
出力例:
Name
Status
Reason
Timestamp
Id
----------------- ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------AnotherDeployment CREATE_PENDING
Resource is defined in the local project
template but does not exist in AWS.
Development
CREATE_COMPLETE
03/04/16 18:43:11
arn:aws:cloudformation:us-east-1:<ACCOUNTID>:stack/foo-hw-DevelopmentZDLXUB7FKR94/8e6492f0-e248-11e5-8e7e-50d5ca6e60ae
User Default Deployment:
(none)
Project Default Deployment: Development
Release Deployment:
(none)
list-importable-resources
現在 AWS に存在する、サポートされているすべてのリソースのリストを取得します。
共通の引数 (p. 221) のほかに、list-importable-resources サブコマンドは次の引数を受け入
れます。
• --type {dynamodb|s3|lambda|sns|sqs}
必須リストを取得する AWS リソースのタイプ。dynamodb、s3、lambda、sns または sqs から選
択します。
• --region {region}
オプション。リソースの AWS リージョン。デフォルト値はプロジェクトスタックのリージョンで
す (存在する場合)。
Note
region オプションを使用できるのは、list-importable-resources コマンドと
create-project-stack コマンドだけです。
Version 1.6
228
Lumberyard 開発者ガイド
Cloud Canvas コマンドラインの使用
list-mappings
論理的リソースと物理的リソースの名前のマッピングを表示します。
出力例:
Name
Type
--------------------------------------- -----------------------------------------------------------------------------------------HelloWorld.SayHello
AWS::Lambda::Function
Development-ZDLXUB7FKR94-HelloWo-SayHello-1FADMFNE5M1CO
PlayerAccessIdentityPool
Custom::CognitoIdentityPool
east-1:108f6d6a-f929-4212-9947-a03269b9582e
PlayerLoginIdentityPool
Custom::CognitoIdentityPool
east-1:3020e175-0ddd-4860-8dad-1db57162cbb2
ProjectPlayerAccessTokenExchangeHandler AWS::Lambda::Function
ProjectPlayerAccessTokenExchangeHandler-1BG6JJ94IZAUV
account_id
Configuration
<ACCOUNTID>
region
Configuration
east-1
Id
foo-hwususfoo-hw-
us-
list-profiles
設定されている AWS プロファイルを一覧表示します。
list-resource-groups
ローカルのデプロイテンプレートと選択した AWS のデプロイで見つかった、すべてのリソースグ
ループのリストを取得します。
共通の引数 (p. 221) のほかに、list-resource-groups サブコマンドは次の引数を受け入れま
す。
• --deployment {deployment-name}
オプション。リソースグループのリスト取得するデプロイの名前。指定しない場合は、デフォルト
デプロイメントが使用されます。
出力例:
Name
Status
Reason
Timestamp
Id
-------------- ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------AnotherResourceGroup CREATE_PENDING
Resource is defined in the local
deployment template but does not exist in AWS.
HelloWorld
CREATE_COMPLETE
03/04/16 18:42:57
arn:aws:cloudformation:us-east-1:<ACCOUNTID>:stack/foo-hw-DevelopmentZDLXUB7FKR94-HelloWorld-WSGZ15EUWX52/9b909d20-e238-11e5-a98d-50fae987c09a
list-resources
プロジェクトに関連付けられているすべてのリソースを表示します。
Version 1.6
229
Lumberyard 開発者ガイド
Cloud Canvas コマンドラインの使用
共通の引数 (p. 221) のほかに、list-resources サブコマンドは次の引数を受け入れます。
• --stack-id {stackid}
オプション。リソースを一覧表示するスタックの ARN。デフォルトは、--deployment パラメー
ターと --resource-group パラメーターによって決まるプロジェクト、デプロイ、またはリソー
スグループの ID です。
• --deployment {deployment-name}
オプション。リソースを一覧表示するデプロイメントの名前。指定しなかった場合は、プロジェク
トのリソースがすべて一覧表示されます。
• --resource-group {resource-group-name}
オプション。リソースのリストを取得するリソースグループの名前。指定する場合
は、deployment も指定する必要があります。指定しない場合は、すべてのデプロイメントまたは
プロジェクトのリソースが一覧表示されます。
出力例:
Name
Type
Status
Timestamp
Id
-------------------------------------------------------------------------- --------------- ----------------------------------------------------------------------------------------------------------Configuration
AWS::S3::Bucket
CREATE_COMPLETE 03/04/16 18:38:25 foo-hw-configuration-vxaq1g44s0ef
Development
AWS::CloudFormation::Stack
CREATE_COMPLETE 03/04/16 18:43:11 arn:aws:cloudformation:useast-1:<ACCOUNTID>:stack/foo-hw-Development-ZDLXUB7FKR94/8e6492f0e238-11e5-8e7e-50d5ca6e60ae
Development.HelloWorld
AWS::CloudFormation::Stack
CREATE_COMPLETE 03/04/16 18:42:57 arn:aws:cloudformation:useast-1:<ACCOUNTID>:stack/foo-hw-Development-ZDLXUB7FKR94-HelloWorldWSGZ15EUWX52/9b909d20-e238-11e5-a98d-50fae987c09a
Development.HelloWorld.Messages
AWS::DynamoDB::Table
CREATE_COMPLETE 03/04/16 18:41:24 foo-hw-Development-ZDLXUB7FKR94HelloWorld-WSGZ15EUWX52-Messages-W8398CX6EB7C
Development.HelloWorld.PlayerAccess
Custom::PlayerAccess
CREATE_COMPLETE 03/04/16 18:42:54 CloudCanvas:PlayerAccess:foo-hwDevelopment-ZDLXUB7FKR94-HelloWorld-WSGZ15EUWX52
Development.HelloWorld.SayHello
AWS::Lambda::Function
CREATE_COMPLETE 03/04/16 18:42:45 foo-hw-Development-ZDLXUB7FKR94HelloWo-SayHello-1FADMFNE5M1CO
Development.HelloWorld.SayHelloConfiguration Custom::LambdaConfiguration
CREATE_COMPLETE 03/04/16 18:42:39 CloudCanvas:LambdaConfiguration:foo-hwDevelopment-ZDLXUB7FKR94-HelloWorld-WSGZ15EUWX52:SayHello:6e3be3f1-933b-47b7b3f6-21a045cbdda7
Development.HelloWorldConfiguration
Custom::ResourceGroupConfiguration
CREATE_COMPLETE 03/04/16 18:40:39
CloudCanvas:LambdaConfiguration:foo-hw-Development-ZDLXUB7FKR94:HelloWorld
DevelopmentAccess
AWS::CloudFormation::Stack
CREATE_COMPLETE 03/04/16 18:44:58 arn:aws:cloudformation:useast-1:<ACCOUNTID>:stack/foo-hw-DevelopmentAccess-14RNG9550IZMJ/f56ff7f0e238-11e5-a77e-50d5cd148236
DevelopmentAccess.Owner
AWS::IAM::Role
CREATE_COMPLETE 03/04/16 18:44:38 foo-hw-DevelopmentAccess-14RNG9550IZMJOwner-1H1MHLAZOKELJ
Version 1.6
230
Lumberyard 開発者ガイド
Cloud Canvas コマンドラインの使用
DevelopmentAccess.OwnerPolicy
AWS::IAM::ManagedPolicy
CREATE_COMPLETE 03/04/16 18:43:23 arn:aws:iam::<ACCOUNTID>:policy/foo-hw/
Development/foo-hw-DevelopmentAccess-14RNG9550IZMJ-OwnerPolicy-1CE1PRKWZCVRW
DevelopmentAccess.Player
AWS::IAM::Role
CREATE_COMPLETE 03/04/16 18:44:33 foo-hw-DevelopmentAccess-14RNG9550IZMJPlayer-1JXYH5PPO434S
DevelopmentAccess.PlayerAccess
Custom::PlayerAccess
CREATE_COMPLETE 03/04/16 18:44:49 CloudCanvas:PlayerAccess:foo-hwDevelopmentAccess-14RNG9550IZMJ
DevelopmentAccess.PlayerAccessIdentityPool
Custom::CognitoIdentityPool
CREATE_COMPLETE 03/04/16 18:44:41 us-east-1:108f6d6a-f928-4212-9947a03269b9582e
DevelopmentAccess.PlayerLoginIdentityPool
Custom::CognitoIdentityPool
CREATE_COMPLETE 03/04/16 18:44:43 useast-1:3020e175-0ded-4860-8dad-1db57162cbb2
DevelopmentAccess.PlayerLoginRole
AWS::IAM::Role
CREATE_COMPLETE 03/04/16 18:44:33 foo-hw-DevelopmentAccess-14RNG95PlayerLoginRole-70M854BKMJBL
DevelopmentConfiguration
Custom::DeploymentConfiguration CREATE_COMPLETE 03/04/16 18:40:17
CloudCanvas:DeploymentConfiguration:foo-hw:Development
ProjectPlayerAccessTokenExchangeHandler
AWS::Lambda::Function
CREATE_COMPLETE 03/04/16 18:40:39 foo-hwProjectPlayerAccessTokenExchangeHandler-1BG6JJ84IZAUV
ProjectPlayerAccessTokenExchangeHandlerRole
AWS::IAM::Role
CREATE_COMPLETE 03/04/16 18:40:33 foo-hwProjectPlayerAccessTokenExchangeHandlerRo-T0E7MYI0B67N
ProjectResourceHandler
AWS::Lambda::Function
CREATE_COMPLETE 03/04/16 18:40:08 foo-hw-ProjectResourceHandlerXAP5CBAMQCYP
ProjectResourceHandlerExecution
AWS::IAM::Role
CREATE_COMPLETE 03/04/16 18:40:02 foo-hw-ProjectResourceHandlerExecutionK24FL427PVZM
protect-deployment
デプロイを保護済みとしてマークし、ユーザー (開発者やテスターなど) が開発ゲームクライアントを
ライブリソースに接続しようとすると、警告を表示します。詳細については、「保護済みのデプロイ
の使用 (p. 243)」を参照してください。
共通の引数 (p. 221) のほかに、protect-deployment サブコマンドは次の引数を受け入れます。
• --set {deployment-name}
オプション。デプロイが保護済みであることを指定します。
• --clear {deployment-name}
オプション。デプロイが非保護であることを指定します。
• --show
オプション。現在非保護のデプロイのリストを表示します。
Note
デプロイの保護ステータスを表示するために、「 list-deployments (p. 228)」または「 listmappings (p. 229)」のコマンドを使用することもできます。
Version 1.6
231
Lumberyard 開発者ガイド
Cloud Canvas コマンドラインの使用
remove-login-provider
プレイヤのログインプロバイダーを Amazon Cognito ID プールの設定から削除します。
共通の引数 (p. 221) のほかに、remove-login-provider サブコマンドは次の引数を受け入れま
す。
• --provider {provider-name}
必須プロバイダーの名前。
remove-login-provider コマンドによって設定がプロジェクトの設定バケット
内にある /player-access/auth-settings.json オブジェクトに保存されるた
め、ProjectPlayerAccessTokenExchangeHandler Lambda 関数からアクセスできるようにな
ります。
Note
このコマンドの実行後に lmbr_aws update-project-stack を実行
し、PlayerAccessIdentityPool リソース (p. 298) の設定を更新して変更を反映させる必要
があります。
remove-profile
AWS プロファイルを AWS コマンドラインツールの設定から削除します。
共通の引数 (p. 221) のほかに、remove-profile サブコマンドは次の引数を受け入れます。
• --profile {profile-name}
必須削除する AWS プロファイルの名前。
remove-resource-group
リソースグループの ResourceGroupConfiguration と AWS CloudFormation スタックリソースを
deployment-template.json ファイルから削除します。リソースグループで定義されているリソー
スを AWS から削除する前に、デプロイスタックを更新する必要があります。
このコマンドでは、{game}\resource-group\{resource-group-name} ディレクトリは削除されませ
ん。
共通の引数 (p. 221) のほかに、remove-resource-group サブコマンドは次の引数を受け入れま
す。
• --resource-group {resource-group-name}
必須削除するリソースグループの名前。
AWS CloudFormation では、データを含む Amazon S3 バケットを定義するスタックは削除できませ
ん。プロジェクトスタックを削除できるようにするには、project-template.json ファイルで設定
バケットに対して Retain の DeletionPolicy を指定します。この指定によって、プロジェクトス
タックを削除するときに AWS CloudFormation によってこのバケットが削除されなくなります。プロ
ジェクトのスタックを削除した後、このコマンドは設定バケットに含まれるオブジェクトをすべて削
除し、さらにそのバケットを削除します。
rename-profile
AWS コマンドラインツールの設定にある AWS プロファイルの名前を変更します。
Version 1.6
232
Lumberyard 開発者ガイド
Cloud Canvas コマンドラインの使用
共通の引数 (p. 221) のほかに、rename-profile サブコマンドは次の引数を受け入れます。
• --old {old-profile-name}
必須変更する AWS プロファイルの名前。
• --new {new-profile-name}
必須AWS プロファイルの新しい名前。
update-login-provider
Amazon Cognito ID プールの設定にあるプレイヤのログインプロバイダーを更新します。ログインプ
ロバイダーは、ゲームのプレイヤを Facebook のようなソーシャルネットワークの ID や Amazon の
ユーザー ID を使用してログインさせることができます。詳細については、「アクセスコントロールと
プレイヤ ID (p. 310)」を参照してください。
共通の引数 (p. 221) のほかに、update-login-provider サブコマンドは次の引数を受け入れま
す。
• --provider {provider-name}
必須更新されたプロバイダーの名前。この名前は amazon、google、または facebook であるか、
汎用的な OpenID プロバイダーを使用している場合は、プロバイダーを追加したときに選択した名
前である必要があります。
• --app-id {application-id}
オプション。ログインプロバイダーからのアプリケーション ID (通常、これはクライアント ID とは
別のものです)。
• --client-id {client-id}
オプション。ログイン プロバイダーに対する一意のアプリケーションクライアント ID。
• --client-secret {client-secret}
オプション。ログインプロバイダーで使用するシークレットキー。
• --redirect-uri {redirect-uri}
オプション。ログインプロバイダーで使用するリダイレクト URI。
• --provider-uri {provider-uri}
オプション。汎用的な OpenID Connect プロバイダーの URI。これは汎用的な OpenID プロバイ
ダーの場合にのみ使用する引数です。
• --provider-port {provider-port}
オプション。プロバイダーがプロバイダーの API のためにリッスンするポート。これは汎用的な
OpenID プロバイダーの場合にのみ使用する引数です。
• --provider-path {provider-path}
オプション。プロバイダーの URI のパス部分。これは汎用的な OpenID プロバイダーの場合にのみ
使用する引数です。
update-login-provider コマンドによって設定がプロジェクトの設定バケット
内にある /player-access/auth-settings.json オブジェクトに保存されるた
め、ProjectPlayerAccessTokenExchangeHandler Lambda 関数からアクセスできるようにな
ります。
Version 1.6
233
Lumberyard 開発者ガイド
Cloud Canvas コマンドラインの使用
Note
このコマンドの実行後に lmbr_aws update-project-stack を実行
し、PlayerAccessIdentityPool リソース (p. 298) の設定を更新して変更を反映させる必要
があります。
update-mappings
物理的リソース ID のマッピングの分かりやすい名前を更新して、現在のデフォルトデプロイメントま
たはリリースデプロイメントを反映します。
共通の引数 (p. 221) のほかに、update-mappings サブコマンドは次の引数を受け入れます。
• --release
オプション。リリースマッピングが更新されるようにします。デフォルトでは、ゲームをエディタ
内から起動する際に使用するマッピングだけが更新されます。
このコマンドは、resource-template.json (p. 298) ファイル内でリソース定義に関する
Metadata.CloudCanvas.PlayerAccess プロパティを探し出します。次に、現在のデフォルト
のデプロイメントにあるこれらのリソースの物理名を AWS CloudFormation に問い合わせます。-release オプションを指定した場合、リリースデプロイメントが問い合わせの対象になります。
• --deployment {deployment-name}
オプション。{project_directory}\Config ディレクトリに {deploymentname}.awsLogicalMappings.json 形式で、指定したデプロイのマッピングファイルをエクス
ポートします。
ゲームランチャー (dev\Bin64\SamplesProjectLauncher.exe など) を実行するときに使用する
マッピングを -cc_override_resource_map オプションで選択できます。詳細については、「PC
ランチャーを使用してデプロイメントを選択する (p. 242)」を参照してください。
update-profile
AWS プロファイルを更新します。
共通の引数 (p. 221) のほかに、update-profile サブコマンドは次の引数を受け入れます。
• --aws-access-key{accesskey}
オプション。更新したプロファイルに関連付ける AWS アクセスキー。デフォルトでは、プロファ
イルに関連付けられる AWS アクセスキーを変更しません。
• --aws-secret-key{secretkey}
オプション。更新したプロファイルに関連付ける AWS シークレットキー。デフォルトでは、プロ
ファイルに関連付けられる AWS シークレットキーを変更しません。
• --profile {profilename}
必須更新する AWS プロファイルの名前。
Note
既存のプロファイルをデフォルトプロファイルにするには、 default-profile (p. 226) コマン
ドを使用します。
Version 1.6
234
Lumberyard 開発者ガイド
Cloud Canvas コマンドラインの使用
update-project-stack
プロジェクトの AWS CloudFormation スタックを更新します。
共通の引数 (p. 221) のほかに、update-project-stack サブコマンドは次の引数を受け入れま
す。
• --confirm-aws-usage
オプション。このコマンドによって、課金される可能性があり、また AWS アカウントのアクセス
許可に影響するアクションを実行する可能性がある AWS リソースが作成されることを理解済みで
あることを表します。またこのコマンドの実行時に確認プロンプトが表示されないようにします。
• --enable-capability {capability} [{capability} ...]
オプション。AWS CloudFormation で特定のスタックを作成または更新する前に指定する必要があ
る機能の一覧。一部のスタックテンプレートには、AWS アカウントのアクセス許可に影響するリ
ソースが含まれる場合があります。このようなスタックの場合は、このパラメータを指定して、そ
れらの機能を明示的に認識する必要があります。指定できる値には、CAPABILITY_IAM などがあり
ます。
update-project-stack の仕組み
1. project-template.json (p. 284) ファイルと project-code サブディレクトリ (p. 298)の内容が zip
圧縮されたものが、設定バケット (p. 303)にアップロードされます。
2. AWS CloudFormation スタックの更新処理は、アップロードされた project-template.json
ファイルを使用して実行されます。project-code.zip ファイルは、テンプレートによって定義
された Lambda 機能リソースを更新するときに使用されます。
Note
{root}\{game}\AWS\project-settings.json ファイルが存在しない、あるいはこの
ファイルに有効な ProjectStackId プロパティが含まれていない場合、update-projectstack コマンドの実行は失敗します。
upload-resources
指定したデプロイでリソースグループの AWS CloudFormation スタックを更新します。
共通の引数 (p. 221) のほかに、upload-resources サブコマンドは次の引数を受け入れます。
• --deployment
必須更新するデプロイメントの名前。
• --resource-group
必須更新するリソースグループの名前。
• --confirm-aws-usage
オプション。このコマンドによって、課金される可能性があり、また AWS アカウントのアクセス
許可に影響するアクションを実行する可能性がある AWS リソースが作成されることを理解済みで
あることを表します。またこのコマンドの実行時にデフォルトの確認プロンプトが表示されないよ
うにします。
• --enable-capability {capability} [{capability} ...]
オプション。AWS CloudFormation で特定のスタックを作成または更新する前に指定する必要があ
る機能の一覧。一部のスタックテンプレートには、AWS アカウントのアクセス許可に影響するリ
Version 1.6
235
Lumberyard 開発者ガイド
Cloud Canvas の進行状況ログを表示
ソースが含まれる場合があります。このようなスタックの場合は、このパラメータを指定して、そ
れらの機能を明示的に認識する必要があります。指定できる値には、CAPABILITY_IAM などがあり
ます。
resource-template.json (p. 298) ファイルと、zip 圧縮された lambda-function-code サブディ
レクトリ (p. 302)の内容が、設定バケット (p. 303) にアップロードされます。その後、AWS
CloudFormation スタックの更新処理が、アップロードされたテンプレートファイルを使用して実
行されます。lambda-function-code.zip ファイルは、リソーステンプレートで定義されている
Lambda 関数リソースの更新時に使用されます。
Cloud Canvas の進行状況ログを表示
Cloud Canvas Resource Manager の Progress log は、AWS CloudFormation スタック更新の進行状況
を表示します。アップデート中は、進行状況ログが詳細ペインの下部から拡張され、更新の進行状況
を表示します。ログの表示領域は、ペイン間の分離線をドラッグすると調整できます。
進行状況ログを非表示にするには、分離線を下方向にドラッグします。
デプロイでの作業
デプロイとは、ゲームで使用される AWS リソースの独立コピーです。デプロイは、開発、テスト、
本番など、ゲームのライフサイクル段階の間を安全に分離された状態に維持するために役立ちます。
リソースマネージャのナビゲーションペインでは、Deployments ノードにプロジェクトのデプロイス
テータスが表示されます。新しいデプロイを作成するために使用することもできます。
Version 1.6
236
Lumberyard 開発者ガイド
デプロイでの作業
注意: AWS プロファイルが設定されていないときに Deployments ノードが選択されると、プロファイ
ルを設定するよう求められます。プロジェクトのデプロイステータスは、プロファイルが指定されな
い限り表示できません。詳細については、「Cloud Canvas プロファイルの管理 (p. 219)」を参照し
てください。
Create Deployment
デプロイの作成を開始するには、[Create deployment] をクリックします。
リソースを初めてアップロードした場合、このバージョンのダイアログが表示される場合がありま
す。
[Deployment name] に名前を指定します。Lumberyard がこの名前をプロジェクトのスタック名に追加
し、デプロイ用の AWS CloudFormation スタックを作成します。
デプロイの作成プロセスを開始するには、[OK] をクリックします。リソースマネージャのナビゲー
ションペインでは、デプロイのノードが [Deployments] の下に表示されます。詳細ペインについて
は、「Cloud Canvas の進行状況ログを表示 (p. 236)」で作成プロセスの詳細を説明しています。
デプロイステータスのテーブル
[Deployment status] テーブルは、各デプロイ用の AWS CloudFormation スタックのステータスを示
します。[Deployment] にはデプロイの名前が表示されます。このテーブルの残りのフィールドの説
Version 1.6
237
Lumberyard 開発者ガイド
デプロイでの作業
明については、「プロジェクトスタックの操作 (p. 246)」セクションの「Stack Resources テーブ
ル (p. 247)」を参照してください。
個々のデプロイノード
Deployment ノードの子ノードは、Lumberyard プロジェクトのデプロイの 1 つとしてそれぞれ存在し
ます。Deployment ノードが選択されている場合、詳細ペインには選択されたデプロイの現在のステー
タスが表示されます。
Note
AWS プロファイルが設定されていないときに Deployment ノードが選択されると、プロファ
イルを設定するよう求められます。プロジェクトのデプロイステータスは、プロファイル
が指定されない限り表示できません。詳細については、「Cloud Canvas プロファイルの管
理 (p. 219)」を参照してください。
個々のデプロイステータスのテーブル
<Deployment Name> deployment status テーブルには、選択されたデプロイ用の AWS
CloudFormation スタックのステータスが表示されます。このテーブルの内容の説明については、「プ
ロジェクトスタックの操作 (p. 246)」セクションの「Project Stack Status テーブル (p. 246)」を参
照してください。
Upload All Resources
[Upload all resources] をクリックすると、すべてのリソースグループのローカル定義に一致するよう
に、現在の AWS デプロイのリソースを変更、作成、または削除するプロセスが開始します。
Version 1.6
238
Lumberyard 開発者ガイド
デプロイでの作業
Delete Deployment
[Delete deployment] をクリックすると、デプロイのリソースを AWS から削除するプロセスが開始し
ます。すべてのリソースグループによって定義されたリソースが削除されます。
デプロイの削除については、「Cloud Canvas デプロイとそのリソースを削除する (p. 244)」を参照
してください。
Stack Resources テーブル
Stack resources テーブルには、選択されたデプロイのすべてのリソースグループによって定義されて
いるリソースのステータスをそれぞれ示します。このテーブルのフィールドの説明については、「プ
ロジェクトスタックの操作 (p. 246)」セクションの「Stack Resources テーブル (p. 247)」を参照
してください。
トピック
• Cloud Canvas デプロイをアクティブにする (p. 239)
• 異なるマッピングのテスト (p. 241)
• 保護済みのデプロイの使用 (p. 243)
• Cloud Canvas デプロイとそのリソースを削除する (p. 244)
Cloud Canvas デプロイをアクティブにする
Lumberyard エディタ にアクティブだと判断させたいデプロイを選択することができます。アクティ
ブなデプロイとは、Lumberyard エディタ で使用するデプロイのことです。ユーザーがゲームを起動
するとき、Lumberyard エディタ はアクティブなデプロイのリソースを使用します。[Cloud Canvas
Resource Manager] ナビゲーションペインで リソースグループの使用 (p. 247) ノードまたは 個々の
リソース グループ (p. 249) ノードを選択すると、表示されるステータス情報はアクティブなデプロ
イに対応します。
また、すべてのチームメンバーに対してデフォルトでアクティブにするデプロイを選択することもで
きます。
Note
デプロイを選択するには、AWS アカウントで使用できるように Cloud Canvas Resource
Manager を初期化し、デプロイを作成しておく必要があります。詳細については、
「Cloud Canvas Resource Manager を初期化する (p. 218)」および「Create Deployment
(p. 237)」を参照してください。
デプロイをアクティブにする
Cloud Canvas Resource Manager でデプロイをアクティブにする方法は複数あります。
デプロイをアクティブにするには
•
デプロイをアクティブにするには、次のいずれかを実行します。
Version 1.6
239
Lumberyard 開発者ガイド
デプロイでの作業
• Lumberyard エディタ で [AWS]、[Cloud Canvas]、[Select a deployment] の順にクリックしま
す。
• [Cloud Canvas Resource Manager] ツールバーで、現在のデプロイの名前をクリックするか、
何も設定されていない場合は [(none)] をクリックします。
プロンプトが表示されたら、アクティブにするデプロイを選択します。
1 つ以上のデプロイメントに [protected] とマークされている場合があります。詳細について
は、「保護済みのデプロイの使用 (p. 243)」を参照してください。
• [Cloud Canvas Resource Manager] ナビゲーションペインで、アクティブにするデプロイを右
クリックし、[Make active deployment] をクリックします。
デプロイをデフォルトにする
Cloud Canvas Resource Manager を使用して、デプロイをデフォルトにすることができます。
すべてのチームメンバーに対してデフォルトでデプロイをアクティブにするには
1.
Lumberyard エディタ で、[AWS]、[Cloud Canvas]、[Cloud Canvas Resource Manager] の順にク
リックします。
2.
[Cloud Canvas configuration] ナビゲーションツリーで、[Administration (advanced)]、
[Deployments] の順に展開します。
Version 1.6
デフォルトにするデプロイを右クリックし、[Make
default deployment] をクリックします。
240
3.
Lumberyard 開発者ガイド
デプロイでの作業
コマンドラインを使用してデプロイをデフォルトにするには
•
コマンドラインを使用してデプロイをデフォルトにするには、次のコマンドを入力します。
lmbr_aws default-deployment --set <deployment name>
異なるマッピングのテスト
異なる Cloud Canvas リソースのデプロイメントをテストするには、Cloud Canvas Resource
Manager または lmbr_aws コマンドラインを使用して、マッピングをエクスポートできます。
Cloud Canvas Resource Manager からマッピングをエクスポートするには
•
Resource Manager で、次のいずれかを実行します。
• デプロイメントを左クリックし、メインウィンドウで [Export Mapping] をクリックします。
• リストのデプロイメント名を右クリックし、コンテキストメニューから [Export Mapping] を選
択します。
次のイメージは、両方のオプションを示しています。
Version 1.6
241
Lumberyard 開発者ガイド
デプロイでの作業
コマンドラインからマッピングをエクスポートするには
•
次のコマンドを入力します。<name> はデプロイメントの名前です。
lmbr_aws update-mappings --deployment <name>
指定されたデプロイメントのマッピングファイルが、<project_directory>\Config ディレクトリ
に作成され、形式は <deployment_name>.awsLogicalMappings.json になります。
Tip
コマンドラインを使用してマッピングをエクスポートすると、テスト用や開発用のスクリプ
トの作成が容易になります。
PC ランチャーを使用してデプロイメントを選択する
マッピングをエクスポートすると、dev\Bin64\SamplesProjectLauncher.exe にあるようなゲー
ムランチャーを実行するときに使用するマッピングを選択できるようになります。
ランチャーで特定のデプロイメントを使用するように指定するには、次の例のようにコマンドライン
オプション cc_override_resource_map を使用します。
SamplesProjectLauncher.exe -cc_override_resource_map Config
\dev.awsLogicalMappings.json
Version 1.6
242
Lumberyard 開発者ガイド
デプロイでの作業
cc_override_resource_map パラメーターの引数は、使用するマッピングファイルを指定します。
ランチャーに単一のマッピングファイルをエクスポートした場合は、デフォルトでそのマッピ
ングファイルが使用されます。ランチャーに複数のマッピングファイルをエクスポートした場合
は、cc_override_resource_map パラメーターを使用してマッピングを選択する必要があります。
複数のマッピングをエクスポートしてマッピングを指定しないと、ランチャーでエラーメッセージが
表示されマッピングはロードされません。
保護済みのデプロイの使用
Cloud Canvas を使用して、特定のデプロイを保護済みとしてマークできます。保護済みのステータス
により、ユーザー (通常はテスターまたは開発者) が開発ゲームクライアントをライブリソースに誤っ
て接続することを防止できます。
ユーザーが保護済みのゲームを起動すると、保護済みのデプロイを使用しようとしていることがメッ
セージボックスで通知されます。ユーザーは、問題になり得るデータが送信される前に、接続しない
ように選択できます。
保護機能では、オートメーションを "中断" するメッセージボックスが意図的に使用されます。テスト
を実行するスクリプトが保護済みのデプロイを使用するように設定されている場合、Lumberyard クラ
イアントはユーザーの介入なしでは続行されません。
保護済みのデプロイが検出された場合
ゲームが Lumberyard エディタ から実行されるたびに、保護が検出されます。ゲームが Windows ラ
ンチャーから実行されると、そのランチャーがデバッグモードで実行されている場合にのみ、保護が
検出されます。
デプロイを保護済みとしてマークする
現在、protect-deployment コマンドラインツールから lmbr_aws コマンドを使用して、保護を設
定する必要があります。
protect-deployment コマンドでは、以下のパラメーターを使用します。
--set <deployment_name> - デプロイが保護済みであることを指定します。
--clear <deployment_name> - デプロイが非保護であることを指定します。
--show - 現在保護済みのデプロイのリストを表示します。
デプロイの保護ステータスを表示するために、list-deployments または list-mappings コマン
ドを使用することもできます。
Cloud Canvas Resource Manager での保護済みステータスの表示
Cloud Canvas Resource Manager で、デプロイの保護ステータスを表示できますが、変更することは
できません。Lumberyard エディタ からデプロイの保護ステータスを変更する機能は、将来のリリー
スで予定されています。
Note
デプロイを保護済みに設定すると、Cloud Canvas Resource Manager または lmbr_aws コマ
ンドラインツールを使用してリソースをデプロイまたは削除できなくなり、警告機能のみが
有効になります。このため、クリティカルなデプロイに不要な変更を加えることがないよう
に注意してください。デプロイを保護するより包括的なモデルは、Lumberyard の将来のバー
ジョンで予定されています。
Version 1.6
243
Lumberyard 開発者ガイド
デプロイでの作業
Cloud Canvas デプロイとそのリソースを削除する
Lumberyard プロジェクトから Cloud Canvas 機能およびそれに関連する AWS リソースを削除するに
は、Cloud Canvas Resource Manager または Cloud Canvas コマンドラインを使用することができま
す。
Warning
この操作は、必ず管理者が行ってください。Lumberyard プロジェクト用に Cloud Canvas に
よって管理されている AWS リソースをすべて削除する場合、ゲームのプレイヤーは、ゲーム
のクラウド接続機能を実装している Cloud Canvas リソースグループのいずれにもアクセスす
ることはできません。
Cloud Canvas Resource Manager を使用して Cloud Canvas デプロイとそのリソースを削除
するには
1.
ソース管理に Lumberyard をチェックインしている場合は、<root>\<game>\AWS\projectsettings.json ファイルがチェックアウトされ、書き込み可能になっていることを確認してく
ださい。
2.
Lumberyard エディタ で、[AWS]、[Cloud Canvas]、[Cloud Canvas Resource Manager] の順に選
択します。
3.
[Cloud Canvas configuration] ナビゲーションペインで、[Administration (advanced)]、
[Deployments] の順に展開します。プロジェクトのデプロイのリストが表示されます。
4.
削除するデプロイを選択し、[Delete deployment] をクリックします。
5.
確認するよう求められたら、[Yes] をクリックして、AWS からデプロイのリソースを削除するプ
ロセスを開始します。このプロセスには数分かかる場合があります。
6.
AWS からプロジェクトのリソースをすべて削除するには、プロジェクトの各デプロイを削除する
場合と同じ手順に従います。
コマンドラインを使用して Cloud Canvas デプロイとそのリソースを削除するには
1.
ソース管理に Lumberyard をチェックインしている場合は、<root>\<game>\AWS\projectsettings.json ファイルがチェックアウトされ、書き込み可能になっていることを確認してく
ださい。
2.
コマンドラインプロンプトを開き、Lumberyard \dev ディレクトリに移動します。
3.
次のコマンドを入力して、プロジェクトのデプロイの名前を確認します。
lmbr_aws list-deployments
Version 1.6
244
Lumberyard 開発者ガイド
JSON ファイルでの作業
4.
削除するデプロイごとに次のコマンドを入力します。
lmbr_aws delete-deployment --deployment <deployment name>
Note
プロジェクトから Cloud Canvas 機能をすべて削除するには、delete-deployment コ
マンドを使用し、list-deployments によってリストされたデプロイをすべて削除しま
す。その後、次のステップで説明されているとおり、プロジェクトのスタックを削除し
ます。
5.
デプロイをすべて削除したら、次のコマンドを入力して、Cloud Canvas がプロジェクトの管理に
使用しているリソースを削除することができます。
lmbr_aws delete-project-stack
これにより、Cloud Canvas プロジェクトに関連する AWS リソースがすべて削除されます。
JSON ファイルでの作業
Cloud Canvas Resource Manager のナビゲーションペインにある一部のノードは、プロジェクトの
JSON テンプレートまたは設定ファイルを表します。これらのファイルの内容は、「リソースの定
義」で詳しく説明します。ナビゲーションペインでこれらのノードのいずれかを選択すると、詳細ペ
インにそのファイルの内容が表示されます。リソースマネージャーで直接、または外部エディタを使
用してファイルを編集できます。詳細については、「Cloud Canvas ファイルを編集する (p. 216)」
を参照してください。
ナビゲーションペインの一部のテンプレートファイルノードには、子ノードがあります。子ノードは
それぞれ、親ノードのテンプレートファイルの 1 つのセクションを表します。これらの子ノードによ
り、親ノードのテンプレートファイルの対応するセクションを検索して編集することが容易になりま
す。子ノードで行ったあらゆる変更は、常に親テンプレートファイルの対応するセクションに保存さ
れます。
Resource Groups ノード下の各リソースグループには、以下のテンプレートがあります。
resource-template.json
各リソースグループには、resource-template.json ノードと lambda-function-code 子ノードがありま
す。resource-template.json ファイルは、グループのリソースを定義します。詳細については、
「リソースの定義」を参照してください。 ナビゲーションペインでは、resource-template.json 下の
各ノードが resource-template.json ファイルのセクションで定義されたリソースのいずれかを表
します。
以下のテンプレートは Administration (advanced) ノードの下にあります。
[project-settings.json]
project-settings.json ファイルには、プロジェクト設定データが含まれます。詳細については、
「リソースの定義」を参照してください。
project-template.json
project-template.json ファイルは、Cloud Canvas Resource Manager が使用するリソースを定
義します。詳細については、「リソースの定義」を参照してください。
Version 1.6
245
Lumberyard 開発者ガイド
プロジェクトスタックの操作
deployment-template.json
deployment-template.json ファイルは、各プロジェクトリソースグループの AWS
CloudFormation スタックリソースを定義します。詳細については、「リソースの定義」を参照してく
ださい。
deployment-access-template.json
deployment-access-template.json ファイルは、各デプロイのリソースへのアクセスを制御する
AWS CloudFormation スタックリソースを定義します。詳細については、「リソースの定義」および
「アクセスコントロールとプレイヤー ID」を参照してください。
user-settings.json
user-settings.json ファイルには、ユーザー専用の設定が含まれます。詳細については、「リ
ソースの定義」を参照してください。
プロジェクトスタックの操作
[Cloud Canvas Resource Manager] ナビゲーションペインで [Project stack] ノードを選択する
と、Cloud Canvas が使用している AWS CloudFormation スタックに関する情報が詳細ペインに表示
されます。
次の点に注意してください。
• プロジェクトのスタックノードを選択したときに AWS プロファイルが設定されていない場合、プ
ロファイルを設定するように求められます。プロファイルは、Lumberyard がプロジェクトリソー
スのステータスを表示する際に必要です。詳細については、「Cloud Canvas プロファイルの管
理 (p. 219)」を参照してください。
• プロジェクトが Cloud Canvas と共に使用できるように初期化されていない場合、[Project stack]
ノードを選択すると、プロジェクトを初期化してプロジェクトスタックを作成するよう求められま
す。詳細については、「Cloud Canvas Resource Manager を初期化する (p. 218)」を参照してく
ださい。
Project Stack Status テーブル
[Project stack status] テーブルでは、プロジェクトのリソースグループによって使用されるリソースを
含む AWS CloudFormation スタックのステータスが表示されます。
Version 1.6
246
Lumberyard 開発者ガイド
リソースグループの使用
このテーブルには、次の列があります。
Status – AWS CloudFormation スタックのステータス。この列に含まれる可能性のある値について
は、「リソースのステータスの説明について (p. 220)」を参照してください。その他のステータス情
報を表示するには、ステータスインジケータにマウスポインタを置きます。
Created – スタックが作成された時刻。
Updated – スタックのステータスが更新された時刻。
ID - スタックの AWS ID の一部が省略されたもの。完全な ID を表示するには、省略された ID にマウ
スポインタを置きます。
Upload Resources
AWS でリソースを変更、作成、削除するプロセスを開始するには、[Upload resources] をクリック
し、リソースがローカル定義と一致するようにします。
Stack Resources テーブル
[Stack resources] テーブルには、プロジェクトで使用されているリソースのステータスが表示されま
す。
このテーブルには、次の列があります。
Resource Name – リソースの論理名。このリソース名をリソースグループ名に追加すると、フローグ
ラフノードでリソースを参照することができます。
Type – リソースのタイプ (たとえば、Lambda 関数、Amazon S3 バケット、カスタムリソース)。
Status – リソースの現在の状態。ステータスが取り得る値については、「リソースのステータスの説
明について (p. 220)」を参照してください。その他のステータス情報を表示するには、ステータスに
マウスポインタを置きます。
Timestamp – 最後の変更が加えられた時刻。
ID - スタックの AWS ID の一部が省略されたもの。完全な ID を表示するには、省略された ID にマウ
スポインタを置きます。
リソースグループの使用
Cloud Canvas Resource Manager の [Cloud Canvas configuration] ナビゲーションペインで [Resource
Groups] を選択すると、詳細ページにプロジェクトの現在のデプロイに属するリソースグループの状
態が表示されます。次の点に注意してください。
Version 1.6
247
Lumberyard 開発者ガイド
リソースグループの使用
• [Resource Groups] を選択した場合に、AWS プロファイルが設定されていないと、プロファイルを
指定するよう求められます。プロファイルは、Lumberyard がプロジェクトリソースのステータスを
表示する際に必要です。詳細については、「Cloud Canvas プロファイルの管理 (p. 219)」を参照
してください。
• [Resource Groups] を選択したとき、デプロイ環境は存在するがどの環境もアクティブではない場
合は、いずれかのデプロイ環境を選択するよう求められます。詳細については、「Cloud Canvas デ
プロイをアクティブにする (p. 239)」を参照してください。
リソースグループ
[Resource Groups ] 詳細ページには、現在のデプロイ環境内のリソースグループが一覧表示されま
す。
[Resource Groups] 詳細ペインには、以下のオプションが用意されています。
Upload all resources
[Upload all resources] オプションを選択すると、すべてのローカルリソースグループ内のすべて
の定義に合わせて AWS 内のリソースを変更するプロセスが必要に応じて開始されます。更新処
理が進むにつれて、リソースグループのステータスが [Create pending] から [Create complete] に
変わります。更新には数分程かかります。
次の点に注意してください。
• Lumberyard プロジェクトを、アップロードするリソース用の AWS アカウントでまだ初期化
していない場合は、初期化するように求められます。AWS で使用するように Lumberyard プ
ロジェクトを準備するには、使用する AWS アカウントの管理者である必要があります。詳細
については、「Cloud Canvas Resource Manager を初期化する (p. 218)」を参照してくださ
い。
• プロジェクトを初期化したら、プロジェクトのデプロイ環境を作成するよう求められます。デ
プロイを実行すると、リソースグループ定義で指定されたすべての AWS リソースが作成され
ます。詳細については、「Create Deployment (p. 237)」を参照してください。
Version 1.6
248
Lumberyard 開発者ガイド
リソースグループの使用
[Progress log] の詳細については、「Cloud Canvas の進行状況ログを表示 (p. 236)」を参照し
てください。
Add resource group
[Add resource group] オプションを選択すると、Lumberyard プロジェクトに新規のリソースグ
ループ定義を追加できます。リソースグループ定義はハイスコアシステムのような単一のゲーム
機能を表します。この定義には、当該機能が使用する AWS リソースが指定されます。
[Add resource group] をクリックすると [New resource group] ダイアログが開きます。
以下の情報を記述します。
• Resource group name – リソースグループの名前。名前は英数字である必要がありま
す。Lumberyard は、この名前を使用して、AWS CloudFormation スタックリソース定義を
deployment-template.json ファイル内に作成します。
• Example resources – (任意指定) リソースグループ内にサンプルリソースを含めるよう選択し
ます。サンプルを参照してリソースグループ内にリソースを定義する方法を確認できます。ま
た、サンプルを変更して、プロジェクト内の 1 つの機能として利用することもできます。
Resource group status
[Resource group status] テーブルには、アクティブなデプロイ環境内の各リソースグループに
ついて、AWS CloudFormation スタックのステータスが表示されます。[Resource group] にはリ
ソースグループ名が表示されます。このテーブルの残りのフィールドの説明については、「プロ
ジェクトスタックの操作 (p. 246)」セクションの「Stack Resources テーブル (p. 247)」を参
照してください。
個々のリソース グループ
[Resource Groups] の各子ノードは、Lumberyard プロジェクト内のリソースグループを表します。こ
れらのリソースグループの 1 つを選択すると、詳細ペインにそのリソースグループの詳細が表示され
ます。
次の点に注意してください。
Version 1.6
249
Lumberyard 開発者ガイド
リソースグループの使用
• リソースグループを選択した場合に、AWS プロファイルが設定されていないと、プロファイルを指
定するよう求められます。プロファイルは、Lumberyard がプロジェクトリソースのステータスを表
示する際に必要です。詳細については、「Cloud Canvas プロファイルの管理 (p. 219)」を参照し
てください。
• リソースグループを選択したとき、デプロイ環境は存在するがどの環境もアクティブではない場合
は、いずれかのデプロイ環境を選択するよう求められます。詳細については、「Cloud Canvas デプ
ロイをアクティブにする (p. 239)」を参照してください。
新しいリソースグループへのリソースの追加
リソースグループを作成した時点では、そのグループには、AWS リソース定義はまだ存在しません。
リソース定義を追加するには、[Add resource] オプションを使用します。
定義はローカルに作成され、使用する AWS リソースについてのみ記述されます。リソース自体は
[Create resources] をクリックするまで、AWS 内には作成されません。
個々のリソースグループのステータス
リソースグループのステータスペインを使用して、リソースグループを管理できます。次の図
は、DontDieAWS リソースグループのステータスの詳細を示しています。
Version 1.6
250
Lumberyard 開発者ガイド
リソースグループの使用
リソースグループのステータスペインには以下のオプションがあります。
Upload resources
1 つ以上のリソース定義を作成した後、[Upload resources] をクリックすると、[Add resource] オ
プションで作成したローカルのリソース定義に指定されている AWS 内リソースの作成プロセス
が開始されます。
更新処理が進むにつれて、リソースのステータスが [Create pending] から [Create complete] に変
わります。
次の点に注意してください。
• Lumberyard プロジェクトを、アップロードするリソース用の AWS アカウントでまだ初期化
していない場合は、初期化するように求められます。AWS で使用するように Lumberyard プ
ロジェクトを準備するには、使用する AWS アカウントの管理者である必要があります。詳細
については、「Cloud Canvas Resource Manager を初期化する (p. 218)」を参照してくださ
い。
• プロジェクトのデプロイ環境が存在しない場合は、デプロイ環境を作成するよう求められま
す。デプロイを実行すると、リソースグループ定義で指定されたすべての AWS リソースが作
成されます。詳細については、「Create Deployment (p. 237)」を参照してください。
Remove resource group
[Remove resource group] をクリックすると、選択したリソースグループをロカールの設定から削
除できます。
Version 1.6
251
Lumberyard 開発者ガイド
リソースグループの使用
実際のリソースを AWS から削除するに は、以下のセクションの説明に従って [Delete resources]
オプションを使用します。
Note
リソースの削除操作を実行しても、リソースグループの設定データはロカールディスクか
ら削除されません。ディスク上にデータが存在しているかぎり、同じ名前で新しいグルー
プリソースを追加することにより、リソースグループを復元できます。
Delete resources
[Delete resources] オプションは、(たとえば、[Remove resource group] オプションを使用して)
ローカル設定からリソースグループを削除すると表示されます (この時点では、リソースグループ
によって定義されたリソースは AWS 内にまだ存在しています)。
[Delete resources] をクリックすると、Lumberyard エディタ 内で現在アクティブなデプロイ環境
について、AWS 内リソースを削除してよいかどうかの確認を求められます。
[Yes] をクリックすると、削除操作が開始されます。削除には数分程度かかることがあります。
Stack resources
[Stack Resources] テーブルには、リソースグループについて定義した各 AWS リソースのステー
タスが表示されます。このテーブルのフィールドの説明については、「プロジェクトスタックの
操作 (p. 246)」セクションの「Stack Resources テーブル (p. 247)」を参照してください。
resource-template.json
このノードの詳細については、「JSON ファイルでの作業 (p. 245)」を参照してください。
lambda-function-code
lambda-function-code ノードとその子ノードは、プロジェクト内の lambda-function-code ディ
レクトリに対応しています。lambda-function-code ディレクトリには、リソースグループによっ
て定義された AWS Lambda 関数リソースを実装するコードが格納されています。詳細については、
Version 1.6
252
Lumberyard 開発者ガイド
リソースグループの使用
「lambda-function-code ディレクトリ」を参照してください。 「project-code (p. 253)」ノードの関
連情報も参照してください。
project-code
このノードは、リソース管理ナビゲーションツリーの [Administration (advanced)] の下にありま
す。project-code ディレクトリには、Cloud Canvas Resource Manager が使用する AWS Lambda
関数リソースを実装するコードが格納されています。詳細については、「リソースの定義」を参照
してください。project-code ノードには、ファイルとディレクトリの子ノードが格納されています。
ファイルノードをクリックすると、詳細ペインでその内容を確認または編集できます。詳細について
は、「Cloud Canvas ファイルを編集する (p. 216)」を参照してください。
リソース定義の Cloud Canvas へのインポート
Cloud Canvas リソースインポーターを使用して、既存の AWS リソースの定義を Cloud Canvas リ
ソースグループに追加できます。Lumberyard エディタ の Cloud Canvas リソースマネージャーまた
はコマンドラインプロンプトを使用してリソースを追加できます。
Lumberyard エディタ を使用したリソースのインポート
Lumberyard エディタ で、Amazon リソースネーム (ARN) を指定するか、リストから選択すること
で、リソースをインポートできます。
ARN を使用してリソースをインポートするには
1.
Lumberyard エディタ のトップメニューから、[AWS]、[Cloud Canvas]、[Resource Manager] の
順に選択します。
2.
ナビゲーションペインで、リソースグループを選択します。
3.
詳細ウィンドウで、[Import resource]、[Import using ARN] の順にクリックします。また、ナビ
ゲーションペインでリソースのコンテキスト (右クリック) メニューを開き、[Import resource]、
[Import using ARN] の順に選択することもできます。
4.
[Import using ARN] ダイアログボックスで、インポートするリソースの ARN と名前を指定しま
す。両方とも必要です。
情報の両方の項目を指定すると、[Import] ボタンが有効になります。
5.
インポート.
リソースをリストから選択してインポートするには
1.
Lumberyard エディタ のトップメニューから、[AWS]、[Cloud Canvas]、[Resource Manager] の
順に選択します。
2.
ナビゲーションペインで、リソースグループを選択します。
Version 1.6
253
Lumberyard 開発者ガイド
リソースグループの使用
3.
詳細ウィンドウで、[Import resource]、[Import using ARN] の順に選択します。また、ナビゲー
ションペインでリソースのコンテキスト (右クリック) メニューを開き、[Import resource]、
[Import using ARN] の順に選択することもできます。
4.
[Import from list] ダイアログボックスの [Region] で、リソースの AWS リージョンを選択します。
デフォルト値はプロジェクトスタックのリージョンです (存在する場合)。インポート可能なリ
ソースがあるリージョンを選択すると、すぐにリソースがリストにロードされます。
5.
AWS サービスセレクタを使用してリソースをサービスでフィルタリングしてから、[Search] ボッ
クスを使用してリソースを名前でフィルタリングできます。
6.
インポートする各リソースの左側にあるチェックボックスを選択します。
7.
設定.
Version 1.6
254
Lumberyard 開発者ガイド
リソースグループの使用
8.
[Configuration] ダイアログボックスで、各リソースの参照名を指定するか、デフォルト値をその
まま使用します。デフォルト名はリソースの AWS での元の名前です。
9.
選択したリソースを一覧から削除するには、そのリソースのコンテキスト (右クリック) メニュー
を開き、[Delete] を選択します。
10. 準備ができたら、[Import] をクリックします。進行状況バーが表示されます。エラーが発生した
場合は、[Import Error] エラーメッセージで通知されます。
11. [X] をクリックして [Import from list] ダイアログボックスを閉じます。インポートしたリソースは
Cloud Canvas リソースマネージャーの詳細ペインに表示されます。
コマンドラインを使用したリソース定義のインポート
コマンドラインを使用してリソースをリスト表示しインポートするには、「list-importableresources (p. 228)」および「import-resource (p. 227)」を参照してください。
リソース定義について
Cloud Canvas リソースインポーターを使用してリソースの定義をインポートする場合には、インポー
トするのはリソースの定義であり、リソースそのものではないことを理解しておくことが重要です。
たとえば、AWS コンソールを使用して DynamoDB に Table A というハイスコアテーブルを作成す
るとします。スコアをアップロードするゲームクライアントを作成して、そのクライアントをプレイ
ヤーに送信します。Table A に、ゲームをプレイしたユーザーからのデータが入力されていきます。
その後、Cloud Canvas を使用してリソースとデプロイメントを管理することにしました。Table A の
設定値が目的に最適であり、ユースケースで十分に機能していたため、Cloud Canvas リソースマネー
ジャーを使用して、Table A をインポートします。
インポートしたリソースを使用してデプロイメントを作成すると、デプロイメントには Table B が作
成されます。これは Table A の構造を持っていますがデータは含まない新しいテーブルです。Table B
は Cloud Canvas で管理され、Table A と同じ動作をします。ただし、Table B は Table A を参照する
ものではなく、Table A のデータや履歴は含みません。リソース定義をインポートする場合、この違
いに注意してください。
自動的にインポートされたリソース定義
選択した既存のリソースには、他のリソースに関連するものがある場合があります。たとえ
ば、Lambda 関数で指定トリガーからのイベントに対応できます。Amazon S3 バケットからのイベン
Version 1.6
255
Lumberyard 開発者ガイド
リソースグループの使用
ト通知を使用して、アラートを送信したりワークフローをトリガーしたりできます。Cloud Canvas は
関連リソースを自動的にインポートします。
Cloud Canvas では、自動的にインポートされたリソース定義に以下の命名規則が使用されます。
送信元
命名規則
インポートしたリソースの名前
の例
DynamoDB テーブル、Lambda
関数、Amazon SNS トピッ
ク、Amazon SQS キュー
<#####> + "AutoAdded" + <#
######> + <#####>
LambdaFunctionAutoAddedtable0
Lambda 関数設定リソース <Lambda ###> +
"Configuration"
LambdaFunctionConfiguration
Lambda 関数ポリシーリソース
<Lambda ###> + "Permission"
LambdaFunctionPermission
DynamoDB テーブル Lambda
関数イベントソース
<DynamoDB #####> +
"EventSource"
DynamoTableEventSource
インポートでサポートされるリソース
以下のセクションは、Cloud Canvas がサポートされている各 AWS サービスでインポートするリソー
ス属性および関連リソースをまとめたものです。
Dynamo DB テーブル
DynamoDB テーブルでは、Cloud Canvas によって以下のリソース属性がインポートされます。
• AttributeDefinitions
• GlobalSecondaryIndexes
• KeySchema
• LocalSecondaryIndexes
• ProvisionedThroughput
• StreamSpecification
Amazon S3 バケット
Amazon S3 バケットでは、Cloud Canvas によって以下のリソース属性がインポートされます。
• CorsConfiguration
• LifecycleConfiguration
• NotificationConfiguration
• Tags
• VersioningConfiguration
• WebsiteConfiguration
Amazon S3 バケットでは、Cloud Canvas によって以下の関連リソースもインポートされます。
• Lambda 関数
• Amazon SQS キュー
Version 1.6
256
Lumberyard 開発者ガイド
Cloud Canvas フローグラフ ノードのリファレンス
• Amazon SNS トピック
Lambda 関数
Lambda 関数では、Cloud Canvas によって以下のリソース属性がインポートされます。
• Code
• Description
• Handler
• MemorySize
• Role
• Runtime
• Timeout
• VpcConfig
Lambda 関数では、Cloud Canvas によって以下の関連リソースもインポートされます。
• Lambda 関数設定
• Lambda 関数アクセス権限
• DynamoDB テーブル
• イベントソースマッピング
Amazon SNS トピック
Amazon SNS トピックでは、Cloud Canvas によって以下のリソース属性がインポートされます。
• DisplayName
• Subscription
Amazon SNS トピックでは、関連リソースである Lambda 関数があれば Cloud Canvas によってそれ
もインポートされます。
SQS キュー
SQS キューでは、Cloud Canvas によって以下のリソース属性がインポートされます。
• DelaySeconds
• MaximumMessageSize
• MessageRetentionPeriod
• ReceiveMessageWaitTimeSeconds
• RedrivePolicy
• VisibilityTimeout
Cloud Canvas フローグラフ ノードのリファレン
ス
このセクションでは、Cloud Canvas で使用できるフローグラフノードのリファレンスを提供します。
Version 1.6
257
Lumberyard 開発者ガイド
Cloud Canvas Configuration ノード
• Cloud Canvas Configuration ノード (p. 258)
• Cognito (プレイヤー ID) ノード (p. 261)
• DynamoDB (データベース) ノード (p. 263)
• Lambda (クラウド関数) ノード (p. 269)
• S3 (ストレージ) ノード (p. 270)
• SNS (Notification Service) ノード (p. 272)
• SQS (メッセージキューサービス) ノード (p. 275)
• 静的データ (プロトタイプ) ノード (p. 277)
フローグラフノードの使用方法の概要については、「フローグラフシステム」を参照してください。
Cloud Canvas Configuration ノード
以下のフローグラフノードを使用して、Cloud Canvas の設定が編集できます。
トピック
• ApplyConfiguration ノード (p. 258)
• SetConfigurationVariable ノード (p. 258)
• ConfigureProxy ノード (p. 259)
• GetConfigurationVariableValue ノード (p. 260)
• SetDefaultRegion ノード (p. 260)
ApplyConfiguration ノード
管理されたクライアントすべてに AWS 設定を適用します。
入力
ポート
型
説明
適用
すべて
管理されたクライアントすべてに現在の AWS 設定を適用する
出力
ポート
型
説明
Success
すべて
操作が成功するとアクティブ化されます
エラー
文字列
エラーが検出されるとアクティブ化されます。ポートの値はエ
ラーメッセージです
SetConfigurationVariable ノード
設定パラメーター値を設定します。
Version 1.6
258
Lumberyard 開発者ガイド
Cloud Canvas Configuration ノード
入力
ポート
型
説明
設定
すべて
パラメーター値を設定する
名前
文字列
設定するパラメーターの名前
値
文字列
パラメーターに設定する値。$param-name$ 部
分文字列が含まれる場合あり
ポート
型
説明
Success
すべて
操作が成功するとアクティブ化されます
エラー
文字列
エラーが検出されるとアクティブ化されます。
ポートの値はエラーメッセージです
出力
ConfigureProxy ノード
すべての AWS クライアントによって使用されるプロキシ設定を設定します。
入力
ポート
型
説明
設定
すべて
プロキシ設定を設定する
ホスト
文字列
プロキシのホスト
ポート
整数
プロキシのポート
UserName
文字列
プロキシのユーザー名
パスワード
文字列
プロキシのパスワード
ポート
型
説明
Success
すべて
操作が成功するとアクティブ化されます
出力
Version 1.6
259
Lumberyard 開発者ガイド
Cloud Canvas Configuration ノード
ポート
型
説明
エラー
文字列
エラーが検出されるとアクティブ化されます。
ポートの値はエラーメッセージです
GetConfigurationVariableValue ノード
文字列に設定値パラメーターを挿入します。
入力
ポート
型
説明
拡張
すべて
パラメーターリファレンスを展開する
値
文字列
$param-name$ 部分文字列を含む値
出力
ポート
型
説明
Success
すべて
操作が成功するとアクティブ化
されます
エラー
文字列
エラーが検出されるとアクティ
ブ化されます。ポートの値はエ
ラーメッセージです
値
文字列
パラメーター値で置換される
$param-name$ 部分文字列を持
つ値
SetDefaultRegion ノード
現在のプロジェクトですべての AWS クライアントのためにリージョンを設定 (オーバーライド) しま
す。
入力
ポート
型
説明
有効化
すべて
現在のプロジェクトですべての AWS クライアン
トのためにリージョンを設定する
サービス対象
文字列
すべての AWS クライアントのためにデフォルト
のリージョンとして設定するリージョンの名前
Version 1.6
260
Lumberyard 開発者ガイド
Cognito (プレイヤー ID) ノード
出力
ポート
型
説明
Success
すべて
操作が成功するとアクティブ化されます
エラー
文字列
エラーが検出されるとアクティブ化されます。
ポートの値はエラーメッセージです
設定の変更をすべての AWS クライアントにすぐに適用したい場合は、[Apply] を選択します。[Apply]
が [false] に設定されている場合、変更を有効にするには、ApplyConfiguration (p. 258) フローノード
を追加する必要があります。
Cognito (プレイヤー ID) ノード
Amazon Cognito を使用して、以下のフローグラフノードを含むプレイヤー ID を設定します。
トピック
• ConfigureAnonymousPlayer ノード (p. 261)
• ConfigureAuthenticatedPlayer ノード (p. 262)
ConfigureAnonymousPlayer ノード
AWS アカウントで、匿名 ID をデバイスに作成します。
入力
ポート
型
説明
設定
すべて
匿名プレイヤーが Amazon Cognito を使用するようにゲームを設
定します
AWSAccountNumber
文字列
AWS アカウント番号。これは Amazon Cognito にアクセスする
ために必要です。
IdentityPoolID
文字列
Amazon Cognito ID プールに付いている一意の ID。ID プール
の ID を作成するには、AWS マネジメントコンソール にサイン
インし、https://console.aws.amazon.com/cognito/ で Amazon
Cognito コンソールを使用します。
CachingFileLocationOverride
文字列
これを指定すると、<HOME_DIR>/.aws/.identities の代わ
りに、指定したパスに Amazon Cognito ID がキャッシュされま
す。
出力
ポート
型
説明
Success
すべ
て
操作が成功するとアクティブ化されます
Version 1.6
261
Lumberyard 開発者ガイド
Cognito (プレイヤー ID) ノード
ポート
型
説明
エラー
文字
列
エラーが検出されるとアクティブ化されます。ポートの値はエ
ラーメッセージです
CognitoIdentityID
文字
列
ユーザーに付けられた一意の ID
プレイヤーが初めてゲームを実行し、このノードがトリガーされると、匿名 ID がプレイヤーに生成さ
れます。この ID はローカルに保持され、これ以降、ゲームを実行すると同じ ID が使用されます。
ConfigureAuthenticatedPlayer ノード
AWS アカウントで、認証された ID をデバイスに作成します。
入力
ポート
型
説明
設定
すべて
指定された値で Amazon Cognito を使用するよ
うゲームを設定します。
AWSAccountNumber
文字列
AWS アカウント番号。これは Amazon Cognito
の設定に必要です。
IdentityPoolID
文字列
Amazon Cognito ID プールに付いている一意の
ID。ID プール ID を編集するには、AWS マネジ
メントコンソール を開いて [Cognito] を選択しま
す。
ProviderName
文字列
ユーザーを認証するプロバイダーを指定します
ProviderToken
文字列
ユーザーの認証に使用するプロバイダーのトー
クン
ポート
型
説明
Success
すべて
操作が成功するとアクティブ化されます
エラー
文字列
エラーが検出されるとアクティブ化されます。
ポートの値はエラーメッセージです
CognitoIdentityID
文字列
ユーザーに付けられた一意の ID
出力
プレイヤーが初めてゲームを実行し、このノードがトリガーされると、認証された ID がプレイヤーに
生成されます。別のデバイスであっても、同じアカウントでユーザーがログインすると、常に同じ ID
が返されます。
Version 1.6
262
Lumberyard 開発者ガイド
DynamoDB (データベース) ノード
DynamoDB (データベース) ノード
これらフローグラフノードを使用して、ゲームを Amazon DynamoDB に接続できます。
トピック
• AtomicAdd ノード (p. 263)
• DeleteItem ノード (p. 264)
• GetItem ノード (p. 264)
• PutItem ノード (p. 265)
• Query ノード (p. 266)
• ScanTable ノード (p. 267)
• UpdateItem ノード (p. 268)
• GetStringSet ノード (p. 269)
AtomicAdd ノード
DynamoDB 内の属性に数を追加し、その数を返します。
入力
ポート
型
説明
追加
すべて
Value ポートで指定された val を DynamoDB に
書き込みます
テーブル名
文字列
書き込み先の DynamoDB テーブルの名前
TableKeyName
文字列
テーブルで使用するキー名
キー
文字列
書き込み先のキーを指定します
属性
文字列
書き込み先の属性を指定します
値
整数
書き込む値を指定します
ポート
型
説明
Success
すべて
操作が成功するとアクティブ化されます
エラー
文字列
エラーが検出されるとアクティブ化されます。
ポートの値はエラーメッセージです
NewValue
文字列
追加後の属性の値。
出力
これはアトミックオペレーションです。属性を使用する前にその属性を作成する必要はありません。
Version 1.6
263
Lumberyard 開発者ガイド
DynamoDB (データベース) ノード
DeleteItem ノード
DynamoDB 内のレコードを削除します。
入力
ポート
型
説明
DeleteItem すべ
て
指定された項目を DynamoDB から削除します。
テーブル
名
削除する DynamoDB テーブルの名前。
文字
列
TableKeyName
文字
列
テーブルで使用するキー名
KeyValue 文字
列
削除するキーを指定します。
出力
ポート
型
説明
Success すべて
操作が成功するとアクティブ化されます
エラー
エラーが検出されるとアクティブ化されます。ポートの値はエラーメッセージ
です
文字列
DeletedItems
すべて
一致する項目が見つかって削除されるとアクティブ化されます
NoResultsすべて
一致する結果が見つかりませんでした
GetItem ノード
DynamoDB から値を取得します。
入力
ポート
型
説明
GetItem
すべて
指定された項目を DynamoDB から取得します
Version 1.6
264
Lumberyard 開発者ガイド
DynamoDB (データベース) ノード
ポート
型
説明
テーブル名
文字列
読み取る DynamoDB テーブルの名前。
TableKeyName
文字列
テーブルで使用するキー名
KeyValue
文字列
読み取るキーを指定します
AttributeToReturn
文字列
読み取る属性を指定します
ポート
型
説明
Success
すべて
操作が成功するとアクティブ化されます
エラー
文字列
エラーが検出されるとアクティブ化されます。
ポートの値はエラーメッセージです
DataOut
文字列
DynamoDB から読み取られた文字列データ
NumberOut
文字列
DynamoDB から読み取られた数値データ
BoolOut
文字列
DynamoDB から読み取られたブール値
NoResults
すべて
指定されたテーブル、キー、および属性に一致
する結果が見つかりませんでした
出力
PutItem ノード
DynamoDB に値を書き込みます。
入力
ポート
型
説明
PutItem
すべて
指定された項目を DynamoDB に書き込みます。
テーブル名
文字列
書き込み先の DynamoDB テーブルの名前
TableKeyName
文字列
テーブルで使用するキー名
KeyValue
文字列
書き込むキーを指定します
AttributeToWrite
文字列
書き込む属性を指定します
DataIn
文字列
書き込むデータ
Version 1.6
265
Lumberyard 開発者ガイド
DynamoDB (データベース) ノード
ポート
型
説明
DataType
文字列
書き込むデータのデータ型
KeyMustNotExist
Boolean
true の場合、キーがすでに存在していない必要
があることを指定します。デフォルトは true で
す。false に設定すると、テーブル内の既存の
キーやそのキーの既存のすべての属性を上書き
して、新しいキーと新しい属性値に置き換える
ことができます。
ポート
型
説明
Success
すべて
操作が成功するとアクティブ化されます
エラー
文字列
エラーが検出されるとアクティブ化されます。
ポートの値はエラーメッセージです
KeyAlreadyExists
すべて
キーがすでに存在するため、変更されませんで
した
出力
Query ノード
DynamoDB での値のクエリを実行します。
入力
ポート
型
説明
Query
すべ
て
DynamoDB 内のテーブルデータのクエリを実行します
テーブル名
文字
列
クエリを実行する DynamoDB テーブルの名前。
TableKeyName
文字
列
クエリを実行するテーブルキーの名前。
KeyValue
文字
列
クエリを実行するキーの値
AttributeToCheck
文字
列
クエリを実行する属性
AttributeComparisonType文字
列
属性に対して行う比較のタイプ。デフォ
ルトは EQUALS です。デフォルト値以外
Version 1.6
266
Lumberyard 開発者ガイド
DynamoDB (データベース) ノード
ポート
型
説明
に、GREATER_THAN、GREATER_THAN_OR_EQUALS、LESS_THAN、LESS_THAN_OR_E
を指定できます。
AttributeComparisonValue文字
列
属性に対して比較する値
AttributeComparisonValueType
文字 AttributeComparisonValue のデータ型 (stringbool または
列
number)。デフォルトは string です。
出力
ポート
型
説明
Success
すべて
操作が成功するとアクティブ化されます
エラー
文字列
エラーが検出されるとアクティブ化されます。
ポートの値はエラーメッセージです
MatchFound
すべて
一致が見つかりました
NoMatch
すべて
一致は見つかりませんでした
ScanTable ノード
DynamoDB で比較テストに合格したエントリをスキャンします。
入力
ポート
型
説明
スキャン
すべ
て
指定された属性を使用して、DynamoDB テーブルデータでの一致を
スキャンします
テーブル名
文字
列
スキャンする DynamoDB テーブルの名前。
属性
文字
列
スキャンする属性
AttributeComparisonType文字
列
属性に対して行う比較のタイプ。デフォルトは EQUALS です。
AttributeComparisonValue
文字
列
属性に対して比較する値
AttributeComparisonValueType
文字 AttributeComparisonValue のデータ型 (stringbool または
列
number)。デフォルトは string です。
Version 1.6
267
Lumberyard 開発者ガイド
DynamoDB (データベース) ノード
出力
ポート
型
説明
Success
すべ
て
操作が成功するとアクティブ化されます
エラー
文字
列
エラーが検出されるとアクティブ化されます。ポートの値はエラーメッセージ
です
MatchesFound
すべ
て
正常に処理されたスキャンで見つかった一致の数
UpdateItem ノード
DynamoDB で既存の項目の属性値を更新します。
入力
ポート
型
説明
UpdateItem
すべて
DynamoDB の 1 つの項目を更新します
テーブル名
文字列
使用する DynamoDB テーブルの名前
TableKeyName
文字列
テーブル内のキーの名前
KeyValue
文字列
書き込むキーの値
AttributeToWrite
文字列
書き込む属性
DataIn
文字列
書き込むデータ
DataType
文字列
書き込むデータのデータ型
KeyMustExist
Boolean
指定されたキーがテーブルにすでに存在する必
要がある場合は true。デフォルトは true です。
AttributeMustExist
Boolean
指定されたキーの属性が存在する必要がある場
合は true。デフォルトは true です。
出力
ポー
ト
型
Successすべ
て
説明
操作が成功するとアクティブ化されます
Version 1.6
268
Lumberyard 開発者ガイド
Lambda (クラウド関数) ノード
ポー
ト
型
説明
エ
ラー
文字
列
エラーが検出されるとアクティブ化されます。ポートの値はエラーメッセージです
ConditionsFailed
すべ 見つからなかったキーまたは属性 (KeyMustExist または AttributeMustExist
て
条件が失敗した場合)
GetStringSet ノード
文字列セットのメンバーを取得します。
入力
ポート
型
説明
GetItem
すべて
DynamoDB からデータを読み取ります
テーブル名
文字列
使用する DynamoDB テーブルの名前
TableKeyName
文字列
テーブル内のキーの名前
KeyValue
文字列
書き込むキーの値
AttributeToWrite
文字列
書き込む属性
ポート
型
説明
Success
すべて
操作が成功するとアクティブ化されます
エラー
文字列
エラーが検出されるとアクティブ化されます。
ポートの値はエラーメッセージです
DataOut
文字列
DynamoDB から読み取られたデータ。セットの
各メンバーに対して一度ずつ DataOut ポートが
トリガーされます。
出力
Success ポートは、セットのすべてのメンバーが出力されていることを表します。
Lambda (クラウド関数) ノード
このフローグラフノードを使用して、AWS Lambda 関数を呼び出すことができます。
Version 1.6
269
Lumberyard 開発者ガイド
S3 (ストレージ) ノード
ノードを呼び出してください
入力
ポート
型
説明
呼び出し
す
べ
て
Args ポートを使ってオプションで JSON データを引数として提供し、Lambda 関
数を呼び出します。詳細については、AWS Lambda の「呼び出し」の「リクエス
トの構文」を参照してください。
機能の名
称
文
字
列
呼び出す Lambda 関数の名前。
Args
文
字
列
JSON 形式で引数として Lambda 関数呼び出しに送信される入力データ。詳細に
ついては、AWS Lambda の「呼び出し」の「リクエストの構文」を参照してくだ
さい。
出力
ポート
型
説明
Success
すべて
操作が成功するとアクティブ化されます
エラー
文字列
エラーが検出されるとアクティブ化されます。
ポートの値はエラーメッセージです
結果
文字列
エラーが発生しなかった場合に Lambda 関数に
よって出力されたデータ
S3 (ストレージ) ノード
以下のフローグラフノードを使用して、Amazon Simple Storage Service (Amazon S3) からファイル
をダウンロードおよびアップロードし、また、Amazon S3 の特定の場所を指すパブリック URL を生
成できます。
トピック
• DownloadFile ノード (p. 270)
• UploadFile ノード (p. 271)
• GeneratePublicUrl ノード (p. 272)
DownloadFile ノード
Amazon S3 からファイルをダウンロードします。
Version 1.6
270
Lumberyard 開発者ガイド
S3 (ストレージ) ノード
入力
ポート
型
説明
DownloadFile
すべて
Amazon S3 バケットからファイルデータを読み
取ります
BucketName
文字列
使用する Amazon S3 バケットの名前
KeyName
文字列
Amazon S3 からダウンロードするファイルの名
前
FileName
文字列
ダウンロードしたオブジェクトに使用するファ
イル名
ポート
型
説明
Success
すべて
操作が成功するとアクティブ化されます
エラー
文字列
エラーが検出されるとアクティブ化されます。
ポートの値はエラーメッセージです
出力
UploadFile ノード
ファイルを Amazon S3 にアップロードします。
入力
ポート
型
説明
UploadFile
すべて
Amazon S3 バケットにファイルをアップロード
します
BucketName
文字列
使用する Amazon S3 バケットの名前
KeyName
文字列
Amazon S3 にアップロードされたオブジェクト
に付ける名前。この値がその後の使用で変更さ
れない場合、既存の Amazon S3 オブジェクトが
上書きされます。
ContentType
文字列
アップロードされるオブジェクトに使
用する MIME コンテンツタイプ (たとえ
ば、text/html、video/mpeg、video/
avi、application/zip など)。このタイプは
Amazon S3 レコードに保存されます。このタイ
プを使用して、後で特定タイプのデータを識別
して取得できます。デフォルト: application/
octet-stream。
Version 1.6
271
Lumberyard 開発者ガイド
SNS (Notification Service) ノード
ポート
型
説明
FileName
文字列
アップロードするファイルの名前
ポート
型
説明
Success
すべて
操作が成功するとアクティブ化されます
エラー
文字列
エラーが検出されるとアクティブ化されます。
ポートの値はエラーメッセージです
出力
GeneratePublicUrl ノード
指定した Amazon S3 の場所を指す 署名付き URL を生成します。
入力
ポート
型
説明
PresignUrl
すべて
指定した Amazon S3 の場所を示す 署名付き
URL を生成します
BucketName
文字列
使用する Amazon S3 バケットの名前
KeyName
文字列
Amazon S3 にアップロードされたオブジェクト
に付ける名前。この値がその後の使用で変更さ
れない場合、既存の Amazon S3 オブジェクトが
上書きされます。
Http Request Method
文字列
署名する HTTP メソッド
(DELETE、GET、POST、または PUT)
ポート
型
説明
Success
すべて
操作が成功するとアクティブ化されます
エラー
文字列
エラーが検出されるとアクティブ化されます。
ポートの値はエラーメッセージです
Url
文字列
署名付き URL
出力
SNS (Notification Service) ノード
これらのフローグラフノードを使用して、Amazon Simple Notification Service (Amazon SNS) メッ
セージを処理することができます。
Version 1.6
272
Lumberyard 開発者ガイド
SNS (Notification Service) ノード
トピック
• ParseMessage ノード (p. 273)
• 通知ノード (p. 273)
• CheckArnSubscribed ノード (p. 274)
• SubscribeToTopic ノード (p. 275)
ParseMessage ノード
入力
ポート
型
説明
Parse
すべて
Amazon SNS メッセージから JSON 形式の件名
と本文テキストを抽出します。
メッセージ
文字列
逆シリアル化する JSON メッセージ。
ポート
型
説明
Success
すべて
操作が成功するとアクティブ化されます
エラー
文字列
エラーが検出されるとアクティブ化されます。
ポートの値はエラーメッセージです
本文
文字列
メッセージ本文
件名
文字列
メッセージの件名
出力
通知ノード
Amazon SNS トピックにメッセージを発行します。
入力
ポート
型
説明
通知
すべて
Amazon SNS トピックに通知を送信します。
Version 1.6
273
Lumberyard 開発者ガイド
SNS (Notification Service) ノード
ポート
型
説明
メッセージ
文字列
送信するメッセージ
件名
文字列
メッセージの件名
TopicARN
文字列
Amazon SNS トピックの Amazon リソースネー
ム
ポート
型
説明
Success
すべて
操作が成功するとアクティブ化されます
エラー
文字列
エラーが検出されるとアクティブ化されます。
ポートの値はエラーメッセージです
出力
CheckArnSubscribed ノード
ARN が Amazon SNS トピックにサブスクライブされるかどうかを確認します。
入力
ポート
型
説明
チェック
すべて
ARN が Amazon SNS トピックにサブスクライ
ブされるかどうかを確認します。
TopicARN
文字列
確認する Amazon SNS トピック ARN
エンドポイント
文字列
指定したトピックへのサブスクライブを確認す
るエンドポイント。エンドポイントは E メー
ルアドレス、Amazon SQS、キュー、または
Amazon SNS によってサポートされている他の
エンドポイントタイプのいずれかです。
出力
ポート
型
説明
Success すべ
て
操作が成功するとアクティブ化されます
エラー
文字
列
エラーが検出されるとアクティブ化されます。ポートの値はエラーメッセージで
す
True
すべ
て
ARN は Amazon SNS トピックにサブスクライブされます。
Version 1.6
274
Lumberyard 開発者ガイド
SQS (メッセージキューサービス) ノード
ポート
型
説明
False
すべ
て
ARN は Amazon SNS トピックに登録されません。
SubscribeToTopic ノード
Amazon SNS トピックに登録します。
入力
ポート
型
説明
サブスクリプション
すべて
トピックに発行されたメッセージを受信するた
め、そのトピックにサブスクライブします。
詳細については、「トピックへのサブスクライ
ブ」を参照してください。
プロトコル
文字列
サブスクライブ先のエンドポイントのプロトコ
ル
TopicARN
文字列
サブスクライブ先の Amazon SNS トピックの
ARN
エンドポイント
文字列
サブスクライブするエンドポイントのアドレス
(E メールアドレスなど)。HTTP または HTTPS
への送信については、「HTTP/HTTPS エンドポ
イントに Amazon SNS メッセージを送信」を参
照してください。
ポート
型
説明
Success
すべて
操作が成功するとアクティブ化されます
エラー
文字列
エラーが検出されるとアクティブ化されます。
ポートの値はエラーメッセージです
SubscriptionArn
文字列
作成されたサブスクリプションの ARN
出力
Amazon SNS の詳細については、「Amazon Simple Notification Service 開発者ガイド」を参照してく
ださい。
SQS (メッセージキューサービス) ノード
これらのフローグラフノードを使用して、AWS キューのポーリングを開始したり、AWS キューに
メッセージをプッシュすることができます。
トピック
Version 1.6
275
Lumberyard 開発者ガイド
SQS (メッセージキューサービス) ノード
• PollAndNotify ノード (p. 276)
• Push ノード (p. 276)
PollAndNotify ノード
入力
ポート
型
説明
開始
すべて
AWS キューのポーリングを開始する
QueueName
文字列
すでに作成されている AWS キューの名前
ポート
型
説明
Success
すべて
操作が成功するとアクティブ化されます
エラー
文字列
エラーが検出されるとアクティブ化されます。
ポートの値はエラーメッセージです
OnMessageReceived
文字列
スタックの最新メッセージ
QueueArn
文字列
キューの ARN (Amazon リソースネーム)
出力
Push ノード
AWS キューにメッセージをプッシュする
入力
ポート
型
説明
Push
すべて
AWS キューにメッセージをプッシュする
QueueName
文字列
すでに作成されている AWS キューの名前
メッセージ
文字列
送信するメッセージ
ポート
型
説明
Success
すべて
操作が成功するとアクティブ化されます
出力
Version 1.6
276
Lumberyard 開発者ガイド
静的データ (プロトタイプ) ノード
ポート
型
説明
エラー
文字列
エラーが検出されるとアクティブ化されます。
ポートの値はエラーメッセージです
静的データ (プロトタイプ) ノード
静的データは、監視された Amazon S3 バケットを通じて変更される頻度の低いゲームデータ管理を
管理する Lumberyard システムです。これらのフローグラフノードを使用して、自由なバケットの更
新やクエリ実行、または定期的な変更のモニタリング (またはその両方) を行うことができます。
トピック
• Add Monitored Bucket ノード (p. 277)
• Get Static Data ノード (p. 277)
• Load Static Data ノード (p. 278)
• Remove Monitored Bucket ノード (p. 279)
• バケットノードのリクエスト (p. 279)
• 更新頻度ノードの設定 (p. 280)
Add Monitored Bucket ノード
Amazon S3 バケットを監視対象に追加します。
入力
ポート
型
説明
AddBucket
Void
更新を監視するバケットを追加します。
BucketName
文字列
監視する Amazon S3 バケットの名前
ポート
型
説明
Success
すべて
操作が成功するとアクティブ化されます
エラー
文字列
エラーが検出されるとアクティブ化されます。
ポートの値はエラーメッセージです
Finished
文字列
バケットが追加されました。
出力
Get Static Data ノード
静的データ定義からフィールドを取得します。
Version 1.6
277
Lumberyard 開発者ガイド
静的データ (プロトタイプ) ノード
入力
ポート
型
説明
Get
Void
静的データから値を取得します。
StaticDataType
文字列
取得する静的データのタイプ
StaticDataId
文字列
テーブルの静的データ定義の識別子
StaticDataField
文字列
取得するデータのフィールド名
ActivateOnUpdate
Void
次にデータの更新が発生した際に、再度ノード
を起動します。
ポート
型
説明
Success
すべて
操作が成功するとアクティブ化されます
エラー
文字列
エラーが検出されるとアクティブ化されます。
ポートの値はエラーメッセージです
StringOut
文字列
文字列フィールドの出力
NumberOut
整数
数値フィールドの出力
BoolOut
Boolean
ブールの出力
FloatOut
整数
浮動小数点数値フィールドの出力
出力
Load Static Data ノード
指定されたタイプの静的データのロードを試行します。
入力
ポート
型
説明
Load
すべて
あるタイプの静的データをロードします。
StaticDataType
文字列
ロードする静的データのタイプ
Version 1.6
278
Lumberyard 開発者ガイド
静的データ (プロトタイプ) ノード
出力
ポート
型
説明
Success
すべて
操作が成功するとアクティブ化されます
エラー
文字列
エラーが検出されるとアクティブ化されます。
ポートの値はエラーメッセージです
Finished
文字列
ロード試行の完了
Remove Monitored Bucket ノード
監視対象バケットのリストからバケット名を削除します。
入力
ポート
型
説明
削除
すべて
監視対象バケットのリストからバケットを削除
します。
BucketName
文字列
削除するバケットの名前
ポート
型
説明
Success
すべて
操作が成功するとアクティブ化されます
エラー
文字列
エラーが検出されるとアクティブ化されます。
ポートの値はエラーメッセージです
Finished
文字列
バケットの削除完了
出力
バケットノードのリクエスト
特定のバケット、またはすべての監視対象バケットの更新をリクエストします。
入力
ポート
型
説明
RequestBucket
すべて
特定のバケット、またはすべての監視対象バ
ケットの更新をリクエストします。
Version 1.6
279
Lumberyard 開発者ガイド
リソースの定義
ポート
型
説明
BucketName
文字列
更新をリクエストするバケットの名前。すべて
のバケットの更新をリクエストするには、この
値を空白のままにします。
ポート
型
説明
Success
すべて
操作が成功するとアクティブ化されます
エラー
文字列
エラーが検出されるとアクティブ化されます。
ポートの値はエラーメッセージです
Finished
文字列
リクエストの送信完了
出力
更新頻度ノードの設定
監視対象バケットを定期的にポーリングするタイマーを設定またはクリアします。
入力
ポート
型
説明
SetTimer
Void
繰り返しタイマーを TimerValue で指定した値
に設定します。
TimerValue
整数
ポーリングする時間の間隔。有効な値は 0 から
100 です。値 0 はタイマーをクリアします。デ
フォルトは 0 です。
ポート
型
説明
Success
すべて
操作が成功するとアクティブ化されます
エラー
文字列
エラーが検出されるとアクティブ化されます。
ポートの値はエラーメッセージです
設定
文字列
タイマー設定の完了
出力
リソースの定義
リソース定義は、ゲーム用に AWS で作成されるリソース (DynamoDB データベース、Lambda 関
数、アクセス管理情報など) を決定する AWS CloudFormation テンプレートファイル形式の仕様で
す。ゲーム コードとフローグラフは AWS リソースを使用します。それらのリソースが存在し、特定
Version 1.6
280
Lumberyard 開発者ガイド
リソースの定義の場所
の方法で設定されていることが想定されています。リソース定義により、このアーキテクチャーと設
定が決まります。
リソースの定義の場所
ゲームによって要求されるリソースの記述は、{root}\{game}\AWS ディレクトリ下のファイルに
保存されます。{root} は Lumberyard インストール場所の \dev サブディレクトリ、{game} は
{root}\bootstrap.cfg ファイルの sys_game_folder プロパティによって識別されるディレク
トリです。たとえば、ゲームが SamplesProject の場合、リソース定義パスは C:\lumberyard\dev
\SamplesProject\AWS のようになります。これらのファイルは、他のゲームコードとデータととも
にプロジェクトのソース管理システムにチェックインされている必要があります。
デフォルトの {game}\AWS ディレクトリのコンテンツは、lmbr_aws create-project-stack (p. 225)
コマンドによって作成されます。
さらに、ユーザー固有の設定データは、{root}\Cache\{game}\pc\user\AWS ディレクトリに保存
されます。このディレクトリのコンテンツは、プロジェクトのソース管理システムにチェックインし
てはいけません。
次に、これらの AWS ディレクトリのコンテンツを示します。
{root}\{game}\AWS\
project-settings.json
project-template.json
deployment-template.json
deployment-access-template.json
project-code\
(Lambda function Code)
resource-groups\
{resource-group}\
resource-template.json
lambda-function-code\
(Lambda function Code)
{root}\Cache\{game}\pc\user\AWS\
user-settings.json
各 .json ファイルについては、続くセクションで説明します。
[project-settings.json]
project-settings.json ファイルには、プロジェクト設定データが含まれます。このファイルの構
造は、次のとおりです。
{
"{key}": "{value}",
"deployment": {
"{deployment}": {
"{key}": "{value}",
"resource-group": {
"{resource-group}": {
"{key}": "{value}"
}
}
}
}
}
Version 1.6
281
Lumberyard 開発者ガイド
[project-settings.json]
[{key}] と [{value}] ペアは個々の設定を表しています。ルートでのペアは、プロジェクトに適用さ
れます。[{deployment}] の下のペアはそのデプロイに適用されます。{resource-group} 下のペア
がそのリソースグループに適用されます。{deployment} と {resource-group} の一方または両方
を * にし、含まれる設定がすべてのデプロイまたはリソースグループにそれぞれ適用されることを示
すこともできます。* エントリの下での設定より、名前の入力の下での設定の方が優先されます。
次に、project-settings.json 設定ファイルの例を示します。
{
"ProjectStackId": "arn:aws:cloudformation:us-west-2:...",
"DefaultDeployment": "Development",
"ReleaseDeployment": "Release",
"deployment": {
"*": {
"resource-group": {
"HelloWorld": {
"parameter": {
"WriteCapacityUnits": 1,
"ReadCapacityUnits": 1,
"Greeting": "Hi"
}
}
}
},
"Development": {
"DeploymentStackId": "arn:aws:cloudformation:us-west-2:..."
"DeploymentAccessStackId": "arn:aws:cloudformation:us-west-2:..."
"resource-group": {
"HelloWorld": {
"parameter": {
"WriteCapacityUnits": 5,
"ReadCapacityUnits": 5
}
}
}
}
}
}
ProjectStackId のプロパティ
ProjectStackId プロパティは、プロジェクトの AWS CloudFormation スタックを識別します。こ
のスタックは、Lumberyard プロジェクトの管理をするため、Cloud Canvas によって使用されるリ
ソースが含まれています。
ProjectStackId プロパティは、create-project-stack (p. 225) コマンドによって設定されます。
何らかの理由でプロジェクトを既存のプロジェクトスタックと関連付ける場合、AWS マネジメン
トコンソール を使用してスタックの ARN を検索し、project-settings.json ファイル (AWS
CloudFormation に移動し、スタックを選択し、[Overview] を選択した後、Stack Id プロパティの値
をコピー) に貼り付けます。
DefaultDeployment のプロパティ
DefaultDeployment プロパティは、Lumberyard エディタ の使用時にデフォルトで使用されるデ
プロイを識別します。user-settings.json (p. 283) ファイルの DefaultDeployment プロ
パティは、この設定を上書きします。プロジェクトとユーザーデフォルトは、lmbr_aws defaultdeployment (p. 226) コマンドを使用して設定できます。DefaultDeployment 設定は、lmbr_aws
update-mappings (p. 234) コマンドでも使用されています。
Version 1.6
282
Lumberyard 開発者ガイド
user-settings.json
ReleaseDeployment のプロパティ
ReleaseDeployment プロパティは、ゲームのリリースビルドで使用されるデプロイを識別しま
す。ReleaseDeployment 設定では、lmbr_aws update-mappings (p. 234) コマンドが使用されま
す。
DeploymentStackId のプロパティ
DeploymentStackId プロパティは、デプロイ用の AWS CloudFormation スタックを識別します。プ
ロジェクトのリソースグループは、これらのスタックの子です。詳細については、「リソースのデプ
ロイ (p. 302)」を参照してください。
DeploymentStackId プロパティは、create-deployment (p. 224) コマンドによって設定されます。
何らかの理由でデプロイを既存のデプロイと関連付ける場合、AWS マネジメントコンソール を使用
してスタックの ARN を検索し、project-settings.json ファイル (AWS CloudFormation に移動
し、スタックを選択して、[Overview] を選択した後、Stack Id プロパティの値をコピー) に貼り付け
ます。
DeploymentAccessStackId のプロパティ
DeploymentAccessStackId プロパティは、デプロイへのアクセスをコントロールする、リソース
用の AWS CloudFormation スタックを識別します。
DeploymentAccessStackIdは、create-deployment (p. 224)コマンドによって設定されます。何ら
かの理由でデプロイを既存のデプロイスタックと関連付ける場合、AWS マネジメントコンソール を
使用してスタックの ARN を検索し、project-settings.json ファイル (AWS CloudFormation に
移動し、スタックを選択し、[Overview] を選択した後、Stack Id プロパティの値をコピー) に貼り付
けます。
パラメーターのプロパティ
parameter プロパティは、リソーステンプレートパラメーターの値を提供します。プロパティは、次
のようになります。
{
...
"parameter": {
"{template-parameter-name-1}": {template-parametervalue-1},
...
"{template-parameter-name-n}": {template-parametervalue-n}
}
...
}
user-settings.json
user-settings.json ファイルには、ユーザー専用の設定データが含まれます。
ファイルの場所
user-settings.json ファイルは、{root}\Cache\{game}\pc\user\AWS\usersettings.json にあります。プロジェクトの管理システムにチェックインされてはならないた
め、{root}\{game}\AWS ディレクトリの中に、このセクションで説明されている他のファイルと一
緒には含まれていません。
次に、user-settings.json ファイルの例を示します。
Version 1.6
283
Lumberyard 開発者ガイド
project-template.json
{
"DefaultDeployment": "Test",
"Mappings": {
"HelloWorld.SayHello": {
"ResourceType": "AWS::Lambda::Function",
"PhysicalResourceId": "MyGame-Test-xxxxxxxxxxxxx-HelloWorldyyyyyyyyyyyy-SayHello-zzzzzzzzzzzz"
}
}
}
DefaultDeployment のプロパティ
DefaultDeployment プロパティは、Lumberyard エディタ の使用時にデフォルトで使用される
デプロイを識別します。user-settings.json ファイルの DefaultDeployment プロパティ
は、[project-settings.json] (p. 281) ファイルのプロパティを上書きします。プロジェクト
とユーザーデフォルトは、lmbr_aws default-deployment (p. 226) コマンドを使用して設定できま
す。
マッピングのプロパティ
Mappings プロパティは、Lumberyard エディタ で使用される分かりやすい名前のマッピ
ングを実際のリソース名に指定します。たとえば、DailyGiftTable] DynamoDB テーブル
は、SamplesProject-DontDieDeployment-78AIXR0N0O4N-DontDieAWS-1I1ZC6YO7KU7FDailyGiftTable-1G4G33K16D8ZS のような名前にマッピングされます。
このプロパティは、デフォルトのデプロイが変更された場合、またはデフォルトのデプロイがアップ
デートされたとき、自動的にアップデートされます。lmbr_aws update-mappings (p. 234) コマンド
を使用して、このファイルを手動で更新することもできます。
project-template.json
project-template.json ファイルは、Cloud Canvas リソース管理システムをサポートするリソー
スを定義する AWS CloudFormation テンプレートです。
次に、project-template.json ファイルの例を示します。
{
"AWSTemplateFormatVersion": "2010-09-09",
"Metadata": {
"CloudCanvas": {
"Id": "$Revision: #6 $"
}
},
"Parameters": {
"ConfigurationKey": {
"Type": "String",
"Description": "Location in the configuration bucket of
configuration data."
}
},
"Resources": {
"Configuration": {
Version 1.6
284
Lumberyard 開発者ガイド
project-template.json
"Type": "AWS::S3::Bucket",
"DeletionPolicy": "Retain",
"Properties": {
"VersioningConfiguration": {
"Status": "Enabled"
},
"LifecycleConfiguration": {
"Rules": [
{
"Id": "DeleteOldVersions",
"NoncurrentVersionExpirationInDays": "2",
"Status": "Enabled"
},
{
"Id": "DeleteUploads",
"Prefix": "uploads",
"ExpirationInDays": 2,
"Status": "Enabled"
}
]
}
}
},
"ProjectPlayerAccessTokenExchangeHandlerRole": {
"Type": "AWS::IAM::Role",
"Properties": {
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Principal": {
"Service": "lambda.amazonaws.com"
}
}
]
},
"Policies": [
{
"PolicyName": "PlayerAccessTokenExchange",
"PolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Sid": "WriteLogs",
"Effect": "Allow",
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents"
],
"Resource": "arn:aws:logs:*:*:*"
},
{
"Sid": "GetAuthSettings",
"Action": [
"s3:GetObject",
Version 1.6
285
Lumberyard 開発者ガイド
project-template.json
"s3:HeadObject"
],
"Effect": "Allow",
"Resource": [
{ "Fn::Join": [ "",
[ "arn:aws:s3:::", { "Ref": "Configuration" }, "/player-access/authsettings.json" ]] }
]
},
{
"Sid": "DescribeStacks",
"Action": [
"cloudformation:DescribeStackResources",
"cloudformation:DescribeStackResource"
],
"Effect": "Allow",
"Resource": [
"*"
]
}
]
}
}
]
}
},
"ProjectResourceHandlerExecution": {
"Type": "AWS::IAM::Role",
"Properties": {
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Principal": {
"Service": "lambda.amazonaws.com"
}
}
]
},
"Policies": [
{
"PolicyName": "ProjectAccess",
"PolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Sid": "WriteLogs",
"Effect": "Allow",
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents"
],
"Resource": "arn:aws:logs:*:*:*"
Version 1.6
286
Lumberyard 開発者ガイド
project-template.json
},
{
"Sid":
"ReadAndWriteUploadedConfiguration",
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject"
],
"Resource": { "Fn::Join": [ "",
[ "arn:aws:s3:::", { "Ref": "Configuration" }, "/upload/*" ]] }
},
{
"Sid": "DescribeStacksAndResources",
"Effect": "Allow",
"Action": [
"cloudformation:DescribeStackResources",
"cloudformation:DescribeStackResource",
"cloudformation:DescribeStacks"
],
"Resource": [
"*"
]
},
{
"Sid": "ManagePlayerAndFunctionRoles",
"Effect": "Allow",
"Action": [
"iam:CreateRole",
"iam:DeleteRole",
"iam:GetRole",
"iam:DeleteRolePolicy",
"iam:PutRolePolicy"
],
"Resource": { "Fn::Join": [ "",
[ "arn:aws:iam::", {"Ref": "AWS::AccountId"}, ":role/", {"Ref":
"AWS::StackName"}, "/*"]] }
},
{
"Sid": "CreateUpdateCognitoIdentity",
"Effect": "Allow",
"Action": [
"cognito-identity:*"
],
"Resource": { "Fn::Join": [ "",
[ "arn:aws:cognito-identity:", {"Ref": "AWS::Region" }, ":", { "Ref":
"AWS::AccountId" }, ":identitypool/*" ]] }
},
{
"Sid": "ReadPlayerAccessConfiguration",
"Effect": "Allow",
"Action": [
"s3:GetObject"
],
"Resource": { "Fn::Join": [ "",
[ "arn:aws:s3:::", { "Ref": "Configuration" }, "/player-access/authsettings.json" ]] }
Version 1.6
287
Lumberyard 開発者ガイド
project-template.json
}
]
}
}
]
}
},
"ProjectResourceHandler": {
"Type": "AWS::Lambda::Function",
"Properties": {
"Description": "Implements the custom resources used in this
project's templates.",
"Handler": "custom_resource.handler",
"Role": { "Fn::GetAtt": [ "ProjectResourceHandlerExecution",
"Arn" ] },
"Runtime": "python2.7",
"Timeout" : 90,
"Code": {
"S3Bucket": { "Ref": "Configuration" },
"S3Key": { "Fn::Join": [ "/", [ { "Ref":
"ConfigurationKey" }, "project-code.zip" ]] }
}
}
},
"ProjectPlayerAccessTokenExchangeHandler": {
"Type": "AWS::Lambda::Function",
"Properties": {
"Description": "Implements the token exchange for oAuth and
openid used for player access.",
"Handler": "auth_token_exchange.handler",
"Role": { "Fn::GetAtt":
[ "ProjectPlayerAccessTokenExchangeHandlerRole", "Arn" ] },
"Runtime": "python2.7",
"Code": {
"S3Bucket": { "Ref": "Configuration" },
"S3Key": { "Fn::Join": [ "/", [ { "Ref":
"ConfigurationKey" }, "project-code.zip" ]] }
}
}
}
}
}
ConfigurationKey パラメーター
ConfigurationKey パラメーターは、設定バケット内にある設定データの場所を識別します。パ
ラメーター値は、テンプレートを使って AWS CloudFormation スタックをアップデートする場合
に、Cloud Canvas によって設定されます。
設定リソース
Configuration リソースは、プロジェクト設定データの保存に使用される Amazon S3 バケットにつ
いて説明します。
Version 1.6
288
Lumberyard 開発者ガイド
deployment-template.json
ProjectPlayerAccessTokenExchangeHandlerRole リソース
ProjectPlayerAccessTokenExchangeHandlerRole リソース
は、ProjectPlayerAccessTokenExchangeHandler リソースの許可に使用される IAM ロールにつ
いて説明します。
ProjectResourceHandlerExecution リソース
ProjectResourceHandlerExecution リソースは、ProjectResourceHandler Lambda 関数リ
ソースへの許可に使用される IAM ロールについて説明します。
ProjectResourceHandler リソース
ProjectResourceHandler リソースは、プロジェクトの AWS CloudFormation テンプレートに使
用される AWS CloudFormation カスタムリソースハンドラーを実装する Lambda 関数について説明
します。この Lambda 関数のコードは {game}\AWS\project-code ディレクトリから、lmbr_aws
create-project-stack (p. 225) と update-project-stack (p. 235) コマンドによってアップロードされ
ます。詳細については、「カスタムリソース (p. 306)」を参照してください。
ProjectPlayerAccessTokenExchangeHandler リソース
ProjectPlayerAccessTokenExchangeHandler リソースは、プレイヤアクセスにトークン交換プ
ロセスを実装する Lambda 機能について説明します。この Lambda 関数のコードは、{game}\AWS
\project-code ディレクトリから、lmbr_aws create-project-stack (p. 225) と update-projectstack (p. 235) コマンドによってアップロードされます。詳細については、「アクセスコントロール
とプレイヤ ID (p. 310)」を参照してください。
deployment-template.json
deployment-template.json ファイルは、各プロジェクトのリソースグループの子 AWS
CloudFormation スタックリソースを定義する AWS CloudFormation テンプレートです。次に示すとお
り、各リソースグループはゲームが使用する AWS リソースの任意グループです。
次に、deployment-template.json ファイルの例を示します。
{
"AWSTemplateFormatVersion": "2010-09-09",
"Metadata": {
"CloudCanvas": {
"Id": "$Revision: #4 $"
}
},
"Parameters" : {
"ProjectResourceHandler": {
"Type": "String",
"Description": "Service token of the custom resource handler."
},
"ConfigurationBucket": {
"Type": "String",
"Description": "Bucket that contains configuration data."
},
"ConfigurationKey": {
"Type": "String",
"Description": "Location in the configuration bucket of
configuration data."
Version 1.6
289
Lumberyard 開発者ガイド
deployment-template.json
} ,
"DeploymentName": {
"Type": "String",
"Description": "The name of the deployment associated with this
stack."
},
"ProjectStackId": {
"Type": "String",
"Description": "The ARN of the project stack associated with this
deployment."
}
},
"Resources": {
"HelloWorldConfiguration" : {
"Type": "Custom::ResourceGroupConfiguration",
"Properties": {
"ServiceToken": { "Ref": "ProjectResourceHandler" },
"ConfigurationBucket": { "Ref": "ConfigurationBucket" },
"ConfigurationKey": { "Ref": "ConfigurationKey" },
"ResourceGroup": "HelloWorld"
}
},
"HelloWorld": {
"Type": "AWS::Cloud Formation::Stack",
"Properties": {
"TemplateURL": { "Fn::GetAtt": [ "HelloWorldConfiguration",
"TemplateURL" ] },
"Parameters": {
"ProjectResourceHandler": { "Ref":
"ProjectResourceHandler" },
"ConfigurationBucket": { "Fn::GetAtt":
[ "HelloWorldConfiguration", "ConfigurationBucket" ] },
"ConfigurationKey": { "Fn::GetAtt":
[ "HelloWorldConfiguration", "ConfigurationKey" ] }
}
}
}
},
"Outputs": {
"StackName": {
"Description": "The deployment stack name.",
"Value": {"Ref": "AWS::StackName"}
}
}
}
パラメーター
deployment-template.json ファイルには、次のパラメーターがあります。パラメーター値は、テ
ンプレートを使用して AWS CloudFormation スタックをアップデートするときに Cloud Canvas から
提供されます。
ProjectResourceHandler パラメーター
ProjectResourceHandler パラメーターは、プロジェクトに使用されるカスタムリソースハンド
ラー Lambda 関数を識別します。
Version 1.6
290
Lumberyard 開発者ガイド
deployment-access-template.json
ConfigurationBucket パラメーター
ConfigurationBucket パラメーターは、設定バケットを識別します。
ConfigurationKey パラメーター
ConfigurationKey パラメーターは、設定バケット内にある設定データの場所を識別します。
DeploymentName パラメーター
DeploymentName パラメーターは、このスタックに関連したデプロイ名を識別します。
ProjectStackId パラメーター
ProjectStackId パラメーターは、このデプロイに関連したプロジェクトスタックを識別します。
リソース
deployment-template.json ファイルは、2 つのリソースを識別します。
HelloWorldConfiguration リソース
HelloWorldConfiguration リソースは、HelloWorld リソースを設定するのに使用される
ResourceGroupConfiguration (p. 307) カスタムリソースを説明します。
deployment-template.json ファイルには、各プロジェクトのリソースグループの似たような
ResourceGroupConfiguration リソースが含まれます。
HelloWorld リソース
HelloWorld リソースは、プロジェクトの HelloWorld リソースグループを実装する AWS
CloudFormation スタックについて説明します。
deployment-template.json ファイルには、各プロジェクトのリソースグループの似たような
AWS CloudFormation スタックリソースが含まれます。
出力
テンプレートの Outputs セクションでは、テンプレートが生成する値を定義します。
deployment-access-template.json
deployment-access-template.json ファイルは、デプロイを保護するのに使用されるリソースを
定義する AWS CloudFormation テンプレートです。
次に、deployment-access-template.json の例を示します。
{
"AWSTemplateFormatVersion": "2010-09-09",
"Metadata": {
"CloudCanvas": {
"Id": "$Revision: #6 $"
}
},
"Parameters": {
"ProjectResourceHandler": {
"Type": "String",
Version 1.6
291
Lumberyard 開発者ガイド
deployment-access-template.json
"Description": "The the project resource handler lambda ARN."
},
"ConfigurationBucket": {
"Type": "String",
"Description": "Bucket that contains configuration data."
},
"ConfigurationKey": {
"Type": "String",
"Description": "Key that contains the current upload location."
},
"ProjectPlayerAccessTokenExchangeHandler": {
"Type": "String",
"Description": "ARN for the lambda that the login cognitoidentity pool needs access to."
},
"ProjectStack": {
"Type": "String",
"Description": "The name of the project stack."
},
"DeploymentName": {
"Type": "String",
"Description": "The name of the deployment."
},
"DeploymentStack": {
"Type": "String",
"Description": "The name of the deployment stack."
},
"DeploymentStackArn": {
"Type": "String",
"Description": "The ARN of the deployment stack."
}
},
"Resources": {
"OwnerPolicy": {
"Type": "AWS::IAM::ManagedPolicy",
"Properties": {
"Description": "Policy that grants permissions to update a
deployment stack, and all of it's resource group stacks.",
"Path": { "Fn::Join": [ "", [ "/", { "Ref": "ProjectStack" },
"/", { "Ref": "DeploymentName" }, "/" ]] },
"PolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Sid":
"ReadProjectDeploymentAndResourceGroupStackState",
"Effect": "Allow",
"Action": [
"cloudformation:DescribeStackResource",
Version 1.6
292
Lumberyard 開発者ガイド
deployment-access-template.json
"cloudformation:DescribeStackResources",
"cloudformation:DescribeStackEvents"
],
"Resource": [
{ "Fn::Join": [ "",
[ "arn:aws:cloudformation:", { "Ref": "AWS::Region" }, ":", { "Ref":
"AWS::AccountId" }, ":stack/", { "Ref": "ProjectStack" }, "/*" ]] },
{ "Fn::Join": [ "",
[ "arn:aws:cloudformation:", { "Ref": "AWS::Region" }, ":", { "Ref":
"AWS::AccountId" }, ":stack/", { "Ref": "ProjectStack" }, "-*" ]] },
{ "Fn::Join": [ "",
[ "arn:aws:cloudformation:", { "Ref": "AWS::Region" }, ":", { "Ref":
"AWS::AccountId" }, ":stack/", { "Ref": "DeploymentStack" }, "/*" ]] },
{ "Fn::Join": [ "",
[ "arn:aws:cloudformation:", { "Ref": "AWS::Region" }, ":", { "Ref":
"AWS::AccountId" }, ":stack/", { "Ref": "DeploymentStack" }, "-*" ]] }
]
},
{
"Sid": "InvokeProjectResourceHandler",
"Effect": "Allow",
"Action": [
"lambda:InvokeFunction"
],
"Resource": [
{ "Ref": "ProjectResourceHandler" }
]
},
{
"Sid":
"ReadAndWriteDeploymentAndResourceGroupConfiguration",
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject"
],
"Resource": [
{ "Fn::Join": [ "", [ "arn:aws:s3:::",
{ "Ref": "ConfigurationBucket" }, "/upload/*/deployment/", { "Ref":
"DeploymentName" }, "/*" ]] }
]
},
{
"Sid": "UpdateDeploymentStack",
"Effect": "Allow",
"Action": [
"cloudformation:UpdateStack"
],
"Resource": [
{ "Fn::Join": [ "",
[ "arn:aws:cloudformation:", { "Ref": "AWS::Region" }, ":", { "Ref":
"AWS::AccountId" }, ":stack/", { "Ref": "DeploymentStack" }, "/*" ]] }
]
},
{
"Sid":
"CreateUpdateAndDeleteResourceGroupStacks",
"Effect": "Allow",
"Action": [
Version 1.6
293
Lumberyard 開発者ガイド
deployment-access-template.json
"cloudformation:CreateStack",
"cloudformation:UpdateStack",
"cloudformation:DeleteStack"
],
"Resource": [
{ "Fn::Join": [ "",
[ "arn:aws:cloudformation:", { "Ref": "AWS::Region" }, ":", { "Ref":
"AWS::AccountId" }, ":stack/", { "Ref": "DeploymentStack" }, "-*" ]] }
]
},
{
"Sid":
"FullAccessToDeploymentAndResourceGroupResources",
"Effect": "Allow",
"Action": [
"dynamodb:*",
"s3:*",
"sqs:*",
"sns:*",
"lambda:*"
],
"Resource": [
{ "Fn::Join": [ "", [ "arn:aws:dynamodb:",
{ "Ref": "AWS::Region" }, ":", { "Ref": "AWS::AccountId" }, ":table/",
{ "Ref": "DeploymentStack" }, "-*" ]] },
{ "Fn::Join": [ "", [ "arn:aws:s3:::",
{ "Ref": "DeploymentStack" }, "-*" ] ] },
{ "Fn::Join": [ "", [ "arn:aws:sqs:",
{ "Ref": "AWS::Region" }, ":", { "Ref": "AWS::AccountId" }, ":", { "Ref":
"DeploymentStack" }, "-*" ]] },
{ "Fn::Join": [ "", [ "arn:aws:sns:*:",
{ "Ref": "AWS::AccountId" }, ":", { "Ref": "DeploymentStack" }, "-*" ] ] },
{ "Fn::Join": [ "", [ "arn:aws:lambda:",
{ "Ref": "AWS::Region" }, ":", { "Ref": "AWS::AccountId" }, ":function:",
{ "Ref": "DeploymentStack" }, "-*" ]] }
]
},
{
"Sid": "PassDeploymentRolesToLambdaFunctions",
"Effect": "Allow",
"Action": [
"iam:PassRole"
],
"Resource": [
{ "Fn::Join": [ "", [ "arn:aws:iam::",
{"Ref": "AWS::AccountId"}, ":role/", {"Ref": "ProjectStack"}, "/", {"Ref":
"DeploymentName"}, "/*"]] }
]
},
{
"Sid": "CreateLambdaFunctions",
"Effect": "Allow",
"Action": "lambda:CreateFunction",
"Resource": "*"
}
]
}
}
},
Version 1.6
294
Lumberyard 開発者ガイド
deployment-access-template.json
"Owner": {
"Type": "AWS::IAM::Role",
"Properties": {
"Path": { "Fn::Join": [ "", [ "/", { "Ref": "ProjectStack" },
"/", { "Ref": "DeploymentName" }, "/" ]] },
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AccountUserAssumeRole",
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Principal": { "AWS": {"Ref": "AWS::AccountId"} }
}
]
},
"ManagedPolicyArns": [
{ "Ref": "OwnerPolicy" }
]
}
},
"Player": {
"Type": "AWS::IAM::Role",
"Properties": {
"Path": { "Fn::Join": [ "", [ "/", { "Ref": "ProjectStack" },
"/", { "Ref": "DeploymentName" }, "/" ]] },
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "sts:AssumeRoleWithWebIdentity",
"Principal": {
"Federated": "cognito-identity.amazonaws.com"
}
}
]
}
}
},
"PlayerAccess": {
"Type": "Custom::PlayerAccess",
"Properties": {
"ServiceToken": { "Ref": "ProjectResourceHandler" },
"ConfigurationBucket": { "Ref": "ConfigurationBucket" },
"ConfigurationKey": { "Ref": "ConfigurationKey" },
"DeploymentStack": { "Ref": "DeploymentStackArn" }
},
"DependsOn": [ "Player" ]
},
"PlayerLoginRole": {
"Type": "AWS::IAM::Role",
"Properties": {
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
Version 1.6
295
Lumberyard 開発者ガイド
deployment-access-template.json
"Statement": [
{
"Effect": "Allow",
"Action": "sts:AssumeRoleWithWebIdentity",
"Principal": {
"Federated": "cognito-identity.amazonaws.com"
}
}
]
},
"Policies": [
{
"PolicyName": "ExchangeTokenAccess",
"PolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Sid": "PlayerLoginExecution",
"Effect": "Allow",
"Action": [ "lambda:InvokeFunction" ],
"Resource": { "Ref":
"ProjectPlayerAccessTokenExchangeHandler" }
}
]
}
}
]
}
},
"PlayerLoginIdentityPool": {
"Type": "Custom::CognitoIdentityPool",
"Properties": {
"ServiceToken": { "Ref": "ProjectResourceHandler" },
"AllowUnauthenticatedIdentities": "true",
"UseAuthSettingsObject": "false",
"ConfigurationBucket": { "Ref": "ConfigurationBucket" },
"ConfigurationKey": { "Ref": "ConfigurationKey" },
"IdentityPoolName": "PlayerLogin",
"Roles": {
"unauthenticated": { "Fn::GetAtt": [ "PlayerLoginRole",
"Arn" ] }
}
}
},
"PlayerAccessIdentityPool": {
"Type": "Custom::CognitoIdentityPool",
"Properties": {
"ServiceToken": { "Ref": "ProjectResourceHandler" },
"AllowUnauthenticatedIdentities": "true",
"UseAuthSettingsObject": "true",
"ConfigurationBucket": { "Ref": "ConfigurationBucket" },
"ConfigurationKey": { "Ref": "ConfigurationKey" },
"IdentityPoolName": "PlayerAccess",
"Roles": {
"unauthenticated": { "Fn::GetAtt": [ "Player",
"Arn"] },
"authenticated": { "Fn::GetAtt": [ "Player", "Arn" ] }
Version 1.6
296
Lumberyard 開発者ガイド
deployment-access-template.json
}
}
}
}
}
パラメーター
デプロイアクセススタックは、デプロイのセキュリティを設定するのに必要なデプロイとその他のリ
ソースを識別するパラメーターを定義します。これらの各パラメーターの値は、デプロイ作成時に
Cloud Canvas によって提供されます。
リソース
このセクションでは、deployment-access-template.json ファイル例で定義されているリソース
について説明します。
OwnerPolicy リソース
OwnerPolicy リソースは、デプロイにオーナーレベルアクセスを与える IAM 管理ポリシーについて
説明します。AWS アカウント管理者は常にデプロイへのフルアクセスがありますが、他のユーザー
のアクセスを特定のデプロイに制限することが推奨されています。そのためには、OwnerPolicy を
IAM ユーザー (または、デプロイアクセステンプレートによっても定義された Owner ロールを使用可)
に添付します。
オーナーアクセスには、次のものが含まれています。
• デプロイとそのすべてのリソースグループをアップデートする機能。
• デプロイ用に作成されたグループのリソースへのフルアクセス。
詳細については、「プロジェクトのアクセスコントロール (p. 310)」を参照してください。
オーナーリソース
Owner リソースは、OwnerPolicy が添付された IAM ロールについて説明します。
詳細については、「プロジェクトのアクセスコントロール (p. 310)」を参照してください。
プレイヤのリソース
Player リソースは、プレイヤに許可されたアクセスを識別する IAM ロールについて説明しま
す。たとえば、ゲームが Lambda 関数を呼び出す場合、プレイヤは Lambda 関数リソースで
lambda:InvokeFunction アクションが許可される必要があります。
ロールのポリシーは、プロジェクトのリソーステンプレート (PlayerAccessresourcetemplate.json (p. 298) ###) ######## メタデータ要素によって決定されます。
ロールのポリシーは、deployment-access-template.json (p. 291) と resourcetemplate.json (p. 298) ファイルに表示される PlayerAccess カスタムリソースによってアッ
プデートされます。PlayerAccessIdentityPool Amazon Cognito ID プール は、プレイヤがこの
ロールを引き受けられるようにします。
詳細については、「PlayerAccessIdentityPool リソース (p. 298)」および「アクセスコントロールと
プレイヤ ID (p. 310)」を参照してください。
PlayerAccess リソース
PlayerAccess リソースは、PlayerAccessIdentityPool リソース (p. 298) について説明します。こ
のリソースは、プレイヤがアクセスできるリソースにある PlayerAccess メタデータを使用してプレイ
ヤのロールを設定します。
Version 1.6
297
Lumberyard 開発者ガイド
プロジェクトコードのサブディレクトリ
詳細については、「アクセスコントロールとプレイヤ ID (p. 310)」を参照してください。
PlayerLoginRole リソース
PlayerLoginRole リソースは、ログインプロセスの一環としてプレイヤによって一時的に引き受け
られた IAM ロールについて説明します。
詳細については、「アクセスコントロールとプレイヤ ID (p. 310)」を参照してください。
PlayerLoginIdentityPool リソース
PlayerLoginIdentityPool リソースは、ログインプロセス中にプレイヤに一時的なアイデンティ
ティを提供する Amazon Cognito ID プールについて説明します。
詳細については、「アクセスコントロールとプレイヤ ID (p. 310)」を参照してください。
PlayerAccessIdentityPool リソース
PlayerAccessIdentityPool リソースは、ログインプロセス中にプレイヤに一時的なアイデンティ
ティを提供する Amazon Cognito ID プールについて説明します。
詳細については、「アクセスコントロールとプレイヤ ID (p. 310)」を参照してください。
プロジェクトコードのサブディレクトリ
project-code サブディレクトリには、プロジェクトの AWS CloudFormation テンプレートで使用
される AWS CloudFormation カスタムリソースハンドラーのソースコードが含まれます。カスタムリ
ソースの管理の詳細については、「カスタムリソース (p. 306)」を参照してください
また、プレイヤのログインプロセスでトークンを交換するステップを実行するコードが含まれます。
詳細については、「アクセスコントロールとプレイヤ ID (p. 310)」を参照してください。
resource-group\{resource-group} サブディレクトリ
ゲームが使用する AWS リソースは別々のリソースグループとして整理され、親 resource-group
ディレクトリ下の個別の {resource-group} サブディレクトリによって表されます。resourcegroup ディレクトリは、任意の数の {resource-group} サブディレクトリを含むことがあり、通常
はそれぞれゲームプロジェクト名にちなんで名前が付けられます。
resource-template.json
resource-template.json ファイルは、各リソースグループに関連した AWS リソースを定義
する AWS CloudFormation テンプレートです。resource-template.json ファイルで、AWS
CloudFormation によってサポートされている任意の AWS リソースタイプを指定できます。使用でき
るリソースタイプのリストについては、AWS CloudFormation の「AWS リソースタイプリファレン
ス」を参照してください。
次の resource-template.json ファイル例では、ゲームによって実行され、プレイヤーへの挨拶を
生成する SayHello Lambda 関数を定義します。生成されたメッセージは、DynamoDB テーブルに保
存されます。
{
"AWSTemplateFormatVersion": "2010-09-09",
"Metadata": {
"CloudCanvas": {
"Id": "$Revision: #3 $"
}
},
Version 1.6
298
Lumberyard 開発者ガイド
resource-template.json
"Parameters": {
"ProjectResourceHandler": {
"Type": "String",
"Description": "Service token of the custom resource handler."
},
"ConfigurationBucket": {
"Type": "String",
"Description": "Bucket that contains configuration data."
},
"ConfigurationKey": {
"Type": "String",
"Description": "Location in the configuration bucket of
configuration data."
},
"ReadCapacityUnits": {
"Type": "Number",
"Default": "1",
"Description": "Number of game state reads per second."
},
"WriteCapacityUnits": {
"Type": "Number",
"Default": "1",
"Description": "Number of game state writes per second."
},
"Greeting": {
"Type": "String",
"Default": "Hello",
"Description": "Greeting used by the SayHello Lambda function."
}
},
"Resources": {
"Messages": {
"Type": "AWS::DynamoDB::Table",
"Properties": {
"AttributeDefinitions": [
{
"AttributeName": "PlayerId",
"AttributeType": "S"
}
],
"KeySchema": [
{
"AttributeName": "PlayerId",
"KeyType": "HASH"
}
],
"ProvisionedThroughput": {
"ReadCapacityUnits": { "Ref": "ReadCapacityUnits" },
"WriteCapacityUnits": { "Ref": "WriteCapacityUnits" }
}
Version 1.6
299
Lumberyard 開発者ガイド
resource-template.json
},
"Metadata": {
"CloudCanvas": {
"FunctionAccess": [
{
"FunctionName": "SayHello",
"Action": "dynamodb:PutItem"
}
]
}
}
},
"SayHelloConfiguration": {
"Type": "Custom::LambdaConfiguration",
"Properties": {
"ServiceToken": { "Ref": "ProjectResourceHandler" },
"ConfigurationBucket": { "Ref": "ConfigurationBucket" },
"ConfigurationKey": { "Ref": "ConfigurationKey" },
"FunctionName": "SayHello",
"Runtime": "python2.7",
"Settings": {
"MessagesTable": { "Ref": "Messages" },
"Greeting": { "Ref": "Greeting" }
}
}
},
"SayHello": {
"Type": "AWS::Lambda::Function",
"Properties": {
"Description": "Example of a function called by the game to
write data into a DynamoDB table.",
"Handler": "main.say_hello",
"Role": { "Fn::GetAtt": [ "SayHelloConfiguration",
"Role" ] },
"Runtime": { "Fn::GetAtt": [ "SayHelloConfiguration",
"Runtime" ] },
"Code": {
"S3Bucket": { "Fn::GetAtt": [ "SayHelloConfiguration",
"ConfigurationBucket" ] },
"S3Key": { "Fn::GetAtt": [ "SayHelloConfiguration",
"ConfigurationKey" ] }
}
},
"Metadata": {
"CloudCanvas": {
"PlayerAccess": {
"Action": "lambda:InvokeFunction"
}
}
}
},
"PlayerAccess": {
"Type": "Custom::PlayerAccess",
"Properties": {
"ServiceToken": { "Ref": "ProjectResourceHandler" },
"ConfigurationBucket": { "Ref": "ConfigurationBucket" },
Version 1.6
300
Lumberyard 開発者ガイド
resource-template.json
"ConfigurationKey": { "Ref": "ConfigurationKey" },
"ResourceGroupStack": { "Ref": "AWS::StackId" }
},
"DependsOn": [ "SayHello" ]
}
}
}
リソーステンプレートのパラメーター
このセクションでは、resource-template.json ファイル例で定義されているパラメーターについ
て説明します。パラメーター値は、テンプレートを使用して AWS CloudFormation スタックをアップ
デートするときに Cloud Canvas から提供されます。
ProjectResourceHandler パラメーター
ProjectResourceHandler パラメーターは、プロジェクトに使用されるカスタムリソースハンド
ラー Lambda 関数を識別します。
ConfigurationBucket パラメーター
ConfigurationBucket パラメーターは、設定バケットを識別します。
ConfigurationKey パラメーター
ConfigurationKey パラメーターは、設定バケット内にある設定データの場所を識別します。
ReadCapacityUnits および WriteCapacityUnits パラメーター
ReadCapacityUnits と WriteCapacityUnits パラメーターは、テンプレートによって定義さ
れた Messages リソースの設定に使用します。これらを含むパラメーターの値は、通常 [projectsettings.json] (p. 281) によって提供させれ、各デプロイ用にカスタマイズできます。
リソース テンプレートのリソース
このセクションでは、resource-template.json ファイル例で定義されているリソースについて説
明します。
メッセージのリソース
Messages リソースは、DynamoDB テーブルについて説明します。AWS CloudFormation DynamoDB
リソース定義形式の詳細については、AWS::DynamoDB::Table を参照してください。
リソース定義の Metadata.CloudCanvas.FunctionAccess プロパティ
は、SayHelloConfiguration カスタムリソースによって使用され、テーブルにデータを書き込む許
可を SayHello Lambda 関数リソースに与えます。詳細については、「Lambda 関数のアクセスコン
トロール (p. 311)」を参照してください。
SayHelloConfiguration リソース
SayHelloConfiguration リソースは、SayHello Lambda 関数リソースに対する各種設定入力を提
供する LambdaConfiguration (p. 308) について説明します。
このリソースの Settings プロパティは、SayHello Lambda 関数に設定データを渡すために使用し
ます。詳細については、「LambdaConfiguration (p. 308)」を参照してください。
Version 1.6
301
Lumberyard 開発者ガイド
lambda-function-code サブディレクトリ
SayHello リソース
SayHello リソースは、Lambda ゲームのロジックの一部を実装する関数リソースにつ
いて説明します。AWS CloudFormation Lambda 関数リソースの定義形式の詳細について
は、AWS::Lambda::Function を参照してください。
関数が実行されたときに持つ AWS 許可を決定する Lambda 関数の Execution ロール
は、SayHelloConfiguration リソースによって生成され、関数がアクセスできるリソース上に表示
される Metadata.CloudCanvas.FunctionAccess プロパティを使用します。
リソース定義の Metadata.CloudCanvas.PlayerAccess は、プレイヤが SayHello リソースに対
して持つアクセスを決定します。この場合、ラムダ関数のみを呼び出せます。
PlayerAccess リソース
リソーステンプレートの PlayerAccess リソースは、PlayerAccess (p. 309) カスタムリソースで
す。プレイヤがアクセスできるリソースで定義された Metadata.CloudCanvas.PlayerAccess プ
ロパティによって指定されるリソースに、プレイヤのアクセスを与えます。
PlayerAccess DependsOn プロパティは、このメタデータプロパティを定義するリソースを表
示します。メタデータプロパティを持つリソースが作成またはアップデートされた後に、AWS
CloudFormation が PlayerAccess リソースを作成またはアップデートするのを確実にします。
lambda-function-code サブディレクトリ
lambda-function-code サブディレクトリは、リソーステンプレートが Lambda 関数リソースを定
義する場合に存在します。このディレクトリは、これらの機能を実行したソースファイルを保存する
場所です。
Lumberyard が提供したツールは、テンプレートを使用し、AWS CloudFormation スタックをアップ
デートする場合に、このディレクトリからコードをアップロードします。
リソースのデプロイ
AWS CloudFormation スタックを使用してデプロイを実行します。Lumberyard によって提供される
ツールを使用して、スタックを作成および管理します。
プロジェクトでは、AWS CloudFormation によって定められた上限までの任意の数のデプロイを定義
できます (詳細については、AWS CloudFormation Limitsを参照してください)。各デプロイには、ゲー
ムに必要な完全に独立した一連のリソースが含まれます。たとえば、開発、テスト、およびリリー
スのデプロイを個別にもつことができるため、開発チームとテストチームは、ゲームのリリースバー
ジョンに使用されるデプロイとは関係なく作業できます。
Lumberyard プロジェクトをホストする AWS アカウントには、次のリソースが含まれます。
• {project} – プロジェクトのすべてのデプロイ用コンテナとして機能する AWS CloudFormation ス
タック。
• {project}-Configuration – 設定データを格納するために使用される S3 バケット。
• {project}-ProjectResourceHandler – テンプレートで使用されるカスタムリソース用のハンド
ラーを実装する Lambda 関数。「カスタムリソース (p. 306)」を参照してください。
• {project}-ProjectResourceHandlerExecution – ProjectResourceHandler Lambda 関数
の実行時に使用されるアクセス権限を付与する IAM ロール。
• {project}-ProjectPlayerAccessTokenExchangeHandler – プレイヤのログインプロセスで、
トークン交換のステップを実装する Lambda 関数。詳細については、「アクセスコントロールとプ
レイヤ ID (p. 310)」を参照してください。
Version 1.6
302
Lumberyard 開発者ガイド
設定バケット
• {project}-ProjectPlayerAccessTokenExchangeHandlerRole –
ProjectPlayerAccessTokenExchangeHandler Lambda 関数の実行時に使用されるアクセス権
限を付与する IAM ロール。
• {project}-{deployment} – プロジェクトの各デプロイ用の AWS CloudFormation スタック。
• {project}-{deployment}Access – プロジェクトの各デプロイへのアクセスを制御する AWS
CloudFormation スタック。
{project}-{deployment}Access-OwnerPolicy – デプロイへの "所有者" アクセスを許可する
IAM 管理ポリシー。「プロジェクトのアクセスコントロール (p. 310)」を参照してください。
• {project}-{deployment}Access-Owner – デプロイへの "所有者" アクセスを許可する IAM ロー
ル。「プロジェクトのアクセスコントロール (p. 310)」を参照してください。
• {project}-{deployment}Access-Player – デプロイへの "プレイヤ" アクセスを許可する IAM
ロール。「アクセスコントロールとプレイヤ ID (p. 310)」を参照してください。
• {project}-{deployment}Access-PlayerLoginRole – プレイヤのログインプロセスで使用され
る、プレイヤの一時的な匿名アクセスを許可する IAM ロール。「アクセスコントロールとプレイヤ
ID (p. 310)」を参照してください。
• {project}-{deployment}Access-PlayerAccessIdentityPool – プレイヤ ID に使用される
Amazon Cognito ID プール。詳細については、「アクセスコントロールとプレイヤ ID (p. 310)」
を参照してください。
• {project}-{deployment}Access-PlayerLoginIdentityPool – プレイヤのログインプロセ
スで使用される、一時的なプレイヤ ID を提供する Amazon Cognito ID プール。詳細については、
「アクセスコントロールとプレイヤ ID (p. 310)」を参照してください。
• {project}-{deployment}-{resource-group} – プロジェクトの各リソースグループの AWS
CloudFormation スタック。
• {project}-{deployment}-{resource-group}-{resource} – リソースグループによって定
義されているリソース。AWS CloudFormation の機能によって、これらの名前の一部に一意の ID
が付加されます。たとえば、Development という名前のデプロイと HighScore という名前の機
能をもつ MyGame という名前のプロジェクトの場合、Scores リソースの実際の名前は MyGameDevelopment-1FLFSUKM3MC4B-HighScore-1T7DK9P46SQF8-Scores-1A1WIH6MZKPRI のよう
になります。ほとんどの場合、Lumberyard が提供するツールによってこの実際のリソース名は非表
示になっています。
設定バケット
設定 Amazon S3 バケットは、プロジェクトの設定データを格納するために使用されます。Cloud
Canvas で提供されるツールによって、このバケットへのアップロードを管理します。
設定バケットのコンテンツは次のとおりです。
/
upload/
{upload-id}/
project-template.json
project-code.zip
deployment/
{deployment}/
deployment-template.json
resource-group/
{resource-group}/
resource-template.json
lambda-function-code.zip
lambda-function-code.zip.{functionname}.configured
player-access/
Version 1.6
303
Lumberyard 開発者ガイド
リソースマッピング
auth-settings.json
このバケット内のすべての /upload/{upload-id}/* オブジェクト (*.configured オブジェクト
を除く) は、スタック管理操作の実行時に Cloud Canvas ツールによって {game}/AWS ディレクトリ
からアップロードされます。各操作のアップロードに一意の {upload-id} 値が割り当てられ、同時
操作が相互に影響しあうことを回避します。
このバケット内の lambda-function-code.zip.{function-name}.configured オブジェクト
は、設定がコード内に挿入されたときに LambdaConfiguration カスタムリソースによって作成さ
れます。詳細については、「LambdaConfiguration (p. 308)」を参照してください。
/player-access/auth-settings.json ファイルには、Facebook などのソーシャルネットワー
クやプレイヤの Amazon 認証情報を使用したプレイヤログインを実装するために使用されるセキュ
リティ認証情報が格納されます。このファイルは、lmbr_aws add-login-provider (p. 223)、updatelogin-provider (p. 233)、および remove-login-provider (p. 232) コマンドで作成および更新されま
す。
リソースマッピング
リソースマッピングにより、ゲームのリソースの定義 (p. 280)で使用されるフレ
ンドリ名が、1 つまたは複数の特定のリソースのデプロイ (p. 302)用に作成され
たリソースの実際の名前にマッピングされます。たとえば、DailyGiftTable などの
DynamoDB テーブル名は、SamplesProject-DontDieDeployment-78AIXR0N0O4NDontDieAWS-1I1ZC6YO7KU7F-DailyGiftTable-1G4G33K16D8ZS のような名前にマッピ
ングされます。ここで、SamplesProject はプロジェクトの名前で、DontDieDeployment
はデプロイの名前で、DontDieAWS はリソースグループの名前です。リソース名の
78AIXR0N0O4N、1I1ZC6YO7KU7F、および 1G4G33K16D8ZS の部分は AWS CloudFormation によっ
て挿入され、リソース名が継続して一意であることが保証されます。したがって、リソースが削除さ
れ、同じ論理名を持つ新しいリソースが作成された場合は、物理リソース ID が異なります。
通常、ゲーム開発とゲームのリリースバージョンには、異なるデプロイメントとその結果としての
異なるマッピングが使用されます。また、多くの場合、開発チーム、テストチーム、およびその他の
チームがそれぞれ独自のデプロイで作業するため、各チームが異なるマッピングを使用します。
開発中にデフォルトで使用されるデプロイは {root}\{game}\AWS\[projectsettings.json] (p. 281) ファイルで指定されており、各ユーザー向けに、{root}\Cache
\{game}\pc\user\AWS\user-settings.json (p. 283) ファイルによってオーバーライドす
ることができます。lmbr_awsdefault-deployment (p. 226) コマンドを使用するか、Cloud Canvas
Resource Manager (p. 240) を使用して、デフォルトのデプロイを変更できます。
Ctrl+G を押して、Lumberyard IDE からゲームを起動した場合、開発中に使用されるマッピングは、
上記の user-settings.json (p. 283) ファイルに格納されます。デフォルトのデプロイメントが
変更された場合、デフォルトのデプロイメントが更新された場合、および Lumberyard エディタ が起
動された場合、このファイルは自動的に更新されます。lmbr_aws update-mappings (p. 234) コマン
ドを使用して、このファイルを手動で更新することもできます。
Lumberyard で作成されたゲームランチャーアプリケーションによって、ゲームのリリースビルドが
起動された場合は、ゲームのマッピングが {root}\{game}\Config\awsLogicalMappings.json
ファイルに格納されます。これらのマッピングは、lmbr_aws update-mappings -release (p. 234) コマンド (awsLogicalMappings.json ファイルを生成する) を手動で更新でき
ます。[project-settings.json] (p. 281) ファイルの ReleaseDeployment プロパティでリ
リースマッピングのデプロイメントを指定することができます。
どちらの場合も、AWS クライアント設定 (p. 319) システムはマッピングデータで構成されま
す。AWS フローノード、AWS C++ SDK、および Lambda 関数でこの構成を使用することができま
す。
Version 1.6
304
Lumberyard 開発者ガイド
AWS フローノードでマッピングを使用する
AWS フローノードでマッピングを使用する
TableName (DynamoDB)、FunctionName (Lambda)、QueueName (Amazon SQS)、TopicARN
(Amazon SNS)、または BucketName (Amazon S3) ポートを定義する AWS フローノードはマッピ
ングと連携します。ポートを {resource-group} などの値に設定します。{resource} のよう
な値に設定します。ここで、{resource-group} はリソースを定義するリソースグループの名前
で、{resource} はリソースグループの resource-template.json ファイルの Resources セク
ションに表示されるリソースの名前です。AWS フローノードは AWS クライアント設定 (p. 319)
システムを使用して、{resource-group} の名前を参照することにより、実際のリソース名を検索
します。{resource} 形式の名前を参照することにより、実際のリソース名を検索します。Cloud
Canvas フローグラフノードの詳細については、「Cloud Canvas フローグラフ ノードのリファレン
ス (p. 257)」を参照してください。
AWS C++ SDK でマッピングを使用する
AWS クライアント設定 (p. 319) システムはアプリケーション定義の任意の名前を使用して、サービ
ス固有のクライアントの構成をサポートします。Lumberyard IDE は {resource-group} で名前を使
用します。{resource} 形式の名前を使用して、AWS C++ SDK API を呼び出すときに指定する必要
のある実際のリソース名にフレンドリ名をマッピングする構成を定義します。次のような C++ コード
を使用して、この構成を取得および使用することができます。
コード例: C++ を使用したリソース名のマッピング
#include
#include
#include
#include
#include
#include
<LmbrAWS\IAWSClientManager.h>
<LmbrAWS\ILmbrAWS.h>
<aws\lambda\LambdaClient.h>
<aws\lambda\model\InvokeRequest.h>
<aws\lambda\model\InvokeResult.h>
<aws\core\utils\Outcome.h>
void InvokeSayHello()
{
LmbrAWS::IClientManager* clientManager = pEnv->pLmbrAWS>GetClientManager();
// Use {resource-group}.{resource} format name to lookup the configured
client.
LmbrAWS::Lambda::FunctionClient client = clientManager>GetLambdaManager().CreateFunctionClient("HelloWorld.SayHello");
// Get the Lambda function resource name using the
client.GetFunctionName() method.
Aws::Lambda::Model::InvokeRequest req;
req.SetFunctionName(client.GetFunctionName());
// Invoke the Lambda function asynchronously (async isn't required, but
you should never
// do network I/O in the main game thread).
client->InvokeAsync(req,
[]( const Aws::Lambda::LambdaClient*,
const Aws::Lambda::Model::InvokeRequest&,
const Aws::Lambda::Model::InvokeOutcome& outcome,
const std::shared_ptr<const Aws::Client::AsyncCallerContext>&)
{
if(outcome.IsSuccess())
{
Version 1.6
305
Lumberyard 開発者ガイド
Lambda 関数でマッピングを使用する
const Aws::Lambda::Model::InvokeResult& res =
outcome.GetResult();
// TODO: process the result
}
}
);
}
Lambda 関数でマッピングを使用する
多くの場合、リソースグループの一部として定義されている Lambda 関数リソースは、そのリソー
スグループによって定義されているその他のリソースにアクセスする必要があります。これを行う
には、AWS API コールで使用される実際のリソース名にリソースのフレンドリ名をマッピングす
るための方法が関数コードに必要になります。LambdaConfiguration リソースにより、こうし
たマッピングおよびその他の設定を行う方法が lambda コードに提供されます。詳細については、
「LambdaConfiguration (p. 308)」を参照してください。
カスタムリソース
Cloud Canvas は、プロジェクト、デプロイ、リソースグループ AWS CloudFormation テンプレー
トファイルで使用できるいくつもの AWS CloudFormation カスタムリソースを提供します。これ
らのカスタムリソースは、{root}\{game}\AWS\project-code ディレクトリ内にある Lambda
関数コードと、{root}\{game}\AWS\project-template.json ファイルに定義されている
ProjectResourceHandler リソースによって実装されます。これらのリソースは、静的エンティ
ティというよりも、ライブラリ関数のように機能します。各カスタムリソースには、入力プロパティ
と出力プロパティがあります。
カスタムリソースの要約リストは次のとおりです。
• CognitoIdentityPool (p. 306) – Amazon Cognito ID プールのリソースを管理します。
• EmptyDeployment (p. 307) – リソースグループが定義されていない場合に、deploymenttemplate.json で使用されます。
• ResourceGroupConfiguration (p. 307) – リソースグループの AWS CloudFormation stack リソース
の設定データを提供します。
• LambdaConfiguration (p. 308) – Lambda 関数リソースの設定データを提供し、Lambda 関数の実
行ロールを維持します。
• PlayerAccess (p. 309) – プレイヤーロールのポリシーを維持します。
CognitoIdentityPool
Custom::CognitoIdentityPool リソースは、Amazon Cognito ID プールのリソースを作成および
設定するために、deployment-access-template.json ファイルで使用されます。
入力プロパティ
• ConfigurationBucket
必須設定データが含まれている Amazon S3 バケットの名前。
• ConfigurationKey
必須設定バケット内にプロジェクト設定データが存在する、Amazon S3 オブジェクトキープレ
フィックス。このプロパティにより、操作ごとに AWS CloudFormation によってカスタムリソース
ハンドラーが実行されます。
Version 1.6
306
Lumberyard 開発者ガイド
EmptyDeployment
• IdentityPoolName
必須ID プールの名前。
• UseAuthSettingsObject
必須true または false である必要があります。Amazon Cognito ID プールが、add-loginprovider コマンドを使用して作成された認証プロバイダを使用するように設定されているかどう
かを確認します。
• AllowUnauthenticatedIdentities
必須true または false である必要があります。Amazon Cognito ID プールが認証されていない ID
を許可するように設定されているかどうかを確認します。認証された ID と認証されていない ID に
対する Amazon Cognito のサポートの詳細については、ID プールを参照してください。
• Roles
オプション。認証されたユーザーと認証されていないユーザーが引き受ける IAM ロールを確認しま
す。このプロパティについては、 SetIdentityPoolRoles を参照してください。
出力プロパティ
• IdentityPoolName
ID プールの名前 (IdentityPoolName 入力プロパティと同じ)。
• IdentityPoolId
ID プールの物理リソース名。
EmptyDeployment
Custom::EmptyDeployment リソースは、リソースグループが定義されていない場合に
deployment-template.json ファイルで使用されます。これは、テンプレートが少なくとも 1 つの
リソースを定義する AWS CloudFormation 要件を満たすために必要です。
このリソースは、入力または出力プロパティをサポートしていません。
ResourceGroupConfiguration
Custom::ResourceGroupConfiguration リソースは、特定のリソースグループに使用する必要
のある、設定バケット内の resource-template.json ファイルのコピーの場所を特定するため
に、deployment-template.json で使用されます。
入力プロパティ
• ConfigurationBucket
必須設定データが含まれている Amazon S3 バケットの名前。
• ConfigurationKey
必須設定バケット内にデプロイ設定データが存在する、Amazon S3 オブジェクトキープレフィック
ス。
• ResourceGroup
必須設定するリソースグループの名前。
Version 1.6
307
Lumberyard 開発者ガイド
LambdaConfiguration
出力プロパティ
• ConfigurationBucket
設定データが含まれている Amazon S3 バケットの名前。これは、常に ConfigurationBucket 入
力プロパティと同じです。
• ConfigurationKey
設定バケット内に指定されたリソースグループの設定データが存在する、Amazon S3 オブジェクト
キープレフィックス。これは、文字列「ResourceGroup」と ResourceGroup の値が付加された入
力 ConfigurationKey です。
• TemplateURL
設定バケット内にある resource-template.json のリソースグループのコピーの Amazon S3 URL。こ
の値は、リソースグループの TemplateURL プロパティ値として使用する必要があります。
LambdaConfiguration
Custom::LambdaConfiguration リソースは、Lambda 関数リソースの設定データを提供するため
に、resource-template.json ファイルで使用されます。
入力プロパティ
• ConfigurationBucket
必須設定データが含まれている Amazon S3 バケットの名前。
• ConfigurationKey
必須設定バケット内にリソースグループの設定データが存在する、Amazon S3 オブジェクトキープ
レフィックス。
• FunctionName
必須設定する Lambda 関数リソースの分かりやすい名前。
• Settings
オプション。Lambda 関数コードで使用できる値。
• Runtime
必須Lambda 関数に使用されるランタイムを識別します。Cloud Canvas は現時点で次の Lambda ラ
ンタイムをサポートしています: nodejs、python2.7。
出力プロパティ
• ConfigurationBucket
設定データが含まれている Amazon S3 バケットの名前。これは、常に ConfigurationBucket 入
力プロパティと同じです。
• ConfigurationKey
設定バケット内に指定された関数の zip 圧縮されたコードが存在する、Amazon S3 オブジェクト
キープレフィックス。
• Runtime
関数で使用する Lambda ランタイム。これは、常に入力 Runtime プロパティ値と同じです。
Version 1.6
308
Lumberyard 開発者ガイド
PlayerAccess
• Role
この関数用に作成された Lambda 関数実行の ID。
LambdaConfiguration カスタムリソースを使用して、Lambda 関数が特定のプロジェクトリソース
に対して指定したアクションを実行することを強化する方法については、Lambda 関数のアクセスコ
ントロール (p. 311)を参照してください。
PlayerAccess
Custom::PlayerAccess リソースは、プレイヤーがリソースグループのリソースに必要なアクセス
を行えるようにプレイヤーロールを更新するために、resource-template.json ファイルで使用さ
れます。また、deployment-access-template.json ファイルで、プレイヤーロールを更新してプ
レイヤーがデプロイのリソースに対する必要なアクセス権を持つようにするためにも使用されます。
入力プロパティ
• ConfigurationBucket
必須設定データが含まれている Amazon S3 バケットの名前。
• ConfigurationKey
必須設定バケット内にデプロイの設定データが存在する、Amazon S3 オブジェクトキープレフィッ
クス。このプロパティの値は実際には使用されませんが、Cloud Canvas ツールによってキーが
AWS CloudFormation 操作ごとに異なることが保証されるため、このプロパティが存在することは
すべての操作でカスタムリソースハンドラーが AWS CloudFormation によって強制的に実行される
効果を持ちます。
• ResourceGroup
オプション。プレイヤーロールを更新するリソースグループの ID。
• DeploymentStack
オプション。プレイヤーロールを更新するデプロイの ID。
ResourceGroup プロパティと DeploymentStack プロパティのいずれかのみを指定する必要があ
ります。
出力プロパティ
PlayerAccess カスタムリソースは出力値を生成しません。
PlayerAccess メタデータの形式
このカスタムリソースは、プロジェクトのリソースグループ定義の
Metadata.CloudCanvas.PlayerAccess プロパティを探し、プレイヤーロールにアタッチされるポ
リシーを作成します。このポリシーは、それらのリソースに対して指定されたアクションを許可しま
す。Metadata.CloudCanvas.PlayerAccess プロパティの形式は次のとおりです。
{
"AWSTemplateFormatVersion": "2010-09-09",
"Resources": {
"...": {
"Type": "...",
"Properties": {
Version 1.6
309
Lumberyard 開発者ガイド
アクセスコントロールとプレイヤ ID
...
},
"Metadata": {
"CloudCanvas": {
"PlayerAccess": {
"Action": [ "{allowed-action-1}", ..., "{allowedaction-n}" ]
}
}
}
},
...
}
}
必須の Action プロパティは、IAM ポリシー用に定義されたプロパティと同じであり、IAM ポリシー
エレメントの参照で詳細に説明されています。値のリストの代わりに、単一値を指定できることに注
意してください。
アクセスコントロールとプレイヤ ID
Cloud Canvas を使うと、ゲームの AWS リソースへのアクセスを 3 つの方法で制御できます。
• プロジェクトのアクセスコントロール (p. 310)
• プレイヤのアクセスコントロール (p. 311)
• Lambda 関数のアクセスコントロール (p. 311)
プロジェクトのアクセスコントロール
多くの場合、プロジェクトのチームメンバーに対しても、プロジェクトのリソースへのアクセスを制
限する必要があります。この制限により、1 つの開発チームで使用中のリソースが他の開発チームに
よって誤って更新されることを防ぐことができます。また、プロジェクトのチームメンバーがゲーム
のリリースバージョンによって使用されているリソースにアクセスすることを防ぐ必要もあります。
これらの両方の制限は、ゲームのオペレーションに影響を及ぼす可能性のある意図しない変更を防止
し、場合によっては、こうしたリソースに格納されている可能性がある電子メールアドレスなど、プ
レイヤの個人情報にプロジェクトのチームメンバーがアクセスすることも防ぎます。
Cloud Canvas によって提供されるデフォルトの deployment-access-template.json (p. 291) ファイ
ルは、OwnerPolicy リソース (p. 297) IAM 管理ポリシーリソースを定義します。このポリシーによ
り、AWS CloudFormation デプロイスタックが更新され、プロジェクトのリソースグループによっ
て定義されたリソースの作成、更新、削除などが行われます。このテンプレートは オーナーリソー
ス (p. 297). IAM ロールリソース (OwnerPolicy がアタッチされた) も定義します。
必要に応じて、deployment-access-template.json ファイルにある OwnerPolicy リソース定義
を変更したり、追加のポリシーを作成したりできます。ただし、この操作を実行する前に、IAM のア
クセス権限がどのように機能するかを十分に理解している必要があります。このリソース定義を不適
切に使用すると、攻撃および不正使用に対して AWS アカウントが脆弱になり、予期しない AWS 料
金 (その他の影響に加えて) が発生する可能性があります。
Lumberyard エディタ での AWS の使用承認
Lumberyard エディタ を介して開発者グループによる AWS の使用を承認するには、次のステップを
実行します。
Version 1.6
310
Lumberyard 開発者ガイド
プレイヤのアクセスコントロール
Lumberyard エディタ で AWS の使用を承認する
1.
各開発者向けに IAM ユーザーを作成します。
2.
各ユーザーに対して、アクセスキーとシークレットキーを生成します。
3.
IAM ユーザーが実行できる操作が定義されているポリシーをユーザーにアタッチします。これら
のポリシーはプロジェクトが初期化されると生成されます。または、独自のポリシーを適用する
ことができます。
4.
アクセスキーとシークレットキーを安全な方法で開発者に配布します。
Caution
電子メールを使用してアクセスキーまたはシークレットキーを送信しないでください。
また、ソース管理にチェックインしないでください。このような操作は、重大なセキュ
リティリスクをもたらします。
5.
Lumberyard エディタ で、各開発者が [AWS]、[Cloud Canvas]、[Permissions and deployments]
に移動します。
6.
開発者が、配布されたアクセスキーおよびシークレットキーを使用した新しいプロファイルを追
加します。
プレイヤのアクセスコントロール
ゲームが実行時に AWS リソースにアクセスできるようにするには、AWS API を呼び出すときに必要
なアクセスを許可する認証情報を使用する必要があります。権限が制限された IAM ユーザーを作成
し、そのユーザーの認証情報 (AWS アクセスキーおよびシークレットキーの両方) をゲームコードに
埋め込むと、ゲームがリソースにアクセスできるようになります。ただし、AWS Amazon Cognito ID
プールを使用すると、この問題に対するより強力かつ安全なソリューションが提供されます。
Cloud Canvas が Amazon Cognito ID プールを使用する方法については、「プレイヤ ID (p. 313)」セ
クションで説明します。
最終的には、プレイヤのアクセスは、デフォルトの Cloud Canvas deployment-accesstemplate.json (p. 291) ファイルで定義されているプレイヤロールによって制御されます。このロー
ルにアタッチされているポリシーは、resource-template.json (p. 298) ファイルにある PlayerAccess
リソース (p. 302) カスタムリソースによって設定されます。
Lambda 関数のアクセスコントロール
AWS Lambda 関数が実行されると、この関数には IAM ロール (他の AWS リソースへのアクセス権限
を指定する) が設定されます。こうしたロールを作成および構成するには、すべてのプロジェクトの
チームメンバーに安全に付与することができない IAM アクセス許可が必要です。このアクセス許可を
チームメンバーに付与すると、チームメンバーが、特定のデプロイメントへのアクセスを制限してい
るセキュリティ対策を回避する可能性があります。
プロジェクトのチームメンバーにこれらの IAM 権限を付与することなく、Lambda 関数のアクセスコ
ントロールを実装するには、Cloud Canvas LambdaConfiguration (p. 308) カスタムリソースを
使用します。LambdaConfiguration リソースのハンドラは、Lambda 関数がアクセスを要求する各
グループリソースの Metadata.CloudCanvas.FunctionAccess エントリを使用して、各 Lambda
関数のロールを作成および構成し、この関数が要求したリソースで指定されたアクションを実行でき
るようにします。
Metadata.CloudCanvas.Function プロパティの形式は次のとおりです。
{
"AWSTemplateFormatVersion": "2010-09-09",
"Resources": {
Version 1.6
311
Lumberyard 開発者ガイド
Lambda 関数のアクセスコントロール
"...": {
"Type": "...",
"Properties": {
...
},
"Metadata": {
"CloudCanvas": {
"FunctionAccess": {
"Action": [ "{allowed-action-1}", ..., "{allowedaction-n}" ],
"ResourceSuffix": "{resource-suffix}"
}
}
}
},
...
}
}
必須の Action プロパティは、IAM ポリシー用に定義されたプロパティと同じであり、IAM ポリシー
エレメントの参照で詳細に説明されています。値のリストの代わりに、単一値を指定できることに注
意してください。
オプションの ResourceSuffix プロパティ値は、生成されたポリシー内のリソースの ARN に付
加されます。このプロパティを使用して、リソースへのアクセスをさらに制限できます。たとえ
ば、Amazon S3 バケットの場合、このプロパティを使用して、名前が一致するオブジェクトへのアク
セスを制限できます。詳細については、IAM ポリシーエレメントの参照の「リソース」を参照してく
ださい。
次の図には、Lumberyard アクセスコントロールのさまざまな要素がどのように連携するかが示されて
います。
Version 1.6
312
Lumberyard 開発者ガイド
プレイヤ ID
図の例では、Lambda 関数により、プレイヤのハイスコアを DynamoDB データベースに送信したり、
このデータベースから上位 10 件のスコアを取得したりするといった、さまざまな処理が実行されま
す。
プレイヤのアクセスコントロールの IAM ポリシーによって、プレイヤの代わりにゲームが Lambda
関数を呼び出すことが可能になります。また、関数のアクセスコントロールのポリシーによっ
て、Lambda 関数がアクセスできる AWS リソース (この例では、DynamoDB データベース) が指定さ
れます。この安全な配置によって、プレイヤが DynamoDB データベースに直接アクセスすることが
防止され、次の利点が提供されます。
• クライアントからの入力を検証し、安全でない入力や不要な入力を削除することができます。たと
えば、クライアントが極端に高いスコアや低いスコアを自己レポートした場合、不要な値がデータ
ベースに書き込まれる前に、その値を拒否できます。
• 顧客が別の顧客のデータにアクセスすることを防ぎます。
• 悪意のある攻撃を防ぎます。
DynamoDB データベース、Lambda 関数、アクセスコントロールポリシーを作成するために (およ
び必要に応じて、後で更新するために)、AWS CloudFormation は、Amazon S3 設定バケットから
AWS CloudFormation テンプレートを読み取り、テンプレートに含まれる命令を実行します。AWS
CloudFormation は deployment-access-template.json ファイルを読み取り、デプロイメント
のアクセスコントロールの IAM ポリシーを作成します。このポリシーにより、AWS CloudFormation
が特定のデプロイメントに対して作成または更新できるリソースが指定されます。これらのプロセス
は、開発、テスト、およびライブデプロイメントを相互に安全に分離させておくうえで重要です。
これらのテンプレートでカスタムリソースを使用して、AWS CloudFormation 自身が実行できない
機能を実装することもできます。Lumberyard では、カスタムリソースはライブラリ関数のように機
能します。たとえば、deployment-access-template.json ファイルは CognitoIdentityPool
カスタムリソースを呼び出して、Amazon Cognito ID プールを作成します。各 Lambda 関数
に対して、関数のアクセスコントロールの IAM ポリシーを作成するために、テンプレートは
LambdaConfiguration カスタムリソースを呼び出します。カスタムリソースは、Lambda 関数がア
クセスできる必要がある特定のリソースの FunctionAccess メタデータエントリを読み取り、現在
のユーザーとデプロイメントが必要とする、関数のアクセスコントロールのポリシーを作成します。
同様に、プレイヤーのアクセスコントロールのポリシーを作成するために、resourcetemplate.json テンプレートの PlayerAccess カスタムリソースが呼び出されます。このポリシー
により、ゲームがプレイヤーの代わりに呼び出して使用できる Lambda 関数とその他のリソースが指
定されます。
プレイヤ ID
前のセクション「プレイヤのアクセスコントロール (p. 311)」で説明したように、ゲームは、AWS
API を呼び出す (C++ AWS SDK または AWS フローノードを使用して) ときに必要なアクセスを許可
する AWS 認証情報を使用する必要があります。Cloud Canvas は Amazon Cognito ID プールを使用し
てこれらの認証情報を取得します。
Amazon Cognito ID プールを使用することのメリットは、ゲームで各プレイヤに一意の ID を付与でき
ることです。この ID を使用して、DynamoDB テーブル、Amazon S3 バケット、またはその他の場所
に格納された、ユーザーが保存したゲーム、ハイスコア、その他のデータをユーザーに関連付けるこ
とができます。
Amazon Cognito ID プールは、認証されていない ID と認証された ID の両方をサポートしています。
認証されていない ID は PC、タブレット、電話などの単一デバイスに関連付けられますが、関連付け
られたユーザー名やパスワードはありません。
認証された ID は、Amazon、Facebook、Google などの外部 ID プロバイダーによって指定された
ユーザー ID に関連付けられます。これにより、プレイヤがゲームをする場所を問わず、Amazon
Cognito がゲームに同じプレイヤ ID を提供できるようになります。ユーザーは、デバイスを変えた
Version 1.6
313
Lumberyard 開発者ガイド
プレイヤ ID
場合でも、ユーザーが保存したゲーム、ハイスコア、およびその他のデータを使用することができま
す。
Amazon Cognito を使用すると、ユーザーは認証されていない ID の使用から始めて、後の時点でその
ID に外部 ID を関連付けることができます。このとき、Amazon Cognito によって提供された ID も引
き続き保持できます。
Cloud Canvas は匿名プレイヤ ID (認証されていない) と認証されたプレイヤ ID の両方をサポートしま
すが、認証された ID のサポートはより複雑で、追加の設定とコーディングを必要とします。
匿名 (認証されていない) プレイヤのログイン
以下の図に、匿名 (認証されていない) プレイヤのログインプロセスを示しています。
gEnv->lmbrAWS->GetClientManager()->ApplyConfiguration() を呼び出すことによって、ま
たは Cloud Canvas (AWS):Configuration:ApplyConfiguration フローノードを使用することに
よって、Cloud Canvas クライアント構成システムが初期化されると、このプロセスが自動的に開始さ
れます。
Version 1.6
314
Lumberyard 開発者ガイド
プレイヤ ID
認証されたプレイヤのログイン
Cloud Canvas を使用して、認証されたプレイヤ ID をゲームに実装する方法を理解するに
は、Amazon Cognito の拡張 (簡略化) 認証フローの知識が必要です。詳細については、Amazon
Cognito 開発者ガイドの認証のフローを参照してください。
以下の図に示されている認証されたプレイヤ ID のログインプロセスは、認証されていないプレイヤの
ログインプロセスよりも複雑です。このログインプロセスには、デフォルトで Cloud Canvas によっ
て提供される設定に加えて、追加の設定が必要です。
Version 1.6
315
Lumberyard 開発者ガイド
プレイヤ ID
Version 1.6
316
Lumberyard 開発者ガイド
プレイヤ ID
gEnv->lmbrAWS->GetClientManager()->ApplyConfiguration() を呼び出すことによって、ま
たは Cloud Canvas (AWS):Configuration:ApplyConfiguration フローノードを使用することに
よって、Cloud Canvas クライアント構成システムが初期化されると、認証されたプレイヤのログイン
プロセスが自動的に開始されます。
auth_token cvar が存在する場合は、Cloud Canvas の認証されたプレイヤのログインフローがト
リガーされます。cvar が設定されていない場合は、匿名プレイヤのログインプロセスが使用されま
す。cvar の値は {provider}:{id} 形式の文字列である必要があります。ここで、{provider} は
ゲーム用に構成した外部 ID プロバイダーで (以降の「外部 ID プロバイダーの設定 (p. 318)」セク
ションを参照してください)、{id} はそのプロバイダーのログインプロセスで返されたプレイヤ ID で
す。
auth_token が設定されている場合、Cloud Canvas は、指定された {id} 値を
ProjectPlayerAccessTokenExchangeHandler Lambda 関数に渡します。Lambda 関数は指定さ
れた ID で外部プロバイダーの API を呼び出し、Amazon Cognito に渡された値を受け取り、プレイヤ
の ID と認証情報を取得します。ProjectPlayerAccessTokenExchangeHandler によって行われ
る呼び出しでは、アプリケーション ID と、外部 ID プロバイダーの構成プロセスの一部として提供し
たシークレット値が使用されます。
Version 1.6
317
Lumberyard 開発者ガイド
プレイヤ ID
前の図で示しているように、Cloud Canvas はある Amazon Cognito ID プールを使用して
ProjectPlayerAccessTokenExchangeHandler の起動に使用される認証情報を取得し、別の
Amazon Cognito ID プールを使用してゲームの残りのリソースへのアクセスに使用される認証情報を
取得します。これが必要なのは、ProjectPlayerAccessTokenExchangeHandler が常に匿名アク
セスであるからです。
認証されたログインフローを実装するコードはすべて、{root}\Code\CryEngine\LmbrAWS
\Configuration ディレクトリにあります。ファイルの説明を次に示します。
• ClientManagerImpl.* – TokenRetrievingPersistentIdentityProvider ID プロバイダー
を使用するように、ゲームの AWS クライアントを設定します。
• ResourceManagementLambdaBasedTokenRetrievalStrategy.* –
ProjectPlayerAccessTokenExchangeHandler Lambda 関数を呼び出すトークン交換プロセス
を実装します。
• TokenRetrievingPersistentIdentityProvider.* –
ResourceManagementLambdaBasedTokenRetrievalStrategy インスタンスを使用してトーク
ン交換プロセスを実装する AWS SDK で定義された PersistentCognitoIdentityProvider イ
ンターフェイスの実装。
外部 ID プロバイダーの設定
Cloud Canvas では、外部 ID プロバイダーから認証コードを取得し、auth_token cvar を設定する
プロセスが自動化されていません。この取得と設定は、ゲーム開発者としての責任で、お客様が実施
してください。利用可能な実装方法の一部を以下に示します。
• PC では、ID プロバイダーの URI を静的ウェブページにリダイレクトさせ、そのウェブペー
ジからユーザーをカスタム URI にリダイレクトさせることができます。カスタム URI を使
用すると、ゲームを起動し、認証コードをコマンドライン引数 (たとえば、yourGame.exe
+auth_token=provider:code) として渡すことができます。Cloud Canvas はこのコマンドライ
ン引数を検出し、ユーザーをゲームに記録します。認証トークンはローカルにキャッシュされるた
め、これを実行する必要があるのは 1 回のみです。
• ゲーム自体に認証コードを取得させることができます (ただし、多くの外部 ID プロバイダーでは、
これを実行するには埋め込み Web ブラウザの使用が必要になる可能性があります)。認証コードを
取得したら、gEnv->lmbrAWS->->GetClientManager()->Login(providerName, code) を
呼び出すか、単に cvar auth_token を設定することができます。
• ゲーム用のランチャーがある場合は、Web ブラウザウィンドウをランチャーに埋め込んで、プレイ
ヤが外部 ID プロバイダーにログインできるようにすることができます。その後、認証コードを取得
して、+auth_token=provider:code パラメーターを使用してゲームを起動できます。
外部 ID プロバイダーは lmbr_aws add-login-provider (p. 223)、update-login-provider (p. 233)、お
よび remove-login-provider (p. 232) コマンドを使用して設定されます。これらのコマンドでは、設
定がプロジェクトの設定バケット内にある /player-access/auth-settings.json オブジェクト
に保存されるため、ProjectPlayerAccessTokenExchangeHandler Lambda 関数がアクセスでき
ます。
Note
PlayerAccessIdentityPool リソース (p. 298) 設定を更新して変更を反映させるには、addlogin-provider、update-login-provider、または remove-login-provider の実行
後に lmbr_aws update-project を実行する必要があります。
トークンの自動更新
外部の ID プロバイダーで Amazon Cognito を使用している場合、そのプロバイダーからのトークン
を定期的に更新し、そのトークンの更新済み認証情報を Amazon Cognito から取得する必要がありま
Version 1.6
318
Lumberyard 開発者ガイド
AWS クライアント設定
す。Cloud Canvas では、ProjectPlayerAccessTokenExchangeHandler Lambda 関数を使用して
このトークン更新プロセスを自動的に実行します。
AWS クライアント設定
C++からの AWS サービスへのアクセスは、AWSクライアントオブジェクトを介して制御されま
す。Cloud Canvas はSDKによって与えられた AWS クライアントの上部に抽象化レイヤーを提供して
います。これにより、Cloud Canvas フローグラフノードで内部的に使用されるものを含むクライアン
トオブジェクトに対する設定変更を簡単に行うことができます。これらの変更は、C++、または提供
されたフローグラフノードを介して設定することができます。
AWS フローグラフノードの設定
Lumberyard は Lambda 関数や DynamoDB テーブルからのデータの読み込みなどといたさまざまな
AWS オペレーションを実行するフローグラフノードを提供します。各フローグラフノードは実行に
必要な AWS リソースを特定するポートを持っています。たとえば、DynamoDB ノードはDynamoDB
テーブルを特定するTableName ポートを持っています。Cloud Canvas フローグラフノードの詳細に
ついては、「Cloud Canvas フローグラフ ノードのリファレンス (p. 257)」を参照してください。
既定により、AWS リソースは名前を指定した値を使用します。リソースにアクセスするクライアント
を設定するために、既定のクライアント設定を使用することができます。
ゲームの設定に基づいて、リソース名を変更できるよう
1.
既定のクライアント設定では、リソース名にパラメータリファレンスを追加します。
2.
リソース名でパラメーターリファレンスを置換する値を設定するには、Cloud Canvas
(AWS):Configuration:SetConfigurationVariable のフローグラフノードを使用します。
たとえば、リソースデプロイは使わないが異なるステージでリソースを管理したい場合は、テーブル
名には "DailyGift_$stage$" を使用し、"$stage$" パラメーター値を設定し、選択する条件に
従って"###" または "####" を行います。
異なる複数のリソースに異なるクライアントの設定 (例：タイムアウト) を使用される場合は、C++
APIを使用して、指定した設定を行えます。フローグラフノードから提供されるリソース名が指定され
た設定に一致するとき、その設定はクライアントがリソースにアクセスできるようにするために使用
されます。
設定に関するフローは次のとおりです。
• ConfigureProxy– AWS サービス呼び出しに使用するHTTP プロキシ、ホスト、ポート、ユーザー
およびパスワードを設定します。
• SetConfigurationVariable–AWS リソースで使用するパラメータ値を設定します。
• GetConfigurationVariableValue– 現在の"$param$"パラメーター値の文字列内の部分文字列
を置き換えます。現在値がない場合は、 ""と置き換えます。
• SetDefaultRegion– 現在のプロジェクトのすべての AWS クライアントの地域を設定します。
• ApplyConfiguration– ほかのフローグラフノード設定で定められた AWS 設定を適用します。不
適切な配置の適用を防ぐために、いくつかの変更をすぐに適用することを許可します。
C++で設定
クライアントマネージャーの実装および AWS フローグラフノード実装は Cloud Canvas Gem を通じ
て提供されます。クライアントマネージャーを使用するには、Cloud Canvas Gem をプロジェクトコ
Version 1.6
319
Lumberyard 開発者ガイド
C++から設定済みクライアントを使用
ンフィギュレータ.を使用してゲームプロジェクトに追加してください。クライアントマネージャーの
コードを獲得するには、gEnv->pLmbrAWS->GetClientManager()を呼び出してください。これに
より、 IClientManagerというインターフェースが返されます。
クライアントマネージャーは、一連のパラメータ名をパラメータ値のマッピングのために維持しま
す。マッピングにアクセスするには、GetConfigurationParameters方法によって返されたオブ
ジェクトを使用します。"$param-name$" 部分文字列を使用して、パラメーター値を特定の設定に挿
入することができます。パラメータ値が "$param-name$" 部分文字列を含む場合は、対応するパラ
メータ値に置き換えられます。
AWS クライアント設定はクライアントマネージャーのGetDefaultClientSettings 方法によって
返されるオブジェクトのプロパティを基にします。GetClientSettingsOverridesCollection 方
法によって返されるコレクションオブジェクトを使用してこれらの設定のために指定したオーバーラ
イドを特定できます。オーバーライドには他の上書きを名前で集計でき、これにより一度指定したも
のは再利用が可能な一般構成設定ができます。これらの名前は、前述したように"$param-name$" 置
き換えられた値が含まれます。AWS フローグラフノードがクライアント設定のオーバーライドコレク
ションの名前と一致する場合は、これらのオーバーライドはリソースにアクセスする際にクライアン
トが使用します。
サービス固有設定は以下のクライアントマネージャーを使用した方法で提供されま
す。GetCognitoIdentityManagerGetDynamoDBManagerGetIAMManagerGetLambdaManagerGetS3ManagerGetS
よびGetSTSManager
それぞれのサービス固有マネージャーが提供するものは以下の通りです：
• すべての特定のサービスクライアントの既定設定を定義するのに使われるオブジェクトを返
すGetDefaultClientSettingsOverrides 方法。
• リソースを名前別に構成することを許可する方法。
たとえば、DynamoDBマネージャーは特定のDynamoDB テーブルを設定（設定名とリソース名は構成
により連結）するのに使用可能なGetTableClientSettingsCollection 方法があります。リソー
ス名は、前述したように、"$param-name$" 置き換えられた値が含まれます。
AWS フローグラフノードでは、その設定を使用するために、設定名をリソース名として使用でき
ます。この場合、設定名は実際のリソース名のエイリアスとして機能します。たとえば、ノードは
"DailyGift" をテーブル名として指定でき、リソース設定"DailyGift" は "foo-bar-$stage$"
をリソース名として指定できます。
もし "DailyGift_$stage$" という名前をフローグラフノード内で使い、リソース設定の
"DailyGift_$stage$" という名前を定義しなかった場合、"DailyGift_$stage$" を設定名およ
びリソース名両方の名前とすることがデフォルトで設定されます。
C++から設定済みクライアントを使用
クライアントマネージャーメソッド(GetCognitoIdentityManager、 GetDynamoDBManager、
GetIAMManager、 GetLambdaManager、 GetS3Manager、 GetSNSManager、 GetSQSManagerお
よび GetSTSManager) は前述した設定で設定されたクライアントの作成方法を提供するオブジェクト
を返します。
CreateManagedClient メソッドは指定された名前で特定されるクライアント設定オーバーライドを
使用して設定されたクライアントオブジェクトを返します。このオブジェクトは値によって渡すこと
ができます。クライアントのメソッドは-> オペレーターを使用してアクセスできます。
リソース専用CreateXClient メソッド（たとえば、DynamoDB用のテーブルリソー
スCreateTableClient ）を使用して、専用リソースにアクセスするクライアントの設定がで
きます。返されたオブジェクトはリソース名を引き出す方法（例：client.GetTableName）を
持っていますが、これはクライアントメソッドが->オペレーターを使用してアクセスされている間
（例：client->GetItem(...)）に行われます。
Version 1.6
320
Lumberyard 開発者ガイド
C++から設定済みクライアントを使用
Important
未設定の状態でクライアントを作成できます。クライアントの設定が完全に初期化する前
に、フローグラフノードと他のゲームのコンポーネントはクライアントを作成できます。た
とえば、ほかのフローグラフノードまたはコンポーネントが AWS サービスにアクセスする
には、Amazon Cognito 認証情報プロバイダーおよび設定パラメーターは、ゲーム開始時点で
トリガーされているフローグラフノードにより初期化する必要があります。このような理由
で、設定確認が完了したら、クライアント設定を明示的にトリガーする必要があります。
クライアントは使用前に、少なくとも一度はクライアントマネージャーのApplyConfigurationメ
ソッドを呼び出す必要があります。設定の変更を行った後は、それらの変更が有効になるまで、メ
ソッドを再度呼び出す必要があります。IsReady メソッド (client.IsReady(), not client>IsReady())を使用して、クライアントが設定されたかどうか確認することができます。
Version 1.6
321
Lumberyard 開発者ガイド
コンポーネントの作成
コンポーネントエンティティシステ
ム
コンポーネントエンティティシステムは現在プレビュー中であり、現在も開発が進められていま
す。これにより、レガシーの「エンティティシステム (p. 391)」が置き換えられます。
このガイドは、エンジンやゲームのプログラマーに、C++ でカスタム Lumberyard コンポーネント
を作成および反映するための例およびベストプラクティスを提供します。Lumberyard エディタ でコ
ンポーネントエンティティシステムを使用する詳細については、Amazon Lumberyard User Guide の
「コンポーネントエンティティシステム」を参照してください。
トピック
• コンポーネントの作成 (p. 322)
• シリアル化と編集のためのコンポーネントのリフレクション (p. 325)
• スライスと動的スライス (p. 331)
コンポーネントの作成
コンポーネントエンティティシステムは現在プレビュー中であり、現在も開発が進められていま
す。これにより、レガシーの「エンティティシステム (p. 391)」が置き換えられます。
Lumberyard のコンポーネントは、Lumberyard の AZ::Component を継承する単純なクラスです。
コンポーネントの動作は、反映済みデータとアクティブ化時に実行されるアクションによって決ま
ります。このセクションでは、Lumberyard コンポーネントをプログラムで作成する方法について説
明します。Lumberyard エディタ で使用できるコンポーネントの追加およびカスタマイズについて
は、Amazon Lumberyard User Guide の「コンポーネントエンティティシステム」を参照してくださ
い。
コンポーネントの例
例のコンポーネントのクラススケルトンは次のとおりです。
class MyComponent
Version 1.6
322
Lumberyard 開発者ガイド
コンポーネントの要素
: public AZ::Component
{
public:
AZ_COMPONENT(MyComponent, "{0C09F774-DECA-40C4-8B54-3A93033EC381}");
//////////////////////////////////////////////////////////////////////////
// AZ::Component interface implementation
void Init() override {}
void Activate() override {}
void Deactivate() override {}
//////////////////////////////////////////////////////////////////////////
// Required Reflect function.
static void Reflect(AZ::ReflectContext* context);
// Optional functions for defining provided and dependent services.
static void
GetProvidedServices(AZ::ComponentDescriptor::DependencyArrayType& provided)
static void
GetDependentServices(AZ::ComponentDescriptor::DependencyArrayType&
dependent);
static void
GetRequiredServices(AZ::ComponentDescriptor::DependencyArrayType& required);
static void
GetIncompatibleServices(AZ::ComponentDescriptor::DependencyArrayType&
incompatible);
};
コンポーネントの要素
コンポーネントを構成する必須の要素とオプションの要素は次のとおりです。
AZ::Component
各コンポーネントでは、継承祖先のどこかに AZ::Componentを含める必要があります。非エ
ディタのコンポーネントは通常、AZ::Component を直接継承しますが、次の例のような独自の
コンポーネントクラス階層を作成できます。
class MyComponent
: public AZ::Component
AZ_COMPONENT マクロ
各コンポーネントでは、クラス定義で AZ_COMPONENT マクロを指定する必要があります。このマ
クロは 2 個の引数を取ります。
1. コンポーネントの型名。
2. 一意の UUID。任意の UUID ジェネレーターを使用して値を生成できます。Visual Studio で
は、[ツール] の [GUID の作成] でこの機能が提供されています。[レジストリ形式] の設定を使
用し、生成された値をコピーして貼り付けます。
AZ_COMPONENT マクロのサンプルを次に示します。
AZ_COMPONENT(MyComponent, "{0C09F774-DECA-40C4-8B54-3A93033EC381}");
AZ::Component 関数
コンポーネントの動作を定義するには、通常は Init、Activate、Deactivate の 3 つの
AZ::Component 関数をオーバーライドします。
Version 1.6
323
Lumberyard 開発者ガイド
コンポーネントの要素
void Init() override
{}
void Activate() override
{}
void Deactivate() override {}
これらの関数について以下に説明します。
Init() – オプション
指定のエンティティに対して一度だけ呼び出されます。コンポーネントはすぐにアクティ
ブ化されないことがあるため、この関数では最小限の構築またはセットアップ作業が必要で
す。コンポーネントが非アクティブの状態ではコンポーネントでの CPU とメモリのオーバー
ヘッドを最小限に抑えることが、重要なベストプラクティスです。
Activate() – 必須
所有エンティティがアクティブ化されるときに呼び出されます。すべての依存サービスおよ
び必須サービスが存在する場合にのみ、システムによってコンポーネントの Activate() 関
数が呼び出されます。Activate 関数は常に、すべての依存コンポーネントの後に呼び出さ
れます。また、エンティティがアクティブである間にそのエンティティのコンポーネント構
成が変更されることはないため、パフォーマンスが重要な場合には、エンティティで他のコ
ンポーネントへのポインタや参照をキャッシュしても安全です。
Deactivate() – 必須
所有エンティティが非アクティブ化されるときに呼び出されます。非アクティブ化の順序は
アクティブ化の逆順であるため、コンポーネントは依存コンポーネントより前に非アクティ
ブ化されます。ベストプラクティスとして、非アクティブ化の状態ではコンポーネントが最
小限のフットプリントに戻るようにします。通常は、非アクティブ化はアクティブ化と対称
になります。
Note
非アクティブ化の後に破壊されるとは限りません。エンティティが非アクティブ化さ
れた後に、破壊されずに再度非アクティブ化されることがあるため、コンポーネント
でそれが効率的にサポートされるようにします。ただし、エンティティを破棄する場
合、Lumberyard では Deactivate() 関数が最初に呼び出されることが保証されて
います。この点を考慮してコンポーネントを作成する必要があります。
Reflect() – 必須
すべてのコンポーネントは AZ 反映済みクラスです。すべてのコンポーネントはシリアル化可能
であり編集可能である必要があるため、以下の例のように Reflect() 関数が含まれている必要
があります。
// Required Reflect function.
static void Reflect(AZ::ReflectContext* context);
詳細については、「シリアル化と編集のためのコンポーネントのリフレクション (p. 325)」を参
照してください。
論理サービス – オプション
コンポーネントでは、提供する論理サービス、依存する論理サービス、または互換性のない論理
サービスの任意の組み合わせを定義できます。これらの論理サービスを定義するには、以下の関
数を使用します。
// Optional functions for defining provided and dependent services.
static
void GetProvidedServices(AZ::ComponentDescriptor::DependencyArrayType&
provided)
static
void GetDependentServices(AZ::ComponentDescriptor::DependencyArrayType&
dependent);
Version 1.6
324
Lumberyard 開発者ガイド
シリアル化と編集のためのコ
ンポーネントのリフレクション
static
void GetRequiredServices(AZ::ComponentDescriptor::DependencyArrayType&
required);
static
void GetIncompatibleServices(AZ::ComponentDescriptor::DependencyArrayType&
incompatible);
シリアル化と編集のためのコンポーネントのリフ
レクション
コンポーネントエンティティシステムは現在プレビュー中であり、現在も開発が進められていま
す。これにより、レガシーの「エンティティシステム (p. 391)」が置き換えられます。
コンポーネントは、AZ リフレクションを使用して、シリアル化するデータ、およびコンテンツ作成者
がそれらのデータとやり取りする方法を記述します。
次の例では、シリアル化および編集を行うためにコンポーネントをリフレクションしています。
class MyComponent
: public AZ::Component
{
...
enum class SomeEnum
{
EnumValue1,
EnumValue2,
}
float m_someFloatField;
AZStd::string m_someStringField;
SomeEnum m_someEnumField;
AZStd::vector<SomeClassThatSomeoneHasReflected> m_things;
int m_runtimeStateNoSerialize;
}
/*static*/ void MyComponent::Reflect(AZ::ReflectContext* context)
{
AZ::SerializeContext* serialize =
azrtti_cast<AZ::SerializeContext*>(context);
if (serialize)
{
// Reflect the class fields that you want to serialize.
// In this example, m_runtimeStateNoSerialize is not reflected for
serialization.
serialize->Class<MyComponent>()
->Version(1)
->Field("SomeFloat", &MyComponent::m_someFloatField)
->Field("SomeString", &MyComponent::m_someStringField)
->Field("Things", &MyComponent::m_things)
->Field("SomeEnum", &MyComponent::m_someEnumField)
;
Version 1.6
325
Lumberyard 開発者ガイド
シリアル化と編集のためのコ
ンポーネントのリフレクション
AZ::EditContext* edit = serialize->GetEditContext();
if (edit)
{
edit->Class<MyComponent>("My Component", "The World's Most Clever
Component")
->DataElement(AZ::Edit::DefaultHandler,
&MyComponent::m_someFloatField, "Some Float", "This is a float that means
X.")
->DataElement(AZ::Edit::DefaultHandler,
&MyComponent::m_someStringField, "Some String", "This is a string that means
Y.")
->DataElement("ComboBox", &MyComponent::m_someEnumField,
"Choose an Enum", "Pick an option among a set of enum values.")
->EnumAttribute(MyComponent::SomeEnum::EnumValue1, "Value
1")
->EnumAttribute(MyComponent::SomeEnum::EnumValue2, "Value
2")
->DataElement(AZ::Edit::DefaultHandler,
&MyComponent::m_things, "Bunch of Things", "A list of things for doing Z.")
;
}
}
}
前の例は、5 つのデータメンバーを MyComponent に追加しています。最初の 4 つのデータメンバー
がシリアル化されます。最後のデータメンバーに含まれているのはランタイム状態のみです。した
がって、このメンバーはシリアル化されません。このように、コンポーネントには通常、シリアル化
されるメンバーとシリアル化されないメンバーが混在しています。
これは、変更のコールバック (p. 329)といった高度なリフレクション機能を使用する場合は、編集す
るためではなくシリアル化するためにフィールドをリフレクションするのが一般的です。そのような
場合、コンポーネントはユーザープロパティの変更内容に基づいて内部で複雑な計算を行うこともあ
ります。これらの計算結果は、シリアル化する必要はありますが、編集用に公開してはなりません。
このような場合は、フィールドを SerializeContext にリフレクションして、EditContext にエ
ントリを追加しないようにします。以下に例を示します。
serialize->Class<MyComponent>()
->Version(1)
...
->Field("SomeFloat", &MyComponent::m_someFloatField)
->Field("MoreData", &MyComponent::m_moreData)
...
;
...
AZ::EditContext* edit = serialize->GetEditContext();
if (edit)
{
edit->Class<MyComponent>("My Component", "The World's Most Clever
Component")
->DataElement(AZ::Edit::DefaultHandler,
&MyComponent::m_someFloatField, "Some Float", "This is a float that means
X.")
->EnumAttribute("ChangeNotify", &MyComponent::CalculateMoreData)
// m_moreData is not reflected for editing directly.
;
}
Version 1.6
326
Lumberyard 開発者ガイド
シリアル化
Lumberyard には、さまざまな目的に使用するリフレクションコンテキストが用意されています。
• SerializeContext - オブジェクトのシリアル化と構築のためのリフレクションデータが格納され
ます。
• EditContext –オブジェクトを視覚的に編集するためのリフレクションデータが格納されます。
• BehaviorContext – Lua、フローグラフ、または他の外部ソースのオブジェクトのランタイム操作
のためのリフレクションが格納されます。
• NetworkContext – マーシャリング、量子化、外挿などネットワーキングのためのリフレクション
が格納されます。
Note
このガイドでは、SerializeContext と EditContext の 2 つについて説明します。
Lumberyard のすべてのリフレクション API は、シンプルで、人が読み書き可能で、コードを生成し
なくて済むように設計されています。
コンポーネントの Reflect() 関数は関連するすべてのコンテキストで自動的に呼び出されます。
次のコードは、シリアル化コンテキストに渡される無名コンテキストを動的にキャストしています。
コンポーネントは、この方法で、Reflect() の呼び出し対象となるコンテキストのタイプを識別しま
す。
AZ::SerializeContext* serialize =
azrtti_cast<AZ::SerializeContext*>(context);
シリアル化
シリアル化のためのクラスをリフレクションするには、C++ のビルダーパターンスタイルマークアッ
プが必要です。次に例を示します。
serialize->Class<TestAsset>()
->Version(1)
->Field("SomeFloat", &MyComponent::m_someFloatField)
->Field("SomeString", &MyComponent::m_someStringField)
->Field("Things", &MyComponent::m_things)
->Field("SomeEnum", &MyComponent::m_someEnumField)
;
この例では、コンポーネントで、m_someFloatField、m_someStringField、m_things、および
m_someEnumField をすべてシリアル化するよう指定しています。フィールド名は一意でなければな
らず、ユーザー向けの名前は使用しません。
Tip
今後の実証のためにフィールド名はシンプルにすることをお勧めします。コンポーネントが
大幅に変更されたため、データの下位互換性を維持するためにデータコンバーターを書く場
合は、フィールド名を直接参照する必要があります。
上記の例では、2 つのプリミティブ型 (浮動小数点型と文字列型)、および特定の構造体のコンテナ (ベ
クタ) をリフレクションしています。AZ リフレクション、シリアル化、および編集では、さまざまな
広範囲の型をサポートしています。
Version 1.6
327
Lumberyard 開発者ガイド
AWS OpsWorks の
• プリミティブ型、すなわち整数型 (符号付き、符号なし、全サイズ)、浮動小数点型、および文字列
型。
• 列挙型
• AZStd コンテナ (フラットおよび連
想)。AZStd::vector、AZStd::list、AZStd::map、AZStd::unordered_map、AZStd::set、AZStd::unorde
固定長 C 形式の配列など。
• ポインタ。AZStd::smart_ptr、AZStd::intrusive_ptr、および RAW ネイティブポインタ。
• それ自体もリフレクションされている任意のクラスや構造体。
Note
例では、SomeClassThatSomeoneHasReflected のリフレクションコードを省略していま
す。このコードは、クラスをリフレクションするだけです。リフレクション後は、そのクラ
スのメンバーやコンテナを別のクラスで自由にリフレクションできます。
AWS OpsWorks の
Lumberyard エディタ などの Lumberyard ツールを実行する際には、EditContext と
SerializeContext が提供されます。これらのコンテキスト内で堅牢な機能を使用してフィールド
をコンテンツ作成者に公開できます。
次のコードは、基本的な編集コンテキストリフレクションを示しています。
AZ::EditContext* edit = serialize->GetEditContext();
if (edit)
{
edit->Class<TestAsset>("My Component", "The World's Most Clever
Component")
->DataElement(AZ::Edit::DefaultHandler,
&MyComponent::m_someFloatField, "Some Float", "This is a float that means
X.")
->DataElement(AZ::Edit::DefaultHandler,
&MyComponent::m_someStringField, "Some String", "This is a string that means
Y.")
->DataElement("ComboBox", &MyComponent::m_someEnumField, "Choose an
Enum", "Pick an option among a set of enum values.")
->EnumAttribute(MyComponent::SomeEnum::EnumValue1, "Value 1")
->EnumAttribute(MyComponent::SomeEnum::EnumValue2, "Value 2")
->DataElement(AZ::Edit::DefaultHandler, &MyComponent::m_things,
"Bunch of Things", "A list of things for doing Z.")
;
}
この例は最も簡単な使い方を示したものです。この他にも、構造体 (コンポーネントを含む) を編集コ
ンテキストにリフレクションする場合に多数の機能やオプションを使用できます。この例では、コン
テンツ作成者に直接フィールドを公開するため、DataElement の 第 3 および第 4 パラメーターにわ
かりやすい名前と説明 (ツールヒント) を指定しています。3 つのフィールドの場合、DataElement
の最初のパラメーターは、デフォルト UI ハンドラ AZ::Edit::DefaultHandler です。プロパティ
システムのアーキテクチャでは、UI ハンドラをいくつでも追加できる機能をサポートしています。各
ハンドラは、1 つ以上のフィールドタイプに使用できます。指定された型には利用可能なハンドラを
複数割り当てることができます。このうち 1 つがデフォルトのハンドラとして指定されます。たとえ
ば、浮動小数点型の場合、デフォルトのハンドラは SpinBox ですが、Slider ハンドラも利用できま
す。
次の例では、浮動小数点数をスライダにバインドしています。
Version 1.6
328
Lumberyard 開発者ガイド
属性
->DataElement("Slider", &MyComponent::m_someFloatField, "Some Float", "This
is a float that means X.")
->Attribute("Min", 0.f)
->Attribute("Max", 10.f)
->Attribute("Step", 0.1f)
Slider UI ハンドラは、Min 属性と Max 属性を受け取ります。また、必要に応じて、Step 値を指
定することもできます。この例では、増分として 0.1 を指定しています。Step 値を省略すると、デ
フォルトの増分として 1.0 が使用されます。
Note
プロパティシステムは外部 UI ハンドラをサポートしているため、ユーザーは独自のモジュー
ルで独自の UI ハンドラを実装できます。これにより、フィールドの動作、フィールドが使用
する Qt コントロール、フィールドが監視する属性をカスタマイズできます。
属性
上の例は、属性の使い方も示しています。属性は、編集コンテキストの汎用的な構造体であり、リテ
ラル、または値を返す関数を名前付きの属性にバインドすることができます。UI ハンドラはこのデー
タを取得し、それを使用して機能を実行できます。
属性値は、以下にバインドできます。
• リテラル値
• Attribute("Min", 0.f)
• 静的変数またはグローバル変数
• Attribute("Min", &g_globalMin)
• メンバー変数
• Attribute("Min", &MyComponent::m_min)
• 静的関数またはグローバル関数
• &SomeGlobalFunction
• メンバー関数
• &MyComponent::SomeMemberFunction
変更通知コールバック
編集コンテキストのもう 1 つのよく使用される機能として、変更通知コールバックにバインドする機
能があります。
->DataElement(AZ::Edit::DefaultHandler, &MyComponent::m_someStringField,
"Some String", "This is a string that means Y.")
->Attribute("ChangeNotify", &MyComponent::OnStringFieldChanged)
この例では、このプログラムが変更されると呼び出されるメンバー関数をバインドしています。これ
により、コンポーネントは別のロジックを実行できます。ChangeNotify 属性により、任意指定の
戻り値を監視して、プロパティシステムに状態のさまざまな部分を更新する必要があるかどうかを通
知することもできます。たとえば、変更コールバックがプロパティシステムに影響を与える他の内部
データを変更した場合、値の更新をリクエストできます。コールバックがデータを変更し、属性の再
評価 (およびバインド関数がある場合はその再呼び出し) が必要となった場合は、属性と値の更新をリ
Version 1.6
329
Lumberyard 開発者ガイド
変更通知コールバック
クエストできます。最後にコールバックが完全な更新を必要とする処理を実行した場合は (これは一般
的ではない)、状態全体を更新できます。
次の例では、m_someStringField がプロパティグリッドを介して変更されると、プロパティグ
リッドによって値が更新されます。RefreshValues は、基盤となるデータが変更されると、GUI を
更新するようにプロパティグリッドにシグナルを送信します。
->DataElement(AZ::Edit::DefaultHandler, &MyComponent::m_someStringField,
"Some String", "This is a string that means Y.")
->Attribute("ChangeNotify", &MyComponent::OnStringFieldChanged)
...
AZ::u32 MyComponent::OnStringFieldChanged()
{
m_someFloatField = 10.0f;
// We've internally changed displayed data, so tell the property grid to
refresh values (cheap).
return AZ_CRC("RefreshValues");
}
RefreshValues は、使用可能な 3 つの更新モードのうちの 1 つです。
• RefreshValues – 値のみを更新します。プロパティグリッドは、変更コールバックで発生する可
能性のある基盤となるデータの変更を反映するように GUI を更新します。
• RefreshAttributesAndValues – 値を更新し、属性を再評価します。属性はデータメンバー、メ
ンバー関数、グローバル関数、または静的変数にバインドできるため、プロパティグリッドに属性
の再評価 (バインドされている関数の再呼び出しを含む) を要求する必要があることがあります。
• RefreshAll – プロパティグリッドを完全に再評価します。RefreshAttributesAndValues に
よって、多機能で動的なエディタリフレクションの要件はすべてカバーされているはずであるた
め、このモードが必要になることはほとんどありません。
以下に、もう少し複雑な例を示します。この例では、コンボボックスの選択肢として文字列のリスト
をバインドしています。文字列のリストは、文字列フィールド Property A に結合されます。Property
A のコンボボックスで使用可能な選択肢を別の Property B の値で変更する場合は、コンボボックスの
StringList 属性を、選択肢のリストを計算して返すメンバー関数にバインドします。Property B の
ChangeNotify 属性で、システムに属性を再評価するように指示します。これにより、この例のよう
に、選択肢のリストを計算する関数が呼び出されます。
...
bool m_enableAdvancedOptions;
AZStd::string m_useOption;
...
->DataElement(AZ::Edit::DefaultHandler,
&MyComponent::m_enableAdvancedOptions, "Enable Advanced Options", "If set,
advanced options will be shown.")
->Attribute("ChangeNotify", AZ_CRC("RefreshAttributesAndValues"))
->DataElement("ComboBox", &MyComponent::m_useOption, "Options", "Available
options.")
->Attribute("StringList", &MyComponent::GetEnabledOptions)
...
AZStd::vector<const char*> MyComponent::GetEnabledOptions()
{
Version 1.6
330
Lumberyard 開発者ガイド
スライスと動的スライス
AZStd::vector<const char*> options;
options.reserve(16);
options.push_back("Basic option");
options.push_back("Another basic option");
if (m_enableAdvancedOptions)
{
options.push_back("Advanced option");
options.push_back("Another advanced option");
}
return options;
}
スライスと動的スライス
コンポーネントエンティティシステムは現在プレビュー中であり、現在も開発が進められていま
す。これにより、レガシーの「エンティティシステム (p. 391)」が置き換えられます。
スライスは、再利用可能なアセット内の単一のユニットとして保存されている設定済みエンティ
ティ (p. 322)のコレクションです。スライスを使用して、再利用のためにエンティティや他のスラ
イスを簡単にグループ化できます。スライスはプレハブに似ていますが、新しいコンポーネントエ
ンティティシステムの一部です。スライスにはコンポーネントエンティティを含めることができます
が、プレハブではできません。プレハブとは異なり、スライスは完全カスケード階層にネストできま
す。たとえば、レベル、家、車、および世界全体はすべてスライスであり、(カスケードされている)
いくつかの他のスライスに依存しています。
任意の個数の配置および設定済みエンティティが含まれるスライスアセットを生成できます。これら
のエンティティでは任意の関係を持つことができます。たとえば、それらのエンティティは親/子の変
換階層に存在できますが、必須ではありません。
スライスアセットを作成したら、ビューポートで右クリックして [Instantiate Slice] を選択するか、
または直接 File Browser からビューポートへスライスアセットをドラッグすることによって、エディ
タを使用してそのスライスアセットを自分の世界でインスタンス化できます。標準のプレハブシステ
ムと同様に、スライスインスタンスでエンティティを変更できます。そのスライスアセットのすべて
のインスタンスやそのスライスアセットからカスケードされている他のスライスに影響を与える変更
を、元のスライスアセットにプッシュすることもできます。
スライスには他のスライスのインスタンスを含めることができます。別のスライス内のスライスイン
スタンスを変更すると、その変更はオーバーライドとしてそのインスタンスに (データの差分またはデ
ルタの形式で) 保存されます。保存される変更には、エンティティの追加、エンティティの削除、コン
ポーネントのプロパティの変更、などがあります。
スライスの構造
次の図は、他の 2 つのスライス B と C への参照が含まれているスライス A の例を示していて、スラ
イス A には B と C の 2 つのインスタンスがあります。
Version 1.6
331
Lumberyard 開発者ガイド
動的スライスの使用
各インスタンスにはデータパッチが含まれていて、変更やオーバーライドがない場合は空である可能
性があります。スライス A でのスライス B のインスタンス化が元のアセット B から変更されている
場合は、その差分がデータパッチに含まれています。スライス A が再度インスタンス化されると、そ
の変更内容が適用されているスライス B のインスタンスが含まれます。オーバーライドされていない
すべてのフィールドは階層全体に伝達されます。ディスク上のスライス B アセットのプロパティ値を
変更すると、スライス A に含まれている B のインスタンスにその変更内容が反映されます。そのイン
スタンスのプロパティがまだオーバーライドされていない場合は、そのインスタンスのデータパッチ
に反映されます。
他のスライスへの参照に加えて、スライスにはゼロ個または複数個のエンティティを含めることがで
きます。これらのエンティティはそのスライスに固有であり、参照先のスライスインスタンスでは取
得されません。スライスに他のスライスへの参照を含める必要はありません。元のエンティティ (図の
下部のボックスで示されている) だけが含まれていて、他のスライスへの参照がないスライスは、リー
フスライスと呼ばれます。
動的スライスの使用
スライスは世界のエンティティデータを編成するための強力なツールです。エディタでは、階層全体
でのデータ共有や継承の利点を保持したままで、スライスをカスケードしてエンティティデータを任
意の細分度で編成することを選択できます。たとえば、レベルベースのゲームでは、他の多数のスラ
イスのインスタンスを含む個別のスライスアセットとして各レベルを実装します。これらのスライス
では、多数のレベルを深くカスケードできます。他のスライスからスライスを作成し、必要な要素だ
けを継承することも選択できます。
標準スライスアセット (.slice ファイル) はエディタに依存していて、実行時にインスタンス化す
ることはできません。ただし、Lumberyard では、構築済みの任意の .slice アセットを動的スライ
スとして指定するためのメカニズムが提供されています。スライスを動的スライスとして指定する
と、アセットプロセッサによってそのスライスが処理および最適化され、.dynamicslice ファイル
アセットが作成されます。動的スライスは元のスライスの単なるランタイム版であり、ランタイムコ
ンポーネントだけが含まれています。エディタ依存のコンポーネントはランタイム対応コンポーネン
トに変換されています。さらに、動的スライスはフラット化されていて、データ階層は維持されてい
ません。そのため、メモリフットプリントが増加し、インスタンス化のパフォーマンスが低下するこ
とがあります。
前述のレベルベースのゲームの例では、大きなレベルのスライスを動的スライスとして指定できま
す。ゲームでそのレベルがロードされる際に、作成された .dynamicslice ファイルがインスタンス
化されます。
ゲームに適した任意の細分度で動的スライスを生成することができます。スライスは完全に非同期に
ロードされるため、ストリーミングでは適切な選択肢になります。たとえば、レーシングゲームで
Version 1.6
332
Lumberyard 開発者ガイド
動的スライスのインスタンス化
は、各街区を個別のスライスとして表現し、プレイヤーの運転動作に応じて予測して街区をロードす
ることができます。
動的スライスを生成する方法
File Browser で .slice アセットを右クリックし、[Set Dynamic Flag] をクリックします。
アセットプロセッサは元の .slice ファイルを処理して .dynamicslice ファイルを生成します。新
しい .dynamicslice ファイルは固有のアセットとしてファイルブラウザに表示されます。
動的スライスを削除する方法
元の .slice ファイルを右クリックして [Unset Dynamic Flag] を選択します。
アセットプロセッサはその .dynamicslice ファイルをアセットキャッシュから削除します。
動的スライスのインスタンス化
動的スライスは各自のコンポーネントからインスタンス化できます。そうするには、DynamicSlice
アセット参照を反映 (p. 325)させます。その参照は、エディタで .dynamicslice アセットをファ
イルブラウザからコンポーネントの反映済みアセットプロパティにドラッグする、などの通常の方法
で入力できます。次の EBus 呼び出しを使用して、その参照されている動的スライスを世界の目的の
場所でインスタンス化します。
// Asset reference member, which must be reflected.
AZ::Data::Asset<AZ::DynamicPrefabAsset> m_sliceAsset;
// Create an instance of the dynamic slice.
AZ::Transform location = ...;
EBUS_EVENT(AzFramework::GameEntityContextRequestBus, InstantiateDynamicSlice,
m_sliceAsset, location);
Lumberyard には、この動作を示す良い例であるスポナーコンポーネントが付属しています。このスポ
ナーコンポーネントは、直接使用するか、または独自のアプリケーションを構築するための例として
使用できます。
Version 1.6
333
Lumberyard 開発者ガイド
動的スライスのインスタンス化
スポナーコンポーネントのソースコードは、Lumberyard のインストール先フォルダーの dev\Code
\Engine\LmbrCentral\source\Scripting\SpawnerComponent.cpp にあります。
AZ::Module の作成については、「AZ モジュールの作成」を参照してください。スライスの使用に
ついては、「スライスの使用」を参照してください。
Version 1.6
334
Lumberyard 開発者ガイド
アクションマップ
コントローラデバイスとゲームの入
力
このセクションでは、コントロールおよびアクションマップの設定方法に関する情報な
ど、Lumberyard でサポートされている入力デバイスについて詳しく説明します。
トピック
• アクションマップ (p. 335)
• CryInput (p. 336)
• コントロールおよびアクションマップの設定 (p. 338)
アクションマップ
Action Map Manager は、ゲーム内の入力コントロールを処理するための高レベルインターフェイスを
提供します。アクションマップシステムは Lumberyard に実装され、Lumberyard または GameDLL 内
の任意のコードから直接使用できます。
Action Map Manager の初期化
Action Map Manager の初期化は、Lumberyard が初期化されるときに行われます。ゲームで
defaultProfile.xml ファイルのパスを指定する必要があります (デフォルトのパスは Game/Libs/
Config/defaultProfile.xml です)。これは、マネージャーにパスを渡すことで行います。以下に
例を示します。
IActionMapManager* pActionMapManager = m_pFramework->GetIActionMapManager();
if (pActionMapManager)
{
pActionMapManager->InitActionMaps(filename);
}
Version 1.6
335
Lumberyard 開発者ガイド
Action Map Manager のイベント
初期化時には、Action Map Manager によって既存の初期化済みのマップ、フィルタ、コントローラー
レイアウトがすべて削除されます。
Action Map Manager のイベント
他のシステムが導入されていて、そのシステムでアクションマップのイベントを認識する必要がある
場合は、IActionMapEventListener インターフェイスを使用して Action Map Manager のイベント
にサブスクライブできます。
利用できるイベントは次のとおりです。
• eActionMapManagerEvent_ActionMapsInitialized – アクションマップ定義が正しく初期化
されました。
• eActionMapManagerEvent_DefaultActionEntityChanged – デフォルトのアクションエン
ティティが変更されました (このエンティティには、マネージャーによって自動的に新しいアクショ
ンマップが割り当てられます)。
• eActionMapManagerEvent_FilterStatusChanged – 既存のフィルタが有効化または無効化さ
れました。
• eActionMapManagerEvent_ActionMapStatusChanged – 既存のアクションマップが有効化また
は無効化されました。
実行時のアクションの受信
実行時にアクションマップでアクションを受け取る機能を有効にすることができます。次のコードを
使用して、実行中のアクションマップを有効または無効にします。
pActionMapMan->EnableActionMap("default", true);
アクションを受け取るには、クラスに IActionListener インターフェイスを実装します。
CryInput
CryInput の主な目的は、キーボード、マウス、ジョイスティックなどのさまざまな入力デバイスから
入力とステータスを取得するための抽象化を提供することです。
入力デバイスへのフィードバックイベント (力フィードバックイベントなど) の送信もサポートされま
す。
入力システムの共通インターフェイスは、CryCommon プロジェクトの IInput.h にあります。
IInput
IInput は、入力システムのメインインターフェイスです。このインターフェイスを実装するインス
タンスは、システムの初期化時に、InitInput 関数 (CrySystem ではInitSystem.cpp。CryInput の
CryInput.cpp も参照してください) で自動的に作成されます。
このインターフェイスのインスタンスは、1 つだけ作成されます。CrySystem では、入力システムの
更新とシャットダウンも管理されます。
この IInput インスタンスは、SSystemGlobalEnvironment 構造体である gEnv に保存されます。
これには、gEnv->pInput を使用してアクセスできます。または、GetISystem()->GetIInput()
Version 1.6
336
Lumberyard 開発者ガイド
IInputEventListener
を使用してシステムインターフェイスからアクセスすることもできます。最も一般的に使用されてい
るのは、gEnv 変数からアクセスする方法です。
IInputEventListener
入力システム内の一般的ユースケースは、IInputEventListener から継承することで他のモジュー
ル (CryGame など) にリスナークラスを作成し、入力イベントの通知用にリスナークラスを入力シス
テムに登録/登録解除することです。
たとえば、Action Map System は自身を入力リスナーに登録し、プロファイル設定ファイルに定義さ
れているキーに対応するゲームイベントのみを転送して、デバイスからゲームへのプレイヤー入力を
さらに抽象化します。
SInputEvent
SInputEvent は、任意の入力デバイスで作成され、すべての入力イベントリスナーが受け取った情
報をカプセル化します。
IInputDevice
入力デバイスは通常、ジョイパッド、マウス、キーボードなどの物理的な入力デバイスに直接関連し
ています。新しい入力デバイスを作成するには、IInputDevice インターフェイスのすべての関数を
実装し、AddInputDevice 関数を使用して、このインターフェイスのインスタンスを入力システムに
登録する必要があります。
IInputDevice を入力システムに登録すると、Init 関数が呼び出されます。入力デバイスの作成時
に呼び出す必要はありません。
入力システムで更新が発生するたびに、Update 関数が呼び出されます。一般的に、デバイスの状態
を確認/更新し、入力イベントを生成して入力システムに転送するのは、この関数です。
入力デバイスは一般的に、入力デバイスが Init 関数で生成できる各記号のリストを作成して
SInputSymbol に保存します。次に、Update 関数で、変化したボタン/軸に対する記号が照会され、イ
ベントに必要な情報を指定するために (AssignTo 関数を通じて) 使用されます。このイベントは、入
力システムに送られます。
例:
// function from CInputDevice (accessible only within CryInput)
MapSymbol(...)
{
SInputSymbol\* pSymbol = new SInputSymbol( deviceSpecificId, keyId,
name, type );
pSymbol->user = user;
pSymbol->deviceId = m_deviceId;
m_idToInfo\[ keyId \] = pSymbol;
m_devSpecIdToSymbol\[ deviceSpecificId \] = pSymbol;
m_nameToId\[ name \] = deviceSpecificId;
m_nameToInfo\[ name \] = pSymbol;
return pSymbol;
}
bool CMyKeyboardInputDevice::Init()
{
...
Version 1.6
337
Lumberyard 開発者ガイド
コントロールおよびアクションマップの設定
//CreateDeviceEtc();
...
m_symbols\[ DIK_1 \] = MapSymbol( DIK_1, eKI_1, "1" );
m_symbols\[ DIK_2 \] = MapSymbol( DIK_2, eKI_2, "2" );
...
}
void CMyKeyboardInputDevice::Update( ... )
{
// Acquire device if necessary
...
// Will probably want to check for all keys, so the following section
might be part of a loop
SInputSymbol\* pSymbol = m_symbols\[ deviceKeyId \];
...
// check if state changed
...
// This is an example for, when pressed, see ChangeEvent function for
axis type symbols
pSymbol->PressEvent( true );
SInputEvent event;
pSymbol->AssignTo( event, modifiers );
gEnv->pInput->PostInputEvent( event );
}
イベントのリスナーが受信できるように、イベントを入力システムに転送するには、IInput の
PostInputEvent 関数を使用します。
入力デバイスを CryInput に追加する場合は、IInputDevice のほとんどの関数の汎用的な実装が既に提
供されている CInputDevice を直接継承すると、役立つことがあります。
Note
このファイルは、CryEngine のフルソースに含まれています。FreeSDK や GameCodeOnly
ソリューションには含まれていません。これらのライセンスでは、IInputDevice から直接抽出
してください。
コントロールおよびアクションマップの設定
このセクションでは、アクションマップを作成および変更して、ゲームのニーズに合わせてコント
ロールをカスタマイズする方法を示します。
サポートされるすべてのプラットフォームのアクションマッププロファイルは、Game\Libs\Config
\Profile\DefaultProfile.xml にあります。このデフォルトの XML ファイルでは、コントロー
ルが次のセクションに分類され、それぞれは独自のアクションマップによって制御されます。
• multiplayer
• singleplayer
• デバッグ
• flycam
• デフォルト
• player
• vehicle
Version 1.6
338
Lumberyard 開発者ガイド
アクションマップ
• land vehicle
• sea vehicle
• helicopter
各アクションのマップは、フローグラフ、Lua スクリプト、または C++ コードでランタイムに有効ま
たは無効にできます。
SDK パッケージのコントロールの概要については、「デフォルトのコントローラーマッピン
グ (p. 341)」トピックを参照してください。
アクションマップ
アクションマップは、特定のゲームモード用のキー/ボタンのマッピングのセットです。たとえ
ば、"Helicopter" という名前の、ヘリコプターコントロール用の <actionmap> セクションがあ
ります。このセクション内のすべては、ヘリコプターを飛ばすときにのみ適用されるキーとボ
タンのバインドで構成されます。一般的なゲーム内部のバインドを変更するには、<actionmap
name="default"> で始まるセクションに移動します。また、マルチプレイヤ固有のバインド用のセ
クションがあります。もちろん、必要な他の車両またはモード用のセクションもあります。
標準アクションマップの概要を次に示します。ここでは、標準のデバッグマップを示します。
<actionmap name="debug" version="22">
<!-- debug keys – move to debug when we can switch devmode-->
<action name="flymode" onPress="1" noModifiers="1" keyboard="f3" />
<action name="godmode" onPress="1" noModifiers="1" keyboard="f4" />
<action name="toggleaidebugdraw" onPress="1" noModifiers="1"
keyboard="f11" />
<action name="togglepdrawhelpers" onPress="1" noModifiers="1"
keyboard="f10" />
<action name="ulammo" onPress="1" noModifiers="1" keyboard="np_2" />
<action name="debug" onPress="1" keyboard="7" />
<action name="thirdperson" onPress="1" noModifiers="1" keyboard="f1" />
<!-- debug keys – end -->
</actionmap>
バージョニング
<actionmap name="debug" version="22">
バージョンの値を増分すると、Lumberyard により、新しく更新されたアクションマップをユーザープ
ロファイルが受け取るようになります。これは、すでにリリースされているゲームのパッチで新しい
アクションをデプロイする際に非常に役立ちます。バージョンが同じである場合、アクションマップ
への変更または追加はユーザープロファイルには伝播されません。
アクティベーションモード
以下のアクティベーションモードを使用できます。
• onPress – アクションキーが押された
• onRelease – アクションキーが放された
• onHold – アクションキーが押されたままである
• always – 完全にアクティベートされた
Version 1.6
339
Lumberyard 開発者ガイド
アクションフィルタ
アクティベーションモードがアクションリスナーに渡され、対応する Lua 定数によって識別されま
す。
• eAAM_OnPress
• eAAM_OnRelease
• eAAM_OnHold
• eAAM_Always
使用できる修飾子:
• retriggerable • holdTriggerDelay • holdRepeatDelay • noModifiers – Ctrl、Shift、Alt、または Win キーが押されない場合のみアクションが実行されます
• consoleCmd – アクションはコンソールコマンドに対応します
• pressDelayPriority • pressTriggerDelay • pressTriggerDelayRepeatOverride • inputsToBlock – ここでブロックする入力アクションを指定します
• inputBlockTime – 指定された入力アクションをブロックする時間
アクションフィルタ
また、defaultProfile.xml ファイルでアクションフィルタを直接定義することもできます。以下
の属性を使用できます。
• name – フィルタを識別する方法。
• type – actionFail を指定してアクションを失敗させます。actionPass を指定するとアクション
を成功させることができます。
以下はサンプルのアクションフィルタです。
<actionfilter name="no_move" type="actionFail">
<!-- actions that should be filtered -->
<action name="crouch"/>
<action name="jump"/>
<action name="moveleft"/>
<action name="moveright"/>
<action name="moveforward"/>
<action name="moveback"/>
<action name="sprint"/>
<action name="xi_movey"/>
<action name="xi_movex"/>
<!-- actions end -->
</actionfilter>
コントローラーのレイアウト
さまざまなコントローラーのレイアウトへのリンクを、このファイルに保存することもできます。
Version 1.6
340
Lumberyard 開発者ガイド
ランタイムのアクションマップの操作
<controllerlayouts>
<layout name="Layout
<layout name="Layout
<layout name="Layout
<layout name="Layout
</controllerlayouts>
1"
2"
3"
4"
file="buttonlayout_alt.xml"/>
file="buttonlayout_alt2.xml"/>
file="buttonlayout_lefty.xml"/>
file="buttonlayout_lefty2.xml"/>
Note
"file" 属性はデフォルトで "libs/config/controller/" に保存されたファイルにリンクされます。
ランタイムのアクションマップの操作
Lumberyard では、コンソールコマンド i_reloadActionMaps を使用して、定義された値を再初
期化できます。ActionMapManager が、すべてのリスナーにイベントを送信し、エンジン全体の値
を同期します。GameSDK など別の GameActions ファイルを使用している場合は、このクラスが更
新を受け取り、アクション/フィルタを再初期化するようにします。複数の場所で同じ名前を使って
アクションマップ、フィルタ、またはコントローラーのレイアウトを定義することはできません (た
とえば、defaultProfile.xml および GameActions ファイルに定義されたアクションフィルタ
no_move)。
ランタイムにアクションを処理するには、フローグラフまたは Lua スクリプトを使用できます。
• フローグラフ – 入力ノードを使用してアクションを処理できます。フローグラフからデジタル入力
のみを処理できます。詳細については、『Amazon Lumberyard User Guide』の「フローグラフシス
テム」を参照してください。
• Lua スクリプト – 通常、アクションは直接スクリプトによって受け取られるように意図されていま
せんが、Lua から Action Map Manager を操作することは可能です。
デフォルトのコントローラーマッピング
次の表は、PCでの入力に対するデフォルトのマッピングを示しています。独自のゲーム用にコント
ロールを再設定するには、「コントロールおよびアクションマップの設定 (p. 338)」と「アクション
マップ (p. 335)」を参照してください。
プレーヤーのアクショ
ン
PC
プレーヤーの移動
W、A、S、D
プレーヤーの照準設定
マウス XY
ジャンプ
スペースバー
全力疾走
Shift
かがむ
C
スライド (全力疾走中)
C
Fire
マウス 1
ズーム
マウス 2
近接攻撃
V
Version 1.6
341
Lumberyard 開発者ガイド
デフォルトのコントローラーマッピング
プレーヤーのアクショ
ン
PC
射撃モード
2
再ロード
R
使用アイテム
F
武器の切り替え
1
爆薬の切り替え
3
双眼鏡の切り替え
B
ライトの切り替え (ア
タッチメント)
L
三人称視点カメラ
F1
車両のアクション
PC
加速
W
Boost
Shift
ブレーキ/バック
S
ハンドブレーキ
スペースバー
ステアリング
A/D
注視
マウス XY
クラクション
H
Fire
マウス 1
シートの変更
C
ヘッドライト
L
ヘリコプターのアクション
PC
上昇
W
降下
S
左旋回
A
右旋回
D
左転向
マウス X (左)
右転向
マウス X (右)
ピッチアップ
マウス Y (上)
ピッチダウン
マウス Y (下)
Version 1.6
342
Lumberyard 開発者ガイド
キー命名規則
マルチプレーヤーのアクション
PC
スコアボードの表示
Tab
キー命名規則
このページでは、アクションマップに使用される命名規則の一部を紹介します。
キージェスチャ
文字
"a" ～ "z"
数字
"1" ～ "0"
矢印
"up"、"down"、"left"、"right"
ファンクションキー
"f1" ～ "f15"
テンキー
"np_1" ～
"np_0"、"numlock"、"np_divide"、"np_multiply"、"np_subtract"、"np_add"、"np_enter"、"np_p
Esc
"escape"
~
"tilde"
タブ
"tab"
CapsLock
"capslock"
Shift
"lshift"、"rshift"
Ctrl
"lctrl"、"rctrl"
Alt
"lalt"、"ralt"
スペースバー
"スペース"
-
"minus"
=
"equals"
Backspace
"backspace"
[]
"lbracket"、"rbracket"
"\"
"backslash"
;
"semicolon"
'
"apostrophe"
Enter
"enter"
,
"comma"
.
"period"
/
"slash"
Home
"home"
Version 1.6
343
Lumberyard 開発者ガイド
キー命名規則
End
"end"
Delete
"delete"
PageUp
"pgup"
PageDown
"pgdn"
Insert
"insert"
ScrollLock
"scrolllock"
PrintScreen
"print"
Pause/Break
"pause"
マウスジェスチャ
左/マウスの主ボタン
"mouse1"
右/マウスの副ボタン
"mouse2"
マウスホイールアップ
"mwheel_up"
マウスホイールダウン
"mwheel_down"
x 軸方向の新しい位置
"maxis_x"
y 軸方向の新しい位置
"maxis_y"
Version 1.6
344
Lumberyard 開発者ガイド
CryExtension
CryCommon
Code\CryCommon ディレクトリは、すべてのエンジンインターフェイス (および、再利用を促進する
ためにここに保存された、よく使われるコード) 用の中央ディレクトリです。
このセクションでは、次のトピックについて説明します。
• CryExtension (p. 345)
• クライストリング (p. 370)
• ICrySizer (p. 371)
• シリアル化ライブラリ (p. 371)
CryExtension
Lumberyard の複雑さは、それを理解し、設定し、実行し、拡張しようとするユーザーにとって、初
めて使用する場合でも経験があっても負担となることがあります。そこで、Lumberyard を拡張機能
にリファクタリングすると管理が容易になります。既存の機能は削除 (少なくともある程度まで)、置
き換え、またはカスタマイズすることができ、新しい機能の追加も可能です。拡張機能を使用すれ
ば、1 つの機能のコードを 1 か所にまとめることができます。これにより、多数のエンジンのベース
モジュールにわたって機能を断片的に実装する必要がなくなります。拡張機能へのリファクタリング
は、システムを高レベルで理解しやすくするためにも役立ちます。
Lumberyard の拡張機能フレームワークは、Microsoft のコンポーネントオブジェクトモデル (COM)
に使われている基本概念の一部を大まかなベースとしています。フレームワークでは、各拡張機能に
実装する必要のある 2 つの基本インターフェイス、ICryUnknown と ICryFactory が定義されてい
ます。これらは、COM の IUnknown と IClassFactory に似ています。これらのインターフェイス
は、拡張機能をインスタンス化し、インターフェイス型のキャストを実現し、機能の照会と公開を可
能にするための基盤として動作します。
フレームワークでは、共有ポインタの概念を採用し、一貫性のある使用法が強制されるように実装す
ることで、リソースリークの可能性を低減しています。エンジンの拡張機能へのリファクタリング
を支援するために、いくつかのマクロにラップされた一連の C++ テンプレートがグルーコードマク
ロ (p. 352)として用意されています。グルーコードは、すべての基本サービスを効率的に実装し、エ
ンジンに拡張機能を登録します。さらに、インターフェイスポインタのタイプセーフなキャスト、拡
Version 1.6
345
Lumberyard 開発者ガイド
コンポジット
張機能インターフェイスの ID の照会、拡張機能クラスの簡単なインスタンス化を実装するヘルパー関
数も用意されています。このため、冗長な共通コードを何度も記述する必要はなく、バグが埋め込ま
れる可能性も抑えられます。例は「グルーコードを使用する場合 (p. 360)」セクションにあります。
用意されているグルーコードを利用できない場合は、「グルーコードを使用しない場合 (p. 362)」で
説明されているように、インターフェイスと基本サービスを手動で実装する必要があります。
クライアントは、システムレベルのファクトリレジストリを通じて拡張機能にアクセスします。レジ
ストリでは、特定の拡張機能クラスを名前または ID で検索したり、インターフェイス ID を使用して
拡張機能を反復処理したりできます。
コンポジット
フレームワークでは、拡張機能に集約されている内部オブジェクト、または拡張機能を構成している
内部オブジェクトを公開できるようになっています。これらはコンポジットと呼ばれ、それ自身も
ICryUnknown を継承する拡張機能です。コンポジットでは、安全なキャストや疎結合のために、型
情報などの必要なプロパティを実行時に再利用することができます。
共有インターフェイスポインタと raw インターフェ
イスポインタ
フレームワークの設計と実装では、リソースリークの可能性を減らすために、共有ポインタを利用
し、その使用法を強制するようになっていますが、raw インターフェイスポインタを取得することも
できます。このような raw インターフェイスポインタは、共有ポインタオブジェクトで再ラップしな
いように注意する必要があります。構築時に元の共有ポインタオブジェクトを渡し、その内部参照カ
ウンタが参照されるようにしないと、参照カウントの整合性が失われ、クラッシュが発生する可能性
があります。ベストプラクティスとして、raw インターフェイスポインタは一時的にインターフェイ
スを操作する場合にのみ使い、後で使用するように保存することは避けてください。
GUID
拡張機能とそのインターフェイスを一意に識別するには、グローバル一意識別子 (GUID) を使用する
必要があります。GUID は、基本的に 128 ビットの数値で、Lumberyard などのシステム内で 1 つし
か存在しないことを保証するアルゴリズムによって生成されます。拡張機能インターフェイスのタイ
プセーフなキャストを実装するためには、GUID の使用がキーとなります。これは、大規模な開発プ
ロジェクトで特に重要です。GUID を作成するには、Visual Studio の [GUID の作成] 機能や以下に示
すマクロのような、既に用意されているツールを使用できます。
GUID は次のように定義されます。
struct CryGUID
{
uint64 hipart;
uint64 lopart;
...
};
typedef CryGUID CryInterfaceID;
typedef CryGUID CryClassID;
宣言は、フレームワークの次のヘッダーファイルに含まれています。
• CryCommon/CryExtension/CryGUID.h
• CryCommon/CryExtension/CryTypeID.h
Version 1.6
346
Lumberyard 開発者ガイド
ICryUnknown
次の Visual Studio マクロを使用すると、IDE 内で簡単に GUID を生成できます。このマクロは、
ソースコードエディタウィンドウの現在のカーソル位置に GUID を出力します。マクロエクスプロー
ラーに追加すると、マクロをキーボードショートカットや (カスタムの) ツールバーにバインドできま
す。
Public Module CryGUIDGenModule
Sub GenerateCryGUID()
Dim newGuid As System.Guid
newGuid = System.Guid.NewGuid()
Dim guidStr As String
guidStr = newGuid.ToString("N")
guidStr = guidStr.Insert(16, ", 0x")
guidStr = guidStr.Insert(0, "0x")
REM guidStr = guidStr + vbNewLine
REM guidStr = guidStr + newGuid.ToString("D")
DTE.ActiveDocument.Selection.Text = guidStr
End Sub
End Module
ICryUnknown
ICryUnknown は、すべての拡張機能の基本インターフェイスを提供します。これをクラス階層の最
上位にすることができない場合または望ましくない場合は (サードパーティコードなど)、追加のレベ
ルを適用し、拡張機能フレームワークを使用して間接的にコードを公開できます。例については、
「ICryUnknown を拡張クラスのベースにできない場合 (p. 368)」を参照してください。
ICryUnknown は次のように宣言されています。
struct ICryUnknown
{
CRYINTERFACE_DECLARE(ICryUnknown, 0x1000000010001000, 0x1000100000000000)
virtual ICryFactory* GetFactory() const = 0;
protected:
virtual void* QueryInterface(const CryInterfaceID& iid) const = 0;
virtual void* QueryComposite(const char* name) const = 0;
};
typedef boost::shared_ptr<ICryUnknown> ICryUnknownPtr;
• GetFactory() は、指定された拡張機能オブジェクトをインスタンス化したファクトリを返しま
す。用意されているグルーコードを使用すると、この関数の実行時間は一定になります。
• QueryInterface() は、要求されたインターフェイスを拡張機能が実装していればその void ポ
インタを返し、それ以外の場合は NULL を返します。この関数は、タイプセーフなインターフェ
イスキャストのセマンティクスの使用を強制するために、意図的に protected として宣言されてい
ます。キャストのセマンティクスの詳細については、「インターフェスのキャストのセマンティク
ス (p. 350)」を参照してください。用意されているグルーコードを使用すると、この関数の実行
Version 1.6
347
Lumberyard 開発者ガイド
ICryFactory
時間は、(最悪の場合) サポートされているインターフェイスの数に対して線形になります。詳細は
グルーコードによって実装されるため、追加で内部関数を呼び出す必要はありません。汎用コード
ジェネレーターにより、インターフェイス ID を比較して正しくキャストされたポインタを返す一連
の命令が生成されます。
• QueryComposite() は、照会されたコンポジットを拡張機能が公開していればその void ポインタ
を返し、それ以外の場合は NULL を返します。QueryInterface() と同様に、この関数は、タイ
プクエリを強制するために意図的に protected として宣言されています。タイプクエリの詳細につ
いては、「コンポジットの照会 (p. 351)」を参照してください。この関数の実行時間は、(最悪の
場合) 公開されているコンポジットの数に対して線形になります。
• COM とは異なり、ICryUnknown には AddRef() と Release() はありません。参照カウントは、
拡張機能クラスがインスタンス化されるときにフレームワークから返される共有ポインタによって
背後で実装されます。
宣言は、フレームワークの次のヘッダーファイルに含まれています。
• CryCommon/CryExtension/ICryUnknown.h
ICryFactory
ICryFactory は、拡張機能をインスタンス化する基本インターフェイスを提供します。これは次の
ように宣言されています。
struct ICryFactory
{
virtual const char* GetClassName() const = 0;
virtual const CryClassID& GetClassID() const = 0;
virtual bool ClassSupports(const CryInterfaceID& iid) const = 0;
virtual void ClassSupports(const CryInterfaceID*& pIIDs, size_t& numIIDs)
const = 0;
virtual ICryUnknownPtr CreateClassInstance() const = 0;
protected:
virtual ~ICryFactory() {}
};
• GetClassName() は、拡張機能クラスの名前を返します。用意されているグルーコードを使用する
と、この関数の実行時間は一定になります。
• GetClassID() は、拡張機能クラスの ID を返します。用意されているグルーコードを使用する
と、この関数の実行時間は一定になります。
• ClassSupports(iid) は、指定された ID のインターフェイスが拡張機能クラスでサポートされて
いれば true を返し、それ以外の場合は false を返します。用意されているグルーコードを使用する
と、この関数の実行時間は、(最悪の場合) サポートされているインターフェイスの数に対して線形
になります。
• ClassSupports(pIIDs, numIIDs) は、この拡張機能クラスでサポートされているインターフェ
イスをすべて列挙する内部 ID 配列へのポインタと、その配列の長さを返します。用意されているグ
ルーコードを使用すると、この関数の実行時間は一定になります。
Version 1.6
348
Lumberyard 開発者ガイド
ICryFactoryRegistry
• CreateClassInstance() は、拡張機能クラスのインスタンスを動的に作成し、その共有ポインタ
を返します。拡張機能クラスがシングルトンとして実装されている場合は、その拡張機能クラスの
単一のインスタンスをラップする (静的な) 共有ポインタが返されます。用意されているグルーコー
ドを使用すると、この関数の実行時間は、非シングルトンの拡張機能のコンストラクタ呼び出しの
コストを除いて一定になります。
• deleteや boost::shared_ptr<T> などを使用してクライアント側で明示的に破棄されること
がないように、デストラクタは protected として宣言されています。ICryFactory インスタンス
は、Lumberyard プロセスの有効期間を通じて (シングルトンとして) 存在している必要があり、破
棄してはいけません。
宣言は、フレームワークの次のヘッダーファイルに含まれています。
• CryCommon/CryExtension/ICryFactory.h
ICryFactoryRegistry
ICryFactoryRegistry はシステムによって実装されるインターフェイスで、クライアントからの拡張機
能の照会を可能にします。これは次のように宣言されています。
struct ICryFactoryRegistry
{
virtual ICryFactory* GetFactory(const char* cname) const = 0;
virtual ICryFactory* GetFactory(const CryClassID& cid) const = 0;
virtual void IterateFactories(const CryInterfaceID& iid, ICryFactory**
pFactories, size_t& numFactories) const = 0;
protected:
virtual ~ICryFactoryRegistry() {}
};
• GetFactory(cname) は、指定された名前を持つ拡張機能クラスのファクトリを返します。見つか
らない場合は NULL を返します。
• GetFactory(cid) は、指定された ID を持つ拡張機能クラスのファクトリを返します。見つからな
い場合は NULL を返します。
• IterateFactory() pFactories が NULL でない場合、IterateFactory は、iid をサポー
トする拡張機能ファクトリへのポインタのエントリを最大 numFactories 個までコピーしま
す。numFactories には、コピーされたポインタの数が返されます。pFactories が NULL の場
合、numFactories は、iid をサポートする拡張機能ファクトリの合計数を返します。
• deleteや boost::shared_ptr<T> などを使用してクライアント側で明示的に破棄されること
がないように、デストラクタは protected として宣言されています。ICryFactoryRegistry
は、CryEngine プロセスの有効期間を通じて存在するシステムインターフェイスであり、破棄して
はいけません。
宣言は、フレームワークの次のヘッダーファイルに含まれています。
• CryCommon/CryExtension/ICryFactoryRegistry.h
Version 1.6
349
Lumberyard 開発者ガイド
その他の拡張機能
その他の拡張機能
その他の機能については、ICryUnknown に定義されているメソッドを使用します。
インターフェスのキャストのセマンティクス
インターフェイスのキャストのセマンティクスは、使いやすい構文でタイプセーフなインターフェイ
スのキャストを提供するように実装されています。構文は、従来の C++ 型キャストに準拠するように
設計され、const のルールも適用されます。
ICryFactory* pFactory = ...;
assert(pFactory);
ICryUnknownPtr pUnk = pFactory->CreateClassInstance();
IMyExtensionPtr pMyExtension = cryinterface_cast<IMyExtension>(pUnk);
if (pMyExtension)
{
// it's safe to work with pMyExtension
}
インターフェイスのキャストは、raw インターフェイスポインタに対しても機能します。ただし、
「共有インターフェイスポインタと raw インターフェイスポインタ (p. 346)」セクションに記載さ
れているガイドラインを考慮してください。
宣言は、フレームワークの次のヘッダーファイルに含まれています。
• CryCommon/CryExtension/ICryUnknown.h
インターフェイス識別子の照会
場合によっては、インターフェイスの ID を取得する必要が生じることがあります。たとえ
ば、ICryFactoryRegistry::IterateFactories() に ID を渡す場合が当てはまります。これは
次のように実行できます。
CryInterfaceID iid = cryiidof<IMyExtension>();
宣言は、フレームワークの次のヘッダーファイルに含まれています。
• CryCommon/CryExtension/ICryUnknown.h
ポインタのチェック
別々のインターフェイスへのポインタが同じクラスインスタンスに属するかどうかを確認するには、
次の拡張機能を使用します。
IMyExtensionAPtr pA = ...;
IMyExtensionBPtr pB = ...;
if (CryIsSameClassInstance(pA, pB))
{
Version 1.6
350
Lumberyard 開発者ガイド
その他の拡張機能
...
}
これは、共有インターフェイスポインタでも raw インターフェイスポインタでも動作します。
宣言は、フレームワークの次のヘッダーファイルに含まれています。
• CryCommon/CryExtension/ICryUnknown.h
コンポジットの照会
拡張機能からコンポジットを照会するには、次のような方法を使用します。
IMyExtensionPtr pMyExtension = ...;
ICryUnknownPtr pCompUnk = crycomposite_query(pMyExtension, "foo");
IFooPtr pComposite = cryinterface_cast<IFoo>(pCompUnk);
if (pComposite)
{
// it's safe to work with pComposite, a composite of pMyExtention exposed as
"foo" implementing IFoo
}
指定したコンポジットがまだ作成されていない場合は、crycomposite_query() の呼び出しから
NULL が返されます。詳しい情報を収集するには、照会の処理を次のように書き直すことができま
す。
IMyExtensionPtr pMyExtension = ...;
bool exposed = false;
ICryUnknownPtr pCompUnk = crycomposite_query(pMyExtension, "foo", &exposed);
if (exposed)
{
if (pCompUnk)
{
// "foo" exposed and created
IFooPtr pComposite = cryinterface_cast<IFoo>(pCompUnk);
if (pComposite)
{
// it's safe to work with pComposite, a composite of pMyExtention exposed
as "foo" implementing IFoo
}
}
else
{
// "foo" exposed but not yet created
}
}
else
{
// "foo" not exposed by pMyExtension
}
Version 1.6
351
Lumberyard 開発者ガイド
グルーコードマクロ
インターフェイスのキャストと同様に、コンポジットの照会も raw インターフェイスポインタ
に対して機能します。ただし、「共有インターフェイスポインタと raw インターフェイスポイン
タ (p. 346)」セクションに記載されているガイドラインを考慮してください。
宣言は、フレームワークの次のヘッダーファイルに含まれています。
• CryCommon/CryExtension/ICryUnknown.h
グルーコードマクロ
以下のマクロは、基本インターフェイスと基本サービスを実装し、スレッドセーフな方法でフレーム
ワークをサポートするためのグルーコードを提供するものです。拡張機能の実装時には、これらを使
用することを強く推奨します。
これらのマクロを組み合わせて使用する例については、「グルーコードを使用する場合 (p. 360)」を
参照してください。
宣言は、フレームワークの次のヘッダーファイルに含まれています。
• CryCommon/CryExtension/Impl/ClassWeaver.h
• CryCommon/CryExtension/CryGUID.h
CRYINTERFACE_DECLARE(iname, iidHigh, iidLow)
インターフェイスおよび関連付けられる ID を宣言します。インターフェイスがクライアント側で誤っ
て削除されないように保護します。つまり、boost::shared_ptr<T> を使用した破棄だけが許可さ
れます。このマクロは、インターフェイスの宣言ごとに 1 回記述する必要があります。
パラメーター
iname
宣言されるインターフェイスの C++ 名。
iidHigh
インターフェイス ID (GUID) の上位 64 ビット部分。
iidLow
インターフェイス ID (GUID) の下位 64 ビット部分。
CRYINTERFACE_BEGIN()
拡張機能クラスの実装内で、インターフェイスリストの始まりを示す開始マーカー。拡張機能クラス
の宣言ごとに 1 回記述する必要があります。
CRYINTERFACE_ADD(iname)
拡張機能クラスの宣言内で、インターフェイスリストを追加することを示すマー
カー。CRYINTERFACE_BEGIN() マーカーと、いずれかの CRYINTERFACE_END*() マーカーとの間
で宣言する必要があります。クラスで直接継承するインターフェイスだけを宣言してください。既
存の拡張機能クラスから継承する場合、継承されたインターフェイスは自動的に追加されます。イン
ターフェイスが複数回宣言された場合、重複は削除されます。ICryUnknown を追加する必要はあり
ません。
Caution
宣言されていない他のインターフェイスには、cryinterface_cast<T>() を使用してキャ
ストすることはできません。
Version 1.6
352
Lumberyard 開発者ガイド
グルーコードマクロ
パラメーター
iname
追加するインターフェイスの C++ 名。
CRYINTERFACE_END()
拡張機能クラスの宣言内で、インターフェイスリストの終わりを示す終了マーカー。既存のどの拡張
機能クラスからも継承しない場合に使用します。拡張機能クラスの宣言ごとに 1 回記述する必要があ
ります。他の CRYINTERFACE_END*() マーカーと同時に使用することはできません。
CRYINTERFACE_ENDWITHBASE(base)
拡張機能クラスの宣言内で、インターフェイスリストの終わりを示す終了マーカー。既存の 1 つの拡
張機能クラスから継承する場合に使用します。拡張機能クラスの宣言ごとに 1 回記述する必要があり
ます。他の CRYINTERFACE_END*() マーカーと同時に使用することはできません。
パラメーター
base
派生元となる拡張機能クラスの C++ 名。
CRYINTERFACE_ENDWITHBASE2(base0, base1)
拡張機能クラスの宣言内で、インターフェイスリストの終わりを示す終了マーカー。既存の 2 つの拡
張機能クラスから継承する場合に使用します。拡張機能クラスの宣言ごとに 1 回記述する必要があり
ます。他の CRYINTERFACE_END*() マーカーと同時に使用することはできません。
パラメーター
base0
派生元となる 1 つ目の拡張機能クラスの C++ 名。
base1
派生元となる 2 つ目の拡張機能クラスの C++ 名。
CRYINTERFACE_ENDWITHBASE3(base0, base1, base2)
拡張機能クラスの宣言内で、インターフェイスリストの終わりを示す終了マーカー。既存の 3 つの拡
張機能クラスから継承する場合に使用します。拡張機能クラスの宣言ごとに 1 回記述する必要があり
ます。他の CRYINTERFACE_END*() マーカーと同時に使用することはできません。
パラメーター
base0
派生元となる 1 つ目の拡張機能クラスの C++ 名。
base1
派生元となる 2 つ目の拡張機能クラスの C++ 名。
base2
派生元となる 3 つ目の拡張機能クラスの C++ 名。
CRYINTERFACE_SIMPLE(iname)
次の一連のコードをまとめた便利なマクロ (おそらく最も一般的な拡張機能の用法です)。
Version 1.6
353
Lumberyard 開発者ガイド
グルーコードマクロ
CRYINTERFACE_BEGIN()
CRYINTERFACE_ADD(iname)
CRYINTERFACE_END()
パラメーター
iname
追加するインターフェイスの C++ 名。
CRYCOMPOSITE_BEGIN()
公開するコンポジットのリストの始まりを示す開始マーカー。
CRYCOMPOSITE_ADD(member, membername)
公開するコンポジットのリストに拡張機能クラスのメンバーを追加するマーカー。
パラメーター
member
公開する拡張機能クラスのメンバー変数の C++ 名。boost::shared_ptr<T> 型 (T は
ICryUnknown から継承) である必要があります。この条件はコンパイル時に適用されます。
membername
コンポジットの名前 (C スタイルの文字列)。後で実行時にこの名前を使用してコンポジットを照
会できます。
CRYCOMPOSITE_END(implclassname)
公開するコンポジットのリストの終わりを示す終了マーカー。コンポジットを公開する既存のどの拡
張クラスからも継承しない場合に使用します。他の CRYCOMPOSITE_END*() マーカーと同時に使用
することはできません。
パラメーター
implclassname
実装する拡張機能クラスの C++ 名。
CRYCOMPOSITE_ENDWITHBASE(implclassname, base)
公開するコンポジットのリストの終わりを示す終了マーカー。コンポジットを公開する既存の 1 つの
拡張機能クラスから継承する場合に使用します。照会時には、crycomposite_query() に指定され
た名前に一致するコンポジットを見つけるために、まず現在のクラスが検索され、次に基本クラスが
検索されます。他の CRYCOMPOSITE_END*() マーカーと同時に使用することはできません。
パラメーター
implclassname
実装する拡張機能クラスの C++ 名。
base
派生元となる拡張機能クラスの C++ 名。
Version 1.6
354
Lumberyard 開発者ガイド
グルーコードマクロ
CRYCOMPOSITE_ENDWITHBASE2(implclassname, base0,
base1)
公開するコンポジットのリストの終わりを示す終了マーカー。コンポジットを公開する既存の 2 つの
拡張機能クラスから継承する場合に使用します。照会時には、crycomposite_query() に指定され
た名前に一致するコンポジットを見つけるために、まず現在のクラスが検索され、次に基本クラスが
検索されます。他の CRYCOMPOSITE_END*() マーカーと同時に使用することはできません。
パラメーター
implclassname
実装する拡張機能クラスの C++ 名。
base0
派生元となる 1 つ目の拡張機能クラスの C++ 名。
base1
派生元となる 2 つ目の拡張機能クラスの C++ 名。
CRYCOMPOSITE_ENDWITHBASE3(implclassname, base0,
base1, base2)
公開するコンポジットのリストの終わりを示す終了マーカー。コンポジットを公開する 3 つの拡張機
能クラスから継承する場合に使用します。照会時には、crycomposite_query() に指定された名前
に一致するコンポジットを見つけるために、まず現在のクラスが検索され、次に基本クラスが検索さ
れます。他の CRYCOMPOSITE_END*() マーカーと同時に使用することはできません。
パラメーター
implclassname
実装する拡張機能クラスの C++ 名。
base0
派生元となる 1 つ目の拡張機能クラスの C++ 名。
base1
派生元となる 2 つ目の拡張機能クラスの C++ 名。
base2
派生元となる 3 つ目の拡張機能クラスの C++ 名。
CRYGENERATE_CLASS(implclassname, cname, cidHigh,
cidLow)
何度でもインスタンス化できる拡張機能クラスの基本インターフェイスと基本サービスをサ
ポートするコードを生成します。拡張機能クラスの宣言ごとに 1 回記述する必要がありま
す。CRYGENERATE_SINGLETONCLASS() と同時に使用することはできません。
パラメーター
implclassname
拡張機能の C++ クラス名。
cname
拡張機能クラス名。この名前でレジストリに登録されます。
cidHigh
拡張機能のクラス ID (GUID) の上位 64 ビット部分。この ID でレジストリに登録されます。
Version 1.6
355
Lumberyard 開発者ガイド
CryExtension のサンプル
cidLow
拡張機能のクラス ID (GUID) の下位 64 ビット部分。この ID でレジストリに登録されます。
CRYGENERATE_SINGLETONCLASS(implclassname, cname,
cidHigh, cidLow)
1 回だけインスタンス化できる (シングルトンの) 拡張機能クラスの基本インターフェイスと基本サー
ビスをサポートするコードを生成します。拡張機能クラスの宣言ごとに 1 回記述する必要がありま
す。CRYGENERATE_CLASS() と同時に使用することはできません。
パラメーター
implclassname
拡張機能の C++ クラス名。
cname
拡張機能クラス名。この名前でレジストリに登録されます。
cidHigh
拡張機能のクラス ID (GUID) の上位 64 ビット部分。この ID でレジストリに登録されます。
cidLow
拡張機能のクラス ID (GUID) の下位 64 ビット部分。この ID でレジストリに登録されます。
CRYREGISTER_CLASS(implclassname)
拡張機能クラスをシステムに登録します。拡張機能クラスごとに 1 回、ファイルスコープで記述する
必要があります。
パラメーター
implclassname
拡張機能の C++ クラス名。
MAKE_CRYGUID(high, low)
パラメーター
CryGUID を構築します。拡張機能のレジストリをクラス ID で検索する場合に役立ちます。
high
low
GUID の上位 64 ビット部分。
GUID の下位 64 ビット部分。
CryExtension のサンプル
サンプル 1 - 拡張機能を使用したソース管理プラグインの実装
//////////////////////////////////////////////////////////////////////////
// source control interface
struct ISourceControl : public ICryUnknown
{
CRYINTERFACE_DECLARE(ISourceControl, 0x399d8fc1d94044cc, 0xa70d2b4e58921453)
Version 1.6
356
Lumberyard 開発者ガイド
CryExtension のサンプル
virtual void GetLatest(const char* filename) = 0;
virtual void Submit() = 0;
};
typedef cryshared_ptr<ISourceControl> ISourceControlPtr;
//////////////////////////////////////////////////////////////////////////
// concrete implementations of source control interface
class CSourceControl_Perforce : public ISourceControl
{
CRYINTERFACE_BEGIN()
CRYINTERFACE_ADD(ISourceControl)
CRYINTERFACE_END()
CRYGENERATE_SINGLETONCLASS(CSourceControl_Perforce,
"CSourceControl_Perforce", 0x7305bff20ee543e3, 0x820792c56e74ecda)
virtual void GetLatest(const char* filename) { ... };
virtual void Submit() { ... };
};
CRYREGISTER_CLASS(CSourceControl_Perforce)
class CSourceControl_SourceSafe : public ISourceControl
{
CRYINTERFACE_BEGIN()
CRYINTERFACE_ADD(ISourceControl)
CRYINTERFACE_END()
CRYGENERATE_SINGLETONCLASS(CSourceControl_SourceSafe,
"CSourceControl_SourceSafe", 0x1df62628db9d4bb2, 0x8164e418dd5b6691)
virtual void GetLatest(const char* filename) { ... };
virtual void Submit() { ... };
};
CRYREGISTER_CLASS(CSourceControl_SourceSafe)
//////////////////////////////////////////////////////////////////////////
// using the interface (submitting changes)
void Submit()
{
ICryFactoryRegistry* pReg = gEnv->pSystem->GetFactoryRegistry();
ICryFactory* pFactory = 0;
size_t numFactories = 1;
pReg->IterateFactories(cryiidof<ISourceControl>(), &pFactory, numFactories);
if (pFactory)
{
ISourceControlPtr pSrcCtrl = cryinterface_cast<ISourceControl>(pFactory>CreateClassInstance());
if (pSrcCtrl)
{
pSrcCtrl->Submit();
Version 1.6
357
Lumberyard 開発者ガイド
拡張機能の使用
}
}
}
拡張機能の使用
特定の拡張クラスの使用
特定の拡張クラスを使用するには、拡張クラスのクラス名またはクラス ID とそのクラスでサポートさ
れているインターフェイスをクライアントが知っている必要があります。その情報を使用して、次の
例のように、作成され使用しているインスタンスであるクラスファクトリをレジストリに照会できま
す。
// IMyExtension.h
#include <CryExtension/ICryUnknown.h>
struct IMyExtension : public ICryUnknown
{
...
};
typedef boost::shared_ptr<IMyExtension> IMyExtensionPtr;
// in client code
#include <IMyExtension.h>
#include <CryExtension/CryCreateClassInstance.h>
IMyExtensionPtr pMyExtension;
#if 0
// create extension by class name
if (CryCreateClassInstance("MyExtension", pMyExtension))
#else
// create extension by class id, guaranteed to create instance of same kind
if (CryCreateClassInstance(MAKE_CRYGUID(0x68c7f0e0c36446fe,
0x82a3bc01b54dc7bf), pMyExtension))
#endif
{
// it's safe to work with pMyExtension
}
// verbose version of client code above
#include <IMyExtension.h>
#include <CryExtension/ICryFactory.h>
#include <CryExtension/ICryFactoryRegistry.h>
ICryFactoryRegistry* pReg = ...;
#if 0
// search extension by class name
ICryFactory* pFactory = pReg->GetFactory("MyExtension");
#else
// search extension by class id, guaranteed to yield same factory as in
search by class name
Version 1.6
358
Lumberyard 開発者ガイド
拡張機能の使用
ICryFactory* pFactory = pReg->GetFactory(MAKE_CRYGUID(0x68c7f0e0c36446fe,
0x82a3bc01b54dc7bf));
#endif
if (pFactory) // see comment below
{
ICryUnknownPtr pUnk = pFactory->CreateClassInstance();
IMyExtensionPtr pMyExtension = cryinterface_cast<IMyExtension>(pUnk);
if (pMyExtension)
{
// it's safe to work with pMyExtension
}
}
最適化のために、次のように if のチェックを強化することができます。
if (pFactory && pFactory->ClassSupports(cryiidof<IMyExtension>()))
{
...
このバージョンの if ステートメントでは、拡張クラスをインスタンス化する前にインターフェイス
のサポートが確認されています。このチェックによって、指定したインターフェイスに対応していな
い拡張の、不要な (高コストの可能性がある) コンストラクションとデストラクションが抑止されま
す。
特定のインターフェイスをサポートしている拡張クラスの検索
レジストリ内で特定のインターフェイスをサポートしている拡張クラスの数を決定してそれらをリス
トするために、クライアントは次のようなクエリを送信できます。
// IMyExtension.h
#include <CryExtension/ICryUnknown.h>
struct IMyExtension : public ICryUnknown
{
...
};
// in client code
#include <IMyExtension.h>
#include <CryExtension/ICryFactory.h>
#include <CryExtension/ICryFactoryRegistry.h>
ICryFactoryRegistry* pReg = ...;
size_t numFactories = 0;
pReg->IterateFactories(cryiidof<IMyExtension>(), 0, numFactories);
ICryFactory** pFactories = new ICryFactory*[numFactories];
pReg->IterateFactories(cryiidof<IMyExtension>(), pFactories, numFactories);
...
delete [] pFactories;
Version 1.6
359
Lumberyard 開発者ガイド
フレームワークの使用による拡張機能の実装
フレームワークの使用による拡張機能の実装
以下のセクションでは、Lumberyard で拡張機能を実装する方法を詳しく説明します。グルーコードを
使用する例とグルーコードを使用しない例も示します。また、ICryUnknown を拡張インターフェイ
スのベースにできない場合に、フレームワークを利用する方法についても説明します。
フレームワークヘッダーファイルを含めるための推奨レイアウ
ト
クライアントによって含められるパブリックインターフェイスヘッダーは次のようになります。
// IMyExtension.h
#include <CryExtension/ICryUnknown.h>
struct IMyExtension : public ICryUnknown
{
...
};
グルーコードを使用している場合は、ヘッダーファイル内で拡張機能の実装クラスを次のように宣言
します。
// MyExtension.h
#include <IMyExtension.h>
#include <CryExtension/Impl/ClassWeaver.h>
class CMyExtension : public IMyExtension
{
...
};
グルーコードを使用する場合
最初の例は、前の例の IMyExtension クラスについて、考えられる実装を示しています。
///////////////////////////////////////////
// public section
// IMyExtension.h
#include <CryExtension/ICryUnknown.h>
struct IMyExtension : public ICryUnknown
{
CRYINTERFACE_DECLARE(IMyExtension, 0x4fb87a5f83f74323, 0xa7e42ca947c549d8)
virtual void CallMe() = 0;
};
typedef boost::shared_ptr<IMyExtension> IMyExtensionPtr;
///////////////////////////////////////////
// private section not visible to client
// MyExtension.h
#include <IMyExtension.h>
Version 1.6
360
Lumberyard 開発者ガイド
フレームワークの使用による拡張機能の実装
#include <CryExtension/Impl/ClassWeaver.h>
class CMyExtension : public IMyExtension
{
CRYINTERFACE_BEGIN()
CRYINTERFACE_ADD(IMyExtension)
CRYINTERFACE_END()
CRYGENERATE_CLASS(CMyExtension, "MyExtension", 0x68c7f0e0c36446fe,
0x82a3bc01b54dc7bf)
public:
virtual void CallMe();
};
// MyExtension.cpp
#include "MyExtension.h"
CRYREGISTER_CLASS(CMyExtension)
CMyExtension::CMyExtension()
{
}
CMyExtension::~CMyExtension()
{
}
void CMyExtension::CallMe()
{
printf("Inside CMyExtension::CallMe()...");
}
次の例は、拡張クラス MyExtension をカスタマイズして拡張し、あと 2 つのインターフェイス
(IFoo と IBar) を実装する方法を示しています。
///////////////////////////////////////////
// public section
// IFoo.h
#include <CryExtension/ICryUnknown.h>
struct IFoo : public ICryUnknown
{
CRYINTERFACE_DECLARE(IFoo, 0x7f073239d1e6433f, 0xb59c1b6ff5f68d79)
virtual void Foo() = 0;
};
// IBar.h
#include <CryExtension/ICryUnknown.h>
struct IBar : public ICryUnknown
{
CRYINTERFACE_DECLARE(IBar, 0xa9361937f60d4054, 0xb716cb711970b5d1)
virtual void Bar() = 0;
};
Version 1.6
361
Lumberyard 開発者ガイド
フレームワークの使用による拡張機能の実装
///////////////////////////////////////////
// private section not visible to client
// MyExtensionCustomized.h
#include "MyExtension.h"
#include <IFoo.h>
#include <IBar.h>
#include <CryExtension/Impl/ClassWeaver.h>
class CMyExtensionCustomized : public CMyExtension, public IFoo, public IBar
{
CRYINTERFACE_BEGIN()
CRYINTERFACE_ADD(IFoo)
CRYINTERFACE_ADD(IBar)
CRYINTERFACE_ENDWITHBASE(CMyExtension)
CRYGENERATE_CLASS(CMyExtensionCustomized, "MyExtensionCustomized",
0x07bfa7c543a64f0c, 0x861e9fa3f7d7d264)
public:
virtual void CallMe(); // chose to override MyExtension's impl
virtual void Foo();
virtual void Bar();
};
// MyExtensionCustomized.cpp
#include "MyExtensionCustomized.h"
CRYREGISTER_CLASS(CMyExtensionCustomized)
CMyExtensionCustomized::CMyExtensionCustomized()
{
}
CMyExtensionCustomized::~CMyExtensionCustomized()
{
}
void CMyExtensionCustomized::CallMe()
{
printf("Inside CMyExtensionCustomized::CallMe()...");
}
void CMyExtensionCustomized::Foo()
{
printf("Inside CMyExtensionCustomized::Foo()...");
}
void CMyExtensionCustomized::Bar()
{
printf("Inside CMyExtensionCustomized::Bar()...");
}
グルーコードを使用しない場合
なんらかの理由でグルーコードの使用が望ましくなく適切でもない場合は、拡張を次のように実装で
きます。ICryUnknown と ICryFactory は、グルーコードを使用した場合とランタイムコストが同
Version 1.6
362
Lumberyard 開発者ガイド
フレームワークの使用による拡張機能の実装
等になるように実装することをお勧めします。詳細については、「ICryUnknown (p. 347)」および
「ICryFactory (p. 348)」を参照してください。
///////////////////////////////////////////
// public section
// INoMacros.h
#include <CryExtension/ICryUnknown.h>
struct INoMacros : public ICryUnknown
{
// befriend cryiidof and boost::checked_delete
template <class T> friend const CryInterfaceID&
InterfaceCastSemantics::cryiidof();
template <class T> friend void boost::checked_delete(T* x);
protected:
virtual ~INoMacros() {}
private:
// It's very important that this static function is implemented for each
interface!
// Otherwise the consistency of cryinterface_cast<T>() is compromised
because
// cryiidof<T>() = cryiidof<baseof<T>>() {baseof<T> = ICryUnknown in most
cases}
static const CryInterfaceID& IID()
{
static const CryInterfaceID iid = {0xd0fda1427dee4cceull,
0x88ff91b6b7be2a1full};
return iid;
}
public:
virtual void TellMeWhyIDontLikeMacros() = 0;
};
typedef boost::shared_ptr<INoMacros> INoMacrosPtr;
///////////////////////////////////////////
// private section not visible to client
// NoMacros.cpp
//
// This is just an exemplary implementation!
// For brevity the whole implementation is packed into this cpp file.
#include <INoMacros.h>
#include <CryExtension/ICryFactory.h>
#include <CryExtension/Impl/RegFactoryNode.h>
// implement factory first
class CNoMacrosFactory : public ICryFactory
{
// ICryFactory
public:
virtual const char* GetClassName() const
{
return "NoMacros";
}
Version 1.6
363
Lumberyard 開発者ガイド
フレームワークの使用による拡張機能の実装
virtual const CryClassID& GetClassID() const
{
static const CryClassID cid = {0xa4550317690145c1ull,
0xa7eb5d85403dfad4ull};
return cid;
}
virtual bool ClassSupports(const CryInterfaceID& iid) const
{
return iid == cryiidof<ICryUnknown>() || iid == cryiidof<INoMacros>();
}
virtual void ClassSupports(const CryInterfaceID*& pIIDs, size_t& numIIDs)
const
{
static const CryInterfaceID iids[2] = {cryiidof<ICryUnknown>(),
cryiidof<INoMacros>()};
pIIDs = iids;
numIIDs = 2;
}
virtual ICryUnknownPtr CreateClassInstance() const;
public:
static CNoMacrosFactory& Access()
{
return s_factory;
}
private:
CNoMacrosFactory() {}
~CNoMacrosFactory() {}
private:
static CNoMacrosFactory s_factory;
};
CNoMacrosFactory CNoMacrosFactory::s_factory;
// implement extension class
class CNoMacros : public INoMacros
{
// ICryUnknown
public:
virtual ICryFactory* GetFactory() const
{
return &CNoMacrosFactory::Access();
};
// befriend boost::checked_delete
// only needed to be able to create initial shared_ptr<CNoMacros>
// so we don't lose type info for debugging (i.e. inspecting shared_ptr)
template <class T> friend void boost::checked_delete(T* x);
protected:
virtual void* QueryInterface(const CryInterfaceID& iid) const
{
if (iid == cryiidof<ICryUnknown>())
return (void*) (ICryUnknown*) this;
else if (iid == cryiidof<INoMacros>())
return (void*) (INoMacros*) this;
else
Version 1.6
364
Lumberyard 開発者ガイド
フレームワークの使用による拡張機能の実装
return 0;
}
virtual void* QueryComposite(const char* name) const
{
return 0;
}
// INoMacros
public:
virtual void TellMeWhyIDontLikeMacros()
{
printf("Woohoo, no macros...\n");
}
CNoMacros() {}
protected:
virtual ~CNoMacros() {}
};
// implement factory's CreateClassInstance method now that extension class is
fully visible to compiler
ICryUnknownPtr CNoMacrosFactory::CreateClassInstance() const
{
boost::shared_ptr<CNoMacros> p(new CDontLikeMacros);
return
ICryUnknownPtr(*static_cast<boost::shared_ptr<ICryUnknown>*>(static_cast<void*>(&p)));
}
// register extension
static SRegFactoryNode g_noMacrosFactory(&CNoMacrosFactory::Access());
コンポジットの公開
次の例は、(継承された) コンポジットを公開する方法を示しています。わかりやすくするために、サ
ンプルはファイルに分離されていません。
//////////////////////////////////////////////////////////////////////////
struct ITestExt1 : public ICryUnknown
{
CRYINTERFACE_DECLARE(ITestExt1, 0x9d9e0dcfa5764cb0, 0xa73701595f75bd32)
virtual void Call1() = 0;
};
typedef boost::shared_ptr<ITestExt1> ITestExt1Ptr;
class CTestExt1 : public ITestExt1
{
CRYINTERFACE_BEGIN()
CRYINTERFACE_ADD(ITestExt1)
CRYINTERFACE_END()
CRYGENERATE_CLASS(CTestExt1, "TestExt1", 0x43b04e7cc1be45ca,
0x9df6ccb1c0dc1ad8)
public:
Version 1.6
365
Lumberyard 開発者ガイド
フレームワークの使用による拡張機能の実装
virtual void Call1();
};
CRYREGISTER_CLASS(CTestExt1)
CTestExt1::CTestExt1()
{
}
CTestExt1::~CTestExt1()
{
}
void CTestExt1::Call1()
{
}
//////////////////////////////////////////////////////////////////////////
class CComposed : public ICryUnknown
{
CRYINTERFACE_BEGIN()
CRYINTERFACE_END()
CRYCOMPOSITE_BEGIN()
CRYCOMPOSITE_ADD(m_pTestExt1, "Ext1")
CRYCOMPOSITE_END(CComposed)
CRYGENERATE_CLASS(CComposed, "Composed", 0x0439d74b8dcd4b7f,
0x9287dcdf7e26a3a5)
private:
ITestExt1Ptr m_pTestExt1;
};
CRYREGISTER_CLASS(CComposed)
CComposed::CComposed()
: m_pTestExt1()
{
CryCreateClassInstance("TestExt1", m_pTestExt1);
}
CComposed::~CComposed()
{
}
//////////////////////////////////////////////////////////////////////////
struct ITestExt2 : public ICryUnknown
{
CRYINTERFACE_DECLARE(ITestExt2, 0x8eb7a4b399874b9c, 0xb96bd6da7a8c72f9)
virtual void Call2() = 0;
};
DECLARE_BOOST_POINTERS(ITestExt2);
class CTestExt2 : public ITestExt2
{
CRYINTERFACE_BEGIN()
Version 1.6
366
Lumberyard 開発者ガイド
フレームワークの使用による拡張機能の実装
CRYINTERFACE_ADD(ITestExt2)
CRYINTERFACE_END()
CRYGENERATE_CLASS(CTestExt2, "TestExt2", 0x25b3ebf8f1754b9a,
0xb5494e3da7cdd80f)
public:
virtual void Call2();
};
CRYREGISTER_CLASS(CTestExt2)
CTestExt2::CTestExt2()
{
}
CTestExt2::~CTestExt2()
{
}
void CTestExt2::Call2()
{
}
//////////////////////////////////////////////////////////////////////////
class CMultiComposed : public CComposed
{
CRYCOMPOSITE_BEGIN()
CRYCOMPOSITE_ADD(m_pTestExt2, "Ext2")
CRYCOMPOSITE_ENDWITHBASE(CMultiComposed, CComposed)
CRYGENERATE_CLASS(CMultiComposed, "MultiComposed", 0x0419d74b8dcd4b7e,
0x9287dcdf7e26a3a6)
private:
ITestExt2Ptr m_pTestExt2;
};
CRYREGISTER_CLASS(CMultiComposed)
CMultiComposed::CMultiComposed()
: m_pTestExt2()
{
CryCreateClassInstance("TestExt2", m_pTestExt2);
}
CMultiComposed::~CMultiComposed()
{
}
...
//////////////////////////////////////////////////////////////////////////
// let's use it
ICryUnknownPtr p;
if (CryCreateClassInstance("MultiComposed", p))
{
Version 1.6
367
Lumberyard 開発者ガイド
フレームワークの使用による拡張機能の実装
ITestExt1Ptr p1 = cryinterface_cast<ITestExt1>(crycomposite_query(p,
"Ext1"));
if (p1)
p1->Call1(); // calls CTestExt1::Call1()
ITestExt2Ptr p2 = cryinterface_cast<ITestExt2>(crycomposite_query(p,
"Ext2"));
if (p2)
p2->Call2(); // calls CTestExt2::Call2()
}
ICryUnknown を拡張クラスのベースにできない場合
ICryUnknown を拡張クラスのベースにすることができないケースもあります。たとえば、レガシー
コードのベースを変更できない場合や、サードパーティーのソースコードにフルアクセスできない場
合、コードの変更自体が現実的でない場合などがあります。ただし、これらのコードベースは、エン
ジンの拡張機能として公開すると、(動画の再生や Flash 再生などに役立つ) 便利な機能を提供できま
す。次のサンプルは、追加の間接レベルでサードパーティー API を公開する方法を説明しています。
///////////////////////////////////////////
// public section
// IExposeThirdPartyAPI.h
#include <CryExtension/ICryUnknown.h>
#include <IThirdPartyAPI.h>
struct IExposeThirdPartyAPI : public ICryUnknown
{
CRYINTERFACE_DECLARE(IExposeThirdPartyAPI, 0x804250bbaacf4a5f,
0x90ef0327bb7a0a7f)
virtual IThirdPartyAPI* Create() = 0;
};
typedef boost::shared_ptr<IExposeThirdPartyAPI> IExposeThirdPartyAPIPtr;
///////////////////////////////////////////
// private section not visible to client
// Expose3rdPartyAPI.h
#include <IExposeThirdPartyAPI.h>
#include <CryExtension/Impl/ClassWeaver.h>
class CExposeThirdPartyAPI : public IExposeThirdPartyAPI
{
CRYINTERFACE_BEGIN()
CRYINTERFACE_ADD(IExposeThirdPartyAPI)
CRYINTERFACE_END()
CRYGENERATE_CLASS(CExposeThirdPartyAPI, "ExposeThirdPartyAPI",
0xa93b970b2c434a21, 0x86acfe94d8dae547)
public:
virtual IThirdPartyAPI* Create();
};
// ExposeThirdPartyAPI.cpp
#include "ExposeThirdPartyAPI.h"
Version 1.6
368
Lumberyard 開発者ガイド
フレームワークの使用による拡張機能の実装
#include "ThirdPartyAPI.h"
CRYREGISTER_CLASS(CExposeThirdPartyAPI)
CExposeThirdPartyAPI::CExposeThirdPartyAPI()
{
}
CExposeThirdPartyAPI::~CExposeThirdPartyAPI()
{
}
IThirdPartyAPI* CExposeThirdPartyAPI::Create()
{
return new CThirdPartyAPI; // CThirdPartyAPI implements IThirdPartyAPI
}
拡張機能のカスタムインクルードと除外
拡張機能を簡単にインクルードまたは除外できるように、Lumberyard ではグローバルの "拡張機能
定義" ヘッダーを使用できます。これは、platform.h ファイルを使用してすべてのモジュールに自
動的にインクルードされる CryCommon/ProjectDefines.h とよく似ています。拡張機能実装コー
ドをラップするには、拡張機能定義ヘッダーに #define ステートメントを含めます。使用しない拡
張機能をコメントアウトすることで、使用しない拡張機能コードをビルドから除外することもできま
す。インターフェイスヘッダーは #if defined ステートメントの影響を受けないため、これらの有
無に関係なく、クライアントコードはそのままコンパイルされます。
///////////////////////////////////////////
// public section
// IMyExtension.h
#include <CryExtension/ICryUnknown.h>
struct IMyExtension : public ICryUnknown
{
...
};
typedef boost::shared_ptr<IMyExtension> IMyExtensionPtr;
// ExtensionDefines.h
...
#define INCLUDE_MYEXTENSION
...
///////////////////////////////////////////
// private section not visible to client
// MyExtension.h
#if defined(INCLUDE_MYEXTENSION)
#include <IMyExtension.h>
#include <CryExtension/Impl/ClassWeaver.h>
class CMyExtension : public IMyExtension
{
...
};
Version 1.6
369
Lumberyard 開発者ガイド
クライストリング
#endif // #if defined(INCLUDE_MYEXTENSION)
// MyExtension.cpp
#if defined(INCLUDE_MYEXTENSION)
#include "MyExtension.h"
CRYREGISTER_CLASS(CMyExtension)
...
#endif // #if defined(INCLUDE_MYEXTENSION)
拡張機能はビルドから除去されることがあるため、クライアントコードは拡張機能を使用できること
を前提にせずに記述する必要があります。詳細については、「拡張機能の使用 (p. 358)」を参照して
ください。
クライストリング
Lumberyardはカスタムの参照カウントの文字列クラスCryString (CryString.hに公表されていま
す) であり、STL std::stringの代わりになります。常にstd::stringではなく、CryString が優
先されるべきです。利便性を考慮して、stringはCryStringのtypedefとして使用されています。
STLコンテナの主要な値として文字列を使用する方
法
以下のコードは良い (効率的) 及び悪い使用例を示します。
const char *szKey= "Test";
map< string, int >::const_iterator iter =
m_values.find( CONST_TEMP_STRING( szKey ) );
// Good
map< string, int >::const_iterator iter = m_values.find( szKey );
// Bad
推奨される方法を使用すれば、ほとんどの文字列クラスによく発生する一時文字列オブジェクトの割
り当て、割り当て解除、およびコピーの問題を回避できます。マクロCONST_TEMP_STRINGを使用す
ると、文字列クラスは後々データを手放さずともポインタを直接使用できます。
使用詳細ヒント
• std::stringやstd::wstringを使用しないでください。そのかわりstringとwstringを使用
し、標準文字列ヘッダー<string>を絶対に含めないでください。
• c_str()方法を使用し、文字列の内容にアクセスしてください。
• 文字列は参照カウントされているため、c_str()方法で返されたメモリは絶対に変更しないでくだ
さい。変更すると間違った文字列インスタンスに影響を与えることがあります。
• 文字列を抽象的なインターフェースに通すことは絶対におやめください。すべてのインターフェー
スは const char*のインターフェース方法を使用する必要があります。
• CryString はstd::stringとMFCCStringが結合されているインターフェースがあるため、両方
のインターフェースタイプを文字列オペレーションに使用できます。
Version 1.6
370
Lumberyard 開発者ガイド
ICrySizer
• メモリに再配分が生じるため、ランタイム時に多くの文字列オペレーションを行うことは避けま
しょう。
• 固定されたサイズの文字列(例：256文字)には、静的なcharアレイではなくCryFixedStringTを優
先的に使用してください。
ICrySizer
ICrySizer インターフェイスを実装して、クラスのメモリ使用量に関する詳細を記録することができ
ます。
Note
この情報は、エディタの [エンジンのメモリ情報] でも確認できます。
ICrySizer インターフェイスの使用方法
次の例は ICrySizer インターフェイスの使用方法を示しています。
void GetMemoryUsage( ICrySizer *pSizer )
{
{
SIZER_COMPONENT_NAME( pSizer, "Renderer (Aux Geometries)" );
pSizer->Add(*this);
}
pSizer->AddObject(<element_prow>,<element_count>);
pSizer->AddObject(<container>);
m_SubObject.GetMemoryUsage(pSizer);
}
シリアル化ライブラリ
CryCommon シリアル化ライブラリには以下の機能があります。
• ユーザーシリアル化コードの、実際のストレージ形式からの分離。これにより、ユーザーコードを
変更せずに XML、JSON、バイナリの形式間で切り替えることができます。
• PropertyTree での編集で同じシリアル化コードの再利用。シリアル化コードを一度記述すれば、そ
れを使用してパラメータツリーとしてエディタでその構造を公開できます。
• シリアル化タイプを変更せずに、不侵入方法 (グローバル多重定義関数として) でシリアル化コード
を記述できるようになります。
• 形式の変更が簡単になります。たとえば、フィールドを追加、削除、または名前変更しても、既存
のデータをロードできます。
チュートリアル
この例は、標準の型、列挙、およびコンテナを使用するデータレイアウトで開始しています。この例
では、固定署名を持つ構造に Serialize メソッドを追加しています。
データの定義
#include "Serialization/IArchive.h"
Version 1.6
371
Lumberyard 開発者ガイド
チュートリアル
#include "Serialization/STL.h"
enum AttachmentType
{
ATTACHMENT_SKIN,
ATTACHMENT_BONE
};
struct Attachment
{
string name;
AttachmentType type;
string model;
void Serialize(Serialization::IArchive& ar)
{
ar(name, "name", "Name");
ar(type, "type", "Type");
ar(model, "model", "Model");
}
};
struct Actor
{
string character;
float speed;
bool alive;
std::vector<Attachment> attachments;
Actor()
: speed(1.0f)
, alive(true)
{
}
void Serialize(Serialization::IArchive& ar)
{
ar(character, "character", "Character");
ar(speed, "speed", "Speed");
ar(alive, "alive", "Alive");
ar(attachments, "attachments", "Attachment");
}
};
// Implementation file:
#include "Serialization/Enum.h"
SERIALIZATION_ENUM_BEGIN(AttachmentType, "Attachment Type")
SERIALIZATION_ENUM(ATTACHMENT_BONE, "bone", "Bone")
SERIALIZATION_ENUM(ATTACHMENT_SKIN, "skin", "Skin")
SERIALIZATION_ENUM_END()
2 つの名前が必要なのはなぜですか?
ar() 呼び出しは 2 つの文字列型の引数を取り、1 番目は name、2 番目は label です。name 引数は
パラメータを永続的に格納するために使用されます (たとえば、JSON や XML 用)。label パラメー
タは PropertyTree 用に使用されます。label パラメータは通常は長くて説明的であり、空白文字が含
まれていて、既存データとの互換性をなくさずに簡単に変更できます。これに対して、name は C ス
タイルの ID です。name を変数名と同じにしておくと、開発者はデータファイルで検索してその変数
を簡単に見つけることができるため便利です。
label パラメータを省略 (nullptr を渡すことと同じ) すると、そのパラメータは PropertyTree で
は非表示になりますが、その場合でもシリアル化され、コピーして貼り付けを使用して親とともにコ
ピーできます。
Version 1.6
372
Lumberyard 開発者ガイド
チュートリアル
Note
SERIALIZATION_ENUM マクロにはシンボル定義が含まれているため、.cpp 実装ファイルに
置く必要があります。
ファイルに対するシリアル化
データを定義したので、シリアル化の準備ができています。シリアル化を実装するには、次の例のよ
うに Serialization::SaveJsonFile を使用できます。
#include <Serialization/IArchiveHost.h>
Actor actor;
Serialization::SaveJsonFile("filename.json", actor);
これにより、次の形式のコンテンツが出力されます。
{
"character": "nanosuit.cdf",
"speed": 2.5,
"alive": true,
"attachments": [
{ "name": "attachment 1", "type": "bone", "model": "model1.cgf" },
{ "name": "attachment 2", "type": "skin", "model": "model2.cgf" }
]
}
データの読み取るコードは、Serialization::LoadJsonFile を使用すること以外はシリアル化の
コードに似ています。
#include <Serialization/IArchiveHost.h>
Actor actor;
Serialization::LoadJsonFile(actor, "filename.json");
使用される保存およびロードの関数は IArchiveHost インターフェイスのラッパーであり、そのイン
スタンスは gEnv->pSystem->GetArchiveHost() にあります。ただし、アーカイブコード (たとえ
ば、CrySystem または EditorCommon で) に直接アクセス権がある場合は、次の例に示すように、
アーカイブクラスを直接使用できます。
#include <Serialization/JSONOArchive.h>
#include <Serialization/JSONIArchive.h>
Serialization::JSONOArchive oa;
Actor actor;
oa(actor);
oa.save("filename.json");
// to get access to the data without saving:
const char* jsonString = oa.c_str();
// and to load
Serialization::JSONIArchive ia;
Version 1.6
373
Lumberyard 開発者ガイド
ユースケース
if (ia.load("filename.json"))
{
Actor loadedActor;
ia(loadedActor);
}
PropertyTree での編集
型に対する Serialize メソッドを実装している場合は、次の例に示しているように、それを簡単に
QPropertyTree に公開できます。
#include <QPropertyTree/QPropertyTree.h>
QPropertyTree* tree = new QPropertyTree(parent);
static Actor actor;
tree->attach(Serialization::SStruct(actor));
リストから列挙値を選択し、[2] ボタンまたはコンテキストメニューを使用してベクトル要素を追加ま
たは削除します。
アタッチした時点で、Serialize メソッドが呼び出され、オブジェクトからプロパティが抽出され
ます。ユーザーが UI でプロパティを変更すると、すぐに Serialize メソッドが呼び出され、プロパ
ティがオブジェクトに書き戻されます。
Note
アタッチされたオブジェクトへの参照を QPropertyTree が保持していること
を覚えておくことが重要です。オブジェクトの存続期間がツリーより短い場合
は、QPropertyTree::detach() の呼び出しを明示的に実行する必要があります。
ユースケース
不侵入シリアル化
通常は、struct またはクラスインスタンスがアーカイブに渡されると、そのインスタンスの
Serialize メソッドが呼び出されます。ただし、次のグローバル関数を宣言することによって、この
動作をオーバーライドできます。
Version 1.6
374
Lumberyard 開発者ガイド
ユースケース
bool Serialize(Serialization::IArchive&, Type& value, const char* name, const
char* label);
ここでの戻り値の動作は IArchive::operator(). と同じです。入力アーカイブに対しては、
フィールドがない場合や読み取られていない場合、この関数は false を返します。出力アーカイブに
対しては、この関数は常に true を返します。
Note
この戻り値は上位に伝播されません。入れ子フィールドのいずれかがない場合でも、最上位
ブロックは true を返します。
グローバル関数手法は次の場合に便利です。
• 不侵入方法でシリアル化を追加する。
• シリアル化中にデータを変換する。
• プレーンポインタなど、サポートされていない型のサポートを追加する。
次の例では、Serialize 関数に std::pair<> 型のサポートを追加しています。
template<class T1, class T2>
struct pair_serializable : std::pair<T1, T2>
{
void Serialize(Serialization::IArchive& ar)
{
ar(first, "first", "First");
ar(second, "second", "Second");
}
}
template<class T1, class T2>
bool Serialize(Serialization::IArchive& ar, std::pair<T1, T2>& value, const
char* name, const char* label)
{
return ar(static_cast<pair_serializable<T1, T2>&>(value), name, label);
}
継承を使用する利点は、保護されたフィールドにアクセスできることです。アクセスポリシーが重要
ではなく、継承が望ましくない場合は、前のコードを次のパターンで置き換えることができます。
template<class T1, class T2>
struct pair_serializable
{
std::pair<T1, T2>& instance;
pair_serializable(std::pair<T1, T2>& instance) : instance(instance) {}
void Serialize(Serialization::IArchive& ar)
{
ar(instance.first, "first", "First");
ar(instance.second, "second", "Second");
}
}
template<class T1, class T2>
Version 1.6
375
Lumberyard 開発者ガイド
ユースケース
bool Serialize(Serialization::IArchive& ar, std::pair<T1, T2>& value, const
char* name, const char* label)
{
pair_serializable<T1, T2> serializer(value);
return ar(serializer, name, label);
}
クラスでの Enum の登録
クラス内の列挙型 (入れ子の "enum") を指定している場合は通常、SERIALIZATION_ENUM_BEGIN()
はコンパイルされません。この欠点を克服するには、次の例のように
SERIALIZATION_ENUM_BEGIN_NESTED を使用します。
SERIALIZATION_ENUM_BEGIN_NESTED(Class, Enum, "Label")
SERIALIZATION_ENUM(Class::ENUM_VALUE1, "value1", "Value 1")
SERIALIZATION_ENUM(Class::ENUM_VALUE2, "value2", "Value 2")
SERIALIZATION_ENUM_END()
多相型
シリアル化ライブラリでは、多相型のロードと保存がサポートされています。これは、スマートポイ
ンタ基本型にシリアル化することによって実装されています。
たとえば、次の階層があるとします。
IBase
• ImplementationA
• ImplementationB 次の例のように、派生型をマクロに登録する必要があります。
SERIALIZATION_CLASS_NAME(IBase, ImplementationA, "impl_a", "Implementation
A");
SERIALIZATION_CLASS_NAME(IBase, ImplementationA, "impl_b", "Implementation
B");
これで、ポインタを基本型にシリアル化できます。
#include <Serialization/SmartPtr.h>
_smart_ptr<IInterfface> pointer;
ar(pointer, "pointer", "Pointer");
最初の文字列は永続的ストレージのタイプの名前として使用され、2 番目の文字列は人間が読み取れ
る名前で、PropertyTree での表示に使用されます。
PropertyTree での表現のカスタマイズ
PropertyTree 内でカスタマイズできる 2 つの側面があります。
1. プロパティフィールドのレイアウト。これはラベル (IArchive::operator() の 3 番目の引数) の
コントロールシーケンスによって制御されます。
Version 1.6
376
Lumberyard 開発者ガイド
ユースケース
2. デコレータ。これは、特定のプロパティを編集または表現するのと同じ方法で定義されています。
制御文字
コントロールシーケンスは、IArchive::operator() の 3 番目の引数にプレフィックスとして追
加されます。PropertyTree のプロパティフィールドのレイアウトはこれらの文字によって制御されま
す。
レイアウト制御文字
プレフィックス
ロール
説明
!
読み取り専用
フィールド
ユーザーがプロパティの値を変更できないようにします。
この効果は再帰的ではありません。
^
インライン
構造ルートの名前と同じ行にプロパティを配置します。複
数のフィールドを、デフォルトの垂直リストではなく、水
平レイアウトで 1 行に配置するために使用できます。
^^
インラインで名前
の前に
プロパティ名を親構造の名前の前に配置します。名前の前
にチェックボックスを追加するのに役立ちます。
<
値フィールドを展
開
プロパティの値の部分を、使用可能なすべてのスペースを
使うように拡大します。
>
値フィールドを縮
小
値フィールドの幅を最小値に縮小します。インライン
フィールドの幅を制限するのに役立ちます。
>N>
フィールド幅を N
ピクセルに制限
UI を細かく制御するのに役立ちます。エディタ以外で使用
するのは推奨されません。
+
デフォルトで列を
拡大。
どの構造またはコンテナをデフォルトで拡大する
かを制御するのに使用できます。項目ごとの制御
が必要な場合にのみ使用します。そうでない場合
は、QPropertyTree::setExpandLevels を使用する方
が適切です。
[S]
S 制御文字を子に
適用。
子プロパティに制御文字を適用します。コンテナで特に役
立ちます。
制御文字の組み合わせ
次の例のように、複数の制御文字をまとめて効果を組み合わせることができます。
ar(name, "name", "^!<Name"); // inline, read-only, expanded value field
デコレータ
デコレータには 2 種類あります。
1. 元の値の変換を実行するカスタムシリアル化関数を実装するラッパー。たとえ
ば、Serialization/Math.h には、角度をラジアンで格納および編集できる
Serialization::RadiansAsDeg(float&) があります。
2. 変換はしませんが、PropertyTree でカスタムプロパティの実装の選択にその型が使用されるラッ
パー。リソースセレクタはこの種類のラッパーの例です。
Version 1.6
377
Lumberyard 開発者ガイド
ユースケース
デコレータ
目的
型の定義
必要なコンテキスト
AnimationPath
完全アニメーションパ
スの選択 UI。
文字列と似た次のよう
な型。
std::string、
string
(CryStringT)、
SCRCRef
CCryName
CharacterPath
UI: キャラクタパス
(cdf) のブラウズ。
CharacterPhysicsPathUI: キャラクタ .phys
ファイルのブラウズ。
CharacterRigPath
UI: .rig ファイルのブラ
ウズ。
SkeletonPath
UI: .chr または .skel
ファイルのブラウズ。
JointName
UI: キャラクタジョイ
ントのリスト
ICharacterInstance*
AttachmentName
UI: キャラクタアタッ
チメントのリスト
ICharacterInstance*
SoundName
UI: サウンドのリスト
ParticleName
UI: パーティクル効果
の選択
ラジアンを度として格
納または編集。
float。Vec3
数値のソフト制限また
はハード制限を設定
し、スライダー UI を
提供。
数値型
プロパティごとのコー
ルバック関数を提供。
「PropertyTree へ
のコールバックの追
加 (p. 380)」を参照
してください。
複合型 (構造やコンテ
ナ) から分離されたす
べての型
Serialization/
Decorators/Math.h
RadiansAsDeg
Serialization/
Decorators/
Range.h
Range
Serialization/
Callback.h
Callback
Version 1.6
378
Lumberyard 開発者ガイド
ユースケース
デコレータの例
次の例では、Range と CharacterPath デコレータを使用しています。
float scalar;
ar(Serialization::Range(scalar), 0.0f, 1.0f); // provides slider-UI
string filename;
ar(Serialization::CharacterPath(filename), "character", "Character"); //
provides UI for file selection with character filter
シリアル化コンテキスト
Serialize メソッドの署名は固定です。これにより、入れ子の Serialize メソッドに追加の引数を
渡すことができません。この問題を解決するために、次の例のようにシリアル化コンテキストを使用
して、入れ子の Serialize メソッド呼び出しに特定の型のポインタを渡すことができます。
void Scene::Serialize(Serialization::IArchive& ar)
{
Serialization::SContext sceneContext(ar, this);
ar(rootNode, "rootNode")
}
void Node::Serialize(Serialization::IArchive& ar)
{
if (Scene* scene = ar.FindContext<Scene>())
{
// use scene
}
}
コンテキストはリンクリストにまとめられています。ノードは SContext インスタンス内のスタック
に格納されています。
複数のコンテキストを使用できます。同じ型の複数のインスタンスを指定している場合は、最も内側
のコンテキストが取得されます。
既存のシリアル化コードを変更することなく、PropertyTree でコンテキストを使用できます。これを
行う最も簡単な方法は、次の例のように CContextList (QPropertyTree/ContextList.h) を使用
することです。
// CContextList m_contextList;
tree = new QPropertyTree();
m_contextList.Update<Scene>(m_scenePointer);
tree->setArchiveContext(m_contextList.Tail());
tree->attach(Serialization::SStruct(node));
不透明データブロックのシリアル化
アーカイブ内のデータブロックを不透明な方法で処理できます。この機能により、未知のデータ形式
をエディタで作業できるようになります。
これらのデータブロックは Serialization::SBlackBox 内に格納できます。SBlackBox は、他の
値としてシリアル化または逆シリアル化できます。ただし、SBlackBox を特定の種類のアーカイブか
ら逆シリアル化する場合は、対応するアーカイブを使用してシリアル化する必要があります。たとえ
Version 1.6
379
Lumberyard 開発者ガイド
ユースケース
ば、JSONIArchive から SBlackBox を取得した場合は、JSONOArchive を使用してそれを保存する
必要があります。
PropertyTree へのコールバックの追加
プロパティツリー内の単一のプロパティを変更すると、アタッチされているオブジェクト全体が逆シ
リアル化されます。これは、1 つのプロパティだけが変更された場合でもすべてのプロパティが更新
されることを意味します。このアプローチは無駄が多いように見えますが、次のような利点がありま
す。
• 入れ子プロパティの存続期間を追跡する必要がなくなり、入れ子型を安全な方法で外部から参照す
る要件がなくなります。
• プロパティツリーのコンテンツは静的データではなく、関数呼び出しの結果です。これにより、コ
ンテンツを完全に動的にできます。プロパティの存続期間を追跡する必要がないため、スタックに
構築された変数をシリアル化および逆シリアル化できます。
• 追跡の要件がなくなることによって、コード量が少なくなります。
その場合でも、どのプロパティが変更されたかを正確に知っておくことが望ましい状況があります。
その場合は、1) Serialize メソッドを使用する、または 2) Serialization::Callback を使用す
る、という 2 つの方法のいずれかで実現できます。
1. Serialize メソッドを使用して、次の例のように、新しい値を以前の値と比較します。
void Type::Serialize(IArchive& ar)
{
float oldValue = value;
ar(value, "value", "Value");
if (ar.IsInput() && oldValue != value)
{
// handle change
}
}
2. 2 番目のオプションは、次の例に示しているように、Serialization::Callback デコレータを
使用して、1 つまたは複数のプロパティに対してコールバック関数を追加することです。
#include <Serialization/Callback.h>
using Serialization::Callback;
ar(Callback(value,
[](float newValue) { /* handle change */ }),
"value", "Value");
Note
Callback は PropertyTree に対してのみ機能し、エディタのコードでのみ使用します。
Callback は他のデコレータと一緒に使用することもできますが、次の例のように、かなり不格好
な方法になります。
ar(Callback(value,
[](float newValue) { /* handle change*/ },
[](float& v) { return Range(v, 0.0f, 1.0f); }),
"value", "Value");
Version 1.6
380
Lumberyard 開発者ガイド
ユースケース
2 つのアプローチの中で、コールバックのアプローチの方が柔軟性がありますが、コールバックラム
ダ式またはコールバック関数で使用されるオブジェクトの存続期間を慎重に追跡する必要がありま
す。
MFC ウィンドウでの PropertyTree
コードベースでまだ MFC を使用している場合は、次の例のように、PropertyTree を MFC と一緒に使
用できるようにするラッパーを使用します。
#include <IPropertyTree.h> // located in Editor/Include
int CMyWindow::OnCreate(LPCREATESTRUCT pCreateStruct)
{
...
CRect clientRect;
GetClientRect(clientRect);
IPropertyTree* pPropertyTree = CreatePropertyTree(this, clientRect);
...
}
IPropertyTree インターフェイスでは QPropertyTree のメソッド
(Attach、Detach、SetExpandLevels など) が公開されます。
ドキュメントおよび検証
QPropertyTree では、ツールチップ形式の短いドキュメントおよび基本的な検証を追加する方法が
提供されています。
Doc メソッドでは、次の例のように、QPropertyTree にツールチップを追加できます。
void IArchive::Doc(const char*)
void SProjectileParameter::Serialize(IArchive& ar)
{
ar.Doc("Defines projectile physics.");
ar(m_velocity, "velocity", "Velocity");
ar.Doc("Defines initial velocity of the projectile.");
}
Doc メソッドでは、最後にシリアル化された要素にツールチップが追加されます。関数の最初で使用
すると、ブロック全体にツールチップが追加されます。
Warning および Error の呼び出しでは、次の例のように、プロパティツリー内の特定のプロパティ
に関連付けられている警告メッセージおよびエラーメッセージを表示できます。
template<class T> void IArchive::Warning(T& instance, const char*
format, ...)
template<class T> void IArchive::Error(T& instance, const char* format, ...)
void BlendSpace::Serialize(IArchive& ar)
{
ar(m_dimensions, "dimensions, "Dimensions");
if (m_dimensions.empty())
Version 1.6
381
Lumberyard 開発者ガイド
ユースケース
ar.Error(m_dimensions, "At least one dimension is required for
BlendSpace");
}
エラーメッセージは次のように表示されます。
警告メッセージは次のように表示されます。
動的リストを使用したドロップダウンメニュー
列挙値を指定する場合は、「データの定義 (p. 371)」セクションで説明している enum 登録マクロを
使用できます。
ドロップダウンメニューを定義するには、1) データを Serialization::StringListValue に変換
する、または 2) UI にカスタム PropertyRow を実装する、という 2 つの方法があります。
最初のアプローチの簡単な例を以下に示します。この例ではカスタム参照を使用しています。
// a little decorator that would annotate string as a special reference
struct MyReference
{
string& str;
MyReference(string& str) : str(str) {}
};
inline bool Serialize(Serialization::IArchive& ar, MyReference& wrapper,
const char* name, const char* label)
{
if (ar.IsEdit())
{
Serialization::StringList items;
items.push_back("");
items.push_back("Item 1");
items.push_back("Item 2");
items.push_back("Item 3");
Serialization::StringListValue dropDown(items, wrapper.str.c_str());
if (!ar(dropDown, name, label))
return false;
if (ar.IsInput())
wrapper.str = dropDown.c_str();
return true;
}
else
{
// when loading from disk we are interested only in the string
return ar(wrapper.str, name, label);
Version 1.6
382
Lumberyard 開発者ガイド
ユースケース
}
}
これで、次の例のように、文字列をドロップダウン項目としてシリアル化するための MyReference
を Serialize メソッド内のスタックに構築できます。
struct SType
{
string m_reference;
void SType::Serialize(Serialization::IArchive& ar)
{
ar(MyReference(m_reference), "reference", "Reference");
}
};
ドロップダウンメニューを定義する 2 番目の方法では、UI にカスタム PropertyRow を実装する必要
があります。この方法では多くの労力がかかりますが、選択可能項目のリストをすべてエディタコー
ド内で作成できます。
Version 1.6
383
Lumberyard 開発者ガイド
動画および音声をキャプチャします。
デモと動画キャプチャ
このセクションには、ベンチマーク用のビデオ録画に関する情報が含まれています。Lumberyard エ
ディタ の Perspective ビューを使用するか、Launcher を通じて純粋なゲームモードで、音声と動画を
キャプチャする方法についても説明します。
トピック
• 動画および音声をキャプチャします。 (p. 384)
• タイムデモの記録 (p. 389)
動画および音声をキャプチャします。
このチュートリアルでは、Lumberyardエディタ (またはゲーム) を設定してビデオをキャプチャする方
法を説明します。Lumberyard 単一フレームとして動画を出力します。必要に応じて、ステレオまた
は.wavファイル形式内の5.1のサラウンドサウンドオーディオを出力できます。一般的に利用されて
いるビデオ編集ソフトウェアを使用して出力を編集できます。
準備
キャプチャ準備のためにビデオと音声ストリームを開始するには、まず動画がどのようにキャプチャ
されるかを指定し設定する必要があります。コンソールコマンドを使用して、これらを設定します。
コンソールにコマンドを直接入力せずに、必要なコマンドを実行する設定ファイルを作成することで
時間を節約できます。設定ファイルの例は、このトピックの後半に説明します。
次のセクションではその設定とコンソールコマンドについて説明します。
ビデオ設定
フレームサイズと解像度
エディタ内でキャプチャされたフレームの高さと幅は通常パースペクティブウィンドウでレンダーし
たビューサイズにしたがって設定されます。ビューサイズを変更するには、パースペクティブウィン
ドウを再スケール、またはフレームのサイズが表示されているパースペクティブビューポートの右上
を右クリックします。
Version 1.6
384
Lumberyard 開発者ガイド
ビデオ設定
Lumberyard エディタ タおよびランチャーからレンダーしたイメージより高くキャプチャできます。
キャプチャフレームと接続して使用されるコンソールの変数は次のとおりです。
• r_CustomResHeight=N - 希望のフレームの高さをNピクセルで指定します。
• r_CustomResWidth=M - 希望のフレーム幅をMピクセルで指定します。
• r_CustomResMaxSize=P - エンジンがPピクセルでフレームをレンダーする最大解像度を指定しま
す。
• r_CustomResPreview=R - プレビューをビューポイントに表示するかどうか、またどのように表示
するかを指定します。Rで想定される値は、
r_CustomResPreview
プ
レ
ビュー
ス
テー
タ
ス
0
プ
レ
ビュー
な
し
1 ュー
ビ
ポー
ト
の
サ
イ
ズ
に
合
わ
せ
て
ス
ケー
ル
す
る
2 ュー
ビ
ポー
ト
サ
イ
ズ
に
合
わ
せ
て
ト
リ
Version 1.6
385
Lumberyard 開発者ガイド
ビデオ設定
r_CustomResPreview
プ
レ
ビュー
ス
テー
タ
ス
ミ
ン
グ
す
る
秒ごとのフレーム
指定するフレームの1秒あたりの数を決定するときは、以下に注意してください:
• NTSCスタンダード動画は1秒あたり約30フレームで、これは画質とファイルサイズの良い妥協点で
す。
• 高品質の動画は1秒あたり最大60フレーム入りますが、フレーム数を増やしたときでも品質の違い
はほとんど出ず、多くのファイルスペースを占有します。
• FPSが24未満 (映画標準) の動画は、スムーズに表示されません。
フレーム率を固定するには、コマンドを使用します。
t_fixedstep N
Nはタイムステップを指定します。タイムステップは計算式を使用して計算されます。
step = 1 second/<number of frames>
一般的なタイムステップの値は以下の表のとおりです。
FPS
タ
イ
ム
ス
テッ
プ
0.04
25
(PAL)
0.033333333
30
0.0166666667
60
ビデオキャプチャのファイル形式
いくつかの異なるファイル形式の画像を取得できます。平均的な画質は.jpegファイル形式で
す。.tgaまたは.bmpファイル形式は、高画質を希望する際に良く、.hdrはHDR合成に適していま
す。
Version 1.6
386
Lumberyard 開発者ガイド
録画の開始と終了
キャプチャするファイル形式を指定するには、コンソールコマンドを使用します。
capture_file_format N
Nは jpg、bmp、tgaまたはhdrです。
ビデオキャプチャのファイル場所
デフォルトでは、記録されたフレームは<root>\CaptureOutputディレクトリに保存されます。カ
スタムディレクトリを指定するには、コマンドを使用します。
capture_folder N
Nカスタムディレクトリ名です。
Caution
録画を開始すると、取得されたフレームは現在指定のディレクトリに配置され、同じ名前の
既存のファイルを上書きします。作業中のファイルが消去されるのを防ぐため、録画ごとに
ディレクトリを作成するか、開始前に既存のファイルを別のディレクトリに移動してくださ
い。
録画の開始と終了
前のセクションで説明した値を指定すると、コマンドを使用して録画を開始できます。
capture_frames N
Nを1に設定すると録画を開始し、Nを0に設定すると停止します。
オーディオ設定
開始する前にステレオオーディオまたは5.1サラウンドフォーマットを必要とするかを決定し、その後
設定内容に応じてWindowsのコントロールパネルで音声設定を変更します。
サウンドシステムの停止
キャプチャをするゲームのレベルをロードした後、ファイルを正常な出力でリダイレクトすることが
できるようにサウンドシステムを停止させなければなりません。サウンドシステムを停止するには以
下のコマンドを使用します。
#Sound.DeactivateAudioDevice()
これによりサウンド出力をゲームのルートディレクトリにある.wavファイルにリダイレクトします。
音はリアルタイムで実行されませんが、事前に設定するタイムステップに正確にリンクされます。
サウンドキャプチャを書き込むには以下のコマンドを使用します。
s_OutputConfig N
Nを3に設定すると、.wavへサウンドの非リアルタイムでの書き込みが有効化されます。Nを0に設定
すると、自動検出 (デフォルト) を指定します。
Version 1.6
387
Lumberyard 開発者ガイド
設定ファイル
サウンドシステムの再開
サウンドシステムを再設定するには以下のコマンドを使用します。
#Sound.ActivateAudioDevice()
これはゲームのルートディレクトリ内にある.wavファイルを作成します。ファイルは以下のコマンド
を組み合わせて音声デバイスを停止させるまで継続して書き込まれます。
#Sound.DeactivateAudioDevice()
s_OutputConfig 0
#Sound.ActivateAudioDevice()
Tip
これらのコマンドはサウンドシステムをリセットしますが、いくつかのサウンドは再度正し
くトリガーされるまで開始されません。これは特に繰り返されるサウンドに適用されます。
繰り返すサウンドを再生するには動画や音声の録画・録音を先に開始し、その後録音したい
繰り返されるサウンドをトリガーする任意のエリアを入力します。
設定ファイル
構成ファイルの作成
• 複数の録画をまったく同じ設定で必ず使用できるようにするには、各録画に使用できる構成ファイ
ルを作成します。これによりキャプチャされた全てのファイルが同じ形式であることを確認できま
す。
構成ファイルの例：
sys_spec = 4
Fixed_time_step 0.0333333333
Capture_file_format jpg
Capture_folder myrecording
r_width 1280
r_height 800
コマンドsys_spec = 4は最適な外観を生成するため、ゲームグラフィック設定を「非常に高い」
に設定します。
• 録画の開始・停止プロセスを高速化するには、2つの構成ファイルを作成します。1つは動画の開
始、もう1つは停止させるファイルです。
• 録画を開始するには、次のような構成ファイルを使用します。
#Sound.DeactivateAudioDevice()
s_OutputConfig 3
#Sound.ActivateAudioDevice()
Capture_frames 1
• 録画を停止するには、次のような構成ファイルを使用します。
Version 1.6
388
Lumberyard 開発者ガイド
タイムデモの記録
Capture_frames 0
#Sound.DeactivateAudioDevice()
s_OutputConfig 0
#Sound.ActivateAudioDevice()
構成ファイルの実行
構成ファイルを実行するには、コンソールを開いて以下のコマンドを入力します。
Exec N
N#は構成ファイルの名前です。
タイムデモの記録
概要
Lumberyard エディタ は、プレイヤ入力とカメラの動きを記録して再生できます。
Note
車両の移動など、いくつかのプレイヤアクションの記録はサポートされません。
この機能を使用するには、Lumberyard エディタ でゲームモードを開始してから記録する必要があり
ます。ゲームモードを開始するには、レベルが完全にロードされた後、Ctrl + G を押すか、純粋な
ゲームモードでレベルをロードします。
コンソールと、使用するレベルに対応したディレクトリの timedemo.log ファイルの両方に次のよう
な出力が表示されます。
TimeDemo Run 131 Finished.
Play Time: 3.96s, Average FPS: 50.48
Min FPS: 0.63 at frame 117, Max FPS: 69.84 at frame 189
Average Tri/Sec: 14037316, Tri/Frame: 278071
Recorded/Played Tris ratio: 0.99
記録の制御
コ
キー
マ
ス
ン
ン
ト
ソー
ド
ロー
ル
ク
コ
マ
ン
ド
record
記
Ctrl
録
+
の
PrintScreen
Version 1.6
389
Lumberyard 開発者ガイド
関連するコンソール変数
コ
キー
マ
ス
ン
ン
ト
ソー
ド
ロー
ル
ク
コ
マ
ン
ド
開
始
stoprecording
記
Ctrl
録
+
の
Break
終
了
demo
再
Shift
生
+
の
PrintScreen
開
始
stopdemo
再
Ctrl
生
+
の
Break
終
了
関連するコンソール変数
• stopdemo - タイムデモの再生を停止します。
• demo demoname - 指定したファイルからタイムデモを再生します。
• demo_fixed_timestep - 1 秒あたりの更新回数を指定します。
• demo_panoramic - デモを再生するときにパノラマビューを使用します。
• demo_restart_level N - 各ループ後にレベルを再開します。N に使用できる値は次のとおりで
す。0 = オフ、1 = 最初の再生で quicksave を使用、2 =レベルのロードを開始。
• demo_ai - デモ中に AI を有効または無効にします。
• demo_savestats - ループの最後にレベルの統計情報を保存します。
• demo_max_frames - 保存するフレームの最大数を指定します。
• demo_screenshot_frame N - デモの再生中に指定フレームのスクリーンショットを作成しま
す。N に負の値が指定されている場合は、N フレームごとにスクリーンショットが取得されます。
• demo_quit - デモの実行が終了した後、ゲームを終了します。
• demo_noinfo - デモの再生中に情報の表示を無効にします。
• demo_scroll_pause - ScrollLock キーの使用を有効にして、デモの再生と記録を一時停止しま
す。
• demo_num_runs - タイムデモをループする回数を指定します。
• demo_profile - デモのプロファイリングを有効にします。
• demo_file - タイムデモのファイル名を指定します。
Version 1.6
390
Lumberyard 開発者ガイド
エンティティプロパティのプレフィックス
エンティティシステム
エンティティシステムは現在非推奨になる予定で、Lumberyard コンポーネントエンティティシステ
ム (p. 322)に切り替えています。
このセクションではエンティティシステムに関するトピックについて説明します。エンティティは、
プレーヤーがインタラクトできるレベル内に設置されるオブジェクトです。
このセクションでは、次のトピックについて説明します。
• エンティティプロパティのプレフィックス (p. 391)
• 新しいエンティティクラスの作成 (p. 392)
• エンティティプールシステム (p. 394)
• 説明されるエンティティ ID (p. 404)
• エンティティに使用可能なサポートの追加 (p. 405)
• エンティティのスクリプト化 (p. 406)
エンティティプロパティのプレフィックス
Lumberyard エディタ では、プロパティ名の特別なプレフィックスから派生した型である型付きプロ
パティがサポートされています。サポートされているプレフィックスの一覧については、Objects/
EntityScript.cpp で定義されている s_paramTypes 配列を参照してください。この配列によっ
て、プレフィックスが変数型にマッピングされています。
Lumberyard では以下のプレフィックスがサポートされています。
{ "n",
IVariable::INT, IVariable::DT_SIMPLE,
SCRIPTPARAM_POSITIVE },
{ "i",
IVariable::INT, IVariable::DT_SIMPLE,0 },
{ "b",
IVariable::BOOL, IVariable::DT_SIMPLE,0 },
{ "f",
IVariable::FLOAT, IVariable::DT_SIMPLE,0 },
{ "s",
IVariable::STRING, IVariable::DT_SIMPLE,0 },
{ "ei",
{ "es",
IVariable::INT, IVariable::DT_UIENUM,0 },
IVariable::STRING, IVariable::DT_UIENUM,0 },
{ "shader",
{ "clr",
IVariable::STRING, IVariable::DT_SHADER,0 },
IVariable::VECTOR, IVariable::DT_COLOR,0 },
Version 1.6
391
Lumberyard 開発者ガイド
新しいエンティティクラスの作成
{ "color",
IVariable::VECTOR, IVariable::DT_COLOR,0 },
{ "vector",
IVariable::VECTOR, IVariable::DT_SIMPLE,0 },
{ "snd",
{ "sound",
{ "dialog",
IVariable::STRING, IVariable::DT_SOUND,0 },
IVariable::STRING, IVariable::DT_SOUND,0 },
IVariable::STRING, IVariable::DT_DIALOG,0 },
{ "tex",
{ "texture",
IVariable::STRING, IVariable::DT_TEXTURE,0 },
IVariable::STRING, IVariable::DT_TEXTURE,0 },
{ "obj",
{ "object",
IVariable::STRING, IVariable::DT_OBJECT,0 },
IVariable::STRING, IVariable::DT_OBJECT,0 },
{ "file",
IVariable::STRING,
{ "aibehavior",
IVariable::STRING,
{ "aicharacter",
IVariable::STRING,
{ "aipfpropertieslist", IVariable::STRING,
IVariable::DT_AI_PFPROPERTIESLIST,0 },
{ "aiterritory",
IVariable::STRING,
{ "aiwave",
IVariable::STRING,
IVariable::DT_FILE,0 },
IVariable::DT_AI_BEHAVIOR,0 },
IVariable::DT_AI_CHARACTER,0 },
{
{
{
{
IVariable::DT_LOCAL_STRING,0 },
IVariable::DT_EQUIP,0 },
IVariable::DT_REVERBPRESET,0 },
IVariable::DT_REVERBPRESET,0 },
"text",
"equip",
"reverbpreset",
"eaxpreset",
IVariable::STRING,
IVariable::STRING,
IVariable::STRING,
IVariable::STRING,
IVariable::DT_AITERRITORY,0 },
IVariable::DT_AIWAVE,0 },
{ "aianchor",
IVariable::STRING, IVariable::DT_AI_ANCHOR,0 },
{
{
{
{
{
{
{
{
{
{
{
{
{
{
IVariable::STRING,
IVariable::STRING,
IVariable::STRING,
IVariable::STRING,
IVariable::STRING,
IVariable::STRING,
IVariable::STRING,
IVariable::STRING,
IVariable::STRING,
IVariable::STRING,
IVariable::STRING,
IVariable::STRING,
IVariable::STRING,
IVariable::STRING,
"soclass",
"soclasses",
"sostate",
"sostates",
"sopattern",
"soaction",
"sohelper",
"sonavhelper",
"soanimhelper",
"soevent",
"sotemplate",
"gametoken",
"seq_",
"mission_",
IVariable::DT_SOCLASS,0 },
IVariable::DT_SOCLASSES,0 },
IVariable::DT_SOSTATE,0 },
IVariable::DT_SOSTATES,0 },
IVariable::DT_SOSTATEPATTERN,0 },
IVariable::DT_SOACTION,0 },
IVariable::DT_SOHELPER,0 },
IVariable::DT_SONAVHELPER,0 },
IVariable::DT_SOANIMHELPER,0 },
IVariable::DT_SOEVENT,0 },
IVariable::DT_SOTEMPLATE,0 },
IVariable::DT_GAMETOKEN, 0 },
IVariable::DT_SEQUENCE, 0 },
IVariable::DT_MISSIONOBJ, 0 },
新しいエンティティクラスの作成
以下は、ファンと呼ばれるエンティティクラスの作成の例です。
• ".ent", for example "GameSDK\Entities\Fan.entのような、".ent"の拡張子が付いた新しいエン
ティティ定義ファイルを作成します。このファイルはエンジンにエンティティを開示します。
<Entity
Name="Fan"
Script="Scripts/Entities/Fan.lua"
/>
Version 1.6
392
Lumberyard 開発者ガイド
新しいエンティティクラスの作成
• 例えばGameSDK\Entities\Scripts\Fan.luaのような新しいLuaスクリプトファイルを作成しま
す。Luaファイルはエンティティロジックを定義します。
Fan = {
type = "Fan",
scripting
-- can be useful for
-- instance member variables
minrotspeed = 0,
maxrotspeed = 1300,
acceleration = 300,
currrotspeed = 0,
changespeed = 0,
currangle = 0,
-- following entries become automatically exposed to the editor and
serialized (load/save)
-- type is defined by the prefix (for more prefix types, search for
s_paramTypes in /Editor/Objects/EntityScript.cpp)
Properties = {
bName = 0,
-- boolean example, 0/1
fName = 1.2,
-- float example
soundName = "",
-- sound example
fileModelName = "Objects/box.cgf",
-- file model
},
-- optional editor information
Editor = {
Model = "Editor/Objects/Particles.cgf",
represents this object in editor
Icon = "Clouds.bmp",
represents this object in editor
},
-- optional 3d object that
-- optional 2d icon that
}
-- optional. Called only once on loading a level.
-- Consider calling self:OnReset(not System.IsEditor()); here
function Fan:OnInit()
self:SetName( "Fan" );
self:LoadObject( "Objects/Indoor/Fan.cgf", 0, 0 );
self:DrawObject( 0, 1 );
end
-- OnReset() is usually called only from the Editor, so we also need
OnInit()
-- Note the parameter
function Fan:OnReset(bGameStarts)
end
-- optional. To start having this callback called, activate the entity:
-- self:Activate(1); -- Turn on OnUpdate() callback
function Fan:OnUpdate(dt)
if ( self.changespeed == 0 ) then
self.currrotspeed = self.currrotspeed - System.GetFrameTime() *
self.acceleration;
if ( self.currrotspeed < self.minrotspeed ) then
self.currrotspeed = self.minrotspeed;
end
Version 1.6
393
Lumberyard 開発者ガイド
エンティティプールシステム
else
self.currrotspeed = self.currrotspeed + System.GetFrameTime() *
self.acceleration;
if ( self.currrotspeed > self.maxrotspeed ) then
self.currrotspeed = self.maxrotspeed;
end
end
self.currangle = self.currangle + System.GetFrameTime() *
self.currrotspeed;
local a = { x=0, y=0, z=-self.currangle };
self:SetAngles( a );
end
-- optional serialization
function Fan:OnSave(tbl)
tbl.currangle = self.currangle;
end
-- optional serialization
function Fan:OnLoad(tbl)
self.currangle = tbl.currangle;
end
-- optional
function Fan:OnSpawn()
end
-- optional
function Fan:OnDestroy()
end
-- optional
function Fan:OnShutDown()
end
-- optional
function Fan:OnActivate()
self.changespeed = 1 - self.changespeed;
end
エンティティプールシステム
このセクションのトピックでは、エンティティプールシステムについて、実装する方法、プー
ルされる新しいエンティティクラスを登録する方法、およびデバッグする方法などを説明しま
す。Lumberyard エディタ でエンティティプールを使用する方法の詳細については、Lumberyard の
ユーザーガイドを参照してください。
このセクションでは、次のトピックについて説明します。
• エンティティプールの定義 (p. 395)
• エンティティプールの作成 (p. 397)
• プールを使用した静的エンティティの作成と破棄 (p. 398)
• プールを使用した動的エンティティの作成と破棄 (p. 401)
• シリアル化 (p. 402)
• リスナー/イベント登録 (p. 403)
Version 1.6
394
Lumberyard 開発者ガイド
エディタの使用
• デバッグユーティリティ (p. 403)
エンティティプールを作成し、これを使用できるよう準備する際には、以下のプロセスを経る必要が
あります。各手順については、それぞれ詳しく説明します。
1. エンティティプール定義の情報を使用してエンティティプールが作成されます。
2. エンティティプールにエンティティコンテナが取り込まれます。
3. エンティティコンテナのいずれかのエンティティプールエンティティの署名を、プールにマップさ
れている各 Entity クラスのエンティティプールの署名と比較してテストし、エンティティプール
を評価します。
4. プールによって作成されたとしてマークされたすべてのエンティティには、それらに対して作成さ
れたエンティティプールのブックマークがあります。
5. エンティティプールのブックマークはエンティティプールによって準備されるか、エンティティ
プールに戻されます。これは要求に応じて Entity クラスにマップされます。
エディタの使用
Lumberyard エディタ を実行する際には、エンティティプールシステムは完全には有効になりませ
ん。エディタでゲームをプレイする際、すべてのエンティティはプールの外部に作成されます。ただ
し、エンティティプールを伴うフローノードアクションは、すべて引き続き Lumberyard エディタ で
動作し、ゲーム内に表示される最終結果を模倣します。
Note
エンティティプールのリスナーである OnEntityPreparedFromPool と
OnEntityReturnedToPool は、エンティティ自体が削除または再使用されていない場合で
も引き続きエディタで呼び出されます。
静的と動的なエンティティ
エンティティは静的または動的にすることができます。静的なエンティティはエディタに配置され、
レベルと共にエクスポートされます。このエンティティは常に存在します。エクスポートされた情報
に関連するプロパティによって、これをプールすべきか (そしてレベルのロードの際に作成しない)、
あるいはその代わりとして、これに対して作成されたエンティティプールのブックマークを保持する
かどうかが決定されます。動的なエンティティは実行時に、通常はゲームコードから作成されます。
情報は実行時、通常は作成される直前に構築され、処理のためにエンティティシステムに渡されま
す。この情報は、エンティティプールを経由すべきかどうかも表します。
エンティティプールの定義
エンティティプールは、\Game\Scripts\Entities\EntityPoolDefinitons.xml ファイルで定
義する必要があります。エンティティプールの定義では、次の項目を定義します。
• エンティティコンテナが使用されていないときに使用する空のクラス
• プールにマッピングされたエンティティクラス
• プールとその使用方法に関するその他のプロパティ
一般的に、プールは、最初、定義された数のエンティティコンテナで満たされています。言い換えれ
ば、定義にマッピングされたエンティティクラスに属するエンティティを完全にインスタンス化する
際に通常作成される、必要なすべてのエンティティプロキシおよびゲームオブジェクト拡張機能が含
まれた空の CEntity クラスと言えます。たとえば、通常の AI エンティティには、サウンド拡張機
能、スクリプト拡張機能、レンダー拡張機能、ユーザー拡張機能としてゲームオブジェクト、さらに
Version 1.6
395
Lumberyard 開発者ガイド
エンティティプールの定義
ゲームオブジェクト拡張機能として CPlayer クラスといったエンティティプロキシが含まれていま
す。これらすべてのクラスは、空の CEntity インスタンスに対してそれぞれインスタンス化され、
プールから作成されるときにエンティティによって再利用されます。
次は、エンティティプールの定義を示しています。
EntityPoolDefinitions.xml
<Definition name="AI" emptyClass="NullAI" maxSize="16" hasAI="1"
defaultBookmarked="0" forcedBookmarked="0">
<Contains>
<Class>Grunt</Class>
<Class>Flyer</Class>
</Contains>
</Definition>
空のクラス
空のクラスは、emptyClass 属性を使用して定義します。この属性は、有効なエンティティクラスの
名前を取得します。空のクラスを定義することには、次の目的があります。
• エンティティに常に空のエンティティクラスを関連付ける必要があるというエンジンの要件を満た
すことができます。このエンティティクラスに対して、空のコンテナが初期化されて再利用されま
す。
• 必要なすべてのエンティティプロキシおよびエンティティに必要なゲームオブジェクト拡張機能を
準備することができます。
たとえば、前のセクションに示されている定義を構築する場合、"NullAI" という名前の空のクラスを作
成し、それを上記のその他の AI クラスと同じように登録します。次に:
1. エンティティクラスを宣言し、Game Factory を使用して、それを Lua スクリプトにマッピングし
ます。
GameFactory.cpp
REGISTER_FACTORY(pFramework, "NullAI", CPlayer, true);
2. エンティティクラスに Lua スクリプトを作成します。\Game\Scripts\Entities\AI
\NullAI.lua にあるサンプルコードを参照してください。
これにより、Lumberyard で "NullAI" を有効なエンティティクラスとして表示できるようになります。
加えて、CPlayer をエンティティクラスにマッピングすることで、エンティティコンテナに対して
正しいゲームオブジェクト拡張機能がインスタンス化されるようにすることができます。Lua スクリ
プトでは、エンティティコンテナに対して、すべてのエンティティプロキシを作成する必要があり
ます。サンプルコードでは、レンダープロキシが作成されていますが、このエンティティに対してア
セットモデルはロードされません。詳細については、「エンティティプールの作成 (p. 397)」にある
エンティティプールの署名に関する説明を参照してください。
エンティティクラスのマッピング
エンティティプールの定義ファイルの <Contains> セクションでは、このプールからエンティティを
作成するときにエンティティが属する必要があるすべてのエンティティクラスをマッピングする必要
があります。このセクションに新しい <Class> ノードを追加することで、任意の数のエンティティ
クラスをマッピングすることができます。完全にインスタンス化したときに各エンティティに空のク
ラスと同じ動的クラスの階層が含まれていることが重要です。このことを確認することができる便利
なデバッグツールの詳細については、「デバッグユーティリティ (p. 403)」を参照してください。
Version 1.6
396
Lumberyard 開発者ガイド
エンティティプールの作成
その他のプロパティ
エンティティプールの定義では、次の追加のプロパティを定義することもできます。
name
エンティティプールに付けられた一意の ID です。これは、デバッグを行うときに便利で
す。name は、すべての定義を通じて一意である必要があります。
maxSize
このプールが到達することができるプールの最大サイズです。デフォルトでは、これは、レベル
をロードするときにプールを満たすために作成されるエンティティコンテナの数でもあります。
この値は、レベルについて上書きすることができます。その場合、レベルのルートディレクトリ
に EntityPools.xml ファイルを含めます。このファイルは、プールあたりに作成されるエン
ティティコンテナの数を減らす目的でのみ使用することができます。ここで定義した maxSize 値
を超えることはありません。これは、レベルあたりのエンティティプールのメモリフットプリン
トを減らす必要がある場合に便利です。次のファイル例では、AI エンティティプールのサイズが
"2" に調整されています。
LevelEntityPools.xml
<EntityPools>
<AI count="2" />
</EntityPools>
hasAI
AI が関連付けられているエンティティをエンティティプールに含めるかどうかを指定するブール
値です。AI が含まれるエンティティをプールする場合は、このプロパティを TRUE に設定するこ
とが重要です。
defaultBookmarked
このプールにマッピングされているエンティティクラスのいずれかに属するエンティティに
"created through pool" というフラグを付けるかどうかを指定するブール値です (「プールを使用
した静的エンティティの作成と破棄 (p. 398)」を参照してください)。このフラグによって、レ
ベルのロード時にインスタンス化する代わりにエンティティに対してエンティティプールブック
マークを作成するかどうかが決定されます。
forcedBookmarked
このプールにマッピングされているエンティティクラスのいずれかに属するエンティティをプー
ルから作成する必要があるかどうかを指定するブール値です。このプロパティは、エンティティ
の "created through pool" フラグをオーバーライドします (「プールを使用した静的エンティティ
の作成と破棄 (p. 398)」を参照してください)。
エンティティプールの作成
レベルをロードすると、各エンティティプールの定義に対してエンティティプールが作成されます。
エンティティプールが作成されると、emptyClass 属性値がエンティティクラスとして使用されて、
プールが空のコンテナ (CEntity のインスタンス) で満たされます。これらの空のコンテナには、満た
す必要のある条件がいくつかあります。
• コンテナのサイズは最小である必要があります。つまり、コンテナにアセットまたは大量のデー
タをロードすることはできません。たとえば、サンプルの Lua スクリプト (\Game\Scripts
\Entities\AI\NullAI.lua) では、NullAI エンティティがキャラクターモデル、アニメーション
グラフ、ボディーダメージの定義などを定義しません。
• それぞれにマッピングされたエンティティクラスを使用して完全にインスタンス化された CEntity
とは異なり、これらのコンテナには、コンテナ向けに作成された同じエンティティプロキシとゲー
ムオブジェクト拡張機能が存在する必要があります。
Version 1.6
397
Lumberyard 開発者ガイド
プールを使用した静的エンティティの作成と破棄
プールが作成されると、いずれかの空のコンテナを使用して、エンティティプールの署名が生成され
ます。エンティティプールの署名は、エンティティの動的クラスの階層をマッピングするシンプルな
コンテナです。
エンティティプールシステムの機能の 1 つは、エンティティによって使用されるデリゲートクラス
に対する動的割り当てを可能な限り回避することです。これらのデリゲートクラスの主要な例は、エ
ンティティによって使用されるエンティティプロキシとゲームオブジェクト拡張機能です。エンティ
ティプールの空のコンテナが最初に作成されると、コンテナに含まれる実際のエンティティによって
使用されるデリゲートクラスも作成されるはずです。デリゲートクラスが確実に作成されるようにす
るために、エンティティプールの署名が使用されます。このプロセスは、次のように機能します。
1. TSerialize ライターが作成されます。このライターは、エンティティに存在する各エンティティ
プロキシとゲームオブジェクト拡張機能に渡されます。
2. 各プロキシと拡張機能は、いくつかの情報を TSerialize ライターに書き込みます。この情報は一
意である必要があります。
3. 次に、2 つの署名を比較することにより、署名に同じ情報が書き込まれているかどうかが確認さ
れ、署名に同じ動的クラスの階層が含まれていることが検証されます。
すべてのエンティティプロキシでは、その情報を TSerialize ライターに書き込むための設定が完
了しています。ただし、新しいゲームオブジェクト拡張機能 (または新しいエンティティプロキシ) を
作成する場合は、必要に応じて署名ヘルパーに応答するためのクラスを設定する必要があります。
このクラスを設定するには、仮想メソッド (エンティティプロキシの場合は GetSignature、ゲー
ムオブジェクト拡張機能の場合は GetEntityPoolSignature) を実装し、クラスに関する情報を
TSerialize ライターに書き込みます。通常、必要なことは、クラス名でグループを開始/終了するこ
とだけです。この関数は、これまでのところ署名が有効であることを示すために、TRUE を返すはず
です。
CActor::GetEntityPoolSignature Example
bool CActor::GetEntityPoolSignature( TSerialize signature )
{
signature.BeginGroup("Actor");
signature.EndGroup();
return true;
}
このデバッグユーティリティ (p. 403)セクションでは、すべての要素が正常に機能していることを検
証するために、エンティティプール署名テストの結果を表示する方法について説明しています。
プールを使用した静的エンティティの作成と破棄
このトピックでは、静的エンティティの処理に関する問題について説明します。
エンティティプールのブックマーク
プールから作成するエンティティとしてエンティティにマークが付けられている場合、そのエンティ
ティはレベルのロード中にインスタンス化されません。代わりに、エンティティプールのブックマー
クが生成されます。ブックマークには、次のいくつかの項目が含まれています。
• エンティティに予約されたエンティティ ID。このエンティティ ID は、レベルがエクスポートされ
るときに割り当てられます。また、このエンティティ ID は、後でシステムにエンティティを作成す
るよう指示するときに使用します。
• エンティティを一意にする、静的にインスタンス化されたデータ。これには、エリア情報、フロー
グラフ情報、親子関係、PropertiesInstance テーブルなどが含まれた、mission.xml ファイルの
<EntityInfo> セクションが含まれます。
Version 1.6
398
Lumberyard 開発者ガイド
プールを使用した静的エンティティの作成と破棄
• シリアル化されたエンティティの状態 (過去にエンティティがプールに戻されたことがある場合)。
詳細については、「シリアル化 (p. 402)」を参照してください。
(レベルをエディタからエクスポートしたときに生成される) mission.xml ファイルの各エンティ
ティの <EntityInfo> セクションには、CreatedThroughPool プロパティが含まれています。こ
のプロパティは、SEntitySpawnParams 構造体から参照することができます。TRUE に設定する
と、EntityLoadManager モジュールはエンティティに CEntity インスタンスを作成しません。代
わりに、静的にインスタンス化されたデータと予約済みのエンティティ ID を EntityPoolManager
に委任し、ブックマークを作成します。
CEntityLoadManager::ParseEntities
SEntityLoadParams loadParams;
if (ExtractEntityLoadParams(entityNode, loadParams))
{
if (bEnablePoolUse && loadParams.spawnParams.bCreatedThroughPool)
{
CEntityPoolManager *pPoolManager = m_pEntitySystem>GetEntityPoolManager();
bSuccess = (pPoolManager && pPoolManager>AddPoolBookmark(loadParams));
}
// Default to creating the entity
if (!bSuccess)
{
EntityId usingId = 0;
bSuccess = CreateEntity(loadParams, usingId);
}
}
静的エンティティの準備
静的エンティティの準備を行うには、IEntityPoolManager::PrepareFromPool を呼び出し、作
成する静的エンティティに関連付けられたエンティティ ID を渡します。これにより、以下の実行フ
ローが行われます。
1. 現在のフレームでリクエストを処理できるかどうかシステムによって判断されます。その際、リ
クエストを分散させるために、1 つのフレームのキューに対して、なるべく複数のリクエストが
追加されます。bPrepareNow パラメーターが TRUE に設定されている場合や、現在のフレー
ムで処理された準備リクエストがない場合、リクエストはすぐに処理されます。それ以外の場
合、リクエストはキューに追加されます。CEntityPoolManager::LoadBookmarkedFromPool
で、EntityLoadManager に対してエンティティを作成するようにリクエストされます。
Note
注意: この操作をエディタで実行する場合、エンティティでは、Enable イベントが呼び出
されるだけです。これにより、フローグラフを使用してエンティティを有効にする (非表示
を解除する) 場合が再現されます。その場合、実行フローは最後の手順までスキップされま
す。
2. リクエストされたエンティティを保持するための (空またはまだ使用されている) エンティティコ
ンテナがシステムによって検索されます。関数 CEntityPoolManager::GetPoolEntity によっ
て、アクティブなエンティティプールの中から指定された静的エンティティのエンティティクラス
を含むプールが検索されます。正しいプールが検索されたら、そこからコンテナが取得されます。
実際は、次の順序で行われます。
Version 1.6
399
Lumberyard 開発者ガイド
プールを使用した静的エンティティの作成と破棄
a. forcedPoolId (プールを満たすために作成されたいずれかの空のコンテナのエンティティ ID)
がリクエストされた場合、該当するエンティティコンテナが検索されて返されます。
b. forcedPoolId がリクエストされていない場合、アクティブでないセットからエンティティコ
ンテナ (現在使用されていないエンティティコンテナ) が取得されます。
c. アクティブでないコンテナが利用できない場合、アクティブなセットからエンティティ
コンテナ (現在使用されているエンティティコンテナ) が取得されます。その際、"ウェ
イト" 値を使用して返されるコンテナが決定されます。スクリプトで特別な Lua 関数
(CEntityPoolManager::GetReturnToPoolWeight) が使用され、空のコンテナのウェイトが
それぞれリクエストされます。ウェイト値がマイナスであるコンテナは、できるだけ使用しない
でください。システムによって緊急フラグが渡される場合があります。その場合、プールは最大
サイズに到達しています。
d. 空のコンテナが依然として見つからない場合、システムは、緊急フラグを無視して、プールを拡
大しようとします。これができるのは、プールが最大サイズで作成されていない場合に限ります
(これは、レベルについて最大プールサイズを小さな最大サイズでオーバーライドした場合に起
こります)。その場合、新しいエンティティコンテナが生成されてプールに追加され、すぐに使
用されます。
3. 静的にインスタンス化されたデータとブックマークから生成された予約済みのエンティティ ID と
一緒に、取得されたエンティティコンテナが関数 CEntityLoadManager::CreateEntity に渡さ
れ、再ロードプロセスが開始されます。CreateEntity は、新しい CEntity インスタンスを作成
する代わりに、提供されたエンティティコンテナを使用します。また、再ロードパイプラインの呼
び出しをエンティティコンテナ上で処理し、準備された静的エンティティに静的にインスタンス化
されたすべてのデータをインストールします。再ロードパイプラインは、次のとおりです。
a. エンティティコンテナで関数 CEntity::ReloadEntity が呼び出されます。CEntity インス
タンスによって、内部のデータが消去され、準備しているエンティティの静的にインスタンス化
されたデータが使用され始めます。Lua スクリプトでも、関数 OnBeingReused を使用してデー
タの消去が行われます。
b. エンティティシステムの SALT バッファおよびその他の内部コンテナが更新され、このエンティ
ティコンテナに予約済みのエンティティ ID が保持され、それを使用して取得できるようになり
ます。
c. 提供された静的にインスタンス化されたデータを使用してエンティティプロキシを再ロードする
ように促されます。これは、IEntityProxy::Reload を呼び出すことによって実行されます。
各プロキシが提供された新しいデータによって正しくリセットされます。他のプロキシによって
使用される前に Lua スクリプトが正しく関連付けられるように、常にスクリプトプロキシが最初
に再ロードされます。
ゲームオブジェクトをユーザープロキシとして使用している場合は、コンテナのすべてのゲー
ムオブジェクト拡張機能も再ロードするように促されます。これは、すべての拡張機能で
IGameObjectExtension::ReloadExtension を呼び出すことによって実行されます。この
関数が FALSE を返す場合は、拡張機能が削除されます。これが完了すると、すべての拡張機能
で IGameObjectExtension::PostReloadExtension が呼び出されます。これにより、Init お
よび PostInit ロジックが再現されます。各拡張機能が提供された新しいデータによって正しくリ
セットされます。
4. ブックマーク内にシリアル化されたデータが存在する場合は、そのデータを使用してエンティティ
コンテナがロードされます。これにより、最後にプールに戻されたときの状態に静的エンティティ
を回復することができます。このプロセスは、静的エンティティを初めて準備している場合はス
キップされます。
この時点で CEntity::GetEntity または CEntity::FindEntityByName を呼び出すと、静的エン
ティティとその情報が現在置かれているエンティティコンテナが返されます。
プールへの静的エンティティの返還
静的エンティティを戻すには、関数 IEntityPoolManager::ReturnToPool を呼び出します。静的
エンティティに関連付けられたエンティティ ID を渡す必要があります。これにより、以下の実行フ
ローが行われます。
Version 1.6
400
Lumberyard 開発者ガイド
プールを使用した動的エンティティの作成と破棄
1. 関数 CEntityPoolManager::ReturnToPool は、ブックマークに加えて、静的エンティティが置
かれている現在のエンティティコンテナが含まれるエンティティプールを検索します。
2. 引数 bSaveState に応じて、CEntity インスタンスが保存され、シリアル化された情報がブック
マークに追加されます。これにより、後で静的エンティティの準備を再度行ったときに、現在の状
態に回復することができます。
3. エンティティコンテナに対して、再ロードプロセスが再度実行されます。しかし、今回は、空のク
ラスを使用してエンティティコンテナが再ロードされます。これにより、ロード済みのアセット/コ
ンテンツへの参照が効果的にすべて削除され、必要最小限の状態に戻ります。
この時点で CEntity::GetEntity または CEntity::FindEntityByName を呼び出して、静的エン
ティティを検索すると、NULL が返されます。
プールを使用した動的エンティティの作成と破棄
動的エンティティの作成と破棄プロセスは、動的エンティティにはエンティティプールのブックマー
クがない (少なくとも初回はありません) という主な例外を除き、静的エンティティの場合と同じで
す。動的エンティティはレベル内にエクスポートされないため、静的にインスタンス化されたデータ
は関連付けられず、ブックマークは作成されません。
動的エンティティの作成
静的エンティティの場合と同様に、プールを使用した動的エンティティの作成
は、IEntitySystem::SpawnEntity の呼び出しから開始します。SEntitySpawnParams インスタ
ンスを作成して、静的にインスタンス化されたデータを説明します。プールを介してエンティティを
作成する場合は、この構造体に入力するときに bCreatedThroughPool プロパティを TRUE に設定
します。次の例では、Vehicle システムの vehicle 部分はプールを介して起動されます。
SEntitySpawnParams spawnParams;
spawnParams.sName = pPartName
spawnParams.pClass = gEnv->pEntitySystem->GetClassRegistry()>FindClass("VehiclePartDetached");
spawnParams.nFlags = ENTITY_FLAG_CLIENT_ONLY;
spawnParams.bCreatedThroughPool = true;
IEntity* pSpawnedDebris = gEnv->pEntitySystem->SpawnEntity(spawnParams);
SpawnEntity の次に、以下の実行フローが行われます。
1. CEntitySystem::SpawnEntity は指定されたエンティティクラスに関連付けられたエンティ
ティプールの有無を確認します。ある場合、エンティティプールマネージャーにワークロードを委
任します。
2. CEntityPoolManager::PrepareDynamicFromPool 内で、エンティティプールのブックマーク
が新しいエンティティに対して作成されます。これは主にシリアル化のために行います。
3. 実行フローは静的エンティティを準備するときと同じ順序で行われます (プールを使用した静的エ
ンティティの作成と破棄 (p. 398) を参照してください)。
4. プロセスが正常に完了すると、情報が現在置かれているエンティティコンテナが返されます。それ
以外の場合、SpawnEntity はリクエストを満たす新しい CEntity インスタンスを作成します。
この時点で CEntity::GetEntity または CEntity::FindEntityByName を呼び出すと、動的エン
ティティとその情報が現在置かれているエンティティコンテナが返されます。
Version 1.6
401
Lumberyard 開発者ガイド
シリアル化
プールを使用した動的エンティティの破棄
静的エンティティの場合と同様に、IEntitySystem::RemoveEntity またはエンティティを破棄で
きるその他の方法を使用します。エンティティプールマネージャーはプールにエンティティコンテナ
を返し、他の場所で使用できるように開放するか、プロセスで動的エンティティを削除します。結果
として生じる実行フローは、次の 2 つの点で静的エンティティの破棄とは異なります。
• 動的エンティティは返されたときにシリアル化されません。
• 動的エンティティに関連付けられるエンティティプールのブックマークは削除されます。これは必
要がなくなります。
この時点で CEntity::GetEntity または CEntity::FindEntityByName を呼び出すと NULL が返
されます。
シリアル化
エンティティプールシステムを通じて作成された、または準備された全てのエンティティはゲームの
セーブ/ロードシステムによってシリアル化されます。上記の理由により、通常のシリアル化において
プール内からのエンティティIEntity:IsFromPoolはシリアル化しないでください。これは ゲーム
のセーブとロードを行うため、Lumberyardのデフォルト実装で扱われます。
エンティティプールシステムはエンティティシステムによるSerialize関数の実装によってシリアル
化されます。
エンティティプールをセーブする
以下のプロセスはゲームがセーブされる時に発生します。
1. エンティティプール内の全実行中エンティティコンテナは最新版に更新されています。これによ
りCEntityPoolManager::UpdatePoolBookmarkは実行中のすべてのエンティティコンテナに
必要な要素となります。エンティティにENTITY_FLAG_NO_SAVEフラグの設定がされていない限
り、ブックマークは次のとおりシリアル化されます:
a. シリアル化ヘルパーは、エンティティのシリアル化状態を保持するブックマーク
のpLastState（ISerializedObject）に書き込みます。
b. コールバックはCEntityPoolManager::OnBookmarkEntitySerialize、 エンティティのシ
リアル化プロセスを通して実行します。これは一般情報、プロパティそして全てのエンティティ
プロキシがオーバーロードされたSerialize()の実装を用いてシリアル化されたことを保証し
ます。
c. OnBookmarkEntitySerializeコールバックに有料会員として登録しているリスナーは、ブッ
クマークにデータを書き込むことができます。これはまたエンティティと同時にAIオブジェクト
をブックマークするのにも使用されます。
2. 静的エンティティおよび動的エンティティの使用カウントを含む、すべてのエンティティプールの
ブックマークがセーブされます。
3. なんらかの準備リクエストがキューに入れられている場合、準備リクエストのキューはセーブされ
ます。
エンティティプールのローディング
以下のプロセスはゲームがロードされる時に発生します。
1. セーブされたエンティティプールのブックマークは読み込まれています。ブックマークに動的エン
ティティが含まれていると示される場合、本当に存在することを確認するために読み込まれます。
各ブックマークのpLastStateが読み込まれ、更新されます。
Version 1.6
402
Lumberyard 開発者ガイド
リスナー/イベント登録
2. ゲームがセーブされた時に実行中だったエンティティがエンティティプールのブックマークに含ま
れている場合、そのエンティティはプールから再度作成／準備されます。
a. エンティティが作成/準備されている間に、最終段階でpLastStateを用いて内部状態をロードし
ます。これはこの時点でオブジェクトに情報が含まれるためです。
b. これは同時に、OnBookmarkEntitySerializeリスナーコールバックを呼び出します。それに
より他のシステムがブックマークから情報を読み取ることができます。
リスナー/イベント登録
エンティティプールの使用量を処理する複数のリスナーとさまざまなイベントのコールバックがあり
ます。これらのコールバックはエンティティ登録に依存するサブシステムで重要です。エンティティ
が準備されるかプールに返された場合に通知を送信して、必要に応じてサブシステムに登録または登
録解除できるようにします。
IEntityPoolListener
このリスナーは IEntityPoolManager::AddListener 経由でサブスクライブできます。これに
は、以下のコールバックが含まれています。
OnPoolBookmarkCreated
エンティティプールのブックマークが作成されると呼び出されます。プールされたエンティティ
に予約されたエンティティ ID が、それに属する静的にインスタンス化されたデータとともに渡さ
れます。
OnEntityPreparedFromPool
エンティティ (静的または動的) がプールから準備されると呼び出されます。エンティティ ID と
そのエンティティが現在置かれているエンティティコンテナの両方が与えられます。これは、エ
ンティティの準備プロセスが終了すると呼び出されます。
OnEntityReturnedToPool
エンティティ (静的または動的) がプールに返されると呼び出されます。エンティティ ID とその
エンティティが現在置かれているエンティティコンテナの両方が与えられます。これは、エン
ティティを返すプロセスが開始されると呼び出されます。
OnPoolDefinitionsLoaded
リスナーがプールで操作する独自のリソースをセットアップできるようにする情報とともに、初
期化時に呼び出されます。現在、AI がアタッチされたプール済みエンティティの総数が渡されま
す。
OnBookmarkEntitySerialize
エンティティのブックマークから読み取りおよび書き込み中に呼び出され、リスナーが追加の
データをブックマークに保存できるようにします。
IEntitySystemSink
このリスナーには、エンティティが再ロードされると通知が送信される特殊なコールバック
OnReused があります。これは、エンティティコンテナに静的エンティティが準備されるかエンティ
ティコンテナ内で動的エンティティが作成されるときに、エンティティコンテナで行われるプロセス
です。エンティティとそれに属する静的にインスタンス化されたデータが置かれるエンティティコン
テナが与えられます。
デバッグユーティリティ
エンティティプールを管理したり、ゲームプレイ中にエンティティプールが使用される方法を確認し
たりするためのデバッグユーティリティがいくつか提供されています。
Version 1.6
403
Lumberyard 開発者ガイド
説明されるエンティティ ID
エンティティプールのブックマークのデバッグ
ゲーム中に現在存在しているエンティティプールのすべてのブックマークのステータスを表示するに
は、次のコンソールコマンドを使用します。
es_dump_bookmarks [filterName] [dumpToDisk]
このコマンドにより、リクエストされたすべてのブックマークのコンソールおよびゲームログファイ
ルにテキストが書き込まれます。
引数
filterName
(オプション) 名前に指定した値がサブストリングとして含まれるエンティティのみのブックマー
クを取得するようにリクエストをフィルタリングできます。すべてのブックマークを表示するに
は、この引数を "all" に設定するか、空白のままにします。
dumpToDisk
(オプション) 表示されたブックマークに関連付けられているインスタンス化されたすべての静的
データをディスクに出力できます。この引数が指定されていて、0 以外の数値のファイルである
場合、データは \User\Bookmarks\LevelName\EntityName.xml に格納されます。
表示されるデータ
各ブックマークに対して、次の情報が表示されます。
• ブックマークされたエンティティの名前。
• ブックマークされたエンティティが属するレイヤー。
• ブックマークされたエンティティが使用するエンティティクラス名。
• ブックマークされたエンティティに関連付けられている予約されたエンティティ ID。
• ブックマークされたエンティティに自身に関連付けられている No Save Entity Flag があるかどう
か。
• ブックマークされたエンティティが静的または動的のどちらであるか。
• ブックマークされたエンティティにシリアル化されたデータ (および利用可能な場合は情報のメモリ
フットプリント) が含まれるかどうか。
• ブックマークされたエンティティにインスタンス化された静的データ (および利用可能な場合は情報
のメモリフットプリント) が含まれるかどうか。
説明されるエンティティ ID
動的 C++ オブジェクトを参照する場合、ポインタおよび参照カウントを使用することができますが、
もっと良い方法は、オブジェクトの削除およびすべての参照の無効化ができる弱い参照を使用するこ
とです。このオプションは、すべてのオブジェクトに関して、削除されるオブジェクトの無効化とい
う反復作業を限定的なものとし、パフォーマンスの低下を防ぎます。
各参照によって、Lumberyard は「salt」 (または「magic number」) と呼ばれる数値を保管します。
この数値は、インデックス とともに、ゲームのライフタイムにわたってオブジェクトに一意のエン
ティティ ID を付与します。オブジェクトが廃棄され、インデックスが再利用されるときはいつで
も、salt が増加し、同じインデックスのすべての参照は無効になります。エンティティの位置または
ポインタを取得するには、エンティティマネージャーはエンティティ ID を解決する必要があります
が、salt が異なるためその方法は失敗します。
Version 1.6
404
Lumberyard 開発者ガイド
エンティティに使用可能なサポートの追加
CSaltBufferArray クラスは、オブジェクトの追加および削除を行い、また salt に必要な調整を加
えます。よりキャッシュに負担をかけないメモリアクセスのために、オブジェクト配列をコンパクト
に保ちます。ディスクへの EntityId 参照の保存は可能であり、それは保存したゲームのために使用
され、またエディタゲームエクスポートによって使用される。しかしながら、あるレベルの保存した
ゲームをロードするとき、それがパッチ処理され、より多くのエンティティを有するものとなってい
る場合、それは深刻な競合を発生させることがあります。この問題を解決するために、高インデック
スカウントダウンから始まる動的エンティティが作成され、一方で低インデックスカウントアップか
ら始まる静的エンティティが作成されます。
エンティティ ID には以下の制限があります:
• 16 ビットインデックスは、最大約 65,000 のライブオブジェクトを割り当てます。これは小規模マ
ルチプレイヤーゲームのために十分なものと考えられます。大規模マルチプレイヤーゲームにおい
ては、ここで説明する方法をサーバーで使用してはいけません。ただし、特定のクライアントおよ
びサーバー間では使用することができます。
• 16 ビットの salt 値によって、ゲームは最大約 65,000 回までインデックスを再利用できます。最大
回数まで再利用した場合、それ以上のインデックスの再利用はできなくなります。これは注意して
使用する場合、小規模マルチプレイヤーゲームのために十分なものと考えられます — オブジェクト
(弾丸等) は、あまりにも速く生成および破壊してはいけません。大規模マルチプレイヤーゲーム、
または複数日ゲームセッションをサポートするゲームは、この制限に達する可能性があります。
エンティティに使用可能なサポートの追加
概要
プレイヤーはキープレス（デフォルトで設定で 'F'）を使用してエンティティとインタラクトできま
す。プレーヤーは、インタラクションが可能なエンティティが有効化されたことをゲーム内の特別な
画面上アイコンで通知されます。
この機能を使用するには、二つの関数IsUsable() とOnUsed()を実行するスクリプトを作成する必
要があります。
スクリプトの準備
スクリプトは以下のようになります。
MakeUsable(NewEntity)
function NewEntity:IsUsable(userId)
-- code implementation
return index;
end
function NewEntity:OnUsed(userId, index)
-- code implementation
end
実装使用可能
IsUsable()関数は、プレーヤーがクロスヘアをエンティティに向けている場合に呼び出されます。
関数はエンティティがエイミングを行っているプレーヤーによってインタラクトできるかどうかを決
定します。関数は単一のパラメータのみ、つまりプレーヤーのエンティティIDを受け取ります。
Version 1.6
405
Lumberyard 開発者ガイド
使用中の実行
プレーヤーがエンティティとインタラクトできない場合、関数は0を返す必要があります。この値に
よって、UIによりエンティティに"USE"アイコンが使用されないようにします。
プレイヤーがエンティティとインタラクトすることができる場合、関数は正の値を返す必要がありま
す。この値は保存され、後でOnUsed()関数を呼び出す際に使用されます。
使用中の実行
OnUsed()関数はプレーヤーがエンティティとのインタラクトするためのキーを押したとき（たとえ
ばUSEアイコンがアクティブな時にUseキーを押すなど）に呼び出されます。この関数は二つのパラ
メータを使用します。(1) プレーヤーのエンティティIDと (2) IsUsable()によって返された値。
エンティティのスクリプト化
このセクションには、Lua スクリプトを使用したエンティティシステムの操作に関するトピックが含
まれています。
このセクションでは、次のトピックについて説明します。
• スクリプトエンティティの構造 (p. 406)
• エンティティ状態の使用 (p. 409)
• エンティティスロットの使用 (p. 410)
• エンティティのリンク (p. 411)
• ネットワークへのエンティティの公開 (p. 412)
スクリプトエンティティの構造
Lua を使用して新しいエンティティを実装するには、2 つのファイルを作成し、ゲームディレクトリ
に格納する必要があります。
• Ent ファイルは、Lua スクリプトファイルの場所をエンティティシステムに伝えます。
• Lua スクリプトファイルは目的のプロパティと関数を実装します。
SDK では、.ent と .lua の両方のファイルが <Game_Folder>\Scripts.pak ファイル内に格納さ
れます。
Ent ファイル
Ent ファイルはすべて <Game_Folder>\Entities ディレクトリ内に格納され、ファイル拡張子
.ent を付ける必要があります。コンテンツは次のような XML です。
<Entity
Name="LivingEntity"
Script="Scripts/Entities/Physics/LivingEntity.lua"
/>
Ent ファイルに設定されるエンティティプロパティには次のようなものがあります。
名前
エンティティクラスの名前。
Script
エンティティクラスを実装する Lua スクリプトへのパス。
Version 1.6
406
Lumberyard 開発者ガイド
スクリプトエンティティの構造
Invisible
エンティティクラスを Lumberyard エディタ で表示するかどうかを示すフラグ。
Lua スクリプト
Lua スクリプトは、エンティティクラスを実装するだけでなく、エンティティをレベルで使用すると
きに Lumberyard エディタ によって使用される一連の情報を提供します。Lua スクリプト内に設定さ
れているプロパティ値は、新しいエンティティインスタンスに割り当てられるデフォルト値です。エ
ディタ変数は、Lumberyard エディタ 内でのエンティティの描画方法を指定します。
次のコード例は、Lumberyard ディレクトリ (.../dev/cache/samplesproject/pc/
samplesproject/scripts/entities/physics/livingentity.lua) のサンプルプロジェクト
ファイルから取得したものです。
LivingEntity = {
Properties = {
soclasses_SmartObjectClass = "",
bMissionCritical = 0,
bCanTriggerAreas = 1,
object_Model = "objects/default/primitive_capsule.cgf",
bExcludeCover=0,
Physics = {
bPhysicalize = 1, -- True if object should be physicalized at all.
bPushableByPlayers = 1,
},
MultiplayerOptions = {
bNetworked = 0,
},
},
...
Editor={
Icon = "physicsobject.bmp",
IconOnTop=1,
},
}
この情報に続いて、エンティティクラスを実装する関数について説明します。
プロパティ
エンティティプロパティはエンティティクラス内にあります。これらのプロパティは、作成され
たエンティティクラスのすべての新しいインスタンスに割り当てられ、Lumberyard エディタ で
インスタンスの [Entity Properties] テーブルとして表示および編集できます。あるレベルに置か
れた個々のエンティティインスタンスに設定されたプロパティ値は、そのレベルのファイルに保
存されます。エンティティインスタンスのプロパティが Lumberyard エディタ で変更された場
合、OnPropertyChange() 関数が呼び出されます (スクリプトエンティティに実装されている場
合)。
Lumberyard エディタ は、複数のインスタンスで再利用される共通のプロパティセットを割り当てる
ための Archetype ツールを提供します (複数レベルにまたがる場合も)。Archetypes の詳細情報につい
ては、Lumberyard のユーザーガイドを参照してください。
エンティティクラスのプロパティ名を指定する場合、次のプレフィックスを使用して、プロパティ値
に対して予想されるデータタイプを示します。これにより、設定時に Lumberyard エディタ でプロパ
ティ値を検証することができます。
Version 1.6
407
Lumberyard 開発者ガイド
スクリプトエンティティの構造
エンティティクラスプロパティのプレフィックス
プレフィックス
データ型
b
boolean
f
float
i
integer
s
文字列
clr
色
オブジェクト_
Lumberyard と互換性があるオブジェクト (CFG、CGA、CHR または CDF
ファイル)。
エンジンが利用できるプロパティ値に対して、特別なコメントを追加できます。以下に例を示しま
す。
--[25,100,0.1,"Damage threshold"]
このコメントによって、エンジンに次のことが伝えられます。
• 値は 25～100 に制限されている。
• 浮動小数点値は 0.01 のステップを使用する (値の忠実度を制限します)。
• 「Damage threshold」という文字列が、ツールヒントとして Lumberyard エディタ に表示される。
エディタテーブル
エディタテーブルは、エンティティのインスタンスの処理方法について、追加設定情報を Lumberyard
エディタ に提供します。
エンティティクラスのエディタ変数
可変
説明
Model
エンティティインスタンスでレンダリングされる CGF モデル。
ShowBounds
選択時に境界ボックスをエンティティインスタンスの周りに描画するかど
うかを示すフラグ。
AbsoluteRadius
アイコン
エンティティインスタンス上に描画される BMP アイコン。
IconOnTop
エンティティインスタンスの上または下にアイコンを描画するかどうかを
示すフラグ。
DisplayArrow
リンク
関数
スクリプトエンティティには、エンジンまたはゲームシステムによって呼び出される複数のコール
バック関数を含めることができます。詳細については、「エンティティシステムスクリプトのコール
バック (p. 184)」を参照してください。
Version 1.6
408
Lumberyard 開発者ガイド
エンティティ状態の使用
エンティティ状態の使用
エンティティシステムでは、スクリプトエンティティ用のシンプルな状態切り替えメカニズムが提供
されます。
各状態には次が含まれます。
• 名前 (文字列)
• 状態の名前で識別される、エンティティテーブル内の Lua テーブル
• OnEndState() 関数 (オプション)
• OnBeginState() 関数 (オプション)
• 追加のコールバック関数 (オプション) (「エンティティシステムスクリプトのコールバッ
ク (p. 184)」を参照)
エンティティの状態を宣言するには:
すべてのエンティティの状態は、Entity システムで認識されるように、エンティティのメインテーブ
ルで宣言する必要があります。次の例は、"Opened"、"Closed"、および "Destroyed" 状態を宣言する
方法を示しています。
AdvancedDoor =
{
Client = {},
Server = {},
PropertiesInstance = ...
Properties = ...
States = {"Opened","Closed","Destroyed"},
}
エンティティの状態を定義するには:
エンティティの状態は、サーバーまたはクライアント (またはその両方) の状態とすることができま
す。サーバー側の "Opened" 状態の定義の例を次に示します。
AdvancedDoor.Server.Opened =
{
OnBeginState = function( self )
if(self.Properties.bUsePortal==1)then
System.ActivatePortal(self:GetWorldPos(),1,self.id);
end;
self.bUpdate=1;
self.lasttime=0;
AI.ModifySmartObjectStates( self.id, "Open-Closed" );
self:Play(1);
end,
OnUpdate = function(self, dt)
self:OnUpdate();
end,
}
エンティティの初期状態を設定するには:
最初は、エンティティの状態はありません。エンティティの状態を設定するには、次の例に示されて
いるように、エンティティのコールバック関数の 1 つを使用して (エンティティ状態のコールバック
Version 1.6
409
Lumberyard 開発者ガイド
エンティティスロットの使用
関数と混同しないようにしてください)、その GotoState() メソッドを呼び出します。エンティティ
の状態を設定すると、エンティティはその状態になり、イベントもその状態に移行します。
function AdvancedDoor:OnReset()
self:GotoState("Opened");
end
エンティティの状態を変更するには:
現在の状態からのその他の状態への移行は、次に示すように GotoState() メソッドを使用して行う
こともできます。
function AdvancedDoor.Server:OnHit(hit)
...
if(self:IsDead())then
self:GotoState("Destroyed");
end
end
エンティティの状態を問い合わせるには:
エンティティの現在の状態のクエリは、次に示すように GetState () メソッドを使用して行うことがで
きます。
if (self:GetState()=="Opened") then ...
if (self:GetState()~="Opened") then ...
エンティティスロットの使用
各エンティティには、Lumberyard で使用できるさまざまなリソースを保持するために使用されるス
ロットを含めることができます。このトピックでは、エンティティスロットの操作方法について説明
します。
スロットの割り当て
次の表で、スロットに割り当てることができるリソースと、割り当てに使用される ScriptBind 関数の
一覧を示します。
Lumberyard リソース
機能
静的ジオメトリ
LoadObject() または LoadSubObject()
アニメーションする
キャラクター
LoadCharacter()
パーティクルエミッタ
LoadParticleEffect()
ライト　LoadLight()
cloud
LoadCloud()
fog
LoadFogVolume()
ボリューム
LoadVolumeObject()
Version 1.6
410
Lumberyard 開発者ガイド
エンティティのリンク
スロットパラメータの変更
これらのリソースのそれぞれは、エンティティ自体に対して相対的に移動、回転、またはスケーリン
グすることができます。
• SetSlotPos()
• GetSlotPos()
• SetSlotAngles()
• GetSlotAngles()
• SetSlotScale()
• GetSlotScale()
スロット間に親リンクを追加して、関連する位置を持たせることができます。
• SetParentSlot()
• GetParentSlot()
スロット管理
指定されたスロットが割り当てられているかどうかを確認するには、関数 !IsSlotValid() を呼び
出します。
1 つのスロットを解放するには、!FreeSlot() を呼び出します。
エンティティ内に割り当てられているすべてのスロットを解放するには、!FreeAllSlots() を呼び
出します。
スロットのロード
以下の例は、スクリプト関数でのスロットのロードを示しています。
local pos={x=0,y=0,z=0};
self:LoadObject(0,props.fileModel);
self:SetSlotPos(0,pos);
self:SetCurrentSlot(0);
エンティティのリンク
Lumberyard エディタでは、エンティティと他のエンティティをリンクすることができます。これらの
リンクはエンティティシステム内で整理されます。各エンティティは複数のエンティティにリンクで
きます。各リンクには名前が関連付けられています。 オブジェクトをグループ化、リンクすることに
関する詳細は Amazon Lumberyard User Guide を参照してください。
以下の例ではLuaスクリプトが「ジェネレーター」という名前が付けられた他のエンティティにリン
クしているかをエンティティシステムで検索します。
function RadarBase:IsPowered()
local i=0;
local link = self:GetLinkTarget("Generator", i);
while (link) do
Log("Generator %s", link:GetName());
if (link:GetState() == "PowerOn") then
Version 1.6
411
Lumberyard 開発者ガイド
ネットワークへのエンティティの公開
if (link.PowerConnect) then
link:PowerConnect(self.id);
return true;
end
end
i=i+1;
link=self:GetLinkTarget("Generator", i);
end
return false;
end
以下の機能はエンティティリンクの参照、または作成の際に使用されます:
• CountLinks
• CreateLink
• GetLink
• GetLinkName
• GetLinkTarget
• RemoveAllLinks
• RemoveLink
• SetLinkTarget
ネットワークへのエンティティの公開
スクリプトエンティティは、シリアル化された値としてネットワーク上でやり取りすることができま
す。このアプローチを使用するには、サーバーで値を設定し、それらの値がすべてのクライアントで
自動的に同期されるようにします。これにより、クライアント/サーバー型の RMI 関数を呼び出すこ
とも可能になります。
次の制限に注意が必要です。
• シリアル化された値が変更されたことを示す通知はありません。
• 値はサーバーでのみ制御され、クライアントで値を設定する方法はありません。
CryNetwork へのスクリプトエンティティの公開
エンティティのネットワーク機能を定義するには、次のコードに示すように、ScriptBind 関数の
Net.Expose() を呼び出します。このコードは、関数内ではなく、グローバル領域の Lua スクリプト
内に記述します。
Net.Expose {
Class = DeathMatch,
ClientMethods = {
ClVictory
ClNoWinner
ClClientConnect
ClClientDisconnect
ClClientEnteredGame
},
ServerMethods = {
RequestRevive
= { RELIABLE_ORDERED, POST_ATTACH, ENTITYID, },
= { RELIABLE_ORDERED, POST_ATTACH, },
= { RELIABLE_UNORDERED, POST_ATTACH, STRING, BOOL },
= { RELIABLE_UNORDERED, POST_ATTACH, STRING, },
= { RELIABLE_UNORDERED, POST_ATTACH, STRING, },
= { RELIABLE_UNORDERED, POST_ATTACH, ENTITYID, },
Version 1.6
412
Lumberyard 開発者ガイド
ネットワークへのエンティティの公開
RequestSpectatorTarget = { RELIABLE_UNORDERED, POST_ATTACH, ENTITYID,
INT8 },
},
ServerProperties = {
busy = BOOL,
},
};
RMI 関数
RMI 関数は、Net.Expose() 関数に渡される ClientMethods テーブルと ServerMethods テーブルで
定義されます。
順序フラグ:
• UNRELIABLE_ORDERED
• RELIABLE_ORDERED
• RELIABLE_UNORDERED
次の記述子は、データのシリアル化において RMI がどのようにスケジュールされるかを制御するもの
です。
RMI アタッチフラグ
説明
NO_ATTACH
特別な制御なし (推奨)
PRE_ATTACH
データのシリアル化前に呼び出しを実行
POST_ATTACH
データのシリアル化後に呼び出しを実行
以下は、関数宣言の例を示しています。
function DeathMatch.Client:ClClientConnect(name, reconnect)
以下は、関数呼び出しの例を示しています。
self.allClients:ClVictory( winningPlayerId );
self.otherClients:ClClientConnect( channelId, player:GetName(), reconnect );
self.onClient:ClClientConnect( channelId, player:GetName(), reconnect );
詳細については、RMI 関数 (p. 518) をご覧ください。
Note
注意: スクリプトネットワークには、依存オブジェクトの RMI に相当するものはありません。
ServerProperties テーブル
エンティティテーブルには、同期する必要のあるプロパティを示す ServerProperties テーブルも含ま
れています。これは、変数の型と値を定義する場所でもあります。
Version 1.6
413
Lumberyard 開発者ガイド
ネットワークへのエンティティの公開
スクリプトエンティティの CryAction への公開
さらに、CryAction でゲームオブジェクトを作成し、新しいゲームオブジェクトをネットワークゲーム
セッションにバインドする必要があります。次の例は、OnSpawn() 関数内に追加するコードを示して
います。
CryAction.CreateGameObjectForEntity(self.id);
CryAction.BindGameObjectToNetwork(self.id);
また、次のように CryAction の関数呼び出しを行うと、ゲームオブジェクトでフレームごとの更新
コールバックを受け取ることができます。
CryAction.ForceGameObjectUpdate(self.id, true);
スクリプトエンティティは、Server テーブルの OnUpdate() 関数コールバックを受け取ります。
function Door.Server:OnUpdate(frameTime)
-- some code
end
Note
スクリプトエンティティに更新コールバックのコードを追加すると、ゲームのパフォーマン
スが低下する可能性があります。
Version 1.6
414
Lumberyard 開発者ガイド
バスの構成
イベントバス（EBus）
イベントバス（略称 EBus）は、メッセージをディスパッチするための汎用システムです。Ebus には
次のような数多くのメリットがあります。
• 抽象化 – システム間のハードの依存関係を最小限にします。
• イベント駆動型プログラミング – ポーリングパターンを不要にすることで、ソフトウェアの拡張性
とパフォーマンスを向上します。
• よりクリーンなアプリケーションコード – メッセージが何によって処理されているか、メッセージ
が確実に処理されているかを心配せずに、メッセージを安全にディスパッチできます。
• 同時実行 – さまざまなスレッドからのイベントをキューに追加し、別のスレッドや分散システムア
プリケーション上で安全に実行できます。
• 予測可能性 – 特定のバス上でのハンドラーの順序付けをサポートします。
• デバッグ – 報告、プロファイリング、詳細分析の目的でメッセージをインターセプトします。
EBus のソースコードは Lumberyard ディレクトリの場所（<root>\dev\Code\Framework\AZCore
\AZCore\EBus\EBus.h）にあります。
バスの構成
EBus は、さまざまな利用パターンで構成できます。このセクションでは、一般的な構成とその利用
方法について説明します。
トピック
• 単一ハンドラー (p. 415)
• 複数ハンドラー (p. 416)
• 複数アドレスと単一ハンドラーの Ebus (p. 417)
• 複数アドレスと複数ハンドラーの Ebus (p. 419)
単一ハンドラー
最もシンプルな構成は、シングルトンパターンに非常によく似た、多対 1（または 0）のコミュニ
ケーションバスです。
Version 1.6
415
Lumberyard 開発者ガイド
複数ハンドラー
ハンドラーは最大 1 つで、あらゆる送信元がイベントをディスパッチできます。送信元は、ポイン
ターの確認と間接参照を手動で行う必要はありません。バスに接続しているハンドラーがない場合、
イベントは単に無視されるだけです。
// One handler is supported.
static const AZ::EBusHandlerPolicy HandlerPolicy =
AZ::EBusHandlerPolicy::Single;
// The EBus uses a single address.
static const AZ::EBusAddressPolicy AddressPolicy =
AZ::EBusAddressPolicy::Single;
複数ハンドラー
もう 1 つの一般的な構成は、多くのハンドラーが存在できる構成です。この構成を使用することで、
オブザーバーパターン、システムイベントへのサブスクリプション、汎用のブロードキャストを実装
することができます。
ハンドラーへのイベントを受信する順序は定義できますが、未定義でもかまいません。どちらにする
かは HandlerPolicy トレイトで指定できます。
ハンドラーの順序がない例
特定の順序を設定せずにイベントを処理するには、次のように HandlerPolicy トレイトで
Multiple キーワードを使用します。
// Multiple handlers. Events received in undefined order.
static const AZ::EBusHandlerPolicy HandlerPolicy =
AZ::EBusHandlerPolicy::Multiple;
// The EBus uses a single address.
static const AZ::EBusAddressPolicy AddressPolicy =
AZ::EBusAddressPolicy::Single;
Version 1.6
416
Lumberyard 開発者ガイド
複数アドレスと単一ハンドラーの Ebus
ハンドラーの順序がある例
特定の順序でイベントを処理するには、HandlerPolicy トレイトで MultipleAndOrdered キー
ワードを使用した後、カスタムのハンドラー順序付け関数を実装します。
// Multiple handlers. Events received in defined order.
static const AZ::EBusHandlerPolicy HandlerPolicy =
AZ::EBusHandlerPolicy::MultipleAndOrdered;
// The EBus uses a single address.
static const AZ::EBusAddressPolicy AddressPolicy =
AZ::EBusAddressPolicy::Single;
// Implement a custom handler-ordering function
struct BusHandlerOrderCompare : public
AZStd::binary_function<MyBusInterface*, MyBusInterface*, bool>
{
AZ_FORCE_INLINE bool operator()(const MyBusInterface* left, const
MyBusInterface* right) const { return left->GetOrder() < right->GetOrder();
}
};
複数アドレスと単一ハンドラーの Ebus
EBus は、カスタム ID に基づくアドレス指定もサポートしています。特定の ID にアドレス指定され
たイベントは、その ID に接続されるハンドラーによって受信されます。イベントが、ID を持たない
ブロードキャストの場合、すべてのアドレスのハンドラーがそのイベントを受信します。
一般的このアプローチは、単一エンティティのコンポーネント間のコミュニケーションや、独立して
いるが関連性があるエンティティのコンポーネント間のコミュニケーションに使用されます。この場
合、エンティティ ID がアドレスとなります。
Version 1.6
417
Lumberyard 開発者ガイド
複数アドレスと単一ハンドラーの Ebus
アドレスの順序がない例
次の例では、ID なしでメッセージがブロードキャストされ、特定の順序なしで各アドレスに着信しま
す。
// One handler per address is supported.
static const AZ::EBusHandlerPolicy HandlerPolicy =
AZ::EBusHandlerPolicy::Single;
// The EBus has multiple addresses. Addresses are not ordered.
static const AZ::EBusAddressPolicy AddressPolicy =
AZ::EBusAddressPolicy::ById;
// Messages are addressed by EntityId.
using BusIdType = AZ::EntityId;
アドレスの順序がある例
次の例では、ID ありでメッセージがブロードキャストされ、特定の順序で各アドレスに着信します。
// One handler per address is supported.
static const AZ::EBusHandlerPolicy HandlerPolicy =
AZ::EBusHandlerPolicy::Single;
// The EBus has multiple addresses. Addresses are ordered.
Version 1.6
418
Lumberyard 開発者ガイド
複数アドレスと複数ハンドラーの Ebus
static const AZ::EBusAddressPolicy AddressPolicy =
AZ::EBusAddressPolicy::ByIdAndOrdered;
// Messages are addressed by EntityId.
using BusIdType = AZ::EntityId;
// Addresses are ordered by EntityId.
using BusIdOrderCompare = AZStd::greater<BusIdType>;
複数アドレスと複数ハンドラーの Ebus
前述の構成では、アドレスごとに許可されるハンドラーは 1 つだけでした。これは、上記のシングル
トンの例のように、特定の ID の所有権を EBus に適用する場合に推奨されます。ただし、アドレスご
とに複数のハンドラーが必要な場合は、それに合わせて EBus を構成することができます。
例: アドレスの順序なし
次の例では、ID ありでメッセージがブロードキャストされ、特定の順序なしで各アドレスに着信しま
す。各アドレスでハンドラーがメッセージを受信する順序は EBusHandlerPolicy によって定義され
ます。この例ではシンプルに ById と表記されています。
// Allow any number of handlers per address.
static const AZ::EBusHandlerPolicy HandlerPolicy =
AZ::EBusHandlerPolicy::Multiple;
Version 1.6
419
Lumberyard 開発者ガイド
同期と非同期
// The EBus has multiple addresses. Addresses are not ordered.
static const AZ::EBusAddressPolicy AddressPolicy =
AZ::EBusAddressPolicy::ById;
// Messages are addressed by EntityId.
using BusIdType = AZ::EntityId;
例: アドレスの順序あり
次の例では、ID ありでメッセージがブロードキャストされ、特定の順序で各アドレスに着信します。
各アドレスでハンドラーがメッセージを受信する順序は EBusHandlerPolicy によって定義されま
す。この例ではシンプルに ByIdAndOrdered と表記されています。
// Allow any number of handlers per address.
static const AZ::EBusHandlerPolicy HandlerPolicy =
AZ::EBusHandlerPolicy::Multiple;
// The EBus has multiple addresses. Addresses are ordered.
static const AZ::EBusAddressPolicy AddressPolicy =
AZ::EBusAddressPolicy::ByIdAndOrdered;
// We address the bus EntityId.
using BusIdType = AZ::EntityId;
// Addresses are ordered by EntityId.
using BusIdOrderCompare = AZStd::greater<BusIdType>;
同期と非同期
EBus は、同期メッセージングと非同期（キューを使用する）メッセージングの両方をサポートして
います。
同期メッセージング
EBus イベントが呼び出されると、すべてのハンドラーに非同期メッセージが送信されます。非同期
メッセージでは、非同期プログラミングの機会が制限されますが、次のようなメリットがあります。
• クロージャの格納が要求されない。引数が呼び出し元に直接転送されます。
• ハンドラーから結果（イベントの戻り値）をすぐに取得できる。
• レイテンシーがない。
非同期メッセージング
非同期メッセージングには次のようなメリットがあります。
• 並列処理の機会が数多く提供され、将来にも十分に対応できる。
• すべてのスレッドからのメッセージをキューに追加でき、安全なスレッド（メインスレッドまたは
選択した任意のスレッドなど）でディスパッチできる。
• 記述に使用されるコードには、その性質上レイテンシーに対する耐性があり、アクターモデルやそ
の他の分散プラットフォームにも簡単に移行できる。
• イベントを起動するコードのパフォーマンスが、イベントを処理するコードの効率性に依存しな
い。
Version 1.6
420
Lumberyard 開発者ガイド
その他の機能
• 必要な仮想関数呼び出しの数が少ないため、パフォーマンスが非常に重視されるコードにおいて、iキャッシュと d-キャッシュのパフォーマンスを向上できる。
メッセージのキュー追加と送信を非同期で実行する EBus の宣言の詳細については、このトピックで
後述する「非同期/キューを使用する EBus (p. 425)」を参照してください。
その他の機能
EBus には、その他にもさまざまなパターンと用途に対応した機能があります。
• メッセージのディスパッチ先となるポインターをキャッシュする – ID を使用する EBus の場合に便
利です。各イベントの ID で EBus アドレスを検索する代わりに、キャッシュされたポインターを使
うことでディスパッチを高速化できます。
• 呼び出し可能なすべての関数を EBus でキューに追加する – キューを使用するメッセージングを使
う場合、EBus に対する lambda 関数または bound 関数をキューに追加して別のスレッドで実行す
ることができます。これは、汎用のスレッドセーフなキューの場合に便利です。
使用方法と例
このセクションでは、EBus の宣言方法と構成方法、ハンドラーの実装方法、メッセージの送信方
法、さらに戻り値を受信する方法について説明します。
トピック
• EBus の宣言 (p. 421)
• EBus の構成オプション (p. 422)
• ハンドラーの実装 (p. 423)
• EBus へのメッセージ送信 (p. 424)
• 戻り値の取得 (p. 424)
• 複数ハンドラーからの戻り値 (p. 424)
• 非同期/キューを使用する EBus (p. 425)
EBus の宣言
Ebus の宣言は、C++ の仮想インターフェイスクラスの宣言と非常によく似ています。さらに Ebus の
場合、さまざまな構成オプションを指定して、コンパイル時の EBus の生成方法や EBus の動作を制
御することができます。
基本的なインターフェイスおよび関連する EBus の簡単な例を以下に示します。
class ExampleInterface : public AZ::EBusTraits
{
public:
// ------------------ EBus Configuration ------------------// These override the defaults in EBusTraits.
// One handler per address is supported.
static const AZ::EBusHandlerPolicy HandlerPolicy =
AZ::EBusHandlerPolicy::Single;
// The EBus contains a single address.
Version 1.6
421
Lumberyard 開発者ガイド
EBus の構成オプション
static const AZ::EBusAddressPolicy AddressPolicy =
AZ::EBusAddressPolicy::Single;
// ------------------------ Other ------------------------~ExampleInterface() override { };
// ------------------ Handler Interface ------------------// Handlers inherit from ExampleInterfaceBus::Handler
// Handlers are required to implement this because it's pure virtual.
virtual void DoSomething() = 0;
// Handlers can override this, but are not required to.
virtual void SomeMessage() { }
// Returns a value and has a parameter.
virtual bool ReturnedValue(int x) = 0;
};
using ExampleInterfaceBus = AZ::EBus<ExampleInterface>;
EBus の構成オプション
EBus の動作を制御する鍵となるのが EBus の構成オプションです。以降のセクションでは、上記の例
で使用した構成オプションについて説明します。
HandlerPolicy
HandlerPolicy トレイトは、EBus のアドレスに接続するハンドラーの数と、各アドレスでハンド
ラーがイベントを受信する順序を決定します。次の例では、単一ハンドラー (p. 415)を指定していま
す。
// One handler per address is supported.
static const AZ::EBusHandlerPolicy HandlerPolicy =
AZ::EBusHandlerPolicy::Single;
通常 HandlerPolicy は次の 2 つの目的に使うことができます。
• コードベースの別の場所にある単一システムに対して、さまざまなシステムがメッセージまたはリ
クエストを投稿する、シングルトンパターン。
• EBus に対するメッセージを特定のコンポーネントまたはエンティティが処理するパターン。たと
えば、1 つのエンティティを持つメッシュコンポーネントがある場合、このメッシュコンポーネン
トが、このエンティティの ID にアドレス指定されたメッシュの関連クエリをすべて処理します。
AddressPolicy
AddressPolicy トレイトは、EBus に存在するアドレスの数を定義します。次の例ではアドレスを 1
つだけ指定しています。ID は必要ありません。
// The EBus contains a single address.
static const AZ::EBusAddressPolicy AddressPolicy =
AZ::EBusAddressPolicy::Single;
単一アドレスポリシーの一般的な用途は、コードベースの別の場所にある単一システムに対して、さ
まざまなシステムがメッセージまたはリクエストを投稿するシングルトンパターンです。
Version 1.6
422
Lumberyard 開発者ガイド
ハンドラーの実装
EBusAddressPolicy のオプション
EBusAddressPolicy には次のオプションがあります。
• Single – EBus が単一のアドレスを使用します。ID は使用されません。EBus は単一ハンド
ラー (p. 415)または複数ハンドラー (p. 416)を使用できます。
• ById – EBus が複数のアドレスを使用します。ID なしでイベントをブロードキャストする場合のア
ドレスの通知順序は指定されません。
• ByIdAndOrdered – EBus が複数のアドレスを使用します。ただし、ID なしでイベント
をブロードキャストする場合、個々のアドレスが通知される順序を制御する必要がありま
す。BusIdOrderCompare の定義によって順序を任意にカスタマイズできます。
EBusHandlerPolicy のオプション
EBusHandlerPolicy には次のオプションがあります。
• Single – アドレスあたり 1 つのハンドラーがサポートされます。単一ハンドラー (p. 415)の
EBus または複数アドレスと単一ハンドラーの Ebus (p. 417) に使用できます。
• Multiple – 任意の数のアドレスがサポートされます。順序は無視されます。複数ハンド
ラー (p. 416)または 複数アドレスと複数ハンドラーの Ebus (p. 419) に使用できます。
• MultipleAndOrdered – 任意の数のアドレスがサポートされ、特定の順序でハンドラーに通知され
ます。BusHandlerOrderCompare の定義によって順序を任意にカスタマイズできます。
ハンドラーの実装
EBus のハンドラーは AZ::EBus<x>::Handler から派生します。上記の例 (p. 421)では、
利便性を考慮して ExampleInterfaceBus として定義されています。これは、ハンドラーが
ExampleInterfaceBus::Handler から派生できることを意味しています。
#include "ExampleInterface.h"
// note: derives from bus handler, rather than directly from ExampleInterface
class MyHandler : protected ExampleInterfaceBus::Handler
{
public:
void Activate();
protected:
// Implement the handler interface:
void DoSomething() override; // note:
void SomeMessage() override;
bool ReturnedValue(int x) override;
};
Override specified.
ハンドラーは EBus に自動的に接続しないものの、Handler のデストラクタが BusDisconnect を呼
び出すため、切断は自動的に実行される点に注意してください。
実際に EBus に接続しイベントの受信を開始するには、ハンドラーが BusConnect() を呼び出す必要
があります。
void MyHandler::Activate()
{
// For a single EBus, this would be just BusConnect().
// For multiple EBuses, you must specify the EBus to connect to:
Version 1.6
423
Lumberyard 開発者ガイド
EBus へのメッセージ送信
ExampleInterfaceBus::Handler::BusConnect();
}
BusConnect() は、いつでも、どのスレッドからでも呼び出すことができます。
EBus がアドレス指定されている場合、EBus ID を BusConnect() に渡すことによって EBus に接続
します。すべてのアドレスでリッスンするには、ID を渡さずに BusConnect() を呼び出します。
// connect to the EBus at address 5.
ExampleAddressBus::Handler::BusConnect(5);
EBus へのメッセージ送信
ヘッダーを追加することができれば、誰でもいつでも EBus にメッセージを送信できます。前述の例
を使って、まったく関係のないクラスから DoSomething 呼び出しを EBus に発行します。
#include "ExampleInterface.h"
// note: We don't need to include MyHandler.h
...
...
EBUS_EVENT(ExampleInterfaceBus, DoSomething);
// calls the EBus without reading the result, packs 5 as the first parameter.
EBUS_EVENT(ExampleInterfaceBus, ReturnedValue, 5);
EBus がアドレス指定されている場合、特定のアドレス ID にイベントを送信できます。グローバルに
ブロードキャストされるイベントはすべてのアドレスで受信されます。
// broadcasts to ALL HANDLERS on the EBus regardless of address, even if the
EBus has addresses
EBUS_EVENT(ExampleAddressBus, Test);
// broadcasts only to handlers connected to address 5.
EBUS_EVENT_ID(5, ExampleAddressBus, Test)
戻り値の取得
同期呼び出し（EBUS_EVENT）を実行する場合、結果を配置するための変数を提供することもできま
す。
// ALWAYS INITIALIZE YOUR RESULT!!!
// Since there may be nobody connected to the EBus, your result may not be
populated.
bool result = false;
EBUS_EVENT_RESULT(result, ExampleInterfaceBus, ReturnedValue, 2);
この例では、EBus に接続されているハンドラーが存在しない場合、result 変数は変更されま
せん。1 つ以上のハンドラーが EBus に接続されている場合、各ハンドラーの result 変数で
operator=() が呼び出されます。
複数ハンドラーからの戻り値
ハンドラーが複数ある場合、関数の戻り値を集計することが必要になる場合があります。たとえば、
いずれか 1 つのハンドラーオブジェクトがアプリケーションをシャットダウンするどうかを確認する
Version 1.6
424
Lumberyard 開発者ガイド
非同期/キューを使用する EBus
メッセージを、すべてのハンドラーに送信する場合などです。true を返すハンドラーが 1 つでもあれ
ば、シャットダウンを中止する必要があります。このとき、次の記述では不十分です。
// Counterexample: returnValue contains only the result of the final handler.
bool returnValue = false;
EBUS_EVENT_RESULT(returnValue, SomeInterface::Bus, DoesAnyoneObject);
EBus は operator= を各ハンドラーに送信しているため、returnValue には最後のハンドラーの結
果しか格納されません。
これの代わりに、結果を収集し operator= をオーバーライドするクラスを作成することができま
す。そのための組み込みの型がいくつか用意されていますが、次のように独自に作成することができ
ます。
#include <AZCore/EBus/Results.h>
...
AZ::EBusAggregateResults<bool> results;
EBUS_EVENT_RESULT(results, SomeInterfaceBus, DoesAnyoneObject);
// results now contains a vector of all results from all handlers.
// alternative:
AZ::EBusLogicalResult<bool, AZStd::logical_or<bool> > response(false);
EBUS_EVENT_RESULT(response, SomeInterfaceBus, DoesAnyoneObject);
// response now contains each result, using logical OR operation. So all
responses are OR'd with each other.
Note
追加の構成要素（演算結果など）は、results.h の内部で利用できます。
非同期/キューを使用する EBus
イベントをキューに追加でき、非同期で送信できる EBus を宣言するには、次の記述を EBus 宣言に
追加します。
static const bool EnableEventQueue = true;
EBUS_QUEUE_EVENT およびそのバリエーションを使って EBus でイベントをキューに追加すること
で、場所やスレッドを制御し、そこからイベントをフラッシュできるようになります。
適切な場所またはスレッドでキューをフラッシュするには、次を呼び出します。
ExampleInterfaceBus::ExecuteQueuedEvents();
Version 1.6
425
Lumberyard 開発者ガイド
CryPakファイルアーカイブ
ファイルへのアクセス
このセクションではゲームファイルにアクセスし、追跡することが可能なツールについて説明しま
す。
このセクションでは、次のトピックについて説明します。
• CryPakファイルアーカイブ (p. 426)
• ファイルのアクセスをトラックする (p. 435)
CryPakファイルアーカイブ
CryPakモジュールを利用することによって、ゲームの内容ファイルを圧縮または非圧縮アーカイブで
保存することができます。
特徴
• スタンダードzip形式と互換性があります。
• アーカイブまたはスタンダードファイルシステムでのファイル保存をサポートします。
• IStreamCallback（最大値4GBオフセット、4GBファイル)を介して、同期および非同期すること
でデータを読み取ることができます。
• ファイルが圧縮または非圧縮形式で保存できます。
• 非圧縮ファイルは、必要に応じて部分的な読み取りができます。
• ファイル名比較は大文字・小文字の区別には対応していません。
• .zipまたは.pakファイルののロードを4GBサイズまでサポートします。
ユニコードおよび絶対パスの処理
内部的には、すべてのパス処理はASCIIコードベースで行われます。そのため、いかなるユニコード
(異なる言語の16ビット文字)組み込み関数も使用できません。— これは、メモリ保存および簡潔性を
目的としています。ゲームはASCIIのパス名として開発でき、かつ開発されるべきなので、ユニコード
は実質上必要ありません。これらの条件に沿わないゲーム制作は、多言語との統合性に問題がありま
す。たとえば、ユーザーユニコード文字を使用してディレクトリにゲームをインストールすることに
よって、絶対パス名がエンジン全体を通して明示的に回避されます。
Version 1.6
426
Lumberyard 開発者ガイド
レイヤリング
レイヤリング
通常、ゲームの内容データはゲームのディレクトリに入っている複数の.pakファイルで構成さ
れます。ファイルを開始オペレーションリクエストすると、CryPakシステムは登録されたすべて
の.pakファイルをループします。.pakファイルは作成日時順で検索されます。これはパッチ作成
後に追加される.pakファイルが希望場所に位置するよう許可します。.pakを、ファイルシステム
（.pakファイルではない)に直接保存されたルーズファイルと混合することも可能です。ファイル
が.pakアーカイブ内にルーズファイルとして存在している場合は、ゲームがdevモードにあるとき
ルーズファイルのほうが優先されます。ただし、出荷型ゲーム内でのチートを防ぐために、ゲームが
devモードで実行されていない時は.pakに保存されているファイルの方がルーズファイルよりも優先
されます。
スラッシュ
通常は、フォワードスラッシュ (/)は内部処理に使用されますが、ユーザーがバックスラッシュを含む
パスを入力することも可能です。
特別なフォルダの処理
パスエイリアス%USER%を使用して、ユーザーフォルダに関連したパスを指定することができます。
これはユーザー専用データを保存するのに必要な場合があります。Windowsでは、ユーザーがファイ
ルを保存できる場所に制限があることがあります。たとえば、プログラムフォルダに全く書き込みが
できない場合もあります。このため、スクリーンショット、ゲームデータおよびその他のファイルは
ユーザーフォルダに保存する必要があります。以下は有効なファイル名とパスの例です:
%USER%/ProfilesSingle/Lisa.dat
game/Fred.dat
内部
• ひとつのディレクトリごとに約1000個以上のファイルを使用することで問題が発生する、既知の実
装欠陥はあります。
• 形式プロパティ:
• .zipファイル形式は非圧縮テキスト形式にパスとファイル名を含める小ヘッダーを使用して各
ファイルを保存します。ファイルにより早くアクセスできるよう、ディレクトリはファイルの最
後に表示されています。ディレクトリは、非圧縮テキスト形式でパスとファイル名を保存します
(説明済み)。
7-Zipを使用したpakファイルの作成
.pakファイルを7-Zipの7za.exeコマンドラインツールを使用して作成するには、以下のシンタック
スに従ってください。
7za a -tzip -r -mx0 PakFileName [file1 file2 file3 ...] [dir1 dir2 ...]
大きなPakファイルの処理
zip RFCは二つの.zipファイル（.zip形式バージョンによって示される）を指定します。古
い.zipファイルは4GBオフセットを持っていることがありますが、もしレガシーI/O機能を使用する
場合は、 実用的な制限となる +- 2GBを要求することが可能です。4GBオフセットはネイティブマシ
ン型とは無関係であり、プラットフォームとコンパイラーを介することでサイズ変更も設定変更もさ
れません。.zipファイルの古いバージョンのオフセットはマシン独立型uint32です。.zipファイ
Version 1.6
427
Lumberyard 開発者ガイド
CryPakを使用してファイルにアクセスする
ルの新しいバージョンのオフセットはuint64内にあり、古いバージョンstructに付加されていま
す。.zipファイルが使用するバージョンは.zipファイルのヘッダーから入手できます。新しいバー
ジョンをサポートしないアプリケーションは無料です。詳細については、.ZIPファイル形式の指定を
参照してください。
手動分割は、RCが自動分割をサポートしているため、必要ありません。
• zip_sizesplit – 設定、またはサポートされる最大圧縮サイズに達したら、.zipファイルは自動
的に分割します。デフォルト制限は2GBです。
• zip_maxsize – .zipファイルのKB表示の最大圧縮サイズ (これは明示的な制限がされています)。
すべてのケースの作業を分割し、複数のスレッドおよび差分更新をサポートします。必要なzipパート
のチェーンを自動的に拡張および縮小します。ソートは、増分変更が発生した場合でも可能な限り優
先されますが、個別のファイルはソート順序に反していたとしても、余りのスペースを埋めるために
パーツの末尾に付けることができます。
ZIPファイルについて詳しくは、フィル・カッツのZIPファイル形式リファレンスを参照してくださ
い。
CryPakを使用してファイルにアクセスする
このチュートリアルでは、CryPakを通してファイルの読み込みと記入がどのように機能するかを学び
ます。このチュートリアルで、プロジェクトに新しいファイルを追加する方法、パックアーカイブと
ファイルシステムからファイルを読み取る方法、そしてファイルシステム内でファイルに記入する方
法を学びます。
トピック
• 準備 (p. 428)
• CryPakのあるファイルの読み込み (p. 429)
• CryPakのファイルシステムファイルへの書き込み (p. 432)
• CryArchiveでPakを変更する (p. 433)
• CryPakの詳細 (p. 434)
準備
このチュートリアルでは、ファイルをロードする二つの方法を示します。ファイルシステムから直
接ロードする方法と.pakアーカイブ内からロードする方法です。開始する前に.pakアーカイブ内の
ファイルおよびファイルシステム内にある同じ名前のファイル (ただし異なるコンテンツ) が必要で
す。どのファイルがロードされているかを確認するために、サンプルは各テキストファイル内のコン
テンツを活用します。
サンプルファイルの準備方法
1.
ExampleText.txtという名前のテキストファイルを作成します。
2.
3.
テキストエディタを使用して、ExampleText.txtを開き、次のテキストを打ち込みます:
4.
5.
6.
ファイルを保存します。
GameSDKディレクトリ内に、Examplesというサブフォルダを作成してください。
パスが次のように見えるように、ExampleText.txtファイルをExamplesフォルダーに追加しま
す。
This sample was read from the .pak archive
<root>\GameSDK\Examples\ExampleText.txt
7.
ディレクトリから次のコマンドを実行してください root\GameSDK:
Version 1.6
428
Lumberyard 開発者ガイド
CryPakを使用してファイルにアクセスする
..\Tools\7za.exe a -tzip -r -mx0 Examples.pak Examples
このコマンドは、Examples.pakという名前のExamplesフォルダーのアーカイブ作成するた
めに、実行可能なファイル7za.exe (### フォルダー内にある) を使用します。GameSDKからコ
マンドを実行するので、アーカイブやGameSDKフォルダーに保存されています。.pakファイル
は、Examples\ExampleText.txtファイルのみを含めます。
8.
テキストエディタを使用して、<root>\GameSDK\Examples\ExampleText.txtファイル内の
テキストを何か別の内容に変更します。例えば:
This sample was read from the file system
これで同じパスを持つ二つのテキストファイルが作成され、一つはファイルシステム内に直接保存さ
れ、もう一方は.pakファイル内にあります。 CryPakのあるファイルの読み込み
これで、作成したExampleText.txtファイルからの情報を読み込むためのコードを書くことができ
ます。
1.
コードを組み立てるif-elseステートメントを含める次の内容を入力しま
す。ReadFromExampleFile()関数はファイルのコンテンツを読み込み、成功する場合
はtrueを返し、成功しなければfalseを返します。
char* fileContent = NULL;
if (!ReadFromExampleFile(&fileContent))
{
CryWarning(VALIDATOR_MODULE_SYSTEM, VALIDATOR_WARNING,
"ReadFromExampleFile() failed");
}
else
{
CryLogAlways("ExampleText contains %s", fileContent);
[...] // this line will be added later on
}
ReadFromExampleFile()がExampleText.txtの読み込むに成功した場合、fileContentが読
み込む対象のテキストを含めるメモリースペースになります。
2.
ReadFromExampleFile()関数を取り消すには、次の内容を入力します。
bool ReadFromExampleFile(char** fileContent)
{
CCryFile file;
size_t fileSize = 0;
const char* filename = "examples/exampletext.txt";
[...]
}
• CCryFile タイプの fileは、ファイルシステムもしくは.pakアーカイブの内部からファイル
に直接アクセスするためCryPakを活用します。
• fileSizeはメッセージの末尾を定義します。この場合、無効文字\0を検出しても読み込みは
停止しません。
Version 1.6
429
Lumberyard 開発者ガイド
CryPakを使用してファイルにアクセスする
• filename - ロードされるファイルのパスを指定します。このとき大文字と小文字の区別はされ
ません。
3.
CryPakを使用してファイル検索をするために以下の内容を入力します。
char str[1024];
if (!file.Open(filename, "r"))
{
sprintf(str, "Can't open file, (%s)", filename);
CryWarning(VALIDATOR_MODULE_SYSTEM, VALIDATOR_WARNING, "%s", str);
return false;
}
• filenameで指定されたファイルを検索するために、Open() はCryPakを呼び出します。
• ファイルのアクセスモード"r"は、プレーンテキスト形式のファイルの読み込みを指定しま
す。バイナリファイルを読み込むには、代わりに"rb"を使用します。
4.
ファイルの長さを取得するために次の内容を入力します。ファイルが空でない場合は、ファイル
の長さに示される必要なメモリを割り当てます。その後ファイルコンテンツを読み込みます。コ
ンテンツのサイズがファイルの長さと等しくない場合は破棄されます。
fileSize = file.GetLength();
if (fileSize <= 0)
{
sprintf(str, "File is empty, (%s)", filename);
CryWarning(VALIDATOR_MODULE_SYSTEM, VALIDATOR_WARNING, "%s", str);
return false;
}
char* content = new char[fileSize + 1];
content[fileSize] = '\0';
if (file.ReadRaw(content, fileSize) != fileSize)
{
delete[] content;
sprintf(str, "Can't read file, (%s)", filename);
CryWarning(VALIDATOR_MODULE_SYSTEM, VALIDATOR_WARNING, "%s", str);
return false;
}
• content は、GetLength()と余分な無効文字1文字で返された文字により初期化されるメモリ
のchar配列を指すローカルポインターです。
• ReadRaw はcontentをテキストファイルから読み取った情報で満たします。失敗するとき
は、contentに割り当てられたメモリーはフリーになります。
5.
ファイルハンドルを閉じて、ローカルで作成したデータを関数外で使用できるよ
うfileContentポインターを設定するためには、次の内容を入力します。最終的に読み込みが成
功するとtrueを返します。
file.Close();
*fileContent = content;
return true;
Version 1.6
430
Lumberyard 開発者ガイド
CryPakを使用してファイルにアクセスする
Note
例では、ReadFromExampleFile()の呼び出し元は、テキストファイルのデータを保存
するために割当てられたヒープメモリーをフリーにする役割があります。つまり、デー
タが使用された後にコールdelete[] fileContent;を追加することを必ず確認してく
ださい。
6.
読み込みが成功したかどうかを確認するには、ゲームを実行しGame.logファイルをチェックし
てください。
完全なサンプルコード (ファイル読み取り)
Calling ReadFromExampleFile()
char* fileContent = NULL;
if (!ReadFromExampleFile(&fileContent))
{
CryWarning(VALIDATOR_MODULE_SYSTEM, VALIDATOR_WARNING,
"ReadFromExampleFile() failed");
}
else
{
CryLogAlways("ExampleText contains %s", fileContent);
delete[] fileContent;
}
ReadFromExampleFile() implementation
bool ReadFromExampleFile(char** fileContent)
{
CCryFile file;
size_t fileSize = 0;
const char* filename = "examples/exampletext.txt";
char str[1024];
if (!file.Open(filename, "r"))
{
sprintf(str, "Can't open file, (%s)", filename);
CryWarning(VALIDATOR_MODULE_SYSTEM, VALIDATOR_WARNING, "%s", str);
return false;
}
fileSize = file.GetLength();
if (fileSize <= 0)
{
sprintf(str, "File is empty, (%s)", filename);
CryWarning(VALIDATOR_MODULE_SYSTEM, VALIDATOR_WARNING, "%s", str);
return false;
}
char* content = new char[fileSize + 1];
content[fileSize] = '\0';
if (file.ReadRaw(content, fileSize) != fileSize)
{
delete[] content;
Version 1.6
431
Lumberyard 開発者ガイド
CryPakを使用してファイルにアクセスする
sprintf(str, "Can't read file, (%s)", filename);
CryWarning(VALIDATOR_MODULE_SYSTEM, VALIDATOR_WARNING, "%s", str);
return false;
}
file.Close();
*fileContent = content;
return true;
}
CryPakのファイルシステムファイルへの書き込み
ファイルを書き込むことは、ファイルを読み込むプロセスに似ています。ファイルに書き込むに
は、CCryFile::Writeを使用します。これは.pakアーカイブではなく、必ずファイルシステムに書
き込みます。アーカイブファイルへのファイル書き込みの情報については、CryArchiveでPakを変更す
る (p. 433)を参照してください。
1.
ファイルへ書き込むためのコードを組み立てるif-elseステートメントを含む、次の内容を入
力します。WriteToExampleFile()関数はファイルのコンテンツを書き込み、成功した場合
はtrueを返し、成功しなければfalseを返します。
char* newContent = "File has been modified";
bool appendToFile = false;
if (!WriteToExampleFile(newContent, strlen(newContent), appendToFile))
{
CryWarning(VALIDATOR_MODULE_SYSTEM, VALIDATOR_WARNING,
"WriteToExampleFile() failed");
}
else
{
CryLogAlways("Text has been written to file, %s", newContent);
}
• WriteToExampleFile()は次の3つのパラメータを取得します。
• newContent は、ファイルシステム上のExampleText.txtへ書き込まれるテキストです。
• strlen(newContent) は、バイト数が書き込まれるnewContentのサイズを返します。
• appendToFile - newContentが既存のコンテンツに追加されればtrueになり、ファイルが
上書きされればfalse になります。
2.
WriteToExampleFile)関数については次の内容を入力します。
bool WriteToExampleFile(char* text, int bytes, bool appendToFile)
{
CCryFile file;
const char* filename = "examples/exampletext.txt";
assert(bytes > 0);
char* mode = NULL;
if (appendToFile)
mode = "a";
else
mode = "w";
char str[1024];
if (!file.Open(filename, mode))
{
Version 1.6
432
Lumberyard 開発者ガイド
CryPakを使用してファイルにアクセスする
sprintf(str, "Can't open file, (%s)", filename);
CryWarning(VALIDATOR_MODULE_SYSTEM, VALIDATOR_WARNING, "%s", str);
return false;
}
[...]
file.Close();
return true;
}
• mode は、テキストが既存のファイルに添付されるか、または既存のファイルコンテンツを上書
きするかを指定します。 "w" は空白のファイルに「書き込み」をすることを意味し、"a"は、
既存のファイルへ「添付」することを意味します。
3.
最後のステップはファイルにテキストを書き込み、書き込みのあったバイト数を返すか、何も書
かれない場合はエラーメッセージを表示します。
int bytesWritten = file.Write(text, bytes);
assert(bytesWritten == bytes);
if (bytesWritten == 0)
{
sprintf(str, "Can't write to file, (%s)", filename);
CryWarning(VALIDATOR_MODULE_SYSTEM, VALIDATOR_WARNING, "%s", str);
return false;
}
• bytesWritten は、Write()関数を呼び出すことで書き込まれたバイト数を示します。
CryArchiveでPakを変更する
このセクションは、どのようにファイルがアーカイブから追加、更新、削除されたかを示す簡単な
例を示します。例では、国際標準的にGameSDKフォルダーの代わりにUSERを使用します。なぜなら
なぜなら、GameSDKフォルダ内のpakファイルは、スタートアップ時にデフォルトでロードされるの
で、Read-Onlyとマークされるからです。 (USERフォルダーのファイルは、スタートアップ時にデ
フォルトでロードされるわけではありません。)
string pakFilename = PathUtil::AddSlash("%USER%") + "Examples.pak";
const char* filename = "Examples/ExampleText.txt";
char* text = "File has been modified by CryArchive";
unsigned length = strlen(text);
_smart_ptr<ICryArchive> pCryArchive = gEnv->pCryPak>OpenArchive(pakFilename.c_str(), ICryArchive::FLAGS_RELATIVE_PATHS_ONLY
| ICryArchive::FLAGS_CREATE_NEW);
if (pCryArchive)
{
pCryArchive->UpdateFile(filename, text, length,
ICryArchive::METHOD_STORE, 0);
}
• UpdateFile() - .pakアーカイブ内の既存のファイルを変更するか、もしくはファイルが存在しな
い場合は新しいファイルを作成します。
• ICryArchive::FLAGS_CREATE_NEW - 新しい.pak#####作成するよう強制します。ファイルを追
加（添付）したい場合は、このフラグを削除します。
Version 1.6
433
Lumberyard 開発者ガイド
CryPakを使用してファイルにアクセスする
• アーカイブからファイルやフォルダを削除するには、UpdateFile()にある次のコマンドのうち一
つを使用します。RemoveFile()、RemoveDir()、またはRemoveAll()です。
CryPakの詳細
初期化
.pakファイルがゲームコードからいつでもアクセスできるようにするため、CrySystemモジュールは
次の関数を使用してCSystem::InitにあるCryPakを初期化します。
• InitFileSystem(startupParams.pGameStartup);
• InitFileSystem_LoadEngineFolders();
Tip
ゲーム初期化をテストするのに適した場所は、CGame::Initの初めにあるGame.cppです。
Pakファイルの優先順位
CryPakがファイルシステムのファイルを先に処理するか、または.pakのファイルを先に処理するか
は、pakPriorityの値によって異なります。pakPriorityのデフォルト値は、構築の構成設定に
よって異なりますが、cvarsys_PakPriorityの値0, 1, 2 or 3を手動で割り当てることで変更が
可能です。これらの値が意味するものはEPakPriorityに表示されています。
PakVars.h
enum EPakPriority
{
ePakPriorityFileFirst = 0,
ePakPriorityPakFirst = 1,
ePakPriorityPakOnly
= 2,
ePakPriorityFileFirstModsOnly = 3,
};
Pakのローディング、検索の優先順位
新しいpakファイルをGameSDKフォルダへ追加するのは、.pakファイルがGameSDKパスより最初に
ローディングされるためです。.pakファイルフォルダのローディングと検索の順序は以下のとおりで
す。ロード順序と検索順序は真逆になるので注意してください。
.pakファイルのロード順序
1. GameSDK: <root>\GameSDK\*.pak
2. Engine: <root>\Engine\
a. Engine.pak
b. ShaderCache.pak
c. ShaderCacheStartup.pak
d. Shaders.pak
e. ShadersBin.pak
3. Mods: root\Mods\MyMod\GameSDK\*.pak （コマンドアーギュメント-mod "MyMod"を実行する
ことを前提としています)
.pakファイルを検索する順序
Version 1.6
434
Lumberyard 開発者ガイド
ファイルのアクセスをトラックする
1. Mods 複数のmodフォルダがある場合、追加された順番の逆にチェックされます。
2. Engine
3. GameSDK
ファイルのアクセスをトラックする
ゲームランタイム実行中に発生した無効なファイルを追跡することは可能です。ストリーミング
スレッドではないスレッドからオープンファイルを読み込むもしくは開くことを実行しようとする
と、Invalid File Accessというエラーメッセージが発生します。これらのファイルアクセスオペ
レーションは深刻な停止状態を発生させることがあります。
Note
メインスレッドおよびレンダースレッドからのアクセス試行のみ記録されます。この機能が
リリース構築で無効になっています。
CVars
次のcvarsは追跡ファイルのアクセスに対して、異なるオプションを有効にします。
sys_PakLogInvalidFileAccess
1 (デフォルト):
• アクセス暦はgame.logに記録されます。
• 警告をperfHUD送信します。
• 警告は画面の左上隅に赤で表示されます。
• 非リリース構築の3秒間の停止は誘導されます。
sys_PakMessageInvalidFileAccess
• ファイルにアクセスすると、PCにポップアップダイアログが作成されます。この時点で、デバッ
ガーへ侵入するまたは次に進むかを選択できます。
不正アクセスが定義されるに対し、
ファイルのアクセス試行が無効であるかはICryPak::DisableRuntimeFileAccess を真か偽に戻す
ことによって設定されます。一人プレイヤー用および多人数参加型ゲームに対してはポイントを微調
整する必要があります。
例外
game.logなどのファイルを無視するためにファイルアクセストラッキングに例外を追加するには、
ファイルにアクセスする範囲でCDebugAllowFileAccessのインスタンスを作成します。
ファイルのアクセス呼び出し履歴を解消する
pak_LogInvalidFileAccess 2と収集するファイルについては呼び出し履歴を解決しなければなり
ません。 これを行うには、XenonStackParseフォルダにあるTools directoryのツールが必要となり
ます。
• 構築からの.pdbファイル
Version 1.6
435
Lumberyard 開発者ガイド
不正アクセスが定義されるに対し、
• XenonStackParseツール
• ProcessFileAccess.pyヘルパースクリプト
ProcessFileAccess.pyを実行するディレクトリ構造は次の内容に類似しなければなりません。
<Root>
--> XenonStackParse
--> FileAccessLogs (this folder should contain the .pdb files)
------> Processed (this folder contains the output from XenonStackParse)
FileAccessLogsディレクトリ（XenonStackParse.pdbファイルの検索をする機能をしているディ
レクトリ）からProcessFileAccess.pyを起動します。スクリプトはProcessedというフォルダお
よびその中にある、ログファイルごとに解決するための呼び出し履歴を含むファイルを作成します。
Version 1.6
436
Lumberyard 開発者ガイド
レンダリングノード
グラフィックスとレンダリング
Lumberyard のレンダリングテクノロジを支えるのは、現実世界の物理パラメーター (ベースカラー、
金属量、滑らかさ、鏡面性など) に基づいてマテリアルをレンダリングする最新の物理ベースのシェー
ディングコアです。これにより、最高性能の映画用レンダリングパイプラインと同じ物理ベースのパ
ラメーターを使用して、リアリティのある結果を得ることができます。
レンダリングコアに加えて、最もよく使用されるリアルタイムのライティング、シェーディング、特
殊効果や、物理照明、グローバル照明、ボリューメトリックフォグ、プロシージャル技術による劣化
表現、パーティクルシステム、動的でリアルタイムなシャドウ、モーションブラー、フィールドのボ
ケ深度、ポストカラーコレクションなどのポストエフェクト機能が豊富に用意されています。
Lumberyard のレンダリングエンジンは Lumberyard エディタ に緊密に統合されているため、エディ
タ上で確認できるグラフィックの忠実度やパフォーマンスが、そのままゲームでも再現されます。
エディタで行った変更は、完全にレンダリングされたシーンにすぐに反映されるので、その場での
フィードバックやすばやいイテレーションが可能です。
Lumberyard のレンダリングテクノロジは、最新のハイエンド PC やコンソールプラットフォームを最
大限に活用しながら、古いハードウェアとの互換性も維持するように設計されています。古いハード
ウェアでは、シーンのビジュアル要素を損なうことなく、グラフィカルな機能や忠実度がスケールダ
ウンされます。
このセクションでは、次のトピックについて説明します。
• レンダリングノード (p. 437)
• TrueType フォントのレンダリング (p. 441)
• Stars DAT ファイルの生成 (p. 442)
• アンチエイリアス処理とスーパーサンプリング (p. 443)
レンダリングノード
世界のオブジェクトをビジュアル化するために、Lumberyard では、レンダリングノードとレンダリン
グ要素の概念が定義されています。レンダリングノードは 3D エンジンの一般的なオブジェクトを表
しており、特に、可視性カリングの階層の構築、物理的なインタラクション（オプション）とレンダ
リングの実現に使用されます。
実際にレンダリングを行う場合、レンダリングノードは自身をレンダラーに追加することで、実際
のオブジェクト描画を実装する適切なレンダリング要素を渡します。このプロセスは、次のサンプル
コードに示すように、レンダリングオブジェクトのサポートによって実現します
Version 1.6
437
Lumberyard 開発者ガイド
新しいレンダリングノードの作成
新しいレンダリングノードの作成
次の例では、PrismObject というレンダリングノードを作成します。このノードは IRenderNode か
ら派生し、Code/CryEngine/CryCommon/IEntityRenderState.h で定義されます。
1. IPrismObjectRenderNode のインターフェイスを CryEngine/CryCommon/
IEntityRenderState.h に追加して公開します。
struct IPrismRenderNode : public IRenderNode
{
...
};
2. 新しい enum を、CryEngine/CryCommon/IEntityRenderState.h ですでに定義されているレ
ンダリングノードのリストに追加します。
enum EERType
{
...
eERType_PrismObject,
...
};
3. PrismObjectRenderNode.h を Cry3DEngine に追加します。
#ifndef _PRISM_RENDERNODE_
#define _PRISM_RENDERNODE_
#pragma once
class CPrismRenderNode : public IPrismRenderNode, public Cry3DEngineBase
{
public:
// interface IPrismRenderNode
...
// interface IRenderNode
virtual void SetMatrix(const Matrix34& mat);
virtual EERType GetRenderNodeType();
virtual const char* GetEntityClassName() const { return "PrismObject"; }
virtual const char* GetName() const;
virtual Vec3 GetPos(bool bWorldOnly = true) const;
virtual bool Render(const SRendParams &rParam);
virtual IPhysicalEntity* GetPhysics() const { return 0; }
virtual void SetPhysics(IPhysicalEntity*) {}
virtual void SetMaterial(IMaterial* pMat) { m_pMaterial = pMat; }
virtual IMaterial* GetMaterial(Vec3* pHitPos = 0) { return m_pMaterial; }
virtual float GetMaxViewDist();
virtual void GetMemoryUsage(ICrySizer* pSizer);
virtual const AABB GetBBox() const { return m_WSBBox; }
virtual void SetBBox( const AABB& WSBBox ) { m_WSBBox = WSBBox; }
private:
CPrismRenderNode();
private:
~CPrismRenderNode();
Version 1.6
438
Lumberyard 開発者ガイド
新しいレンダリングノードの作成
AABB m_WSBBox;
Matrix34 m_mat;
_smart_ptr< IMaterial > m_pMaterial;
CREPrismObject* m_pRE;
};
#endif // #ifndef _PRISM_RENDERNODE_
4. PrismObjectRenderNode.cpp を Cry3DEngine に追加します。
#include "StdAfx.h"
#include "PrismRenderNode.h"
CPrismRenderNode::CPrismRenderNode() :m_pMaterial(0)
{
m_mat.SetIdentity();
m_WSBBox = AABB(Vec3(-1, -1, -1), Vec3(1, 1, 1));
m_pRE = (CREPrismObject*) GetRenderer()>EF_CreateRE(eDATA_PrismObject);
m_dwRndFlags |= ERF_CASTSHADOWMAPS |
ERF_HAS_CASTSHADOWMAPS;
}
CPrismRenderNode::~CPrismRenderNode()
{
if (m_pRE)
m_pRE->Release(false);
Get3DEngine()->FreeRenderNodeState(this);
}
void CPrismRenderNode::SetMatrix(const Matrix34& mat)
{
m_mat = mat;
m_WSBBox.SetTransformedAABB(mat, AABB(Vec3(-1, -1, -1),
Vec3(1, 1, 1)));
Get3DEngine()->RegisterEntity(this);
}
const char* CPrismRenderNode::GetName() const
{
return "PrismObject";
}
void CPrismRenderNode::Render(const SRendParams& rParam, const
SRenderingPassInfo &passInfo)
{
FUNCTION_PROFILER_3DENGINE;
if(!m_pMaterial)
return;
// create temp render node to submit this prism object to
the renderer
CRenderObject *pRO = GetRenderer()>EF_GetObject_Temp(passInfo.ThreadID());
could be cached
Version 1.6
439
// pointer
Lumberyard 開発者ガイド
新しいレンダリングノードの作成
if(pRO)
{
// set basic render object properties
pRO->m_II.m_Matrix = m_mat;
pRO->m_ObjFlags |= FOB_TRANS_MASK;
pRO->m_fSort = 0;
pRO->m_fDistance = rParam.fDistance;
// transform camera into object space
const CCamera& cam(passInfo.GetCamera());
Vec3 viewerPosWS(cam.GetPosition());
// set render object properties
m_pRE->m_center = m_mat.GetTranslation();
SShaderItem& shaderItem(m_pMaterial>GetShaderItem(0));
GetRenderer()->EF_AddEf(m_pRE,
shaderItem, pRO, passInfo, EFSLIST_GENERAL, 0,
SRendItemSorter(rParam.rendItemSorter));
}
}
void CPrismRenderNode::GetMemoryUsage(ICrySizer* pSizer) const
{
SIZER_COMPONENT_NAME(pSizer, "PrismRenderNode");
pSizer->AddObject(this, sizeof(*this));
}
void CPrismRenderNode::OffsetPosition(const Vec3& delta)
{
if (m_pRNTmpData) m_pRNTmpData->OffsetPosition(delta);
m_WSBBox.Move(delta);
m_mat.SetTranslation(m_mat.GetTranslation() + delta);
if (m_pRE) m_pRE->m_center += delta;
}
void CPrismRenderNode::FillBBox(AABB & aabb)
{
aabb = CPrismRenderNode::GetBBox();
}
EERType CPrismRenderNode::GetRenderNodeType()
{
return eERType_PrismObject;
}
float CPrismRenderNode::GetMaxViewDist()
{
return 1000.0f;
}
Vec3 CPrismRenderNode::GetPos(bool bWorldOnly) const
{
return m_mat.GetTranslation();
}
Version 1.6
440
Lumberyard 開発者ガイド
TrueType フォントのレンダリング
IMaterial* CPrismRenderNode::GetMaterial(Vec3* pHitPos)
{
return m_pMaterial;
}
5. クライアントコードが、新しいレンダリングノードのインスタンスを作成できるようにするに
は、/Code/CryEngine/Cry3DEngine/3DEngine.cpp で次の関数を拡張します
...
#include "PrismRenderNode.h"
...
IRenderNode * C3DEngine::CreateRenderNode(EERType type)
{
switch (type)
{
...
case eERType_PrismObject:
{
IPrismRenderNode* pRenderNode = new CPrismRenderNode();
return pRenderNode;
}
...
TrueType フォントのレンダリング
画面上のテキストのレンダリングに必要なフォントテクスチャの生成には CryFont が使用されます。
フォントレンダリングのさまざまな機能は、r_DebugFontRendering コンソール変数を使用して確
認できます。
機能のテストだけではなく、機能の使用方法のドキュメントも出力されます。
サポートされている機能
CryFont では次の機能がサポートされています。
• フォントシェーダ – フォントの外観の設定に使用されます。シャドウまたはアウトラインを生成で
きるように、設定可能なオフセットと色を持つ複数のパスがサポートされています。次の XML の例
ではサンプルのフォントシェーダを示しています。
<fontshader>
<font path="VeraMono.ttf" w="288" h="416"/>
<effect name="default">
<pass>
<color r="0" g="0" b="0" a="1"/>
<pos x="1" y="1"/>
</pass>
</effect>
<effect name="console">
<pass>
<color r="0" g="0" b="0" a="0.5"/>
<pos x="2" y="2"/>
</pass>
</effect>
</fontshader>
Version 1.6
441
Lumberyard 開発者ガイド
便利なコンソールコマンド
XML の font 要素の w 属性と h 属性では、フォントテクスチャの幅と高さを指定しています。XML
内での順序によって、パスがレンダリングされる順序が定義されます。子要素を持たない <pass>
要素は、そのパスがデフォルト設定でレンダリングされることを意味しています。<pos> タグは
フォントのオフセットの指定に使用され、<color> タグはフォントの色の設定および透明度の定義
(アルファチャネル a を使用) に使用されています。
• Unicode – 使用されるデフォルトフォントでは一部の Unicode 文字だけがサポートされています (メ
モリを節約するため) が、他のフォントを使用できます。
• ソースとしての TrueType フォント – 小さいテクスチャにキャッシュされます。よく使用される文
字は事前キャッシュされていますが、実行時の更新が可能でサポートされています。
• 色付きテキストレンダリング
• 調整可能な透過度
• 文字列内の色のバリエーション – 利用可能な 10 色の中の 1 色を設定するには $0..9 という値を使
用します。$ 記号自体を出力するには $$ を使用し、この機能をオフに切り替えるには $o を使用し
ます。
• 文字列内のタブを返す
• テキストの整列
• 文字列の幅と高さの計算 – 中央揃えと右揃えの処理のために内部的に使用されます。
• フォントサイズのバリエーション – バイリニアフィルタリングによって一部のぼかしを使用でき
ますが、ミップマッピングは使用されません。そのため、この機能には縮小に対する制限がありま
す。
• プロポーショナルフォントと等幅フォント
• 最高品質のためのテクセルからピクセルへの正確なマッピングを使用した完全ピクセルレンダリン
グ。
便利なコンソールコマンド
以下のコンソールコマンドはフォントレンダリングに関する情報を提供します。
r_DebugFontRendering
さまざまなフォントレンダリング機能に関する情報を提供し、関数の確認や使用法のドキュメン
ト化に有用です。
• 0=オフ
• 1=表示する
r_DumpFontNames
現在ロードされているフォントのリストをログ記録します。
r_DumpFontTexture
指定されたフォントのテクスチャをビットマップファイルにダンプしま
す。r_DumpFontTexture を使用して、ロードされているフォント名を取得できます。
Stars DAT ファイルの生成
Stars DAT ファイルには、空のレンダリングに使用される星のデータが含まれています。このトピッ
クでは、このファイルのデータを変更する場合に必要な情報を提供します。ここでは、バイナリファ
イルの生成にある程度精通していることを前提としています。
星のデータは Build\Engine\EngineAssets\Sky\stars.dat にあります。このデータは
CStars::LoadData 関数で読み込まれ、CRESky.cpp ファイルで実装されます。
Version 1.6
442
Lumberyard 開発者ガイド
ファイル形式
ファイル形式
Stars DAT ファイルではシンプルなバイナリ形式が使用されます。これは編集ツールを使用して簡単
に変更できます。ファイルはヘッダーで始まり、星ごとのエントリが続きます。ヘッダーは、ファイ
ルのエントリ数を指定します。
すべての型は、IEEE-754 形式のリトルエンディアン、float32 で保存されます。
SDK で提供されている星のデータは、実際の情報に基づいています。通常、既存の星のカタログを使
用してこの情報を入力することもできます。
ファイル要素は次のとおりです:
ヘッダー (12 バイト)
名前
オフセット
タイプ
値
Tag
0
uint32
0x52415453 (ASCII: STAR)
バージョン
4
uint32
0 x 00010001
NumStars
8
uint32
ファイルの星のエントリ数
タイプ
値
RightAscension 0
float32
ラジアン単位
Declination
4
float32
ラジアン単位
赤
8
uint8
星の色、レッドチャネル
Green
9
uint8
星の色、グリーンチャネル
青
10
uint8
星の色、ブルーチャネル
Magnitude
11
uint8
明るさ、正規化範囲
エントリ (12 バイト)
名前
オフセット
アンチエイリアス処理とスーパーサンプリング
ゲームで認識されるグラフィッククオリティは、綺麗で安定した画像を用いることに大きく依存しま
す。Lumberyard 効率的で、事後処理ベースの、コンソール変数を使用r_AntialiasingModeした
コンソールでコントロールできるアンチエイリアシング処理ソリューションを提供します。このソ
リューションでは、非常にシャープな画像から柔らかくぼやけた画像まで様々なニーズにぴったりの
グラフィックを作成するのに必要な量のアンチエイリアシング量をゲーム開発者が設定することがで
きます。Lumberyard はまたハイクオリティ･レンダリングのためのスーパーサンプリングをサポート
します。
アンチエイリアシング処理をコントロールする
次の表は、CVarr_AntialiasingModeを使って Lumberyardで使用できる、現在利用可能なアンチエ
イリアシングモードのリストを示します。
Version 1.6
443
Lumberyard 開発者ガイド
アンチエイリアシング処理をコントロールする
モード
CVar値
説明
いいえアンチエイ
リアジング処理
0
事後処理ベースのアンチエイリアシングを無効にします。
デバッギングに有用です。ゲーム開発者たちは、システム
リソースをアンチエイリアシングに使うよりは、むしろ高
いソリューションの方を使用するのです。
SMAA_Low (1X)
1
ポリゴンの縁のジャギー（ステアケース中間生産物）を取
り除くサブプクセルの形態学的アンチエイリアジング処理
（SMAA)を有効にします。このモードはサブピクセルの
ディテールは直しません。
SMAA_Med (1TX)
2
ピクセルのクローリングを軽減させるために、基本的な一
時的再映像化を伴うSMAAを有効にします。
SMAA_High (2TX) 3
マトリックスジッターを含む高度化された一時的再映像化
を伴うSMAAを有効にします。このモードは通常ベストク
オリティの画像を提供しますが、たまに縁部のちらつきが
発生します。
下のイメージは使用されているアンチアイリアジング設定によって達成可能なグラフィッククオリ
ティの範囲を表しています。
Version 1.6
444
Lumberyard 開発者ガイド
アンチエイリアシング処理をコントロールする
Version 1.6
445
Lumberyard 開発者ガイド
スーパーサンプリングをコントロールする
スーパーサンプリングをコントロールする
アンチエイリアジングに加えて、Lumberyardは非常に高いクオリティのレンダリングのスーパーサ
ンプリングをサポートする。スーパーサンプリングは高いソリューションのシーンをレンダーし、ス
ムーズで安定した縁の部分を得るためにダウンスケール。高度な内部レンダリングソリューションに
より、スーパーサンプリングは非常にパフォーマンス重視でハイエンドのPCでプレイするゲームにお
いてのみ維持できます。
Version 1.6
446
Lumberyard 開発者ガイド
Lua スクリプトリファレンス
Lua スクリプト
このセクションでは、Lua スクリプトに関するリファレンス情報やヘルプを提供します。また、Lua
Editor、Lua リモートデバッガー、XML ローダーなどのツールの使用方法についても説明します。
このセクションでは、次のトピックについて説明します。
• Lua スクリプトリファレンス (p. 447)
• Integrating Lua and C++ (p. 467)
• Luaスクリプトの使用 (p. 468)
• Lua Editor (p. 469)
• Luaのリモートデバッガーを使用する (p. 475)
• Lua XML ローダーの使用 (p. 477)
• 推奨する参照情報 (p. 480)
Lua スクリプトリファレンス
このセクションでは、Lua スクリプト関数のリファレンス情報を紹介します。関数は、それらが定義
されているシステムに基づいて整理されています。
ノードの索引
Lua の一般的なグローバルと関数 (p. 449)
• グローバル (p. 449)
• AIDebugToggle() (p. 450)
• ShowTime() (p. 450)
• count() (p. 451)
• new() (p. 451)
• merge() (p. 451)
• mergef() (p. 451)
Version 1.6
447
Lumberyard 開発者ガイド
ノードの索引
• Vec2Str() (p. 451)
• LogError() (p. 452)
• LogWarning() (p. 452)
• ログ() (p. 452)
• dump() (p. 452)
• EmptyString() (p. 452)
• NumberToBool() (p. 453)
• EntityName() (p. 453)
• EntityNamed() (p. 453)
• SafeTableGet() (p. 453)
EntityUtils Lua 関数 (p. 453)
• DumpEntities() (p. 454)
• CompareEntitiesByName() (p. 454)
• CompareEntitiesByDistanceFromPoint() (p. 454)
• BroadcastEvent() (p. 455)
• MakeDerivedEntity() (p. 455)
• MakeDerivedEntityOverride() (p. 455)
• MakeUsable() (p. 455)
• MakePickable() (p. 456)
• MakeSpawnable() (p. 456)
• EntityCommon.PhysicalizeRigid() (p. 456)
数学Luaグローバルと関数 (p. 456)
• グローバルベクトル (p. 456)
• 定数 (p. 457)
ベクトル関数
• IsNullVector () (p. 457)
• IsNotNullVector () (p. 458)
• LengthSqVector () (p. 458)
• LengthVector () (p. 458)
• DistanceSqVectors () (p. 458)
• DistanceSqVectors2d () (p. 458)
• DistanceVectors () (p. 458)
• dotproduct3d () (p. 459)
• dotproduct2d () (p. 459)
• LogVec () (p. 459)
• ZeroVector () (p. 459)
• CopyVector () (p. 460)
• SumVectors () (p. 460)
Version 1.6
448
Lumberyard 開発者ガイド
Lua の一般的なグローバルと関数
• NegVector () (p. 460)
• SubVectors () (p. 460)
• FastSumVectors () (p. 460)
• DifferenceVectors () (p. 461)
• FastDifferenceVectors () (p. 461)
• ProductVectors () (p. 461)
• FastProductVectors () (p. 461)
• ScaleVector () (p. 462)
• ScaleVectorInPlace (a,b) (p. 462)
• NormalizeVector () (p. 462)
• VecRotate90_Z () (p. 462)
• VecRotateMinus90_Z () (p. 463)
• crossproduct3d () (p. 463)
• RotateVectorAroundR () (p. 463)
• ProjectVector() (p. 463)
ユーティリティ関数
• LerpColors () (p. 464)
• Lerp () (p. 464)
• MAX (p. 464)
• __分() (p. 464)
• clamp () (p. 465)
• Interpolate() (p. 465)
• sgn () (p. 465)
• sgnnz () (p. 465)
• sqr () (p. 465)
• randomF() (p. 466)
• iff() (p. 466)
• DistanceLineAndPoint () (p. 463)
Physics Lua 関数 (p. 466)
• Physics.RegisterExplosionShape () (p. 466)
• Physics.RegisterExplosionCrack () (p. 467)
Lua の一般的なグローバルと関数
• ファイルの場所: Game/Scripts/common.lua
• ロード元: Game/Scripts/main.lua
グローバル
Lua の一時的なメモリ割り当てを回避するには、次のグローバルを使用します。
Version 1.6
449
Lumberyard 開発者ガイド
Lua の一般的なグローバルと関数
名前
説明
g_SignalData_point
g_SignalData によって使用される基本的な 3D ベクトル値。
g_SignalData_point2
g_SignalData によって使用される基本的な 3D ベクトル値。
g_SignalData
AI 行動スクリプト内でシグナルデータを渡すために使用される (参照: シ
グナル (p. 88))。
g_StringTemp1
一般的に、Lua 関数内の一時文字列に使用される。
g_HitTable
一般的に、Physics.RayWorldIntersection 関数によって使用される。
Physics.RayWorldIntersection で使用される g_HitTable には次のパラメーターを含めることができま
す。
パラメーター
説明
pos
3D ベクトル世界でのレイヒットの座標。
normal
レイヒットの 3D 標準ベクトル。
dist
レイヒットの距離。
surface
表面ヒットのタイプ。
エンティティ
エンティティヒットのスクリプトテーブル (ヒットであった場合)。
renderNode
枝葉ノードまたは静的レンダリングノードに対するスクリプトハンドル。
g_SignalData テーブルには、次のパラメータータイプを含めることができます。
型
説明
Vec3
3D ベクトル。
ScriptHandle
通常はエンティティ ID を提供するために使用される。
浮動小数点
浮動小数点値。
整数
整数または数値。
文字列
文字列 value.
AIReload()
Lua スクリプト aiconfig.lua (Game/Scripts/AI/) を再ロードします。
AIDebugToggle()
ai_DebugDraw コンソール変数のオンまたはオフを切り替えます。
ShowTime()
コンソールに現在のシステム時刻を記録します。形式は「日/月/年, 時間:分」です。
Version 1.6
450
Lumberyard 開発者ガイド
Lua の一般的なグローバルと関数
count()
特定のテーブルのキーと値のペアの数を返します。
パラメーター
説明
_tbl
キーと値のペアの数を取得するテーブル。
new()
指定された既存のテーブルをコピーして、新しいテーブルを作成します。一般的に、この関数はエン
ティティパラメーターテーブルに基づいてローカルテーブルを作成するために使用されます。
パラメーター
説明
_obj
新しいテーブルの作成元として使用する既存テーブル。
norecurse
すべてのサブテーブルを再帰的に再作成するかどうかを示すフラ
グ。TRUE に設定されている場合、サブテーブルは再作成されません。
merge()
ソーステーブルの関数をマージすることなく、2 つのテーブルをマージします。
パラメーター
説明
dst
ソーステーブル情報のマージ先のテーブル。
src
テーブル情報のマージ元のソーステーブル。
recurse
すべてのサブテーブルを再帰的にマージするかどうかを示すフラグ。
mergef()
ソーステーブルの関数のマージも含めて、2 つのテーブルをマージします。
パラメーター
説明
dst
ソーステーブル情報のマージ先のテーブル。
src
テーブル情報のマージ元のソーステーブル。
recursive
すべてのサブテーブルを再帰的にマージするかどうかを示すフラグ。
Vec2Str()
3D ベクトルテーブルを文字列に変換し、(x: X.XXX y: Y.YYY z: Z.ZZZ) という形式で返します。
パラメーター
説明
vec
変換する 3D ベクトルテーブル。例: {x=1,y=1,z=1}。
Version 1.6
451
Lumberyard 開発者ガイド
Lua の一般的なグローバルと関数
LogError()
エラーメッセージをコンソールとログファイルに記録します。メッセージは赤色のテキストでコン
ソールに表示されます。
パラメーター
説明
fmt
フォーマットされたメッセージの文字列。
...
オプションの引数リスト。以下に例を示します。LogError("MyError:
%f", math.pi);
LogWarning()
警告メッセージをコンソールとログファイルに記録します。メッセージは黄色のテキストでコンソー
ルに表示されます。
パラメーター
説明
fmt
フォーマットされたメッセージの文字列。
...
オプションの引数リスト。以下に例を示しま
す。LogWarning("MyError: %f", math.pi);
ログ()
メッセージをコンソールとログファイルに記録します。一般的にデバッグの目的で使用されます。
パラメーター
説明
fmt
フォーマットされたメッセージの文字列。
...
オプションの引数リスト。以下に例を示します。Log("MyLog: %f",
math.pi);
dump()
指定されたテーブルの情報をコンソールにダンプします。
パラメーター
説明
_class
コンソールにダンプするテーブル。以下に例を示します。g_localActor
no_func
テーブル関数をダンプするかどうかを示すフラグ。
depth
情報のダンプ元であるテーブルツリーの深さ。
EmptyString()
特定の文字列が設定されているかどうか、その長さがゼロより大きいかどうかを確認します。TRUE ま
たは FALSE を返します。
Version 1.6
452
Lumberyard 開発者ガイド
EntityUtils Lua 関数
パラメーター
説明
str
確認する文字列。
NumberToBool()
数値が true (ゼロ以外) または false (ゼロ) であるかどうかを確認します。
パラメーター
説明
n
確認する数値。
EntityName()
指定されたエンティティ ID またはエンティティテーブルの名前を取得します。エンティティが存在し
ない場合、この関数は空の文字列を返します。
パラメーター
説明
エンティティ
名前を返すエンティティテーブルまたはエンティティ ID。
EntityNamed()
指定された名前を持つエンティティがエンティティシステムに存在するかどうかを確認します。TRUE
または FALSE を返します。一般的にデバッグのために使用されます。
パラメーター
説明
name
確認するエンティティの名前。
SafeTableGet()
指定された名前を持つサブテーブルがテーブル内に存在するかどうかを確認します。サブテーブルが
存在する場合、この関数はそのサブテーブルを返します。存在しない場合は nil を返します。
パラメーター
説明
table
サブテーブルの有無を確認するテーブル。
name
確認するサブテーブルの名前。
EntityUtils Lua 関数
このトピックでは、一般的に使用される Lua エンティティのユーティリティ関数について説明しま
す。
• ファイルの場所: Game/Scripts/Utils/EntityUtils.lua
• ロード元: Game/Scripts/common.lua
Version 1.6
453
Lumberyard 開発者ガイド
EntityUtils Lua 関数
DumpEntities()
マップで現在使用されているすべてのエンティティ ID、名前、クラス、位置、角度をコンソールにダ
ンプします。以下に例を示します。
[userdata: 00000002]..name=Grunt1 clsid=Grunt pos=1016.755,1042.764,100.000
ang=0.000,0.000,1.500
[userdata: 00000003]..name=Grunt2 clsid=Grunt pos=1020.755,1072.784,100.000
ang=0.000,0.000,0.500
...
CompareEntitiesByName()
名前で識別される 2 つのエンティティを比較します。この機能は、一般的にテーブルをソートする場
合に使用されます。
パラメーター
説明
ent1
最初のエンティティテーブルの名前。
ent2
2 番目のエンティティテーブルの名前。
例
local entities = System.GetEntitiesByClass("SomeEntityClass");
table.sort(entities, CompareEntitiesByName);
CompareEntitiesByDistanceFromPoint()
2 つのエンティティの指定されたポイントからの距離を比較します。エンティティ 1 の距離が エン
ティティ 2 のそれより長い場合 (すなわち、エンティティ 1 の方が遠い場合)、この関数は TRUE に戻
ります。そうでない場合は FALSE に戻ります。
パラメーター
説明
ent1
エンティティ 1 のテーブル
ent2
エンティティ 2 のテーブル
ポイント
3D 位置ベクトルが距離を測るポイントを示します。
例
local ent1 = System.GetEntityByName("NameEntityOne");
local ent2 = System.GetEntityByName("NameEntityTwo");
if(CompareEntitiesByDistanceFromPoint( ent1, ent2,
g_localActor:GetPos()))then
Log("Entity One is further away from the Player than Entity two...");
end
Version 1.6
454
Lumberyard 開発者ガイド
EntityUtils Lua 関数
BroadcastEvent()
エンティティイベントのブロードキャストを処理します。
パラメーター
説明
支払人
イベントを送信したエンティティ。
event
処理する文字列ベースのエンティティイベント。
例
BroadcastEvent(self, "Used");
MakeDerivedEntity()
親のエンティティテーブルから派生したバージョンの新しいテーブルを作成します。一般的にこの関
数は、別のエンティティに基づいた新しいエンティティスクリプトの作成を簡素化するために使用さ
れます。
パラメーター
説明
_DerivedClass
派生したクラステーブル。
_親
親またはベースのクラステーブル。
MakeDerivedEntityOverride()
親のエンティティから派生したクラスの新しいテーブルを作成します。派生したテーブルのプロパ
ティは、親のプロパティからのものを上書きします。
パラメーター
説明
_DerivedClass
派生したクラステーブル。
_親
親またはベースのクラステーブル。
MakeUsable()
OnUsed のような、使用可能な機能を特定のエンティティに追加します。
パラメーター
説明
エンティティ
使用できるようにするエンティティテーブル。
例
MyEntity = { ... whatever you usually put here ... }
Version 1.6
455
Lumberyard 開発者ガイド
数学Luaグローバルと関数
MakeUsable(MyEntity)
function MyEntity:OnSpawn() ...
function MyEntity:OnReset()
self:ResetOnUsed()
...
end
MakePickable()
「取得できる」基本的な機能を特定のエンティティに追加します。bPickable プロパティは、エン
ティティのプロパティテーブルに追加されます。
パラメーター
説明
エンティティ
取得できるようにするエンティティテーブル。
MakeSpawnable()
起動機能を特定のエンティティに追加します。一般的に、AI アクターの作成時に使用します。
パラメーター
説明
エンティティ
機能可能にするためのエンティティテーブル。
EntityCommon.PhysicalizeRigid()
エンティティを指定されたエンティティスロットとその物理特性に基づいて形に表します。
パラメーター
説明
エンティティ
物理的に描写するためのエンティティテーブル。
nSlot
物理的に描写するためのエンティティスロット。
プロパティ
物理現象のプロパティテーブル
bActive
使用されていません。
数学Luaグローバルと関数
このトピックでは、よく使われる数学のグローバルベクトル・定数・関数について説明します。
• ファイルの場所: Game/Scripts/Utils/Math.lua
• ロード元: Game/Scripts/common.lua
グローバルベクトル
Luaの一時的なメモリ割り当てを回避するには、次のグローバルを使用します。
Version 1.6
456
Lumberyard 開発者ガイド
数学Luaグローバルと関数
グローバルの名前
説明
g_Vectors.v000
基本的なゼロベクトル。
g_Vectors.v001
正のZ軸方向のベクトル。
g_Vectors.v010
正のY軸方向のベクトル。
g_Vectors.v100
正のX軸方向のベクトル。
g_Vectors.v101
X軸とZ軸方向のベクトル。
g_Vectors.v110
X軸とY軸方向のベクトル。
g_Vectors.v111
X軸とY軸とZ軸方向のベクトル。
g_Vectors.up
正のZ軸方向のベクトル。
g_Vectors.down
負のZ軸方向のベクトル。
g_Vectors.temp
一時的なゼロベクトル。
g_Vectors.tempColor
一時的なゼロベクトル。一般的にrgbカラー値を通す際に使用されます。
g_Vectors.temp_v1
一時的なゼロベクトル。
g_Vectors.temp_v2
一時的なゼロベクトル。
g_Vectors.temp_v3
一時的なゼロベクトル。
g_Vectors.temp_v4
一時的なゼロベクトル。
g_Vectors.vecMathTemp1一時的なゼロベクトル。
g_Vectors.vecMathTemp2一時的なゼロベクトル。
定数
定数の名前
説明
g_Rad2Deg
弧度から角度に変換する基本値。
g_Deg2Rad
弧度から角度に変換する基本値。
g_Pi
math.piに基づく基本的な円周率定数。
g_2Pi
math.piに基づく基本的なダブル型円周率定数。
g_Pi2
math.piに基づくハーフ型円周率定数
IsNullVector ()
指定されたベクトルのすべてのコンポーネントがnullであるかどうか確認します。
パラメーター
説明
自
チェックするベクトル。
Version 1.6
457
Lumberyard 開発者ガイド
数学Luaグローバルと関数
IsNotNullVector ()
指定されたベクトルの任意の成分がnullでないかどうか確認します。
パラメーター
説明
自
チェックするベクトル。
LengthSqVector ()
指定されたベクトルの長さの２乗を読み取ります。
パラメーター
説明
自
長さを読み取るためのベクトル
LengthVector ()
指定されたベクトルの長さを読み取ります。
パラメーター
説明
自
長さを読み取るためのベクトル
DistanceSqVectors ()
２つのベクトル間の距離の２乗を読み取ります。
パラメーター
説明
自
1つ目のベクトル
b
2つ目のベクトル
DistanceSqVectors2d ()
2D空間(Z成分なし)の２つのベクトル間の距離の２乗 を読み取ります。
パラメーター
説明
自
1つ目のベクトル
b
2つ目のベクトル
DistanceVectors ()
２つのベクトル間の距離を読み取ります。
Version 1.6
458
Lumberyard 開発者ガイド
数学Luaグローバルと関数
パラメーター
説明
自
1つ目のベクトル
b
2つ目のベクトル
dotproduct3d ()
２つのベクトル間のドット積を読み取ります
パラメーター
説明
自
1つ目のベクトル
b
2つ目のベクトル
dotproduct2d ()
２D空間(Z成分なし)の２つのベクトルのドット積を読み取ります 。
パラメーター
説明
自
1つ目のベクトル
b
2つ目のベクトル
LogVec ()
指定ベクトルをコンソールに記録します。
パラメーター
説明
name
ベクトルを説明する名前。
v
記録するベクトル。
例
LogVec("Local Actor Position", g_localActor:GetPos())
コンソール出力:
<Lua> Local Actor Position = (1104.018066 1983.247925 112.769440)
ZeroVector ()
指定されたベクトルのすべての成分をゼロに設定します。
Version 1.6
459
Lumberyard 開発者ガイド
数学Luaグローバルと関数
パラメーター
説明
dest
ゼロにするベクトル。
CopyVector ()
一つのベクトル成分を他のベクトルにコピーします。
パラメーター
説明
dest
目的地ベクトル
src
ソースベクトル。
SumVectors ()
二つのベクトル成分を加算します。
パラメーター
説明
自
1つ目のベクトル
b
2つ目のベクトル
NegVector ()
指定されたベクトルのすべての成分を無効にします。
パラメーター
説明
自
無効にするベクトル
SubVectors ()
２つのベクトル成分に関する減算を目的地ベクトルにコピーします。
パラメーター
説明
dest
目的地ベクトル
自
1つ目のベクトル
b
2つ目のベクトル
FastSumVectors ()
２つのベクトル成分に関する加算を目的地ベクトルにコピーします。
Version 1.6
460
Lumberyard 開発者ガイド
数学Luaグローバルと関数
パラメーター
説明
dest
目的地ベクトル
自
1つ目のベクトル
b
2つ目のベクトル
DifferenceVectors ()
２つのベクトル間の差異を読み取ります。
パラメーター
説明
自
1つ目のベクトル
b
2つ目のベクトル
FastDifferenceVectors ()
２つのベクトル間の成分に関する差異を目的地ベクトルにコピーします。
パラメーター
説明
dest
目的地ベクトル
自
1つ目のベクトル
b
2つ目のベクトル
ProductVectors ()
２つのベクトルの積を読み取ります。
パラメーター
説明
自
1つ目のベクトル
b
2つ目のベクトル
FastProductVectors ()
２つのベクトルの積を目的地ベクトルにコピーします。
パラメーター
説明
dest
目的地ベクトル
自
1つ目のベクトル
b
2つ目のベクトル
Version 1.6
461
Lumberyard 開発者ガイド
数学Luaグローバルと関数
ScaleVector ()
指定されたベクトルaをb倍で測ります。
パラメーター
説明
自
ベクトル
b
スカラー
ScaleVectorInPlace (a,b)
b倍で測られたベクトルaのコピーに基づいて新しいベクトルを読み取ります。
パラメーター
説明
自
1つ目のベクトル
b
スカラー
ScaleVectorInPlace (desta,b)
b倍で測定したベクトルaを目的地ベクトルにコピーする。
パラメーター
説明
dest
目的地ベクトル
自
1つ目のベクトル
b
スカラー
NormalizeVector ()
指定されたベクトルを標準化します。
パラメーター
説明
自
標準化するベクトル。
VecRotate90_Z ()
指定されたベクトルを、Z軸を中心に90度回転させます
パラメーター
説明
v
回転させるベクトル。
Version 1.6
462
Lumberyard 開発者ガイド
数学Luaグローバルと関数
VecRotateMinus90_Z ()
指定されたベクトルを、Z軸を中心にマイナス90度回転させます。
パラメーター
説明
v
回転させるベクトル。
crossproduct3d ()
２つのベクトル外積の結果を目的地ベクトルにコピーします。
パラメーター
説明
dest
目的地ベクトル
p
1つ目のベクトル
q
2つ目のベクトル
RotateVectorAroundR ()
指定した角度でrベクトルの周りをpベクトルがベクトル回転する結果を目的地ベクトルにコピーす
る。
パラメーター
説明
dest
目的地ベクトル
p
1つ目のベクトル
r
2つ目のベクトル
角度
回転角度
ProjectVector()
Pベクトルのベクトル射影の結果を、指定した法線Nと目的地ベクトルにコピーします。
パラメーター
説明
dest
目的地ベクトル
P
射影するベクトル
N
面法線
DistanceLineAndPoint ()
点aからp と qを結ぶ線の距離を読み取ります。
Version 1.6
463
Lumberyard 開発者ガイド
数学Luaグローバルと関数
パラメーター
説明
自
測定する起点
p
ベクトルp
q
ベクトルｑ
LerpColors ()
k因数を用いて２色ベクトル間の線形補間を実行します。
パラメーター
説明
自
色/ベクトル a.
b
色/ベクトル b
k
因数ｋ
Lerp ()
k因数を用いて2つのスカラー間の線形補間を実行します。
パラメーター
説明
自
スカラーa.
b
スカラーb.
k
因数ｋ
MAX
2つのスカラーの最大値を読み取ります。
パラメーター
説明
自
スカラーa.
b
スカラーb.
__分()
2つのスカラーの最小値を読み取ります。
パラメーター
説明
自
スカラーa.
b
スカラーb.
Version 1.6
464
Lumberyard 開発者ガイド
数学Luaグローバルと関数
clamp ()
最小値と最大値の間の指定された数値を固定（クランプ）します。
パラメーター
説明
_n
クランプする数値。
_分
下限。
_max
上限。
Interpolate()
数字を特定の速度で特定ゴールに補間（インターポレーション）する
パラメーター
説明
実際に
補間する数字
目標
目標:
速度
補間の速度。
sgn ()
指定された数字の符号を読み取ります (0は0を返します)。
パラメーター
説明
自
符号を取得する数字。
sgnnz ()
指定された数字の符号を読み取ります (0は1を返します)。
パラメーター
説明
自
符号を取得する数字。
sqr ()
指定された数字の２乗を読み取ります。
パラメーター
説明
自
２乗する数字。
Version 1.6
465
Lumberyard 開発者ガイド
Physics Lua 関数
randomF()
２つの指定された数字の間のランダム浮動小数点値を読み取ります。
パラメーター
説明
自
１つ目の数。
b
２つ目の数。
iff()
テスト値の条件をチェックし、テスト値がnilかそうでないかによって２つの値のうち１つを返しま
す。
パラメーター
説明
c
テスト値。
自
テスト値がnilでない場合、値を返します。
b
テスト値がnilである場合は値を返します。
Physics Lua 関数
これらの関数は、物理エンジンにおいて新しい爆発や亀裂形状を登録するためによく使用されます。
ファイルの場所: Game/Scripts/physics.lua
• Game/Scripts/main.lua からロード
Physics.RegisterExplosionShape ()
物理学エンジンにおいて破壊可能なオブジェクトのためのブール彫刻形状を登録します。
パラメーター
説明
sGeometryFile
ブール形状 cgf ファイルの名前。
fSize
形状の特性サイズ。
BreakId
破壊可能なマテリアルを特定するために使用される破壊可能性インデック
ス (ゼロベース)。
fProbability
形状の相対的可能性。同じサイズのいつくかの形状が彫刻対象の候補と
なった場合、これらの相対的な可能性を使用してひとつを選択します。
sSplintersfile
破損場所に木の裂片を追加するために使用する splinters cgf ファイルの名
前。
fSplintersOffset
裂片のためのサイズオフセット
sSplintersCloudEffect
splinters particle fx の名前。裂片ベースの制約が破壊され、裂片が消える
ときにこの効果が再生されます。
Version 1.6
466
Lumberyard 開発者ガイド
Integrating Lua and C++
Physics.RegisterExplosionCrack ()
物理エンジンにおける破壊可能なオブジェクトで使用する、新しい爆発亀裂を登録します。
パラメーター
説明
sGeometryFile
crack shape cgf ファイルの名前。このタイプのファイルは、隅をマークす
るために「1」、「2」、「3」という名の 3 つのヘルパーがなければいけ
ません。
BreakId
破壊可能なマテリアルを特定するために使用される破壊可能性インデック
ス (ゼロベース)。
Integrating Lua and C++
CryScriptシステムは他のシステムは他のシステムとゲームコードによって使用できるようにLua仮想
マシンを抽出します。以下のセクションで構成されます。
• スクリプト関数を呼び出す
• スクリプトに公開C++ベースの変数および関数を公開する。
• 仮想マシンのメモリに格納されているスクリプトのテーブルが作成されます。
CryScriptシステムはLua 5.に基づいています。Lua言語についての情報はhttp://www.lua.orgからご覧く
ださい。
アクセス スクリプト テーブル
グローバル スクリプト テーブルはIScriptSystem::GetGlobalValue()を呼び出すことで取得で
きます。IScriptTableはすべてのスクリプトテーブルと変数を表すために使用されます。
C++関数と値の表示
スクリプトにC++関数と変数を公開するには、新しいクラスを実行する必要があります。最も簡単な
方法は、ほとんどの機能を与える、クラスCScriptableBaseを引き出すことです。
定数のエキスポーズ
スクリプトに固定値を公開するには、IScriptSystem::SetGlobalValue()を使用します。例え
ば、スクリプトに、MTL_LAYER_FROZENという名前の定数を公開するには、次のコードを使用しま
す:
gEnv->pScriptSystem->SetGlobalValue("MTL_LAYER_FROZEN", MTL_LAYER_FROZEN);
関数の公開
スクリプトにC++機能を公開するには、次の例に示すようなCScriptableBaseから抽出される新し
いクラスを実行します。
classCScriptBind_Game :
publicCScriptableBase
{
public:
Version 1.6
467
Lumberyard 開発者ガイド
Luaスクリプトの使用
CScriptBind_Game( ISystem* pSystem );
virtual ~CScriptBind_Game() {}
intGameLog(IFunctionHandler* pH, char* pText);
};
次のコードをクラス内のコンストラクターへ追加します:
Init(pSystem->GetIScriptSystem(), pSystem);
SetGlobalName("Game");
#undef SCRIPT_REG_CLASSNAME
#define SCRIPT_REG_CLASSNAME &CScriptBind_Game::
SCRIPT_REG_TEMPLFUNC(GameLog, "text");
Luaスクリプトでは、次のようにScriptBindの新しい機能にアクセスできます:
Game.GameLog("a message");
Luaスクリプトの使用
Lumberyard はLuaをスクリプト言語に使用します。
エンティティシステムでは、データおよび関数を含めることができるテーブル形式となっているどん
なエンティティにもスクリプトプロキシを添付できます。AI動作は、スクリプトに書き込まれます。
さらに、アクター、アイテム、乗り物およびゲームルールを含むいくつかのゲームシステムは機能を
拡張するためにスクリプト作成に依存します。
スクリプトを使用する利点は次の通りです：
• 高速イテレーション – スクリプトはエンジン内でリロードすることができます。
• ランタイムパフォーマンス – 使用可能なリソースを慎重に使用することで、コンパイル済みコード
並の速度を実現します。
• 簡単トラブルシューティング – Luaの埋め込みデバッガーのトラブルシューティングはいつでも実
行できます。
Lumberyard 内のシステムの大部分はLuaにC++で書き込まれている既存コードを呼び出すことを
Luaスクリプトに許可するScriptBind機能を開示しています。詳細については、「ScriptBind の参
照 (p. 572)」を参照してください。
スクリプトの実行
コードからスクリプトファイルを直接呼び出す、またはコマンドを使用してコンソールすることでス
クリプトを実行できます。
インコード
スクリプトは \Game\Scripts ディレクトリーに保存されます。スクリプトファイルを呼び出すに
は、C++ のコードからLoadScript組み込み関数を呼び出します。 詳細については、「Integrating
Lua and C++ (p. 467)」を参照してください。他の選択肢としては、エンティティのスクリプト
化 (p. 406)の説明に従いスクリプトエンティティを作成します。
コンソール
Version 1.6
468
Lumberyard 開発者ガイド
ランタイム時のリロードのスクリプト
スクリプト指示は、ゲーム内のコンソールを使用して実行できます。指示前に# キャラクターを付加
することで実行できます。この機能は Lumberyard エディタ によって、またはランチャーをdevモー
ドで実行した場合に制限されます（-DEVMODE コマンドライン引数を使用）。
ランタイム時のリロードのスクリプト
Lumberyard エディタ 内では、ユーザーインターフェイス内のエンティティのリロードは常に可能で
す。スクリプトエンティティをリロードするときは、ロールアップバーにあるスクリプトのリロード
ボタンを選択します。
以下のScriptBind機能を使ってスクリプトをリロードすることもできます。
• Script.ReloadScript(filename)
• Script.ReloadScripts()
コンソールからこれらの機能を呼び出すには、以下のシンタックスを使用してください：
#Script.ReloadScript("Scripts\\EntityCommon.lua")
Lua Editor
Lua Editor はプレビューリリースであり、変更される可能性があります。
Lumberyard Lua Editor には、ゲームを作成または拡張する時に Lua スクリプトの作成、デバッグ、
編集を容易に行うための、直観的な統合開発環境 (IDE) が提供されています。Lua Editor はスタンド
アロンのアプリケーションですが、Lumberyard エディタ から直接開けます。
チュートリアル: Lua Editor を使用した Lumberyard
Editor でのデバッグ
このチュートリアルでは、Lumberyard エディタ を使用して、Lua スクリプトコンポーネントを含む
コンポーネントエンティティが付属したサンプルレベルを作成する方法を説明します。Lumberyard エ
ディタ から Lua Editor でスクリプトを開き、そのスクリプトでデバッグ手順のサンプルをいくつか実
行します。
Lua Editor をデバッグで使用するには
1.
Lumberyard エディタ で、以下のステップのいずれかを実行して新規のレベルを作成します。
• [Welcome to Lumberyard Editor] ウィンドウで [New level] をクリックする
• [File]、[New] の順にクリックする
• Ctrl+N を押す
2.
[New Level] ダイアログボックスで、レベルに名前を付け、[OK] をクリックします。
3.
[Generate Terrain Texture] ダイアログボックスで [OK] をクリックしてデフォルト値を受け入れ
ます。
4.
Lumberyard エディタ ビューポートを右クリックし、[Create Component Entity] を選択します。
5.
[Entity Inspector] で [Add Component] をクリックし、[Rendering]、[Light] の順に選択します。
6.
[Entity Inspector] で [Add Component] をクリックし、[Scripting]、[Lua Script] の順に選択しま
す。
Version 1.6
469
Lumberyard 開発者ガイド
チュートリアル: Lua Editor を使用し
た Lumberyard Editor でのデバッグ
7.
[Entity Inspector] ウィンドウの [Lua Script] セクションの最下部までスクロールし、[...] をクリッ
クして [Preview] ウィンドウを開きます。
8.
[Preview] ウィンドウで、[Scripts]、[components] の順に移動します。
9.
[lightflicker.lua] を選択し、[Open] をクリックします (注: 追加のサンプルスクリプトが
Lumberyard のディレクトリ \dev\SamplesProject\Scripts にあります)。
10. [Entity Inspector] の [Lua Script] セクションで、空の中括弧 [{ }] をクリックして Lua Editor を起動
します。
デバッグ機能はネットワークソケットを介して有効になるため、デバッグを開始する前に、スク
リプトを実行するターゲットに Lua Editor を接続する必要があります。このチュートリアルで
は、Lumberyard エディタ に接続します。
Note
接続は GridHub (p. 569) により支援されます。これは、デバッグに使用する
Lumberyard の中央接続ハブです。Lua Editor が起動されると GridHub が自動的に起動さ
れます。これは、Lua Editor が接続可能なターゲットを探すために、Lua Editor のバック
グラウンドで動作する必要があります。何らかの理由で Lua Editor を手動で起動する場
合は、\dev\Bin64\LuaIDE.exe で起動できます。
11. Lua Editor のツールバーで、[Target: None] をクリックしてから、[Editor(ID)] をクリックして
Lumberyard エディタ に接続します。
12. Lua Editor ツールバーで、[Context] の設定をデバッグコンテキストの [Default] のままにします。
このチュートリアルで使用するようなコンポーネントエンティティスクリプトのデバッグでは、
デフォルト設定が適しています。[Cry] オプションは、Cry エンティティまたは Game SDK に関
連付けられているようなレガシースクリプトのデバッグに使用します。
13. アタッチ/デタッチアイコンをクリックします。
14. Alt+Tab キーを押して Lumberyard エディタ にフォーカスを変更し、その後に再度 Alt+Tab キー
を押してフォーカスを Lua Editor に戻します。
Note
この Alt+Tab キーのステップは、発生する問題に対する一時的な対処方法です。これは
Lua Editor の次のリリースで修正されます。
フォーカスが Lumberyard エディタ に変更されると、アタッチ/デタッチアイコンが緑色に変わ
り、Lua Editor と Lumberyard エディタ が接続されたことが示されます。
Version 1.6
470
Lumberyard 開発者ガイド
チュートリアル: Lua Editor を使用し
た Lumberyard Editor でのデバッグ
使用可能な Lua ライブラリの情報が [Class Reference] ウィンドウに表示されます。
Note
クラスリファレンス機能は、デフォルトのコンテキストとコンポーネントエンティティ
スクリプトに対してのみ有効です。この機能は Cry コンテキストでは無効です。このコ
ンテキストは下位互換性のためにのみ存在します。
接続した後、ブレークポイントの設定によって、指定したスクリプトの実行が一時停止できま
す。
15.
[Lua Editor] ツールバーで [Breakpoints] アイコン
を表示します。
をクリックして、[Breakpoints] ウィンドウ
16. Lua Editor で、lightflicker.lua スクリプト内の 1 つまたは複数の行番号をクリックまたは
ダブルクリックして、1 つ以上のブレークポイントを設定します。ブレークポイントを追加する
と、その行番号とスクリプトパスが [Breakpoints] ウィンドウに追加されます。
17. Lumberyard エディタ で、Ctrl+G キーを押してゲームを実行するか、ビューポートの下部にあ
る [AI/Physics] をクリックしてゲームのシミュレーションを有効にし、スクリプトを実行しま
す。Lua Editor が開き、到達して停止した最初のブレークポイントが黄色のマーカーで表示され
ます。
Version 1.6
471
Lumberyard 開発者ガイド
個別の検索結果の保持
ブレークポイントで実行が停止すると、[Lua Locals]、[Stack]、[Watched Variables] の各ペイン
に詳細情報が表示されます。
18.
19.
20.
[Stack] アイコン
をクリックして [Stack] ウィンドウを表示します。
[Lua Locals] アイコン
をクリックして Lua のローカル変数を表示します。
[Watched Variables] アイコン
をクリックして [Watched Variables] ウィンドウを開きます。
ここでは表示する変数が指定できます。
21. F11 キーを数回押して、コードを進めます。[Stack]、[Lua Locals]、[Watched Variables] の各
ウィンドウの内容がどのように変化するかに注目してください。
Tip
より使いやすくするために、これらを浮動ウィンドウにしたり固定ウィンドウにしたり
できます。
22. デバッグからデタッチするには、アタッチ/デタッチアイコンをクリックします。
23. Lumberyard エディタ で、Esc キーを押してゲームを停止します。
デバッグ時に使用できるオプション
次の表は、デバッグ時に使用できる共通オプションの概要を示しています。
アイコン
アクション
キーボードショート
カット
説明
エディタで実行
Alt+F5
Lumberyard エディタ で実行します。
ターゲット上で実
行
Ctrl+F5
接続したターゲットにスクリプトを送
信して、そこで実行します。
実行/続行
F5
現在のスクリプトを実行、または実行
を続行します。
入る
F11
現在の行で呼び出されている関数に入
ります。
出る
Shift+F11
呼び出された関数から出ます。
全体を実行
F10
現在の行で呼び出されている関数全体
を実行します。
ブレークポイント
を切り替え
F9
現在の行のブレークポイントを有効化
または無効化します。
個別の検索結果の保持
通常の検索機能に加えて、[Find] 機能では 4 つの異なる検索結果を別個に表示できます。
Version 1.6
472
Lumberyard 開発者ガイド
個別の検索結果の保持
個別の検索結果を保持するには
1.
[Find] アイコン
をクリックするか、Ctrl+F キーを押して、現在開いているファイルまたは開
いているすべてのファイルで検索を実行します。
2.
検索を開始する前に、[Find 1]、[Find 2]、[Find 3]、または [Find 4] を選択して、結果を表示する
ウィンドウを選択します。タブ付きウィンドウで、4 つの検索結果を別々に保持できます。他の
ウィンドウの検索結果は変わりません。
3.
検索結果で示されたコードの行に直接進むには、検索結果の行をダブルクリックします。
Note
[Lua Editor Preview] では、[Find Results] ウィンドウに表示される行番号とスクリプトペ
インの行番号は 1 だけ異なります。
Tip
使いやすくするために、[Find Results] ウィンドウを固定ウィンドウや浮動ウィンドウに
することもできます。
Version 1.6
473
Lumberyard 開発者ガイド
AWS OpsWorks の
AWS OpsWorks の
Lua Editor では、同時に複数のスクリプトが開けます。エディタには、各スクリプトのタブが表示さ
れます。エディタにはテキストを編集するための標準的な機能が用意されていますが、ソースコード
の編集に利用できる便利な機能もあります。
次の表は、編集やデバッグで使用できるオプションの概要を示しています。
アクション
キーボードショートカット
選択したブロックにコメントを入力
Ctrl+K
コピー
Ctrl+C
切り取る
Ctrl+X
Find
Ctrl+F
開いているファイルで検索
Ctrl+Shift+F
次を検索
F3
ソース関数を折りたたむ
Alt+0
行に移動
Ctrl+G
貼り付ける
Ctrl+V
ローカルでクイック検索
Ctrl+F3
ローカルで逆方向にクイック検索
Ctrl+Shift+F3
再実行
Ctrl+Y
置換
Ctrl+R
開いているファイルで置換
Ctrl+Shift+R
すべて選択
Ctrl+A
中括弧を選択¹
Ctrl+Shift+]
行を下に移動
Ctrl+Shift+ 下矢印
行を上に移動
Ctrl+Shift+ 上矢印
選択したブロックのコメントを削除
Ctrl+Shift+K
元に戻す
Ctrl+Z
ソース関数を開く
Alt+Shift+0
Perforce 統合
Lua Editor には Perforce 統合の機能があります。Perforce 環境からファイルを開くと、Lua Editor は
テキスト編集ウィンドウの右上にファイルのステータスを表示します。
Version 1.6
474
Lumberyard 開発者ガイド
Luaのリモートデバッガーを使用する
[Source Control] メニューには、[Check Out/Check In] 機能が提供されています。
Luaのリモートデバッガーを使用する
LumberyardはLuaのスタンドアロンビジュアルスクリプトのデバッガーを含みます。デバッガーを開
始するには、まずコンソールを有効にし、それからLuaRemoteDebugger.exeで実行可能なファイル
を実行します。
1.
Lumberyard エディタコンソールもしくはゲームコンソールで、lua_debugger 1もしく
はlua_debugger 2を入力します。これは、次の２つのモードのうち１つのデバッグを有効にし
ます:
• モード１－デバッガーが両方のブレークポイントとスクリプトエラーを停止する
2.
3.
4.
5.
• モード２ーデバッガーがスクリプトがエラーにのみ停止する。
\dev\Tools\LuaRemoteDebugger\LuaRemoteDebugger.exeの Lumberyard ディレクトリロ
ケーションのLuaリモートデバッガーで実行可能なファイルを実行します。
Luaリモートデバッガーで、ファイルメニュー上の 接続を選択してください。
エディターでゲームを実行し（Ctrl-Gを押した状態）かつスクリプトをデバッグしたい場合
は、PC(エディター)を選択してください。構築ゲーム実行ファイルにデバッガーを添付したい場
合は、PC(ゲーム）を選択してください。
IPアドレスとポートには、接続したいコンピューターのIPアドレスとポートを入力します。デ
フォルトオプションはローカルコンピュータのゲームに接続します。デフォルトのIPアドレス
は127.0.01 (localhost)です。 PC(エディター)のデフォルトポートは9433です。 PC(ゲーム)のデ
フォルトポートは9432です。
接続を選択します。Lumberyard エディタで、コンソールウィンドウは接続されたLuaリモートデ
バッグのクライアントを表示します。
Luaリモートデバッガーを初めて実行すると、自動的にスクリプトのフォルダに移動します。
6.
デフォルトのフォルダは、実行中のプロジェクトの#####フォルダーです。たとえば、サンプル
プロジェクトを実行している場合は、フォルダーはsamplesproject/Scriptsとなります。
デフォルトの場所を受け入れるには、はいをクリックします。
Note
スクリプトフォルダの場所を変更するには、ファイルとスクリプトフォルダー設定を選
びます。
Version 1.6
475
Lumberyard 開発者ガイド
Luaリモートデバッガー内でタスクを実行する
スクリプトフォルダの場所を選択すると、フォルダの内容は左側にあるナビゲーションのツリー
に示されます。
Luaリモートデバッガー内でタスクを実行する
Luaリモートデバッガーで特定のタスクを実行するには、次の表
目的
処理
スクリプトファイルを開
きます。
ナビゲーションペインのツリースクリプトファイルをダブルクリック
するか、Ctrl+O を押して、[ファイルを探す] ダイアログを開きます。
ブレークポイントを設定
します。
ブレークを発生させたいスクリプト内の行の上にカーソルを置き、
ツールバーの赤い点をクリックするかもしくはF9を押します。プログ
ラムの実行がブレークポイントで停止すると、スタック呼び出しおよ
びローカルタブが表示されます。
ブレークポイントを削除
します
削除したいブレークポイントのある行にカーソルを置き、ツールバー
の赤い点をクリックするかF9をクリックしてください。
ブレークポイントタブを
使用します。
ブレークポイントタブウィンドウは、横にチェックボックスのある各
ブレークポイントを表示します。ブレークポイントを有効/無効にし
たい場合は、チェックボックスを選択/解除してください。スクリプト
ウィンドウで、ブレークポイントのステータスは色によって示されま
す。赤はアクティブ、グレーは無効を意味します。
変数値をウォッチ（調
査）する
ブレークポイントで実行が一時停止するときは、ウォッチのタブをク
リックし、空白の行の最初の列をクリックして、ウォッチしたい変数
の名前を入力します。
実行を一時停止する
ツールバーの一時停止 （中断）ボタンをクリックするかCtrl+Alt
+Pauseを押します。
実行を再開する
ツールバーの再生ボタンをクリックするかF5を押します。
手順を繰越す
オリジンアクセスアイデンティティの追加先であるディストリビュー
ションの
手順を割り込む
オリジンアクセスアイデンティティの追加先であるディストリビュー
ションの
手順を中断する
ツールバーアイコンかF10を押します。
ツールバーアイコンかF11を押します。
オリジンアクセスアイデンティティの追加先であるディストリビュー
ションの
ツールバーアイコンかShift+F11を押します。
スクリプトファイルを閉
じます。
ファイルを選択し、閉じるまたはCtrl+Wを押します。
エディタまたはゲームか
ら接続を切断する
Luaデバッガーでファイルを選び、接続を切断するを選択しま
す。Lumberyard コンソールはネットワークコネクションが切断され
たというメッセージを表示します。
Version 1.6
476
Lumberyard 開発者ガイド
Lua XML ローダーの使用
Note
デバッガーウィンドウで変更したコードはロードされたスクリプトを変更せず、デバッガー
ウィンドウが閉じられた後に破棄されます。
Lua XML ローダーの使用
XML ファイルを解析して Lua ファイルに変換するための汎用インターフェイスがあります。このイン
ターフェイスでは、ファイルに含まれている XML の種類とその XML から作成される Lua の種類を宣
言する定義形式として 1 つの XML ファイルが使用されます。その形式には、受け取ったデータが想
定どおりであることを確認するための単純な検証方法が含まれています。
XML データ
XML ローダーは、プロパティ、配列、テーブルの 3 種類のデータを区別できます。
テーブル
次のテーブルは Lua ベースのテーブルを示しています。
letters = { a="a", b="b", c="c" };
XML データファイルでは、このテーブルは次のようになります。
<letters a="a" b="b" c="c"/>
XML 定義ファイルは次のようになります。
<Table name="letters">
<Property name="a" type="string"/>
<Property name="b" type="string"/>
<Property name="c" type="string"/>
</Table>
定義ファイルでは、optional="1" 属性を使用して、各要素をオプションとしてマークできます。
配列
配列には 2 つのタイプがあります。最初の種類は、Lua では次のように示される、要素の単純なグ
ループです。
numbers = {0,1,2,3,4,5,6,7,8,9}
XML データファイルでは、配列は次のようになります。
<numbers>
<number
<number
<number
<number
<number
<number
value="0"/>
value="1"/>
value="2"/>
value="3"/>
value="4"/>
value="5"/>
Version 1.6
477
Lumberyard 開発者ガイド
Lua からのテーブルのロードと保存
<number value="6"/>
<number value="7"/>
<number value="8"/>
<number value="9"/>
</numbers>
データ定義ファイルは次のようになります。
<Array name="numbers" type="int" elementName="number"/>
2 番目の種類はテーブルの配列です。Lua では次のようになります。
wheels = {
{size=3, weight=10},
{size=2, weight=1},
{size=4, weight=20},
}
XML データファイルでは次のようになります。
<wheels>
<wheel size="3" weight="10"/>
<wheel size="2" weight="1"/>
<wheel size="4" weight="20"/>
</wheels>
XML 定義ファイルでは次のようになります。
<Array name="wheels" elementName="wheel"> <!-- note no type is attached -->
<Property name="size" type="float"/>
<Property name="weight" type="int"/>
</Array>
Lua からのテーブルのロードと保存
Lua テーブルをロードして初期化するには次のようにします。
someTable = CryAction.LoadXML( definitionFileName, dataFileName );
スクリプト用の XML ファイルを保存する場合に推奨される方法は、スクリプトで使用されている定義
ファイルをスクリプトと一緒に保持し、Scripts ディレクトリの外部のディレクトリにデータファイル
を保存することです。
Lua からテーブルを保存するには次のようにします。
CryAction.SaveXML( definitionFileName, dataFileName, table );
データ型
以下のデータ型を使用でき、定義ファイルに "type" 属性がある場合はいつでも設定できます。
• float – 浮動小数点数。
Version 1.6
478
Lumberyard 開発者ガイド
列挙型
• int – 整数。
• string – 文字列。
• bool – ブール値。
• Vec3 – 3 つのコンポーネントを持つ浮動小数点ベクトル。この型の値は次のように表現されます:
• XML – "1,2,3"
• Lua – {x=1,y=2,z=3}
列挙型
文字列型のプロパティに対しては、<Enum> 定義を使用できます。プロパティ値は列挙型として検証
されます。
例:
<Property name="view" type="string">
<Enum>
<Value>GhostView</Value>
<Value>ThirdPerson</Value>
<Value>BlackScreen</Value>
</Enum>
</Property>
他のデータ型での列挙型のサポートは、必要に応じて追加できます。
例
XML 定義ファイル:
<Definition root="Data">
<Property name="version" type="string"/>
<Table name="test">
<Property name="a" type="string"/>
<Property name="b" type="int" optional="1"/>
<Array name="c" type="string" elementName="Val"/>
<Array name="d" elementName="Value">
<Property name="da" type="float"/>
<Property name="db" type="Vec3"/>
</Array>
<Property name="e" type="int"/>
</Table>
</Definition>
対応する XML データファイル:
<Data version="Blag 1.0">
<test
a="blag"
e="3">
<c>
<Val value="blag"/>
Version 1.6
479
Lumberyard 開発者ガイド
推奨する参照情報
<Val value="foo"/>
</c>
<d>
<Value da="3.0" db="2.1,2.2,2.3"/>
<Value da="3.1" db="2.1,2.2,2.3"/>
<Value da="3.2" db="3.1,3.2,2.3"/>
</d>
</test>
</Data>
推奨する参照情報
Lumberyard でスクリプトを使用する場合は、Lua 言語に関する次のリソースを読むことをお勧めしま
す。
• Lua 5.1 Reference Manual
• Programming in Lua, Third Edition
• その他の書籍
Version 1.6
480
Lumberyard 開発者ガイド
マルチプレイヤの開始方法
ネットワークシステム
GridMate は Lumberyard のネットワーキングサブシステムです。GridMate は、効率的な帯域幅の利
用率と低レイテンシー通信のために設計されています。GridMate のレプリカフレームワークを使用
すると、ネットワーク経由でオブジェクトを同期できます。GridMate のセッション管理は主要なオン
ラインコンソールサービスに統合され、ホスト移行によりピアツーピアトポロジおよびクライアント
サーバートポロジを処理できます。また GridMate は、ゲーム内の達成項目、リーダーボード、およ
び Xbox Live、PlayStation Network、および Steam などのサードパーティーのソーシャルサービスを
介して保存されたクラウドベースのゲームをサポートします。マルチプレイヤプロジェクトの設定方
法の例については、Amazon Lumberyard User Guideのマルチプレイヤサンプルプロジェクトを参照し
てください。
このセクションでは、Amazon Lumberyard ゲームネットワーキング環境のさまざまなコンポーネン
トおよびセットアップ要件について説明します。ネットワーキングの診断ツールの詳細については、
「プロファイラー (p. 540)」を参照してください。
トピック
• マルチプレイヤの開始方法 (p. 481)
• セッションサービス (p. 484)
• Carrier (p. 490)
• レプリカを使用したゲームの状態の同期 (p. 493)
• OpenSSL の使用 (p. 510)
• 帯域幅の利用率の制御 (p. 515)
• ネットワークのシリアル化と各側面 (p. 517)
• RMI 関数 (p. 518)
マルチプレイヤの開始方法
このセクションでは、マルチプレイヤサーバーのセットアップ、マルチプレイヤサーバーでのゲーム
のホスト、ゲームへの接続、およびコンソールコマンドを使用したサーバーの制御を行う方法につい
て説明します。
マルチプレイヤサーバーのセットアップ
マルチプレイヤレベルを作成して設定し、このレベルを Lumberyard にエクスポートした後、新しい
レベルをホストするサーバーを実行できます。
新しいレベルをホストする前に、以下を行う必要があります。
Version 1.6
481
Lumberyard 開発者ガイド
レベルのホスティング
• レベルを再生するために使用するすべてのコンピュータに同じ SDK ビルドがインストールされてい
ることを確認します。
• レベルを再生する各 SDK インストールにマルチプレイヤレベルディレクトリをコピーします。
例: \<root>\Game\Levels
• 他のプレイヤがゲームに参加することを許可する際に使用するホストサーバーの IP アドレスを識別
します。
レベルのホスティング
少しのステップで、サーバーにレベルをホストすることができます。
サーバーでレベルをホストする
1.
ホストサーバーで、ゲームの実行ファイルを実行します。
2.
コンソールから、実行するタスクのコマンドを実行します。
• sv_port <local_port> – マルチプレイヤーサービスのインバウンドポートを設定しま
す。<local_port> を、ソケットを初期化するために使用する UDP ローカルポートに置き換
えます (オプション)。デフォルトでは、ポート 64090 が使用されます。
• mphost – セッションをホストします。サーバーは、sv_port で指定したポートで着信接続を
リッスンします。
• map <map_name> – 指定したマップを起動します。<map_name> を、使用するマップの名前に
置き換えます。
サーバーへの接続
サーバーが実行状態になると、マルチプレイヤゲームをプレーする各コンピュータから、ホストされ
たゲームに接続できます。
サーバーに接続する
1.
コンピュータで、ゲームの実行ファイルを実行します。
2.
コンソールから、実行するタスクのコマンドを実行します。
• sv_port <local_port> – マルチプレイヤーサービスのインバウンドポートを設定しま
す。<local_port> を、ソケットを初期化するために使用する UDP ローカルポートに置き換
えます (オプション)。デフォルトでは、ポート 64090 が使用されます。同じコンピュータで
サーバーに接続するには、<local_port> を 0 に置き換えて一時ポートを使用します。
Note
サーバーと同じコンピュータでクライアントを実行する場合は、一時ポートを使用す
るようにクライアントを設定します。ポートの競合を防ぐために、sv_port 0 を呼び
出します。
• mpjoin <server_addr> <server_port> – ゲームインスタンスを参加させま
す。<server_addr> および <server_port> 設定はオプションです。デフォルトで
は、Localhost:64090 が使用されます。
コンソールコマンドの概要
ネットワークサーバーを操作するときは、次のコマンドを使用します。
Version 1.6
482
Lumberyard 開発者ガイド
コンソールコマンドの概要
gm_debugdraw debug_draw_level
デバッグ描画レベルを設定します。描画するデバッグデータのフラグをビットで表した数字をパ
ラメーターとして受け入れます。たとえば、1 に設定されている場合は、GridMate のネットワー
ク統計および情報のオーバーレイが表示されます。
enum DebugDrawBits から利用できるビットフラグは次のとおりです。
enum DebugDrawBits
{
Basic
Trace
Stats
Replicas
Actors
EntityDetail
Full
All
=
=
=
=
=
=
BIT(0),
BIT(1),
BIT(2),
BIT(3),
BIT(4),
BIT(5),
= Basic | Trace | Stats | Replicas | Actors,
= 0xffffffff,
};
gm_disconnectDetection
0 に設定すると、切断の検出が無効になります。このコマンドは、サーバーまたはクライアント
をデバッグしているとき、コード内をあちこち移動する際に切断されないようにする場合に便利
です。デフォルト値は 1 です。
gm_dumpstats
GridMate のネットワークプロファイリング統計情報をファイルに書き込みます。
gm_dumpstats_file
GridMate のプロファイリング統計情報が書き込まれるファイル。デフォルトは
net_profile.log です。
gm_net_simulator
GridMate ネットワークシミュレーターをアクティブ化し、レイテンシー、パケット損失、帯
域幅制限、およびその他の状態をシミュレートします。利用可能なオプションを表示するに
は、gm_net_simulator help と入力してください。
gm_setdebugdraw
GridMate の詳細なネットワーク統計および情報のオーバーレイを表示します。ユーザーが使いや
すい、gm_debugdraw debug_draw_level のヘルパーコマンドです。使用できるパラメーター
は、Basic、Trace、Stats、Replicas、および Actors です。
gm_stats_interval_msec
ネットワークプロファイリング統計を収集するときの間隔をミリ秒単位で設定します。デフォル
トは 1000 です。
gm_tracelevel trace_level
GridMate のデバッグトレースの詳細レベルを設定します。デフォルトは 0 です。値が大きくなる
と、より詳細になります。通常の値の範囲は 1 ～ 3 です。
mphost
ホストとしてセッションを作成します。サーバーは、sv_port で指定したポートで着信接続を
リッスンします。
mpjoin [<server_addr>] [<server_port>]
オプションで指定した <server_addr> と <server_port> でサーバーに接続します。デフォル
トは、それぞれ localhost と 64090 です。
map <map_name>
指定したマップ名でレベルをロードします。<map_name> を、使用するマップの名前に置き換え
ます。利用可能なレベルのリストを表示するには、map と入力し、Tab キーを押します。
mpdisconnect
ゲームインスタンスの現在のセッションを終了します。
Version 1.6
483
Lumberyard 開発者ガイド
サンプルプロジェクト
sv_port [<local_port>]
ソケットを初期化する UDP ポートを設定します。デフォルトのポート番号は 64090 です。一時
ポートを使用するには、ポートを 0 に設定します。このコマンドは、クライアントと同じコン
ピュータにあるサーバーに接続する場合に便利です。
サンプルプロジェクト
マルチプレイヤプロジェクトをセットアプする方法の例については、Amazon Lumberyard User
Guideのマルチプレイヤサンプルプロジェクトを参照してください。
セッションサービス
GridMate のセッションサービスは、セッションの接続および管理に使用します。ハブアンドスポー
ク (クライアント/サーバー) トポロジと P2P フルメッシュトポロジの両方がサポートされており、各
GridMate インスタンスに対して複数のセッションを作成することができます。
各セッションでは、それぞれのキャリアマネージャーインスタンスおよびレプリカマネージャーイン
スタンスが作成されるため、セッション間のやり取りはありません。GridMate セッションでは、P2P
モードでの実行時ホスト移行がサポートされます。
セッションサービスの開始と停止
GridMate でセッションサービスを開始するには、次を呼び出します。
GridMate::StartGridMateService<LANSessionService>(gridmate,
GridMate::SessionServiceDesc());
サービスを停止するには、次を呼び出します。
IGridMate::UnregisterService();
これにより、現在のセッションおよび検索がすべて終了します。
セッションサービス開始の例
次に示す LAN マルチプレイヤーサービス例では、オンラインサービスがまだ開始されていない場合、
開始されます。
IGridMate* gridmate = gEnv->pNetwork->GetGridMate();
if (gridmate)
{
GridMate::StartGridMateService<LANSessionService>(gridmate,
GridMate::SessionServiceDesc());
}
セッションのホスティング
セッションをホストするには、SessionService::HostSession() を呼び出します。この関数
は、2 つの引数 (SessionParams、CarrierDesc) を受け取ります。この関数では、GridSession
ポインタが返されます。
Version 1.6
484
Lumberyard 開発者ガイド
セッションのホスティング
SessionParams は、セッションのトポロジ、スロットの数、マッチメーキングプロパティを設定す
るために使用されます。現在のセッションのバインド先ローカルユーザーも、SessionParams を使
用して設定されます。
CarrierDesc は、現在のセッションに使用されるキャリアパラメーターの設定に使用されま
す。CarrierDesc パラメーターについては、「CarrierDesc パラメーター (p. 491)」を参照してく
ださい。
SessionService::HostSession() から返されるポインタ
は、GridSessionCallbacks::OnSessionDelete() イベントが発生するまで有効です。
セッションホスティングの例
GridMate セッションを作成して、セッションに接続するクライアントをリッスンするコンポーネント
の例を次に示します。
// GridMateHost
#include <AZCore/Component/Component.h>
#include <AZCore/Component/TickBus.h>
#include <GridMate/GridMate.h>
#include <GridMate/Session/Session.h>
#include <GridMate/Session/LANSession.h>
class HostComponent
: public AZ::Component
, public AZ::TickBus::Handler
, public GridMate::SessionEventBus::Handler
{
GridMate::IGridMate* mGridMate;
GridMate::LANSessionService* mMultiplayerService;
mMultiplayerService;
GridMate::GridSession* mSession;
public:
AZ_COMPONENT(HostComponent, "{41900198-1122-4392-A579-CDDC85A23277}");
HostComponent() : mSession(nullptr), mGridMate(nullptr),
mMultiplayerService(nullptr) {}
// Events from GridMate::SessionEventBus
void OnSessionCreated(GridMate::GridSession* session) override {};
void OnSessionError(GridMate::GridSession* session, const
GridMate::string& error) override {};
void OnMemberJoined(GridMate::GridSession* session, GridMate::GridMember*
member) {};
void OnMemberLeaving(GridMate::GridSession* session,
GridMate::GridMember* member) {};
void Init() override { }
void Activate() override
{
// The GridMate specific memory allocators must be created before
setting up GridMate.
// If multiple GridMate instances are to be created (e.g. one per
component) this needs
// to be called at that time that the ComponentApplication is
initialized.
AZ::AllocatorInstance<GridMate::GridMateAllocator>::Create();
AZ::AllocatorInstance<GridMate::GridMateAllocatorMP>::Create();
Version 1.6
485
Lumberyard 開発者ガイド
セッションのホスティング
// The port that all game data will be transmitted.
static const AZ::s32 GAME_SEARCH_PORT = 40000;
// The port that is listening for clients searching for games on the
LAN.
static const AZ::s32 GAME_PORT = 20000;
// Initialize GridMate and services systems.
mGridMate = GridMate::GridMateCreate(GridMate::GridMateDesc());
mMultiplayerService =
GridMate::StartGridMateService<LANSessionService>(mGridMate,
GridMate::SessionServiceDesc());
// Attach this component to the event bus.
AZ::TickBus::Handler::BusConnect();
GridMate::SessionEventBus::Handler::BusConnect(mGridMate);
// Configure the session
GridMate::LANSessionParams sessionParam;
sessionParam.m_topology = GridMate::ST_CLIENT_SERVER;
sessionParam.m_numPublicSlots = 2;
sessionParam.m_numPrivateSlots = 0;
sessionParam.m_port = GAME_SEARCH_PORT;
sessionParam.m_peerToPeerTimeout = 60000;
sessionParam.m_flags = 0;
sessionParam.m_numParams = 0;
// Configure the carrier used by the host.
GridMate::CarrierDesc carrierDesc;
carrierDesc.m_enableDisconnectDetection = true;
carrierDesc.m_connectionTimeoutMS = 10000;
carrierDesc.m_threadUpdateTimeMS = 30;
carrierDesc.m_version = 1;
carrierDesc.m_port = GAME_PORT;
// Start creating the session.
// This operation is asynchronous and is only considered complete
when
// OnSessionCreated() or OnSessionError() events are called.
mSession = mMultiplayerService->HostSession(&params, carrierDesc);
}
void Deactivate() override
{
if (mSession)
mSession->Leave(0);
GridMate:SessionEventBus::Handler::BusDisconnect(mGridMate);
AZ::TickBus::Handler::BusDisconnect();
gridMate->UnregisterService(mMultiplayerService);
mMultiplayerService = nullptr;
mGridMate = nullptr;
}
void OnTick(float dateTime, AZ::ScriptTimePoint t)
{
// Update the GridMate system each tick.
mGridMate->Update();
}
static void Reflect(AZ::ReflectContext* context) {};
Version 1.6
486
Lumberyard 開発者ガイド
セッションの検索
};
セッションの検索
使用可能なセッションを検索するには、SessionService::StartGridSearch() を呼び出します。
この関数は、検索の完了時に見つかったセッションのリストが含まれる GridSearch ポインタを返し
ます。検索完了イベントは、SessionService::StartGridSearch() から返される GridSearch
ポインタと共に、GridSessionCallbacks::OnGridSearchComplete() を通じて送信されます。
検索を取り消すには、GridSearch::AbortSearch() を使用します。
GridSearch ポインタは、GridSessionCallbacks::OnGridSearchRelease() イベントが発生
するまで有効です。
セッションへの参加
セッションには、検索によって返された SearchInfo ポインタを使用して
SessionService::JoinSession() を呼び出すことで参加できます。この関数で
は、GridSession ポインタが返されます。クライアントが正常にセッションに参加する
と、GridSessionCallbacks::OnSessionJoined() を通じてイベントが送信されます。
SessionService::JoinSession() から返されるポインタ
は、GridSessionCallbacks::OnSessionDelete() イベントが発生するまで有効です。
セッションへの参加の例
GridMate セッションを検索し、最初に見つかったセッションに参加するコンポーネントの例を次に示
します。
// GridMateJoin
#include <AZCore/Component/Component.h>
#include <AZCore/Component/TickBus.h>
#include <GridMate/GridMate.h>
#include <GridMate/Session/LANSession.h>
#include <GridMate/Session/Session.h>
class JoinComponent
: public AZ::Component
, public AZ::TickBus::Handler
, public GridMate::SessionEventBus::Handler
{
GridMate::IGridMate* mGridMate;
GridMate::LANSessionService* mMultiplayerService;
GridMate::GridSession* mSession;
GridMate::GridSearch* mSearch;
public:
AZ_COMPONENT(JoinComponent, "{41900198-1122-4392-A579-CDDC85A23277}");
JoinComponent() : mSession(nullptr), mGridMate(nullptr),
mMultiplayerService(nullptr) {}
// Events from GridMate::SessionEventBus
void OnSessionJoined(GridMate::GridSession* session) override {};
void OnSessionError(GridMate::GridSession* session, const
GridMate::string& error) override {};
void OnMemberJoined(GridMate::GridSession* session, GridMate::GridMember*
member) {};
Version 1.6
487
Lumberyard 開発者ガイド
セッションへの参加
void OnMemberLeaving(GridMate::GridSession* session,
GridMate::GridMember* member) {};
void OnGridSearchComplete(GridMate::GridSearch* search)
{
if(search->GetNumResults() > 0)
{
const GridMate::SearchInfo* result = search->GetResult(0);
GridMate::CarrierDesc;
carrierDesc.m_enableDisconnectDetection = true;
carrierDesc.m_connectionTimeoutMS = 10000;
carrierDesc.m_threadUpdateTimeMS = 30;
carrierDesc.m_version = 1;
carrierDesc.m_port = 0;
// Join the session.
// This operation is asynchronous and is only considered complete
when
// OnSessionJoined() or OnSessionError() events are called.
mSession = mMultiplayerService->JoinSession(result,
GridMate::JoinParams(), carrierDesc);
}
}
void Init() override { }
void Activate() override
{
// The GridMate specific memory allocators must be created before
setting up GridMate.
// If multiple GridMate instances are to be created (e.g. one per
component) this needs
// to be called at that time that the ComponentApplication is
initialized.
AZ::AllocatorInstance<GridMate::GridMateAllocator>::Create();
AZ::AllocatorInstance<GridMate::GridMateAllocatorMP>::Create();
// The port that all game data will be transmitted.
static const AZ::s32 GAME_SEARCH_PORT = 40000;
// The port that is listening for clients searching for games on the
LAN.
static const AZ::s32 GAME_PORT = 20000;
// Initialize GridMate and services systems.
mGridMate = GridMate::GridMateCreate(GridMate::GridMateDesc()
// Attach this component to the event bus.
AZ::TickBus::Handler::BusConnect();
GridMate::SessionEventBus::Handler::BusConnect(mGridMate);
// Search for games on the LAN.
GridMate::LANSearchParams params;
params.m_serverPort = GAME_SEARCH_PORT;
mSearch = mMultiplayerService->StartGridSearch(&params);
}
void Deactivate() override
{
if(mSession)
mSession->Leave(0);
Version 1.6
488
);
Lumberyard 開発者ガイド
セッションイベントへの対応
GridMate:SessionEventBus::Handler::BusDisconnect(mGridMate);
AZ::TickBus::Handler::BusDisconnect();
GridMate::GridMateDestroy(mGridMate);
mMultiplayerService = nullptr;
mGridMate = nullptr;
}
void OnTick(float dateTime, AZ::ScriptTimePoint t)
{
// Update the GridMate system each tick.
mGridMate->Update();
}
static void Reflect(AZ::ReflectContext* context) {};
};
セッションイベントへの対応
GridMate セッションイベントは、GridMate::SessionEventBus を通じて送信されます。セッショ
ンイベントをリッスンするには、次のステップを実行します。
セッションイベントをリッスンするには
1.
2.
3.
SessionEventBus::Listener からリスナーを取得します。
4.
GridSession インスタンスと GridSearch インスタンスを区別するために、イベントと共に
GridSession ポインタまたは GridSearch ポインタを渡します。
GridSessionCallbacks インターフェイスを実装します。
対応する GridMate ポインタを使用して、リスナーを接続します。
イベントの説明
各セッションイベントの説明は次のとおりです。
virtual void OnSessionServiceReady()
セッションサービスによるセッション処理の準備が整うと発生するコールバック。
virtual void OnGridSearchStart(GridSearch* gridSearch)
グリッド検索が開始されるときのコールバック。
virtual void OnGridSearchComplete(GridSearch* gridSearch)
ゲーム検索クエリが完了したときにタイトルを通知するコールバック。
virtual void OnGridSearchRelease(GridSearch* gridSearch)
グリッド検索が開放 (削除) されたときのコールバック。このイベントが発生した後にグリッドの
ポインタを保持することは、安全ではありません。
virtual void OnMemberJoined(GridSession* session, GridMember* member)
新しいメンバーがゲームセッションに参加するときにタイトルを通知するコールバック。
virtual void OnMemberLeaving(GridSession* session, GridMember* member)
メンバーがゲームセッションを離れることを示すタイトルを通知するコールバック。
Caution
このコールバックからの復帰後は、メンバーのポインタが有効ではありません。
virtual void OnMemberKicked(GridSession* session, GridMember* member)
ホストがメンバーの接続を切断すると決定したときに発生するコールバック。実際のメンバーが
セッションを離れるときには、OnMemberLeaving イベントがトリガーされます。
Version 1.6
489
Lumberyard 開発者ガイド
GameLift によるクラウドホスティング
virtual void OnSessionCreated(GridSession* session)
セッションが作成されるときに発生するコールバック。このコールバックの発生後にセッション
機能にアクセスすることは安全です。クライアントが OnSessionJoined イベントを待機してい
れば、ホストセッションは完全に動作しています。
virtual void OnSessionJoined(GridSession* session)
セッションへの参加が正常に完了したことを示すために、クライアントコンピューターで呼び出
されます。
virtual void OnSessionDelete(GridSession* session)
セッションから離れるときにタイトルを通知するコールバック。
Caution
このコールバックからの復帰後、セッションのポインタは有効ではありません。
virtual void OnSessionError(GridSession* session, const string& errorMsg )
セッションエラーが発生したときに呼び出されます。
virtual void OnSessionStart(GridSession* session)
ゲーム (マッチ) が開始するときに呼び出されます。
virtual void OnSessionEnd(GridSession* session)
ゲーム (マッチ) が終了すると呼び出されます。
virtual void OnMigrationStart(GridSession* session)
ホストの移行が開始すると呼び出されます。
virtual void OnMigrationElectHost(GridSession* session,GridMember*& newHost)
新しいホストになるメンバーをユーザーが選択できるようにするために呼び出されます。
Note
値が null の場合、値が現在のホストの場合、またはメンバーの接続 ID が無効の場合は、
値が無視されます。
virtual void OnMigrationEnd(GridSession* session,GridMember* newHost)
ホストの移行が完了すると呼び出されます。
virtual void OnWriteStatistics(GridSession* session, GridMember* member,
StatisticsData& data)
セッションのメンバーに関する統計データを出力する最後の機会に呼び出されます。
GameLift によるクラウドホスティング
Lumberyard では、GameLift を通じた専用サーバーのクラウドホスティングをサポートしています。
プロジェクトで GameLift を使用するには、GameLift gem を有効にします。gem について
は、Amazon Lumberyard User Guideの「Gem」を参照してください。
開発者は、C++ API を通じて GameLift に直接アクセスすることも、GameLift gem によって提供
されるフローグラフのノードを使用してアクセスすることもできます。GameLift の詳細について
は、Amazon GameLift Developer Guide および Amazon GameLift API Reference を参照してくださ
い。
Carrier
キャリアは、GridMate のメッセージング API です。GridMate は信頼性の高い UDP を実装し、信頼性
の高いメッセージと信頼性の低いメッセージの両方をサポートします。アウトオブオーダー配信はあ
Version 1.6
490
Lumberyard 開発者ガイド
チャネルとメッセージの優先順位
りません。アウトオブオーダーメッセージは、信頼性の高い送信であればキューに入れられ、信頼性
の低い送信であれば破棄されます。
キャリアはチャネル経由でメッセージを送信します。チャネルの目的は、ゲームの状態や音声チャッ
トなどの無関係のトラフィックを分離することです。メッセージの順序は、チャネルをまたがって強
要されることはありません。
また、キャリア API は、 輻輳制御とトラフィックシミュレーションに対するフックを提供します。
チャネルとメッセージの優先順位
メッセージは異なるチャネルで送信でき、異なる優先順位を設定することができます。メッセージの
順序は、同じチャネルで送信される同じ優先度を持つメッセージ間で常に維持されます。
チャネルは、順序が他方に影響することがないように、無関係なメッセージを分離する手段を提供
します。メッセージがアウトオブオーダーで受信されると、信頼性に応じて破棄されるか、または
キューに入れられます (そのため、遅延します)。異なるチャネルを使用すると、無関係のメッセージ
が不必要に削除されたり遅延したりするのを防ぐことができます。たとえば、オブジェクトレプリ
ケーションのトラフィックおよび音声チャットのトラフィックを別のチャネルで送信することができ
ます。そのため、オブジェクトのレプリケーション用の信頼性の高いメッセージが見つからないこと
によって音声チャットデータが削除されたり、あるいはその逆が発生するのを防ぎます。
カスタマイズ可能なクラス
次のクラスをカスタマイズして、独自のネットワーキング機能を実装できます。
• Driver - キャリアがドライバへの実際のネットワーク動作を遅らせるため、異なる実装を異なるプ
ラットフォームに提供することができます。この抽象化によって、Steam や XboxLive などのサー
ビスプロバイダーからのプラットフォーム固有プロトコルを使用できるようになります。デフォル
ト実装では UDP が使用され、IPv4 と IPv6 がサポートされます。
• Simulator - ネットワークシミュレーターがある場合は、キャリアがそれを経由してすべてのインバ
ウンドおよびアウトバウンドのトラフィックを渡します。そのため、異なるネットワークの状況が
シミュレーションできます。キャリアのインスタンスごとに 1 つのシミュレーターのインスタンス
を指定できます。デフォルト実装では、インバウンドまたはアウトバウンド (またはその両方) のレ
イテンシー、帯域幅容量、パケット損失と、パケット順序変更の異なるパターンをシミュレーショ
ンできます。
• Traffic Control - トラフィック制御モジュールには、ネットワーク統計と輻輳制御の 2 つの主要な機
能があります。送信または受信されるメッセージは常にトラフィック制御モジュールに渡され、そ
れによって統計が更新されるため、送信中のデータ量を制限するためにフィードバックを提供する
ことができます。また、メッセージが消失したかどうか、およびキャリアによる再送が必要かどう
かを決定します。
CarrierDesc
CarrierDesc はキャリアの記述子です。キャリアを作成する際は、CarrierDesc 構造を使用して現
在のセッションのパラメーターを指定します。
CarrierDesc パラメーター
キャリアの初期化時は、以下のパラメーターを指定することができます。
パラメータ
データ型
説明
m_address
const char
*
ドライバがバインドするローカル通信アドレスを指定し
ます。値 0 は任意のアドレスを指定します。デフォルト:
nullptr。
Version 1.6
491
Lumberyard 開発者ガイド
CarrierDesc
パラメータ
データ型
説明
m_connectionEvaluationThreshold
float
通信の切断が検出された場合、他のすべ
ての接続が m_connectionTimeoutMS *
m_connectionEvaluationThreshold を使用して確認される際
のしきい値を指定し、他の接続もネットワーク障害によっ
て切断されているかを確認します。デフォルト: 0.5f。
m_connectionTimeoutMSunsigned
int
接続試行を許可する時間を決定します。デフォルト値は
5000 ミリ秒です。
m_disconnectDetectionPacketLossThreshold
float
パケット損失割合のしきい値。有効な値は、1.0 が 100 パー
セントの場合、0.0 から 1.0 です。パケット損失が指定され
た値を超えると、接続が切断されます。デフォルト: 0.3f。
m_disconnectDetectionRttThreshold
float
RTT (round-trip time) のしきい値をミリ秒単位で指定しま
す。RTT 測定値が指定された値を超えると、通信が切断さ
れます。デフォルト: 500.0f。
m_driver
class
Driver *
カスタムのドライバ実装を指定します。デフォルト:
nullptr。
m_driverIsCrossPlatform
ブール
ドライバがクロスプラットフォームの互換性を維持する
かどうかを指定します。true の場合、デフォルトドライバ
は、サポートされるすべてのプラットフォームで最も制限
される MTU (maximum transmission unit) を削除します。デ
フォルト: false。
m_driverIsFullPacketsブール
ドライバが MTU 制限を無視するかどうかを指定します。
このパラメーターはソケットドライバとローカルエリア
ネットワークにのみ適用されます。インターネットパケッ
トは、通常約 1500 バイトです。値を true にすると、64
KB の最大パケットサイズが有効になります。こういった
大きなパケットの送受信はインターネット上では失敗し、
ローカルネットワークでは成功することがよくあります。
デフォルト: false。
m_driverReceiveBufferSize
unsigned
int
ドライバが使用する内部の受信バッファのサイズを指定し
ます。値 0 はデフォルトのバッファサイズを指定します。
このパラメーターは、m_driver == null の場合のみ使用
できます。デフォルト: 0。
m_driverSendBufferSize
unsigned
int
ドライバが使用する内部の送信バッファのサイズを指定し
ます。値 0 はデフォルトのバッファサイズを指定します。
このパラメーターは、m_driver == null の場合のみ使用
できます。デフォルト: 0。
m_enableDisconnectionDetection
ブール
トラフィックの状態が悪い場合に、キャリアが接続を切断
するかどうかを指定します。デフォルト: true。
Note
このパラメーターはデバッグするときにの
み、false に設定する必要があります。
m_familyType
int
ドライバが使用するプロトコルファミリーを指定します。
値 0 はデフォルトファミリーを指定します。
Version 1.6
492
Lumberyard 開発者ガイド
レプリカを使用したゲームの状態の同期
パラメータ
データ型
説明
m_port
unsigned
int
ドライバがバインドするローカル通信ポートを指定しま
す。値 0 はシステムによって割り当てられたポートを指定
します。
m_securityData
const char
*
ポインタをセキュリティデータを持つ文字列に指定しま
す。たとえば XBox One では、この値はセキュリティテン
プレート名です。デフォルト: nullptr。
m_simulator
class
Simulator *
オプションで、全ネットワークメッセージをフィルタリン
グするシミュレーターを指定します。指定すると、キャリ
アが指定シミュレーター経由ですべてのインバウンドおよ
びアウトバウンドのトラフィックを渡すため、さまざまな
ネットワーク状況がシミュレーションできるようになりま
す。キャリアのインスタンスごとに 1 つのシミュレーター
インスタンスを指定できます。
m_threadCpuID
int
キャリアのスレッドを特定の CPU コアに制限します。指定
できる値はプラットフォームに依存します。値 -1 は制限な
しを指定します。デフォルト: -1。
m_threadInstantResponse
ブール
IO イベントでキャリアのスレッドをすぐに起動させるかど
うかを指定します。デフォルト: false。
Note
一般にこの値を true に設定すると、メッセージ
(特に小さいメッセージ) のグループ化が非効率にな
るため、多くの帯域幅が使用されます。
m_threadPriority
int
m_threadUpdateTimeMS int
キャリアのスレッドに対するスレッド優先順位を指定しま
す。指定できる値はプラットフォームに依存します。値
-100000 は、呼び出しスレッドの優先順位を継承します。
デフォルト: -100000。
キャリアスレッドの更新頻度をミリ秒単位で指定します。
このパラメーターは、m_threadInstantResponse が true
の場合は無視されます。有効な値は 0 から 100 です。一般
に、10 ミリ秒よりも高い頻度の間隔を指定する必要があり
ます。そうしない場合、m_threadInstantResponse を
true に設定するとより効率的です。デフォルト値は 30 ミ
リ秒です。
m_trafficControl
class
すべての接続に対するトラフィックフローを制御し、ネッ
TrafficControlトワークの混雑などの問題を処理するカスタムトラフィッ
*
ク制御の実装を指定します。
m_version
VersionType 使用されるキャリア API のバージョンを指定します。バー
ジョン番号が一致しないキャリアは、相互への接続が許可
されません。デフォルト: 1。
レプリカを使用したゲームの状態の同期
ゲームセッションでは、レプリカを使用してそのセッションの状態を同期します。レプリカを使用す
るには、同期する必要がある状態と、サポートされているリモートプロシージャ呼び出し (RPC) を宣
言するだけです。レプリカオブジェクトをネットワークにバインドした後は、エンジンが手間のかか
Version 1.6
493
Lumberyard 開発者ガイド
レプリカ
る作業を行ってくれます。メッセージを適切にルーティングする方法や、リモートオブジェクトの検
出方法について心配する必要はありません。ネットワークにローカル (マスター) レプリカを追加する
と、そのレプリカがリモートノードによって自動的に検出され、対応するリモートプロキシオブジェ
クトがそのリモートノードに作成されます。レプリカの所有者のみが状態を変更でき、新しい状態は
他のすべてのノードに自動的に伝播されます。RPC はどのノードからでも呼び出すことができます
が、検証および処理のためにマスター (所有者) ノードにルーティングされます。
トピック
• レプリカ (p. 494)
• レプリカチャンク (p. 497)
• データセット (p. 500)
• リモートプロシージャ呼び出し (RPC) (p. 501)
• レプリカマネージャー (p. 503)
• マーシャリングとアンマーシャリング (p. 505)
• コンポーネントによるネットワークへのゲーム オブジェクトのバインド (p. 506)
レプリカ
レプリカは、ネットワーク接続された GridMate ピアによって作成された、GridMate のレプリケー
ションシステムのコアコンポーネントです。ピアがレプリカを作成すると、そのレプリカは GridMate
によってネットワークに伝達され、セッション全体でレプリカの状態が同期されます。ローカルに作
成された所有者のいるレプリカはマスターレプリカと呼ばれます。接続されたピアが受け取るマス
ターレプリカのコピーは、プロキシレプリカと呼ばれます。レプリカの同期とインスタンス化は、レ
プリカマネージャー (p. 503) によって処理されます。
レプリカのチャンク
すべてのレプリカに、現在のセッションのすべてのピアと同期している、ユーザー定義の
ReplicaChunk (p. 497) オブジェクトのコレクションが保持されます。レプリカのチャンクは、
ユーザー定義の DataSet (p. 500) オブジェクトとリモートプロシージャ呼び出し (RPC) (p. 501)の
コンテナです。DataSet オブジェクトへの変更または RPC への呼び出しによって、レプリカの状態
がセッション全体で同期されます。
制約事項
レプリカのチャンクには以下の制限があります。
• 各レプリカに含めることができるチャンク数は最大 32 個です。
• チャンクは、レプリカがレプリカマネージャーにバインドされていないときにしかアタッチまたは
デタッチできません。
レプリカの作成とチャンクのアタッチ
レプリカを作成するには、次のメソッドを呼び出します。
GridMate::ReplicaPtr replica = GridMate::Replica::CreateReplica();
ユースケースのほとんどに、レプリカあたり 1 つのチャンクが必要です。1 回の呼び出しでチャンク
を作成し、レプリカにアタッチするには、次の例で示すように、CreateAndAttachReplicaChunk
ヘルパー関数を使用します。
GridMate::CreateAndAttachReplicaChunk<MyReplicaChunk>(replica, ...);
Version 1.6
494
Lumberyard 開発者ガイド
レプリカ
チャンクをレプリカにアタッチするだけの場合は、次を実行します。
replica->AttachReplicaChunk(myChunk);
レプリカのチャンクの作成と伝播については、「レプリカチャンク (p. 497)」を参照してください。
セッションレプリカマネージャーへのレプリカのバインド
レプリカを同期するには、そのレプリカをセッションレプリカマネージャーにバインドする必要が
あります。レプリカを作成し、チャンクをアタッチしたら、レプリカマネージャーを GridMate セッ
ション (p. 484)から取得して、次のようにレプリカをバインドします。
GridMate::ReplicaManager* replicaManager = session->GetReplicaMgr();
replicaManager->AddMaster(replica);
プロキシレプリカは、リモートピアのレプリカマネージャーによって自動的にインスタンス化される
ため、自動的にバインドされます。
レプリカの所有権
ピアがレプリカを作成し、セッションレプリカマネージャーにバインドすると、そのピアがレプリカ
の所有者になります。レプリカはそれぞれ 1 つのピアのみが所有できます。レプリカの所有者はネッ
トワーク上のピアだけで、このピアには、レプリカの状態を変更する権限が付与されています（たと
えば、チャンクのデータセットを変更したり、その RPC を直接実行したりできます）。プロキシレ
プリカでの状態の変更はすべて無効の見なされ、セッションには伝搬されません。プロキシレプリカ
で RPC を呼び出すことはできますが、呼び出しは、確認のため実行前に所有者に転送されます。こ
の確認が完了したら、RPC はすべてのプロキシに送信され、ピアによってローカルでも実行されま
す。マスターレプリカが実行を拒否すると、ピアは RPC 呼び出しを受け取りません。
所有権の変更
レプリカの所有権はピア間で移転できますが、レプリカの現在の所有者がその移転に同意する必要が
あります。レプリカの所有者が所有権の移転を防ぐ方法については、「レプリカチャンク (p. 497)」
を参照してください。
ピアツーピアネットワークでホスト移行が実施されると、所有権は自動的に移転します。次のメソッ
ドを呼び出して、移転を明示的にリクエストすることもできます。
replica->RequestChangeOwnership(); // Request ownership of a given replica
for the local peer
所有権の移転は非同期的に処理されます。所有権の移転が完了すると、変更
は、OnReplicaChangeOwnership コールバック関数によって各レプリカのチャンクに通知されま
す。
レプリカ ID
各レプリカには一意の ID が関連付けられています。レプリカ ID は、特定の GridMate セッション内
で一意であることが保証されます。次の例のようにレプリカ ID を使用して、セッションレプリカマ
ネージャーからレプリカを取得できます。
GridMate::ReplicaManager* replicaManager = session->GetReplicaMgr();
GridMate::ReplicaPtr replica = replicaManager->FindReplica(myReplicaId);
Version 1.6
495
Lumberyard 開発者ガイド
レプリカ
if (replica == nullptr)
{
// Replica with given ID does not exist
return;
}
if (replica->IsProxy())
{
// This is a proxy replica
}
if (replica->IsMaster())
{
// This is a master replica
}
有効期間
レプリカの有効期間は、参照カウントされるスマートポインタ、GridMate::ReplicaPtr によって
制御されます。レプリカマネージャーには、自身にバインドされているすべてのレプリカへの参照が
保持されます。したがって、ユーザーコードからはレプリカへの参照を除外すると安全です。レプリ
カマネージャーで参照が保持されている限り、レプリカが破損することはありません。ただし、次の
メソッドを呼び出すと、レプリカマネージャーに対して参照をリリースし、レプリカを解放するよう
に強制できます。
replica->Destroy();
サンプルコード
この例では、ユーザー定義のチャンクとレプリカを作成し、チャンクをレプリカにアタッチして、レ
プリカをセッションレプリカマネージャーにバインドします。
// User-defined ReplicaChunk class to be carried with the replica
class MyChunk : public GridMate::ReplicaChunk
{
public:
GM_CLASS_ALLOCATOR(MyChunk);
typedef AZStd::intrusive_ptr<MyChunk> Ptr; // smartptr to hold the chunk
static const char* GetChunkName() { return "MyChunk"; } // Unique chunk
name
bool IsReplicaMigratable() override { return false; } // Replica
ownership
// cannot be
changed
MyChunk () : m_data("Data", 0) { } // chunk constructor
void OnReplicaActivate(const ReplicaContext& rc) override // Called when
replica is bound
// to the
replica manager (both
// on local and
remote peers)
{
// printing out whether it is a proxy or a master replica
if (IsMaster())
printf("I am master!\n");
Version 1.6
496
Lumberyard 開発者ガイド
レプリカチャンク
if (IsProxy())
printf("I am proxy!\n");
}
GridMate::DataSet<int> m_data; // data this chunk holds
};
GridMate::ReplicaPtr replica = GridMate::Replica::CreateReplica(); //
Creating a replica
GridMate::CreateAndAttachReplicaChunk<MyChunk>(replica); // Creating chunk of
our custom type
// and attaching it
to the replica
GridMate::ReplicaManager* replicaManager = session->GetReplicaMgr(); //
Getting replica manager instance
// from
current session
replicaManager->AddMaster(replica); // Binding replica to the replica
manager,
// making local peer the owner of this
replica
...
// Starting from this point and up until replica destruction, the replica and
MyChunk object
// that the replica is carrying will be synchronized with other peers.
// Other peers receive the new replica and bind it to their replica managers.
When this is done,
// OnReplicaActivate is triggered, and the "I am proxy" message is printed
out on the remote peers.
// Every change of m_data DataSet results in the synchronization of the new
value in
// the master replica with all of the proxy replicas.
レプリカチャンク
レプリカチャンクは、ユーザー拡張可能なネットワークオブジェクトです。レプリカ (p. 494)は、
レプリカチャンクのコンテナかつマネージャーであり、1 つ以上の ReplicaChunk オブジェクトを所
有できます。レプリカは、マスターピアによって所有され、プロキシレプリカとして他のネットワー
クノードに伝播されます。レプリカチャンクに含まれるデータは、そのレプリカチャンクに保存され
ている他のデータに関連していることが一般的です。1 つのレプリカに複数のチャンクをアタッチす
ることもできるため、関連性のないデータは同じレプリカ内の別のチャンクに保存することができま
す。
レプリカチャンクには、データセット (p. 500)またはリモートプロシージャ呼び出し
(RPC) (p. 501)、あるいはその両方を含めることができます。データセットには、マスターレプリカ
のみによる変更が可能な任意のデータを保存します。変更が発生すると、他のノードのプロキシレプ
リカ内のチャンクに反映されます。RPC は、リモートノードに対して実行できるメソッドです。これ
らはまずマスターで呼び出されます。マスターでは、その呼び出しをプロキシに反映するかどうかが
決定されます。
レプリカチャンクの要件と制限
レプリカチャンクには、次に示すような重要な特性があります。
• 最大 32 の DataSet を定義できます。
Version 1.6
497
Lumberyard 開発者ガイド
レプリカチャンク
• 最大 256 の RPC を定義できます。
• 参照がカウントされており、スマートポインタに保持する必要があります。
• レプリカマネージャーの準備ができるまで、セッション全体では同期されていません。
新しいレプリカチャンク型の実装
新しいレプリカチャンク型を実装するには、データセットの変更と RPC 呼び出し ("ゲームロジック")
をチャンク内で処理する方法とチャンクの外部で処理する方法の 2 種類があります。いずれの場合
も、以下が適用されます。
• チャンク型の名前は、システム全体を通じて一意である必要があります。これを実現するには、す
べてのレプリカチャンク型に静的メンバー関数 (const char* GetChunkName()) を実装する必要
があります。GetChunkName 関数から返される文字列では、チャンク型を一意に特定する必要があ
ります。
• この型のチャンクの所有権が移譲可能かどうかを示すには、すべてのチャンク型で仮想関数 bool
IsReplicaMigratable() をオーバーライドする必要があります。レプリカ内に移行不可能なチャ
ンクがある場合、レプリカの所有権を別のピアに移譲することはできません。
• すべてのチャンク型では、チャンク型インスタンスを保持するスマートポインタを定義する必要が
あります。 レプリカチャンク型の宣言と内部的なゲームロジック処理
レプリカチャンククラスで直接、ゲームロジックを処理するには、ReplicaChunk を継承する必要が
あります。
class MyChunk : public GridMate::ReplicaChunk
{
public:
GM_CLASS_ALLOCATOR(MyChunk); // Using GridMate's allocator
MyChunk()
: m_data("Data", 0)
// Initializing integer DataSet
to zero, and assigning a name for it
, MyRpcMethodRpc("MyRpcMethodRpc") // Initializing RPC by passing in
its name; the RPC name is for debugging purposes
{
}
typedef AZStd::intrusive_ptr<DataSetChunk> Ptr;
// Defining
smart pointer type for this chunk
static const char* GetChunkName() { return "MyChunk"; } // Unique chunk
type name
bool IsReplicaMigratable() override { return false; }
// Specify
whether the chunk can participate in replica's ownership changes
bool MyRpcMethod(int value, const GridMate::RpcContext& context)
{
// Handle event here
return true; // Propagate this call to all proxies
}
GridMate::Rpc<GridMate::RpcArg<int>>::BindInterface<MyChunk,
&CustomChunk::MyRpcMethod> MyRpcMethodRpc;
GridMate::DataSet<int> m_data;
Version 1.6
498
Lumberyard 開発者ガイド
レプリカチャンク
};
レプリカチャンク型の宣言と外部的なゲームロジック処理
レプリカチャンククラスを単純なデータキャリアとして使用するには、データの変化とイベントを専
用ハンドラ (外部クラス) に転送し、ハンドラクラスを ReplicaChunkInterface から継承して、レ
プリカチャンククラスを ReplicaChunkBase から継承します。
class CustomHandler : public GridMate::ReplicaChunkInterface
{
public:
GM_CLASS_ALLOCATOR(CustomHandler); // using GridMate's allocator
void DataSetHandler(const int& value, const GridMate::TimeContext&
context)
{
// Handle changes
}
bool RpcHandler(AZ::u32 value, const GridMate::RpcContext &context)
{
// Handle event here
return true; // Propagate this call to all proxies
}
};
class MyChunk : public GridMate::ReplicaChunkBase
{
public:
GM_CLASS_ALLOCATOR(MyChunk); // Using GridMate's allocator
MyChunk()
: m_data("Data", 0)
// Initializing integer DataSet to
zero and assigning a name for it
, MyRpcMethodRpc("MyRpcMethodRpc") // Initializing RPC by passing its
name; the RPC's name is used for debugging purposes
{
}
typedef AZStd::intrusive_ptr<DataSetChunk> Ptr;
// Defining smart
pointer type for this chunk
static const char* GetChunkName() { return "MyChunk"; } // Unique chunk
type name
bool IsReplicaMigratable() override { return false; }
// Whether chunk
can participate in replica's ownership changes
GridMate::DataSet<int>::BindInterface<CustomHandler,
&CustomHandler::DataSetHandler> m_data;
GridMate::Rpc<GridMate::RpcArg<AZ::u32>>::BindInterface<CustomHandler,
&CustomHandler::RpcHandler> MyRpcMethodRpcPC;
};
チャンク型の登録
ユーザー定義レプリカチャンク型はすべて ReplicaChunkDescriptorTable で登録して、レプリカ
マネージャー (p. 503) で求められるファクトリを作成する必要があります。
Version 1.6
499
Lumberyard 開発者ガイド
データセット
レプリカチャンクを登録するには、次の呼び出しを使用します。
GridMate::ReplicaChunkDescriptorTable::Get().RegisterChunkType<MyChunk>();
レプリカへのレプリカチャンクのアタッチ
レプリカをレプリカマネージャーにバインドするには、レプリカチャンクをレプリカに追加しておく
必要があります。レプリカマネージャーにレプリカをバインドした後は、そのレプリカに対してレプ
リカチャンクの追加または削除を行うことはできません。
レプリカチャンクを作成するには、この呼び出しを使用します。
MyChunk::Ptr myChunk = GridMate::CreateReplicaChunk<MyReplicaChunk>(<...>);
<...> は MyReplicaChunk コンストラクタに転送されます。
レプリカにチャンクをアタッチするには、この呼び出しを使用します。
replica->AttachReplicaChunk(myChunk);
または、チャンクの作成とアタッチを 1 ステップで行うこともできます。
GridMate::CreateAndAttachReplicaChunk<MyReplicaChunk>(replica, <...>);
チャンクをレプリカに追加した後、レプリカにはチャンクへのスマートポインタが保持されます。
チャンクが開放されるのは、レプリカが破壊された場合のみです。
データセット
DataSet オブジェクトを使用すると、ネットワーク全体でセッションの状態を同期させることができ
ます。データセットの値が変更されると、更新が自動的に伝達されます。データセットの型はどの型
でもかまいませんが、代入演算子と比較演算子をサポートしている必要があります。DataSet宣言で
は、カスタムマーシャラーを指定できます。マーシャラーを指定しない場合、DataSet オブジェクト
は GridMate::Marshaler<T> を使用します。
DataSet は ReplicaChunk オブジェクト内で宣言する必要があります。ReplicaChunk オブジェク
トには、32 個までの DataSet オブジェクトを含めることができます。データセットコンストラクタ
にデバッグ名を指定する必要があります。
次の例では、float 型の 2 つの DataSet を持つ ReplicaChunk オブジェクトを宣言しま
す。1 つのデータセットはデフォルトのマーシャラーを使用します。もう 1 つのデータセット
は、MyCustomMarshaler というカスタムマーシャラーを使用します。
class MyChunkType : public GridMate::ReplicaChunk
{
public:
MyChunkType()
: m_synchedFloat("SynchedFloat")
, m_synchedHalf("SynchedHalf")
{
}
GridMate::DataSet<float> m_synchedFloat;
Version 1.6
500
Lumberyard 開発者ガイド
リモートプロシージャ呼び出し (RPC)
GridMate::DataSet<float, MyCustomMarshaler> m_synchedHalf;
};
データセットは、新しいデータの到着時にコールバックが呼び出されるように、オプションでチャン
クインターフェイスのコールバックにバインドできます。
class MyChunkType : public GridMate::ReplicaChunk
{
public:
MyChunkType()
: m_synchedFloat("SynchedFloat")
{
}
// Callback to call when new data arrives.
void OnSynchedFloatData(const float& newValue, const
GridMate::TimeContext& timeContext);
GridMate::DataSet<float>::BindInterface<MyChunkType,
amp;MyChunkType::OnSynchedFloatData> m_synchedFloat;
};
データセットには結果整合性が保証されます。通常、データセットは信頼性の低い状態で伝達されま
す。潜在的なパケット消失を補ったり、レイテンシーを最小限に抑えたりするため、GridMate は次の
順番でイベントを処理します。
1. ユーザーがデータセットの値を変更します。
2. 新しい値がリモートピアにブロードキャストされます。
3. データセットが変更を停止します。
4. ユーザーが設定可能な猶予期間が経過します。
5. 最後の更新が確実に送信されます。
6. 帯域幅を節約するため、次回の変更まで伝達は一時停止されます。
SetMaxIdleTime を呼び出すことで、ステップ 4 の猶予期間の長さを変更できます。
...
GridMate::DataSet<Vector3> m_pos;
...
...
m_pos.SetMaxIdleTime(5.f);
ticks
...
// Suspend sending if m_pos has not changed for 5
リモートプロシージャ呼び出し (RPC)
リモートプロシージャ呼び出し (RPC) によって、ゲームはイベントまたは要求をレプリカから送信し
ます。RPC は頻繁ではない、一度限りのイベントまたは特定のノードにルーティングされるメッセー
ジには最適です。
GridMate では、RPC には次の特徴があります。
• 有効なマーシャラーが提供されている限り、RPC の引数にはあらゆる種類を指定できます。
Version 1.6
501
Lumberyard 開発者ガイド
リモートプロシージャ呼び出し (RPC)
• すべての RPC リクエストは、マスターレプリカにルーティングされます。
• マスターレプリカの RPC ハンドラー組み込み関数は、RPC をプロキシのレプリカに伝達するかど
うかを選択します。
• RPC は履歴に保持されず、遅結合のクライアントはクライアントが結合する前に要求された RPC
を受け取りません。
RPC の宣言
データセットと同様に、RPC はレプリカのチャンクのメンバーとして宣言されます。RPC のハンド
ラー組み込み関数は宣言の一部として RPC にバインドされます。RPC のリクエストは、引数および
要求に関連付けられている RpcContext と共にハンドラー組み込み関数に転送されます。
RPC ハンドラー機能は、要求を処理する前に追加チェックを実行できます。ハンドラー組み込み関数
がマスターレプリカで呼び出されるときに true を返す場合、RPC はすべてのプロキシレプリカに伝
達されます。プロキシで呼び出される場合、戻り値は無視されます。
class MyChunkType : public GridMate::ReplicaChunk
{
public:
// Rpc1 takes two arguments: a float marshaled using default marshaler,
and another float marshaled using CustomFloatMarshaler.
// Requests are handled by MyChunkType::HandleRpc1().
GridMate::Rpc<GridMate::RpcArg<float>, GridMate::RpcArg<float,
CustomFloatMashaler>>::BindInterface<MyChunkType, &HandleRpc1> Rpc1;
// Handler function bound to Rpc1.
// Verifies the RPC and if accepted, returns true so it is propagated to
all proxies.
bool HandleRpc1(float v1, float v2, const GridMate::RpcContext&
rpcContext)
{
// The RPC handler can perform additional checks to verify the
request.
if (VerifyRpcRequest())
{
printf("Execute Rpc1...\n");
// Return true to propagate to all proxies.
return true;
}
// Return false to stop propagation to proxies.
return false;
}
// Rpc2 has no arguments.
// Requests are handled by MyChunkType::HandleRpc2().
GridMate::Rpc<>::BindInterface<MyChunkType, &HandleRpc2,
GridMate::RpcUnreliable> Rpc2;
// Handler function bound to Rpc2.
bool HandleRpc2(const GridMate::RpcContext& rpcContext)
{
printf("Execute Rpc2...\n");
// Never propagate Rpc2 to proxies.
return false;
}
};
Version 1.6
502
Lumberyard 開発者ガイド
レプリカマネージャー
void Foo(MyChunkType* myChunkInstance)
{
// Call Rpc1.
myChunkInstance->Rpc1(1.f, 2.f);
// Call Rpc2.
myChunkInstance->Rpc2();
}
レプリカマネージャー
レプリカマネージャーはレプリカの同期化を管理するサブシステムです。レプリカマネージャーは以
下を行います。
• 各ピアにレプリカを直列化、非直列化します。
• 1人のピアからもう1人へレプリカの転送
• レプリカの所有権の変更処理
• レプリカの有効期間の管理
レプリカの有効期間の管理
レプリカマネージャーは以下を実行する必要があります:
• 参照カウントされたポインタで各マスタとプロキシレプリカオブジェクトを保持し、全てのレプリ
カを管理します。
• レプリカが破壊される前に、すべてのレプリカの最終状態がキャプチャされ伝達されたことを確認
し、セッションの整合性を確保します。
• レプリカが非アクティブ化する前に、すべてのプロキシが結果的に整合性を得ることを保証しま
す。
• オブジェクトが破壊された場合、グリッドメイトレファレンスをレプリカオブジェクトへ公開しま
す。
レプリカマネージャーに新しいマスターのレプリカを結合する
新しいマスターのレプリカが作成されたら、以下の通りレプリカマネージャーに結合されなければな
りません。
GridMate::ReplicaManager* replicaManager = session->GetReplicaMgr(); // Get
replica manager from the current session
replicaManager->AddMaster(myReplica1); // Bind replica to replica manager
replicaManager->AddMaster(myReplica2); // Bind replica to replica manager
プロキシレプリカは、該当セッションのレプリカマネージャーに自動的に結合されます。
各ReplicaManagerインスタンスは、ユーザーがDestroy()をレプリカに呼び出すまで、ま
たReplicaManager自身が破壊されるまで、それにバインドされているすべてのレプリカへの参照が
保持されます。
レプリカをレプリカマネージャーから取得する場合
すべてのレプリカは各セッションに独自の数値識別子があります。IDによってレプリカを検索するに
は、以下の例と同様にFindReplica(<ReplicaId>)を呼び出してください。
Version 1.6
503
Lumberyard 開発者ガイド
レプリカマネージャー
GridMate::ReplicaPtr replica = replicaManager->FindReplica(<myReplicaId>);
AZ_Assert(replica != nullptr, "Replica with id=%d not
found.", <myReplicaId>);
レプリカマネージャーがレプリカを更新する方法
グリッドメイトセッションはレプリカマネージャーをトリガーし、継続的にレプリカの更新を実行し
ます。 これらの更新には以下のアクションが含まれます。
• アンマーシャリング
• レプリカからの更新をします。
• レプリカを更新します。
• マーシャリング
マーシャリング: 他の仲間にデータを送信すること
レプリカの変更はグリッドメイトセッションのすべてのリモート仲間へ複製する必要があります。一
つのレプリカの変更を伝達するには、仲間のレプリカマネージャーが送信バッファにレプリカのオブ
ジェクトをシリアライズしてから、ネットワークにオブジェクトを送信します。レプリカのマーシャ
リングは主に2つのフェーズで発生します。
• データ準備–レプリカの変更内容に基づいて、どのRPCとDataSetオブジェクトを送信するかを定
義するプレマーシャリングフェーズ。さらに、この段階でどのオブジェクトを送信するのかデータ
の整合性を検証します。
• 実際のマーシャリング–レプリカオブジェクトからバイトストリームへの変換。整列する必要
のある実際のデータは、マスターレプリカが持つ関連するリモートプロキシレプリカに関連
する新しい情報量により異なります。例えば、新しいプロキシレプリカは、そのデータセッ
ト (p. 500)、RPC (p. 501)とメタデータの構築を含むマスターレプリカに関するすべての情報が
必要です。以前は同期されたプロキシレプリカは、保留中のRPC呼び出しを含む、異なるマスター
レプリカからの情報のみが必要でした。
アンマーシャリング: 他の仲間からデータを受信する場合
アンマーシャリングでは、レプリカマネージャーが離れた仲間と通信し、新しいデータを受信、解析
し独自のレプリカに対応して更新します。これらの更新には新しい仲間の受け入れ、新しいプロキシ
の例示、所有権変更の取り扱い、プロキシレプリカの破壊などが含まれます。
Note
マーシャリングの詳細については、マーシャリングとアンマーシャリング (p. 505) を参照し
てください。
レプリカからの更新：プロキシレプリカの更新
カスタムレプリカチャンク (p. 497)の変更は、UpdateFromChunkコールバックとなり、すべてのプ
ロキシレプリカの状態が更新されます。プロキシとマスターレプリカのRPCは以下の手順で処理され
呼び出されます。
レプリカの更新：マスターレプリカをローカルに更新する
カスタムレプリカチャンクの変更はUpdateChunkコールバックとなり、全てのローカル仲間にあるマ
スターレプリカが更新されます。
Version 1.6
504
Lumberyard 開発者ガイド
マーシャリングとアンマーシャリング
マーシャリングとアンマーシャリング
マーシャリング: 他の仲間にデータを送信すること (p. 504) で説明したように、マーシャリン
グとは、GridMate セッションでレプリカデータの変更を各ピアインスタンスへ送信することで
す。WriteBuffer を使用してデータがネットワークに書き込まれ、また ReadBuffer を使用して受
信したデータが読み込まれます。バッファごとに、使用するエンディアンネスを指定します。
マーシャラーはバッファからのデータの読み込み、およびバッファへのデータの書き込みを行いま
す。組み込まれているほとんどのデータ型や、よく使用される他のデータ型には、デフォルトのマー
シャラーが用意されています。カスタム型またはカスタム圧縮技術をサポートするには、カスタム
マーシャラーを実装できます。デフォルトのマーシャラーは、C++ のテンプレートの特殊化によって
実装されています。
namespace GridMate
{
template<typename T>
class Marshaler
{
public:
void Marshal(WriteBuffer& wb, const T& value);
void Unmarshal(T& value, ReadBuffer& rb);
};
}
データセットまたは RPC の宣言と一緒にマーシャラーが指定されていない場合は、テンプレートの
特殊化が使用されます。
AZCore の Vector3 の演算処理タイプのデフォルトマーシャラーの実装は、Code/Framework/
GridMate/GridMate/Serialize/MathMarshal.h にあります:
namespace GridMate
{
template<>
class Marshaler<AZ::Vector3>
{
public:
typedef AZ::Vector3 DataType;
static const AZStd::size_t MarshalSize = sizeof(float) * 3;
void Marshal(WriteBuffer& wb, const AZ::Vector3& vec) const
{
Marshaler<float> marshaler;
marshaler.Marshal(wb, vec.GetX());
marshaler.Marshal(wb, vec.GetY());
marshaler.Marshal(wb, vec.GetZ());
}
void Unmarshal(AZ::Vector3& vec, ReadBuffer& rb) const
{
float x, y, z;
Marshaler<float> marshaler;
marshaler.Unmarshal(x, rb);
marshaler.Unmarshal(y, rb);
marshaler.Unmarshal(z, rb);
vec.Set(x, y, z);
}
};
}
Version 1.6
505
Lumberyard 開発者ガイド
コンポーネントによるネットワーク
へのゲーム オブジェクトのバインド
コンポーネントによるネットワークへのゲーム オブ
ジェクトのバインド
ネットワークでデータを共有する ComponentEntity には必ず、NetBindingComponent が含まれ
ている必要があります。NetBindingComponent は、ComponentEntity のレプリカ (p. 494)を作
成し、コンポーネントによって作成されるすべてのレプリカのチャンク (p. 497)をそのレプリカに
バインドできます。基本 Lumberyard コンポーネントは、NetBindingComponent を追加するだけで
ネットワークにバインドできますが、カスタムコンポーネントを使用する場合は、追加のステップが
いくつか必要です。
カスタムコンポーネント
次のステップを使用して、カスタムコンポーネントでネットワーキングを有効にします。
カスタムコンポーネントでネットワーキングを有効にするには
1.
AzFramework::NetBindable からコンポーネントを継承します。
#include <AzFramework/Network/NetBindable.h>
class TransformComponent
: public Component
, public AzFramework::NetBindable
2.
AZ_COMPONENT 定義を変更して、AzFramework::NetBindable を追加します。
AZ_COMPONENT(TransformComponent,"{22B10178-39B6-4C12-BB37-77DB45FDD3B6}",
AzFramework::NetBindable);
AzFramework::NetBindable がないと、NetBindingComponent が、レプリカに追加する
チャンクが含まれるコンポーネントを確認するときに、カスタムコンポーネントが検出されませ
ん。
Note
この定義を変更するには、影響を受けるレベルを再エクスポートする必要があります。
3.
SerializeContext を変更して、AzFramework::NetBindable を追加します。
serializeContext->Class<TransformComponent, AZ::Component,
AzFramework::NetBindable>()
AzFramework::NetBindable がシリアル化定義にない場合、マスターレプリカチャンクは適切
に機能しますが、プロキシレプリカに、そのプロキシのチャンクが届きません。
Note
この定義を変更するには、影響を受けるレベルを再エクスポートする必要があります。
4.
次の AzFramework::NetBindable インターフェイスを実装します。
// Called during network binding on the master. Implementations should
create and return a new binding.
virtual GridMate::ReplicaChunkPtr GetNetworkBinding() = 0;
// Called during network binding on proxies.
Version 1.6
506
Lumberyard 開発者ガイド
コンポーネントによるネットワーク
へのゲーム オブジェクトのバインド
virtual void SetNetworkBinding(GridMate::ReplicaChunkPtr chunk) = 0;
// Called when network is unbound. Implementations should release their
references to the binding.
virtual void UnbindFromNetwork() = 0;
ネットワークバインド関数の詳細
ネットワーク上でコンポーネントエンティティを使用するための関数はいくつかあります。
GetNetworkBinding
GetNetworkBinding 関数は、マスター ComponentEntity でのみ呼び出します。この関数は、レプ
リカのチャンクを返し、セッション全体で同期する必要があるコンポーネントの状態を、コンポーネ
ント自身で初期化できるようにします。返されたチャンクは、適切なレプリカに自動的にアタッチさ
れます。
SetNetworkBinding
すべてのプロキシ ComponentEntity オブジェクトで SetNetworkBinding 関数を呼び出します。
この関数は ReplicaChunk オブジェクトをコンポーネントに渡します。これにより、そのコンポーネ
ントは、受け取ったレプリカのチャンクのデータに合わせて内部データを初期化できます。受け取っ
たチャンクは、適切なデータにすでにバインドされています。
UnbindFromNetwork
マスターが存在しない、非アクティブ化された、あるいはローカルソースに制御を委ねた場合など
に、UnbindFromNetwork 関数を呼び出して、コンポーネントがネットワークからのデータ更新に対
応しないようにします。
チャンクの作成
コンポーネントでインターフェイスを完全に有効にする前に、レプリカのチャンクを作成して、コン
ポーネントが共有する必要がある状態をすべて保存する必要があります。
class TransformReplicaChunk : public GridMate::ReplicaChunk
{
public:
AZ_CLASS_ALLOCATOR(TransformReplicaChunk, AZ::SystemAllocator, 0);
static const char* GetChunkName() { return "TransformReplicaChunk"; }
TransformReplicaChunk()
: m_localTransform("LocalTransformData")
, m_entityId()
{
}
void SetEntityId(EntityId entityId)
{
m_entityId = entityId;
}
const AZ::Transform& GetLocalTransform() const
{
return m_localTransform.Get();
}
void SetLocalTransform(const AZ::Transform& transform)
Version 1.6
507
Lumberyard 開発者ガイド
コンポーネントによるネットワーク
へのゲーム オブジェクトのバインド
{
m_localTransform.Set(transform);
}
void OnTransformChanged(const AZ::Transform& transform, const
GridMate::TimeContext& tc)
{
(void)transform; (void)tc;
Entity* entity = nullptr;
EBUS_EVENT_RESULT(entity, ComponentApplicationBus, FindEntity,
m_entityId);
if (entity)
{
TransformComponent* transformComponent = entity>FindComponent<TransformComponent>();
if (transformComponent)
{
transformComponent->UpdateFromReplicaChunk();
}
}
}
private:
EntityId m_entityId;
GridMate::DataSet<AZ::Transform>::BindInterface<TransformReplicaChunk,
&TransformReplicaChunk::OnTransformChanged> m_localTransform;
};
DataSet オブジェクトの変更にコンポーネントが対応するには、この変更が発生したときに
（DataSet の BindInterface 拡張機能を使用してここで行ったように）レプリカのチャンクが信号
を送信するか、コンポーネントがレプリカのチャンクをポーリングし、DataSet オブジェクトに変更
がないかどうかをチェックする必要があります。
コメント
• 新しい ReplicaChunk オブジェクトを登録する必要があります。詳細については、「チャンク型の
登録 (p. 499)」を参照してください。
• ReplicaChunk オブジェクトには、アンマーシャリングできるように空のコンストラクタが必要で
す。
例: AzFramework::NetBindable インターフェイスへの入力
次の例では、GetNetworkBinding、SetNetworkBinding、および UnbindFromNetwork を使用し
ています。
GetNetworkBinding
GridMate::ReplicaChunkPtr TransformComponent::GetNetworkBinding()
{
TransformReplicaChunk* replicaChunk =
GridMate::CreateReplicaChunk<TransformReplicaChunk>();
replicaChunk->SetEntityId(GetEntityId());
m_replicaChunk = replicaChunk;
UpdateReplicaChunk();
Version 1.6
508
Lumberyard 開発者ガイド
コンポーネントによるネットワーク
へのゲーム オブジェクトのバインド
return m_replicaChunk;
}
SetNetworkBinding
void
TransformComponent::SetNetworkBinding(GridMate::ReplicaChunkPtr replicaChunk)
{
AZ_Assert(m_replicaChunk == nullptr,"ERROR: Being bound to two replica
chunks");
bool isTransformChunk = replicaChunk != nullptr;
AZ_Assert(isTransformChunk,"ERROR: Being bound to invalid chunk type");
if (isTransformChunk)
{
m_replicaChunk = replicaChunk;
TransformReplicaChunk* transformReplicaChunk =
static_cast<TransformReplicaChunk*>(m_replicaChunk.get());
transformReplicaChunk->SetEntityId(GetEntityId());
UpdateFromReplicaChunk();
}
}
UnbindFromNetwork
void TransformComponent::UnbindFromNetwork()
{
m_replicaChunk = nullptr;
}
状態のメンテナンス
最後に、ネットワーク接続可能な目的の状態へのローカルの変更によって、ネットワーク接続された
状態が上書きされていないことを確認し、コンポーネントが状態とローカル状態の変更を制御してい
るときに、レプリカのチャンクを更新します。
// Don't allow external setting of the Transform if it's network controlled.
void TransformComponent::SetLocalTM(const Transform& tm)
{
if (!IsNetworkControlled())
{
ForceLocalTM(tm);
}
}
// Helper function to let the replica bypass the previous safety check.
// Also signals the need to update the replica chunk with the new state.
void TransformComponent::ForceLocalTM(const Transform& tm)
{
m_localTM = tm;
ComputeWorldTM(); // We can use dirty flags and compute it later on
demand
UpdateReplicaChunk();
}
// Don't manipulate the local TM if it's network controlled.
Version 1.6
509
Lumberyard 開発者ガイド
OpenSSL の使用
// And in the case of the master, update the replica with
// the new information that changed here.
void TransformComponent::ComputeLocalTM()
{
if (IsNetworkControlled())
{
return;
}
if (m_parentTM)
{
m_localTM = m_parentTM->GetWorldTM().GetInverseFull() * m_worldTM;
}
else
{
m_localTM = m_worldTM;
}
EBUS_EVENT_PTR(m_notificationBus, TransformNotificationBus,
OnTransformChanged, m_localTM, m_worldTM);
UpdateReplicaChunk();
}
// Helper method
bool TransformComponent::IsNetworkControlled() const
{
return m_replicaChunk != nullptr && !m_replicaChunk->IsMaster();
}
// Helper method that updates the replica chunk's transform from the local
transform.
void TransformComponent::UpdateReplicaChunk()
{
if (m_replicaChunk && m_replicaChunk->IsMaster())
{
TransformReplicaChunk* transformReplicaChunk =
static_cast<TransformReplicaChunk*>(m_replicaChunk.get());
transformReplicaChunk->SetLocalTransform(GetLocalTM());
}
}
// Helper method that updates the local transform from the replica chunk
void TransformComponent::UpdateFromReplicaChunk()
{
if (m_replicaChunk && !m_replicaChunk->IsMaster())
{
TransformReplicaChunk* transformReplicaChunk =
static_cast<TransformReplicaChunk*>(m_replicaChunk.get());
ForceLocalTM(transformReplicaChunk->GetLocalTransform());
}
}
OpenSSL の使用
GridMate は、Datagram Transport Layer Security (DTLS) の OpenSSL による実装を使用して、クラ
イアント/サーバー間のすべての UDP トラフィックの暗号化をサポートしています。
トピック
Version 1.6
510
Lumberyard 開発者ガイド
制約事項
• 制約事項 (p. 511)
• 実装サポート (p. 511)
• 暗号 (p. 511)
• 暗号化してビルドする (p. 511)
• 暗号化の有効化 (p. 512)
制約事項
GridMate の暗号化の実装には以下の制限があります。
• 64 ビット Windows のみサポートされます。
• クライアント/サーバー型トポロジーのみサポートされます。
実装サポート
GridMate では、以下の実装の暗号化をサポートしています。
• サーバーとクライアントの認証
• 自己署名証明書
• 単一の強力な OpenSSL 暗号化
暗号
GridMate では、すべての暗号化接続に、単一の OpenSSL 暗号化 ECDHE-RSA-AES256-GCM-SHA384
を使用しています。
この暗号化では、以下の表に示すテクノロジーを使用しています。
GridMate で使用されている暗号化技術
テクノロ
ジー
ロール
説明
ECDHE
マスターキー交換
Ephemeral Elliptic Curve Diffie-Hellman 匿名鍵共有プ
ロトコル
RSA
ピア認証
クライアントとサーバーの認証に使用される RSA アル
ゴリズム
AES256
対称暗号による暗号化
Advanced Encryption Standard (マスター鍵長 256 ビッ
ト)
GCM
ブロック暗号の動作モード
Galois/Counter Mode による認証暗号化アルゴリズム
SHA384
ハッシュ生成アルゴリズム
SHA-2 (384 ビットのダイジェスト長)
暗号化してビルドする
プロジェクトに GridMate ライブラリが含まれる場合、暗号化サポートが自動的に提供されます。た
だし、GridMate ライブラリは静的にリンクされるため、まず、GridMate を使用する WAF ビルドスク
リプト (wscript) にいくつかの修正を加える必要があります。
Version 1.6
511
Lumberyard 開発者ガイド
暗号化の有効化
暗号化してプロジェクトをビルドする
GridMate で暗号化を使用するには、.wscript ファイルを修正して、GridMate に依存関係を追加し
ます。次に、OpenSSL ライブラリをリンクして、OpenSSL ライブラリパスを指定します。
GridMate で OpenSSL を使用できるように .wscript ファイルを修正するには
1.
GridMate で依存関係を作成するには、以下の行を追加します。
use = ['GridMate']
2.
OpenSSL ライブラリをリンクするには、以下の行を追加します。
win_lib = ['ssleay32', 'libeay32']
3.
次の例のように OpenSSL ライブラリパスを追加します。Lumberyard インストールディレクトリ
では、これらのパスはフォルダー dev\Code\SDKs\OpenSSL\lib\ にあります。
win_x64_debug_libpath = [ bld.Path('Code/SDKs/OpenSSL/lib/
vc120_x64_debug') ],
win_x64_profile_libpath = [ bld.Path('Code/SDKs/OpenSSL/lib/
vc120_x64_release') ],
win_x64_release_libpath = [ bld.Path('Code/SDKs/OpenSSL/lib/
vc120_x64_release') ],
win_x64_debug_dedicated_libpath = [ bld.Path('Code/SDKs/OpenSSL/lib/
vc120_x64_debug') ],
win_x64_profile_dedicated_libpath = [ bld.Path('Code/SDKs/OpenSSL/lib/
vc120_x64_release') ],
win_x64_release_dedicated_libpath = [ bld.Path('Code/SDKs/OpenSSL/lib/
vc120_x64_release') ]
暗号化せずにビルドする
プロジェクトで GridMate を使用するが暗号化のサポートが必要ない場合、GridMateForTools 行が
.wscript ファイルにあることを確認してください。
use = ['GridMateForTools']
暗号化の有効化
GridMate セッションで OpenSSL を使用した暗号化を有効にするには、以下の手順を実行します。
GridMate セッションで暗号化を有効にするには
1.
暗号化パラメーターを設定するために、SecureSocketDesc のインスタンスを作成します。パ
ラメーターが SecureSocketDesc (p. 513) に記述されています。
2.
SecureSocketDesc のインスタンスに入る SecureSocketDriver のインスタンスを作成しま
す。SecureSocketDesc のインスタンスは、GridMate セッションの期間中に有効である必要が
あります。
3.
GridMate セッションをホストする、または結合する前に、CarrierDesc::m_driver プ
ロパティを SecureSocketDriver のインスタンスに設定して、CarrierDesc を定義しま
す。SecureSocketDriver のインスタンスが指定されない場合、プレーンテキスト通信を提供
する非暗号化ドライバが使用されます。
Version 1.6
512
Lumberyard 開発者ガイド
暗号化の有効化
4.
GridMate セッションの終了時に SecureSocketDriver インスタンスを削除できます
(SessionEventBus の OnSessionDelete イベントで削除するのが理想的です)。
このトピックの最後にある「GridMate セッションの暗号化の例 (p. 514)」には、この手順のサンプ
ルコードがあります。
SecureSocketDesc
SecureSocketDriver のコンストラクタでは、安全な接続に必要なすべての暗号化設定を指定する
SecureSocketDesc オブジェクトが必要です。設定パラメーターを次の表で説明します。
SecureSocketDesc の設定パラメーター
パラメータ
説明
m_privateKeyPEM
Base-64 でエンコードされた文字列の PEM プライベートキー。
m_certificatePEM
Base-64 でエンコードされた文字列の PEM 公開証明書。
m_certificateAuthorityPEM
Base-64 でエンコードされた文字列の PEM 認証局。
m_authenticateClient
1 に設定されると、クライアントは認証用の署名証明書が提供される
ものと見なします。これを実装するには、m_certificatePEM をク
ライアントに設定し、サーバーで m_certificateAuthorityPEM を
セットアップする必要があります。デフォルトの設定は 0 です。
サーバー認証のみ
接続するサーバーの信頼性をクライアントが確認する必要がある場合、サーバー認証のみの設定が使
用できます。サーバーは秘密のプライベートキーと、認証局によって署名された公開証明書を保持し
ます。これは、最も一般的な設定です。
サーバー認証のみの設定
ロール
パラメータ
クライアント
m_certificateAuthorityPEM
サーバー
m_privateKeyPEM、m_certificatePEM、m_certificateAutho
クライアントとサーバーの認証
クライアントがサーバーの信頼性を確認する必要があり、同時にサーバーもクライアントの信頼性を
確認する必要がある場合にこの設定を使用します。クライアントは独自の一意のプライベートキー
と、対応する署名された公開証明書を保持します。サーバーは独自の一意のプライベートキーと、対
応する署名された公開証明書を保持します。
両方で同じ認証局を共有または使用できますが、キーと証明書はそれぞれで一意である必要がありま
す。
クライアントとサーバーの認証の設定
ロール
パラメータ
クライアン m_privateKeyPEM、m_certificatePEM、m_certificateAuthorityPEM
ト
Version 1.6
513
Lumberyard 開発者ガイド
暗号化の有効化
ロール
パラメータ
サーバー
m_privateKeyPEM、m_certificatePEM、m_certificateAuthorityPEM
自己署名証明書
開発を目的として自己署名証明書が使用できます。
Warning
本稼働環境では自己署名証明書を使用しないでください。
自己署名証明書を使用すると、公開証明書に署名する認証局がなくなります。認証局の欠如を防止す
るには、m_certificateAuthorityPEM を m_certificatePEM と同じ値に設定します。
GridMate セッションの暗号化の例
次のコード例では、GridMate セッションでの暗号化を有効にします。
class MyClass : public GridMate::SessionEventBus::Handler
{
public:
void OnSessionDelete(GridMate::GridSession* session) override;
private:
GridMate::SecureSocketDriver* m_secureDriver;
};
void MyClass::JoinSession() {
// ...
// Create an instance of SecureSocketDesc and set its encryption
parameters.
GridMate::SecureSocketDesc secureDesc;
secureDesc.m_privateKeyPEM = "..."
secureDesc.m_certificatePEM = "..."
secureDesc.m_certificateAuthorityPEM = "..."
// Create an instance of SecureSocketDriver that passes in the instance of
// SecureSocketDesc.
m_secureDriver = new GridMate::SecureSocketDriver(secureDesc);
// Before hosting or joining a GridMate session, set the
CarrierDesc::m_driver
// property to the instance of SecureSocketDriver.
carrierDesc.m_driver = m_secureDriver;
// ...
}
// At the end of the GridMate session, delete the SecureSocketDriver
instance in
// the OnSessionDelete event.
void MyClass::OnSessionDelete(GridMate::GridSession* session) {
// ...
delete m_secureDriver;
Version 1.6
514
Lumberyard 開発者ガイド
帯域幅の利用率の制御
m_secureDriver = nullptr;
// ...
}
帯域幅の利用率の制御
GridMate (p. 481) では、帯域幅スロットリングなど、ゲームで使用する帯域幅とレプリ
カ (p. 494)の更新の優先順位を制御する方法がいくつかあります。
送信レートの制御
GridMate を使用して、マルチプレイヤーゲームでの帯域幅の利用率を減らすための共通の技術である
サーバーの送信レートを制御できます。このシナリオでは、マルチプレイヤーゲームは、クライアン
トがデフォルトのレート (たとえば、1 秒に 60 フレーム) でレプリカの変更を送信する専用サーバー
によってホストされます。帯域幅の利用率を減らすには、サーバーの送信レートを低くします (たと
えば、1 秒あたり 20 回の送信)。この技術を使用する場合にジッターを避けるには、クライアントは
サーバーから受け取ったゲームの状態を補間できる必要があります。
GridMate でサーバーの送信レートを制御するには、レプリカのデータ送信の時間間隔を設定します。
ReplicaMgr* replicaManager = session->GetReplicaMgr(); // Get the replica
manager instance. This assumes the session has been established.
replicaManager->SetSendTimeInterval(100); // Set the send interval to 100
milliseconds. 10 updates per second will be sent.
SetSendTimeInterval を 0 に設定すると、エンジンのフレームレートでデータを送信します。デ
フォルト: 0。
帯域幅振幅リミッター
もう 1 つの技術は、オブジェクトのレプリケーションでのレイテンシーの増大と引き替えに、送信の
帯域幅を制限することです。GridMate では、レプリカマネージャーに帯域幅制限を設定して、これを
制限できます。そのためには、以下の例のように、SetSendLimit のバイト制限を指定します。
ReplicaMgr* replicaManager = session->GetReplicaMgr(); // Get the replica
manager instance. This assumes the session has been established.
replicaManager->SetSendLimit(10000); // Set the transmission limit to 10
kilobytes per second.
SetSendLimit を 0 に設定すると、帯域幅振幅リミッターが無効になります。デフォルト: 0。
バーストの長さの制御
帯域幅の利用率がまだ最大値になっていない場合、GridMate リミッターを使用して、帯域幅の短期
バーストに対応できます。これは多くのゲームアプリケーションに便利です。たとえば、ユーザーが
マルチプレイヤーロビーにいる場合は、対応する帯域幅の利用率は低くなります。ただし、ユーザー
がゲームを結合すると、最初のゲームの状態はサーバーからクライアントにレプリケートするため、
帯域幅の利用率は急増 (スパイク) します。許可されたバーストの長さを制御するには、次の例のよう
に、SetSendLimitBurstRange の希望の秒数を指定します。
ReplicaMgr* replicaManager = session->GetReplicaMgr(); // Get the replica
manager instance. This assumes the session has been established.
Version 1.6
515
Lumberyard 開発者ガイド
レプリカの更新の優先順位付け
replicaManager->SetSendLimitBurstRange(5.f); // Set the maximum permitted
length of the burst to 5 seconds.
帯域幅利用率のバーストは指定した秒数に対して許可され、その後、帯域幅は SetSendLimit で設定
された値が上限になります。[SetSendLimitBurstRange] のデフォルト値は 10 (秒) です。バースト
が発生したときに帯域幅の利用率がすでに制限値に達していた場合、帯域幅の利用率はずっと制限さ
れ、SetSendLimitBurstRange の設定は効果がありません。
レプリカの更新の優先順位付け
すべての のレプリカのチャンク (p. 497)には、割り当てることができる優先事項があります。優先
順位は 0 ～ 65534 の整数で表されます。大きな整数は優先順位が高いことを表します。優先順位の高
いレプリカは最初に送信されます。デフォルト: 32768。
帯域幅振幅リミッターを使用して、どのオブジェクトがより重要で、どのオブジェクトがそれほど重
要でないかを定義できるため、この優先順位付けは、帯域幅振幅リミッターを使用するときに特に重
要です。ゲームに帯域幅の制限があり、レプリカに適切に優先順位を付けた場合、優先度の高いオブ
ジェクトが頻繁に送信されます。優先度の低いオブジェクトは、対応できる十分な帯域幅がある場合
にのみ送信されます。
便宜上、GridMate は、カスタムレプリカのチャンクに使用できる 5 つの定義済みの優先順位を提供し
ます。
static const ReplicaPriority k_replicaPriorityHighest = 0xFFFE; // Decimal
65534, highest priority.
static const ReplicaPriority k_replicaPriorityHigh = 0xC000;
49152, high priority.
// Decimal
static const ReplicaPriority k_replicaPriorityNormal = 0x8000;
32768, normal priority. This is the Default.
// Decimal
static const ReplicaPriority k_replicaPriorityLow = 0x4000;
16384, low priority.
// Decimal
static const ReplicaPriority k_replicaPriorityLowest = 0x0000;
lowest possible priority.
// Decimal 0,
デフォルトでは、すべてのチャンクに通常の優先順位があります (k_replicaPriorityNormal)。こ
れらの定義済みの優先順位をそのまま使用するか、次の例のように、これらを使用して独自の優先順
位を作成できます。
// A replica chunk with this priority will be sent before all the chunks with
Normal priority, but after all the chunks with High priority:
const ReplicaPriority k_myCustomPriority = (k_replicaPriorityNormal
+ k_replicaPriorityHigh) / 2; // (=Decimal 40960)
レプリカ全体の優先順位は、チャンクでは最高の優先順位です。あるチャンクの優先順位はチャンク
の作成後か、次の例のように、運用期間中いつでも設定できます。
MyChunk::Ptr myChunk = GridMate::CreateReplicaChunk<MyChunk>(...);
myChunk->SetPriority(k_replicaPriorityLow); // Sets low priority for myChunk.
同じ優先順位のチャンクは、作成された順に送受信されます。先に作成されたレプリカは最初に送受
信されます。
Version 1.6
516
Lumberyard 開発者ガイド
実行時の帯域幅調整
実行時の帯域幅調整
次の設定変数 (CVars) を使用して、ゲームの実行中、帯域幅の利用率を調整できます。
CVar
説明
gm_replicasSendTime
レプリカの送信間隔の時間 (ミリ秒)。値が 0 の場合、間隔は GridMate のティック
レートにバインドされます。
gm_replicasSendLimit
1 秒あたりに送信できるレプリカデータ量の制限 (バイト)。値が 0 の場合、制限が
無効になります。
gm_burstTimeLimit
帯域幅でのバーストが許可される時間 (秒)。バーストは、バーストが発生したとき
に帯域幅が制限されない場合のみ許可されます。
ネットワークのシリアル化と各側面
ネットワークを介して同期されるオブジェクトにはすべて、NetSerialize() という関数がありま
す。GameObject では、これは IGameObject::NetSerialize() のように表示されます。
NetSerialize() 関数は ISerialize タイプの TSerialize オブジェクトを使用して、関連データ
をストリームに変換します。シリアル化ではさまざまな側面とプロファイルを使用して、各種のスト
リームを区別します。
Note
特定の側面およびプロファイルでシリアル化されたデータは、固定された状態で維持する必
要があります。たとえば、4 つの浮動小数点数をシリアル化した場合、常に 4 つの浮動小数点
数をシリアル化する必要があります。
側面
側面を使用して、データを論理的にグループ化します。
側面は次のように定義されます。
• eEA_GameClient – クライアントからサーバーに送信された情報 (クライアントがそのオブジェク
トに対する権限をもっている場合)。
• eEA_GameServer – クライアントのデータストリームに対する通常のサーバー。
• Dynamic/Static – 絶えず変化しているデータは Dynamic 側面に追加する必要があります。ほと
んど変更されないオブジェクトは Static 側面に追加する必要があります。変更される値が 1 つの
みの場合、更新は送信されません。
• eEA_Script – スクリプト RMI の呼び出しを含めて、スクリプトネットワークデータがトランス
ポートされる場合に使用されます。
• eEA_Physics – 物理データがトランスポートされる場合に使用されます。常に同じパス (制御クラ
イアント) を使用して他のクライアントに対応するため、クライアント/サーバーに分割されること
はありません。
プロファイル
プロファイルでは、側面の固定形式データを変更することができます。側面ごとに 8 つのプロファイ
ルが存在する可能性があり、物理的な側面にのみ使用されます (たとえば、ラグドールと生きているエ
ンティティ間の切り替え)。
Version 1.6
517
Lumberyard 開発者ガイド
RMI 関数
RMI 関数
リモートメソッドインボケーション (RMIs)を送信するには、以下のシンタックスを持つInvokeRMI
functionを使用します：
void InvokeRMI( IRMIRep& <rep>, ParamsType&& <params>, uint32 <where>,
ChannelId <channel> = kInvalidChannelId );
パラメーター
<rep>
コールされるリモートファンクションを意味します (the RMI ID).
<params>
リモートファンクションに移行するためにパラメーターを特定します。
<where>
RMIが送信されるクライアントのカテゴリーを決定するフラグを特定します。詳しくは、このド
キュメントの下部にある RMI ファンクションフラグ (p. 519) セクションを参照してください。
<Channel>
RMIが送信されるクライアント、または送信されないクライアントを特定します。詳しくは、こ
のドキュメントの下部にある RMI ファンクションフラグ (p. 519) セクションを参照してくださ
い。
RMIファンクションのオーダリング
IGameObject.h ファイルはRMIクラスを示すマクロ（例えば、DECLARE_SERVER_RMI_<...>から
始まるもの)を含みます。異なるデクラレーションタイプは以下の通りです：
• PREATTACH – RMIはオブジェクトのデータ更新の上部に添付されています。このデクラレーション
タイプは新しいインカミングデータのためのリモートエンティティを準備するために使うことがで
きます。
• POSTATTACH – RMIはデータ更新の下部に添付されているため、データが変換された後にコールさ
れます。このデクラレーションタイプは新しいデータを使用したアクションを完了するのに使用す
ることができます。
• NOATTACH – RMIはデータ更新には添付されていないので、RMIはデータを利用することができませ
ん。このデクラレーションタイプはデータに依存しないコールに対して使用できます。.
オーダリングルール
RMIのオーダーはオブジェクトとアタッチメントタイプセット内のみで適用可能です。
例えば、以下の並べられたリストでは、PLAYER RMI 1, 2, 3 はこのオーダーにしたがって到着しま
す。しかし、ITEM RMI 1がほかのPLAYER RMIsよりも前、もしくは後に到着することもあります：
• PLAYER RMI 1
• PLAYER RMI 2
• ITEM RMI 1
• PLAYER RMI 3
デクラレーションタイプの使用は、インカミングデータのオーダーをとても複雑にします。
• PREATTACH – メッセージはその中で整理されます。
Version 1.6
518
Lumberyard 開発者ガイド
RMI ファンクションフラグ
• POSTATTACH – メッセージはその中で整理されます。
• NOATTACH– メッセージはその中で整理されます。しかし、 NOATTACHは以下のダイアグラムのどち
らかのサイドにしか振り分けられず、サイド間に振り分けられることはありません：
RMI ファンクションフラグ
RMIを受け取るクライアントを特定するには、以下のフラグのうちのひとつと<where>パラメーター
とを入れ替えます。パラメーターはファンクション[InvokeRMI function]内にあります。
サーバーRMIs
eRMI_ToClientChannel
RMIをサーバーから特定のクライアントに送信します。 [<channel> parameter]内のデスティ
ネーションチャンネルを特定します。
eRMI_ToOwningClient
RMIをサーバーからアクターを所有するクライアントに送信します。
eRMI_ToOtherClients
RMIをサーバーから、特定のクライアントを除いたすべてのクライアントに送信します。
[<channel> parameter]内で無視するクライアントを特定します。
eRMI_ToRemoteClients
RMIをサーバーからすべてのリモートクライアントに送信します。ローカルクライアントを無視
します。
eRMI_ToOtherRemoteClients
RMIをサーバーから、特定のリモートクライアントを除いたすべてのリモートクライアントに送
信します。ローカルクライアントを無視します。[<channel> parameter]内で無視するように特定
されたリモートクライアント。
eRMI_ToAllClients
RMIをサーバーからすべてのクライアントに送信します。
クライアントRMIs
eRMI_ToServer
RMIをクライアントからサーバーに送信します。
例
RMIとして実行されるファンクションを定義するには、IMPLEMENT_RMI #define を使用します。
（[IGameObject.h]から
#define IMPLEMENT_RMI(cls, name)
）
以下の例はCl_SetAmmoCountという、CInventoryクラス内でタイプTRMIInventory_Ammoの引数
を渡すクライアントサイドRMIとして使用するためにコールされる新機能を実行します：
Class CInventory : public CGameObjectExtensionHelper<CIventory, IInventory>
Version 1.6
519
Lumberyard 開発者ガイド
例
{
// …
DECLARE_CLIENT_RMI_NOATTACH(Cl_SetAmmoCount, TRMIInventory_Ammo,
eNRT_ReliableOrdered);
// …
};
IMPLEMENT_RMI(CInventory, Cl_SetAmmoCount)
{
// Game code:
TRMIInventory_Ammo Info(params);
IEntityClass* pClass = gEnv->pEntitySystem->GetClassRegistry()>FindClass(Info.m_AmmoClass.c_str());
If (pClass)
SetAmmoCount(pClass, Info.m_iAmount);
return true;
// Always return true - false will drop connection
}
The following line will invoke the function:
pInventory->GetGameObject()->InvokeRMI(CInventory::Cl_SetAmmoCount(),
TRMIInventory_Ammo(“Pistol”, 10), eRMI_ToAllClients);
以下のラインでその機能を引き起こします：
pInventory->GetGameObject()->InvokeRMI(CInventory::C1_SetAmmoCount(),
TRMIInventory_Ammo("Pistol", 10), eRMI_ToAllClients);
Version 1.6
520
Lumberyard 開発者ガイド
ジオメトリ
物理
このセクションでは、物理システムの詳細と物理エンジンの操作方法について説明します。
物理世界のオブジェクトを作成するには、CreatePhysicalWorld() 関数を使用しま
す。CreatePhysicalWorld() 関数は、IPhysicalWorld インターフェイスを参照するポインタ
を返します。世界をジオメトリと物理エンティティで埋めます。このセクションで説明されている関
数でエンティティを制御します。ほぼすべてのエンティティに適用できる関数もあれば、特定のエン
ティティ構造にしか適用できない関数もあります。また、エンティティの相互作用を制御したり、世
界がエンティティに与える影響を制御したりする関数もあります。
以下のセクションで、これらのトピックについて詳しく説明します。
トピック
• ジオメトリ (p. 521)
• 物理的なエンティティ (p. 523)
• エンティティ構造の関数 (p. 526)
• Collision クラス (p. 533)
• 世界エンティティに対する関数 (p. 536)
ジオメトリ
ジオメトリは最初に独立オブジェクトとして作成されます。これにより、ジオメトリが公開される
IGeometry インターフェイスを介して単独で使用することができ、その後、物理化して物理的なエン
ティティに追加することができます。ジオメトリの物理化は、物理的性質 (ボリューム、慣性テンソ
ル) の計算と特殊な内部構造への格納を意味しています。これらの構造へのポインタは、物理的なエン
ティティに渡すことができます。
物理化された各ジオメトリには参照カウンタがあり、作成時に 1 に設定され、ジオメトリがエンティ
ティに追加されるたびに増分され、ジオメトリが削除されるかエンティティが削除されるたびに減
らされます。カウンタが 0 に達すると、物理ジオメトリ構造は削除され、対応する IGeometry オブ
ジェクトが解放されます。IGeometry オブジェクトも参照カウントされます。
Version 1.6
521
Lumberyard 開発者ガイド
ジオメトリ管理関数
ジオメトリ管理関数
ジオメトリ管理関数は、物理世界の一部であるジオメトリマネージャーを通じてアクセスできます。
ジオメトリマネージャーへのポインタを取得するには、GetGeomManager() 関数を呼び出します。
CreateMesh
CreateMesh ジオメトリ管理関数は、頂点とインデックスのセット (1 つの三角形に 3 つのインデッ
クス) から三角形メッシュオブジェクトを作成し、対応する IGeometry ポインタを返します。
• エンジンは三角形の連結情報を多くの場所で使用するため、メッシュを閉じてマニホールド化する
ことを強くお勧めします。この関数は空間にある同じポイントを表す異なる頂点を認識し、連結性
を計算することができます (公差は存在せず、正確な複製のみを確認します)。ジオメトリが動的な
物理エンティティとして使用されず、そのジオメトリとのやり取りがほとんど、あるいはまったく
発生しない場合にのみ、エッジが開いていても問題ありません。
• 衝突を検出するために、この関数は OBB、メモリ最適化 AABB、または単一のボックスツリーのい
ずれかを作成できます。対応するフラグを指定することで選択できます。AABB フラグと OBB フラ
グの両方が指定されている場合、関数はジオメトリに最もタイトに適合しているツリーを選択しま
す。ほとんどの場合、OBB ツリーの方がタイトであるため、メモリを節約するために AABB の優先
度が高くなる可能性があります (また、ツリーが同等にタイトである場合、AABB チェックの方がわ
ずかに高速です)。エンジンは、頂点/インデックスのデータをコピーするか、提供されたポインタか
らそのデータを直接使用することができます。
• mesh_multycontact flags は、複数の接触が可能であるかどうかについてのヒントを提供しま
す。複数の接触が発生する可能性を低く指定することで (mesh_multycontact0)、パフォーマンス
を少し向上させることができます。ただし、複数の接触が発生した場合は、それらの接触が失われ
る可能性があります (複数の接触が必ずしも失われるというわけではなく、より積極的に最適化を利
用するアルゴリズムに関するヒントです)。mesh_multycontact2 はこの最適化を無効化します。
推奨されるデフォルト設定は ..1 です。内部的には凸状オブジェクトに対する個別のクラスはあり
ませんが、凸状のジオメトリが検出され、そのジオメトリに対して追加の最適化がいくつか使用さ
れます (将来的に変更される可能性があります)。
• メッシュはフェースごとにマテリアルを持つことができます。マテリアルは、摩擦、跳ね返り度、
ピアシング性の係数を調べるために使用され、衝突検出出力の一部としてゲームによってクエリを
実行できます。
• CreateMesh 関数は、(指定された公差を備えた) プリミティブを表すメッシュを検出することがで
き、代わりにプリミティブオブジェクトを返します。この検出を有効にするには、対応するフラグ
を指定する必要があります。プリミティブはマテリアルを格納できないことに注意してください。
プリミティブは物理的なジオメトリ構造でのみマテリアルを保持できます。そのため、マテリアル
配列に 1 つ以上のマテリアルインデックスがある場合は、この検出は使用されません。
CreatePrimitive
CreatePrimitive: プリミティブジオメトリを明示的に作成します。対応するプリミティブ (シリン
ダー、球体、ボックス、ハイトフィールド、またはレイ) 構造を満たし、::type とともにパラメーター
として渡す必要があります。
RegisterGeometry
RegisterGeometry は物理的性質を計算して補助構造に格納することで、IGeometry オブジェクト
を物理化します。マテリアルインデックス (surfaceidx) はその中に格納でき、ジオメトリ自体にマ
テリアルを指定していない場合に使用されます (プリミティブである場合など)。AddRefGeometry と
UnregisterGeometry は参照「サンドイッチ」で構成されています。後者は、参照カウントが 0 に
なるまでオブジェクトを削除しないことに注意してください。
ジオメトリと物理化されたジオメトリはシリアル化できます。これにより、OBB ツリーの計算に要す
る時間が短縮されます。この計算が特に遅いというわけではありませんが、シリアル化することで高
速化できます。
Version 1.6
522
Lumberyard 開発者ガイド
物理的なエンティティ
物理的なエンティティ
物理的なエンティティは物理的世界のCreatePhysicalEntityメソッドを呼び出すことにより作成
できます。CreatePhysicalEntity は以下の表に示すエンティティの種類を作成できます。
物理的なエンティティのタイプ
型
説明
PE_ARTICULATED
接合個所といくつかのリジッドボディで構成される統合された構造（例えばラグ
ドール）いくつかの接合個所を持つ PE_RIGID エンティティを手動で接合すること
も可能ですが、その場合単一オブジェクトであることを認識しないため、いくつか
の便利な最適化が使用できません。
PE_LIVING
物理世界中を移動し、インタラクトすることが可能なプレーヤーのキャラクターを
表現する特別なエンティティタイプ。
PE_PARTICLE 小さく軽量なリジッドボディを表す簡素なエンティティ。これは点とある程度の厚
みでシミュレートされ、飛行、スライディング、回転モードをサポートします。推
奨使用: ロケット、手榴弾や小さな残骸。
PE_RIGID
単一のリジッドボディ（質量を0に指定することで）無限質量を持つことができま
す。これはシミュレートされませんが、他のシミュレートされたオブジェクトと適
切に作用します。
PE_ROPE
ロープのオブジェクト。自由につるしたり、2つの純粋な物理的エンティティを接
続できます。
PE_SOFT
環境に作用することができる、ゆるく接続された頂点のシステム。一般的な使用方
法は布のオブジェクトです。
PE_STATIC
不動のエンティティ。不動のエンティティは外部から場所を設定して手動で移動さ
せることができますが、シミュレートされたオブジェクトと適切にインタラクショ
ンすることを確認するには、無限質量を持つエンティティPE_RIGIDを使用するこ
とをお勧めします。
PE_WHEELEDVEHICLE
車輪を持つ乗り物内部的にはリジッドボディの上に乗り物としての機能（車輪、サ
スペンション、エンジン、ブレーキ）が追加され構築されます。
Note
PE_RIGID、PE_ARTICULATEDおよびPE_WHEELEDVEHICLEはシミュレーションエンジンの
中心部を構成する真の物理的エンティティです。その他のエンティティは独自に処理されま
す。
エンティティの作成と管理
エンティティを作成および管理する場合、次の点に留意してください。
• エンティティは2Dの標準グリッドを使用して、広範囲フェーズでの衝突検出を高速化します。グ
リッドは、物理的なエンティティが作成される前にSetupEntityGrid関数を呼び出す必要があり
ます。
• エンティティは永続的にもオンデマンドモードでも作成可能で、パラメータlifeTime（永続的な
エンティティには0を使用）により指定されます。オンデマンドモードでは、エンティティのプレー
スホルダーはCreatePhysicalPlaceholderを使用して作成する必要があります。物理はその後
外部システムを呼び出し、このプレースホルダ―の境界ボックスでインタラクションが必要とされる
際に完全なエンティティを作成します。
Version 1.6
523
Lumberyard 開発者ガイド
エンティティの作成と管理
• エンティティが指定期間中にいずれのインタラクションにも関わらない場合は、プレースホルダ―の
みが残りエンティティは破壊されます。プレースホルダーは完全なエンティティよりも必要なメモ
リが少ないです。（約70バイト対260バイト）外部システムは、必要に応じて他のプレースホルダ―
を作成するメタプレースホルダ―などの階層プレースホルダーをサポートすることも可能です。
• セクターベースでオンデマンドのフィジカライズはRegisterBBoxInPODGridが呼び出され
た後に実行されます。エンティティはセクター毎に作成され破壊されます。セクターサイズ
はSetupEntityGridで指定します。
• 物理的世界で1つの特別な静的地形オブジェクトを設定するには、SetHeightfieldDataを使用し
ます。無制限の地形のジオメトリを手動で作成し、エンティティに追加することもできます。
エンティティの破壊、停止、復元
物理的なエンティティを破壊、中断、または復元するには、DestroyPhysicalEntityを使用し
て、modeパラメータをそれぞれ0、1、または2に設定します。エンティティを中断すると、対象
エンティティを削除せずとも、制約を含めた他のエンティティとの接続すべてが消去されます。エ
ンティティを中断した後に復元する場合、切断された接続は全て自動的に復元されるわけではあり
ません。削除されたエンティティはすぐには完全に破壊されません。代わりに、それらのエンティ
ティはごみ箱に入れられます。片方向接続への参照は削除する必要があるかもしれません。ごみ箱は
各TimeStepの最後に空になります。または、PurgeDeletedEntitiesを呼び出すこともできます。
物理的エンティティのID
全ての物理的エンティティには物理的エンジンが自動的に生成する個別のIDがあります。作成時にID
を指定する必要はありません。新しいIDを後に設定することもできます。エンティティは依存関係情
報を保存するこれらのIDをシリアル化の実行中に使用します。保存状態を読み込むときは、エンティ
ティが同じIDを所有していることを確認してください。IDは配列を使用するエンティティのポインタ
にマッピングされるため、桁数の大きいID番号を使用することは、大きく配列の割り当てることにつ
ながります。
外部のオブジェクトの関連付け
外部エンジンオブジェクトの関連付けを維持するには、物理的なエンティティは追加の無効ポインタ
と2つの16ビット整数を格納します (pForeignData、iForeignData、およびiForeignFlags)。
これらのパラメータはエンティティではなく、外部から設定されます。pForeignDataを使用してポ
インタを外部のエンジン参照エンティティに保存し、該当する場合はiForeignDataを使用してエン
ティティタイプを保存します。
各素材インデックスについて、物理的世界は摩擦係数、跳ね返り（変換）計数、およびフラグを保存
します。2つの表面が接触するとき、接続部の摩擦および跳ね返りは、両方の表面の平均値を取って計
算されます。フラグはレイトレーシングのみに影響します。
シミュレーションタイプ
物理的エンティティはシミュレーションタイプの「認知度」が上昇する順にグループ化されます。
レイトレーシングや特定のエリアにおけるエンティティのクエリなど、特定のインターフェース関数
は、これらのエンティティのタイプによる絞り込みが可能です。
• 0 (bitmask ent_static) – 静的エンティティ。地形は静的とみなされますが、特別なシミュレー
ションタイプはありません。これはent_terrainビットマスクから独立して絞り込みが可能です。
• 1bitmask ent_sleeping_rigid) (– 実行を停止した物理的オブジェクト（リジッドボディと接続
されたボディ）
• 2 (bitmask ent_rigid) – 実行中の物理的オブジェクト。
• 3 (bitmask ent_living) – 生きているエンティティ。
• 4 (bitmask ent_independent) – 他のエンティティから独立してシミュレートされる物理的エン
ティティ（パーティクル、ロープ、およびソフトオブジェクト）
• 6 (bitmask ent_triggers) – シミュレートされないエンティティ（またはプレースホルダ―）
で、他のエンティティが境界ボックスに入ったときにコールバックのみを発行するもの
Version 1.6
524
Lumberyard 開発者ガイド
エンティティの作成と管理
• 7 (bitmask ent_deleted) – ごみ箱の中にあるオブジェクト。これは直接使用しないでくださ
い。
シミュレーションタイプの低いエンティティは、高いシミュレーションタイプを持つエンティティを
認識しません（タイプ1と2はこのために考慮されています）。そのため、プレーヤー（タイプ3）お
よびパーティクル（タイプ4）は物理的エンティティ（タイプ1とタイプ2）に対して衝突を確認しま
すが、物理的エンティティは何も知らない状態です。同様に、ロープ（タイプ4）はプレーヤーに対し
て衝突を認識しますが、その逆はありません。しかし、高いタイプのエンティティは衝動と制約を使
用することで低いタイプのエンティティに影響を与えることができます。ほとんどのエンティティは
特定のシミュレーションタイプを想定します（また、自動的に適切な値に設定されます）。
この「認知階層」には例外があります。例えば、接合されたエンティティはタイプ1とタイプ2では完
全な死体として、タイプ4では環境に影響したりされたりすることなく衝撃アニメーションを再生する
ことができる骸骨としてシミュレートできます。
物理的エンティティの関数
物理的エンティティのほとんどのインタラクション
は、AddGeometry、SetParams、GetParams、GetStatus、および Actionを使用します。
• AddGeometry – エンティティに複数のジオメトリ (フィジカライズされたジオメトリ) を追加しま
す。詳細については、以下のジオメトリ追加セクションを参照してください。
• RemoveGeometry – エンティティからジオメトリを削除します。
• SetParams – パラメータを設定します。
• GetParams – シミュレーションの入力パラメータを取得します。
• GetStatus – シミュレーションの出力パラメータを取得します。GetStatus シミュレーション中
にエンティティが変更する値をリクエストします。
• Action – エンティティに衝動の追加など、アクションを実行させます。
これらの関数はパラメータとして構成のポインタを取得します。コマンドを実行するには対応する構
造 (ローカル変数としてなど) を作成し、必要なフィールドのみを指定できます。各構造のコンストラ
クタは、物理エンジンにフィールドが未使用であることを伝える全てのフィールドに特別な値を提供
します。また、MARK_UNUSEDmacro andis_unusedを使用すると、明示的にフィールドが未使用であ
ることを確認できます。
ジオメトリの追加
AddGeometryはエンティティにフィジカライズされたジオメトリを追加します。各ジオメトリには次
のプロパティがあります。
• id – ジオメトリが属するエンティティの境界中にある独自のパーツ識別子。IDを指定する
か、AddGeometryを使用すると値を自動的に生成できます。パーツ配列が変更になった場合（例え
ば、中心のいくつかのパーツが削除された場合）はIDは変更しませんが、内部パーツインデックス
は変更する可能性があります。
• position、orientation、およびuniform scaling – エンティティに関連します。
• mass – 非静的オブジェクトに使用されます。静的オブジェクトは全てのインタラクションにおいて
無限質量を持っていると想定します。補完値が自動的に計算される質量や密度を指定できます（質
量=密度x体積の計算式を使用します。volumeはフィジカライズされたジオメトリ構造に保存され
ジオメトリが縮尺されるとあわせて縮尺されます。）
• surface_idx – Iジオメトリまたはフィジカライズされたジオメトリのどちらにも表面（素材）の
識別子がない場合に使用されます。
• flags およびflagsCollider – エンティティが他のオブジェクトとの衝突を確認するとき、現
在のパーツに通じるフラグマスクを持つパーツのみを確認します。flagsCollider特定のエン
ティティグループを表すには16型ビット(geom_colltype)を使用できます。強制ではありません
Version 1.6
525
Lumberyard 開発者ガイド
エンティティ構造の関数
が、これらの関係を対称に保つことは良い実践です。衝突確認が片方向であることが分かってい
る場合（例えば、エンティティAはエンティティBに対して衝突を確認するが、逆はあり得ない場
合）は、このルールを維持しないことも選択できます。特定のフラグは特別な衝突グループの場合
逆になります。例えばgeom_colltype1 = geom_colltype_playersおよびgeom_colltype2
= geom_colltype_explosionなどです。（爆発圧を計算するときは、このフラグの立った
パーツのみが考慮されます）また、レイトレーシングや浮力の計算にも特別なフラグがありま
す。geom_colltype_ray とgeom_floatsです。
• minContactDist – エンティティの現在のパーツの、他のエンティティのパーツとの接触部間の最
小距離。様々なパーツに属する接続部はこれを確認しません。未使用のまま残すこともでき、その
場合はジオメトリサイズに基づいて、デフォルト値で初期化します。各パーツはジオメトリとプロ
キシジオメトリの両方を保持できます。ジオメトリはレイトレーシングとプロキシジオメトリのみ
に使用されます。プロキシジオメトリを指定しない場合、レイトレーシングがパーツ配列のレイア
ウトを変更をしなくとも高ポリメッシュのテストができるよう、両方のジオメトリが同じに設定さ
れます。
エンティティ構造の関数
全般的および特定のエンティティ構造を制御する関数について説明します。
トピック
• 共通関数 (p. 526)
• 生きているエンティティ専用の機能 (p. 528)
• パーティクルのエンティティ固有の関数 (p. 530)
• 連結型エンティティ固有の関数 (p. 530)
• ロープのエンティティ固有の関数 (p. 532)
• ソフトエンティティ固有の関数 (p. 533)
共通関数
pe_params_pos
エンティティの場所と向きを設定します。相殺/四元数/スケーリング値を直接使うか、もしくは3x3
(orientation+scaling) または4x4 (orientation_scaling+offset）のマトリックスから物理学がそれらの
値を抽出することを許可できます。ベクトルがコラムになりながら、物理学は右から左へ変換す
るルールにしたがいます (vector_in_world = Matrix_Entity * Matrix_Entity_Parts *
vector_in_geometry)。マトリックスをサポートするすべてのインターフェース構造は、メモリー
にある行優先もしくは列優先のいずれか（後者は行列の転置と考えられ、対応するメンバーは名前の
最後にTの文字があります）のマトリックスレイアウトを使用できます。
エンティティごとのスケーリングはありません。スケーリングはパートに対してのみ表示されます。
新しいスケーリニグがpe_params_posとともに設置されると、これは各パートにコピーされ、以前
の個別スケーリングを上書きします。この構造ではマニュアルによってシミュレーションタイプを設
定することも可能です。変更が加えられた後、通常、エンティティの境界は再度計算され、エンティ
ティは衝突ハッシュグリッドに再登録されます。ただし、これはbRecalcBoundsを0にすることで延
期が可能です。
pe_params_bbox
エンティティの区切りボックスを特定の値にセットするか、またはGetParamsと使用されたときにそ
れの問い合わせをします。境界ボックスはエンティティのジオメトリに基づいて自動的に再計算され
ますが、ジオメトリ (トリガーなど)やプレースホルダーを使わずに境界ボックスを手動で設定するこ
Version 1.6
526
Lumberyard 開発者ガイド
共通関数
ともできます。エンティティにジオメトリがある場合、のちに、境界ボックスが後で再計算されるか
上書きされる可能性があります。境界ボックスは座標軸に適合し、世界調整システムに存在します。
pe_params_outer_entity
あるエンティティについての外部エンティティを指定します。関心対象のボックス（の中心）が外部
エンティティとともにエンティティの内部にある場合、外部エンティティは競合可能性の対象セッ
トから除外されます。これにより、関心対象の地域が建物の内部にあるときに、その建物の外部をす
ぐにくり抜くことができます。外部エンティティはネスト化することができ、閉じ込めテストのオプ
ションのジオメトリもサポートされます。
pe_params_part
エンティティパートのプロパティを設定もしくは問い合わせするパートは内部パートインデックスも
しくはIDを使って特定できます。
pe_simulation_params
これらのパラメータを受容できる（物理的エンティティ、ロープ、柔らかいエンティティなど）エン
ティティのためのシミュレーションパラメータを設定します。minEnergy はスリープ速度の二乗に
等しいです。ダンピングと重力は、衝突および落下状態についてそれぞれ独立に指定できます。例え
ば、コンタクトがないときなどです。
pe_params_part
オブジェクトと水線面の浮遊プロパティを設定する。物理エンジンは水容積のリストを持たないた
め、外部システムが変化に従い水線面パラメータを設定をアップデートしなければなりません。水
面は完璧な平面であるという理解されるため、表面の正常状態を乱すことで波の上下運動をシミュ
レーションすることができます。waterFlow は水運動の速度を指定し、waterResistance プロ
パティに基づいてオブジェクトに影響を及ぼします。水中では別のスリープ状態が使用されます
（waterEmin）。
pe_params_sensors
エンティティにセンサーを付ける。センサーは、エンティティがその周囲の環境をサンプル化するた
めに発射できる光線です。エンティティステップの内部から行うほうが、それぞれの光線について
エンティティステップの外側にある世界光線追跡機能を呼び出すよりも効率的です。生きているエン
ティティは垂直方向のセンサーをサポートします。
pe_action_impulse
エンティティに一度限りのインパルスを加えます。impulse はインパルスプロパティです（N*秒で；
インパルスPはオブジェクトの速度を、P/[オブジェクトの質量]だけ変化させます）。point は、イ
ンパルスが適用され、その回転効果を計算するのに使われるワールドスペースのポイントです。of
pointモーメンタムは、回転インパルスを明示的に指定するのに使われます。ポイントもモーメンタ
ムも指定されない場合、インパルスはオブジェクト質量の中心に適用されます。iApplyTime はイン
パルスが適用される時間を指定します。デフォルトで、値は２をとり（"after the next step"）、ソル
バがインパルスを反映させる機会を許可します。
pe_action_add_constraint
2つのオブジェクト間に制約を加えます。ポイントはワールドスペースの制限位置を指定します。2
つめのポイントが使用され、それが１つめのポイントと異なる場合、ソルバはそれに加わろうとしま
す。
相対的位置は常に完全に０（ボディの上にあるポイントは必ず同じスポットに置かれる、など）に制
限しようとし、相対的回転はひねったもしくはまがった方向に制限されます。これらの方向は、X軸
Version 1.6
527
Lumberyard 開発者ガイド
生きているエンティティ専用の機能
の周りの回転と、影響を受けたボディに取り付けられた2つの制約調整フレームとの間の相対的な変換
のYZ平面上（X軸の傾き）のラインの周りの回転に対応しています。
制約フレームの元の位置は、世界もしくはエンティティ調整スペースにあるqframeパラメータ
(flagsの対応するフラグで示されるとおりに)で特定される。１つもしくは両方のqframesが未使用の
場合、世界もしくはエンティティフレームでのアイデンティティ転換と考えられる。
回転制限は xlimits とyzlimits パラメータで、0（最小値）か1（最大値）の有効なエレメ
ント値によって指定されます。もし最小値が最大値と等しいまたは上回っている場合、対応す
る相対回転は禁止される。pConstraintEntity は、制約を体現するエンティティを特定しま
す。pe_action_add_constraint ポインターに渡されるとき、Actionは制約を取り除くことのできる制
約識別子を戻す。0は失敗を意味する。
pe_action_set_velocity
オブジェクトの速度を設定します。これは、無限質量（質量として表される）をもつ硬いボディなど
に有用です。pe_action_set_velocity はボディの速度を物理システムに伝え、オブジェクトが接
触されながらソルバがゼロ相対速度を確保することを助けることができます。速度が設定されず位置
のみが変わった場合、エンジンは接触を強制する侵入に対してのみ依存します。各フレームに手動で
位置が設定される場合は、速度は自動計算されません。一度特定の速度が設定されたら、ボディはそ
の速度で動き続けます。
pe_status_pos
エンティティもしくはその一部の現在の変化（ポジション、方向、スケール）をリクエストす
る。pe_params_posを使用できます（GetParamsを使って）。マトリックスポイントが設定される
とき、エンジンは対応するフォーマットでデータを提供します。この構造のBBoxメンバーはエンティ
ティの位置に相対的です。
pe_status_dymamics
エンティティの動作パラメータを引き出す。加速と角加速度は重力および他のオブジェクトとのイン
テラクションを元に計算される。エンティティに追加された可能性のある外部インパルスは即興であ
ると考えられる。submergedFraction は、最後のフレーム（geom_float フラグとのパーツのみが
考慮される）中のエンティティの水中容積の分数を表します。waterResistance は、ステータスが
最後にリクエストされた時から(ステータスが戻された場合、累積値はクリアされます)エンティティ
が一つのフレームで受ける最大水抵抗を含める。この値は水しぶき効果を与えるのに有用です。
生きているエンティティ専用の機能
生きているエンティティは、シリンダーやカプセルを境界ジオメトリとして使用します。通常、シリ
ンダーは地面から離れて浮遊しており、エンティティは単一の光線を下方向に出して、何かの上に
立っているかどうかを検出します。このシリンダージオメトリは必ず最初のパーツスロットに配置さ
れます（これは自動的に作成されます）。手動でもっと多くのジオメトリを追加することはできます
が、エンティティが動くときの環境への耐性はテストされません。しかし、他のエンティティはエン
ティティに対しての衝突テストを行っているときにそれらを処理します。
生きているエンティティは彼ら自身で方向を変えることはありません。必ず外的に設定されます。通
常、生きているエンティティはZ軸の周りを回転するとされますが、他の方向もサポートされていま
す。ただし、生きているエンティティに対する衝突は必ずシリンダーを垂直に方向づけます。
pe_player_dimensions (GetParams | SetParams)
生きているエンティティの境界ジオメトリの範囲を設定します。
heightPivot 足の位置（通常は０）と考えられるエンティティフレームのポイントのZ座標を設定し
ます。
Version 1.6
528
Lumberyard 開発者ガイド
生きているエンティティ専用の機能
heightEye は、エンティティに付加されるカメラのZ座標です。このカメラはエンティティの移動に
は影響しません。この唯一の目的は、エンティティが影響を受ける高さ変更を均一化にすることです
(範囲が変わったあと、階段などの特にでこぼこな地面を歩いているときや、飛行後の着陸時など)。
カメラの位置はpe_status_living構造を通じてリクエストできます。
sizeCollider はシリンダーのサイズを指定します (xは半径、zは高さの半分、yは未使用です)。
heightColliders はシリンダーの中心Z座標です。
ヘッド部分はシリンダーの上のオブジェクトとの衝突をチェックするための補助装置の球体です。
ヘッド衝突は移動には影響しませんが、カメラの位置が下へ動きます。headRadius は球の半径で、
headHeightは最上部の中心のZ座標です（何にも触れていないとき）。
pe_player_dynamics (GetParams | SetParams)
生きているエンティティの移動パラメータを設定します。生きているエンティティには「望ましい」
（「リクエストされた」ともいう）移動速度があり（ pe_action_moveで設定される）、その速度
に達するよう行動します。それがどのくらい速く起こるのかは、のkInertia設定によって異なりま
す。この値が大きいほど、より早くpe_action_moveで指定された速度に達します。デフォルトは 8
です。0は望ましい速度にすぐに達することを意味します。
kAirControl (0..1) は、エンティティの飛行中にリクエスト速度がどれくらい強く移動に対して影響
するかを指定しましす（１は新しいリクエスト速度が設定された場合に、実際の移動速度へコピーす
ることを意味します）。
kAirResistance は、飛行中にどのくらい速くに速度が低下するかについて説明します。
nodSpeed (デフォルト 60)は、着陸のときのカメラの反応強度を設定します。
bSwimming は、エンティティがすべての方向に動くことができるということを表すフラグです（ただ
し重力は下方向へ引っ張ります）。設定がない場合、エンティティが飛行していなければリクエスト
速度は必ず地面に反映されます。
minSlideAngle、maxClimbAngle、maxJumpAngle、minFallAngleは、特定のアクティビティに
対する最大もしくは最小の地面傾斜を指定する生きているエンティティの閾値の角度です。境界シリ
ンダーが傾斜面で衝突する場合は、動作はこの斜面のみに影響されるわけではないことに留意してく
ださい。
bNetworkの設定は、エンティティに同期が必要とされるであろうより長い移動履歴配列を割り当て
ます（設定がない場合、この配列にはステップバックなどの行動を行うときに最初のネットワーク関
連のアクションがリクエストされるときに割り当てられます）。
bActiveを０に設定すると、生きているエンティティを、環境との衝突をチェックせずリクエスト速
度でのみ動く「非アクティブ」状態へ移行させます（他のエンティティが衝突してくることもあり、
また同じもしくは高いシミュレーションクラスのエンティティにのみ適用されます）。
pe_action_move
生きているエンティティから移動をリクエストします。dirは、エンティティが到達しようとするリ
クエスト速度です。iJumpが０でない場合は、この速度は地面には反映されず、短時間の間地面へ
倒れなくなります。iJumpが１である場合は、移動速度は即座にdirと等しくなるように設定されま
す。iJumpが２である場合、dirが追加されます。dt は内部使用のために留保してあります。
pe_status_living
生きているエンティティのステータスを戻します。
vel は複数のフレームを通して変化したエンティティの位置から平均化された速度です。
Version 1.6
529
Lumberyard 開発者ガイド
パーティクルのエンティティ固有の関数
velUnconstrained は現在の移動速度です。エンティティが障害物にぶつかると、多くの場合、次
のフレームで障害が終わってもスピードは失われないように、移動速度を同じ水準に維持しつつも実
際の移動が制限されるため、現在の移動速度はvelと異なる可能性があります。
エンティティが何かの上に立っている時、groundHeight とgroundSlopeはZ地点の座標および標準
を含みます。それ以外の場合は、bFlyingは１です。pGroundColliderは、エンティティが非静的
オブジェクトに立っている場合にのみ設定されていることに留意してください。
camOffset はエンティティフレーム内の３Dベクトルとしての現在のカメラオフセットを含みます
（ただしZ座標のみがその内部で変化します）。
bOnStairs は、頻繁かつ突然高さが変更になるためにエンティティが現在階段を歩いているとみなす
ことを示す発見的フラグです。
パーティクルのエンティティ固有の関数
pe_params_particle
パーティクルエンティティのパラメータを設定する。
移動の間、それが何かに当たるかどうかをチェックするために、パーティクルは道の長
さsize*0.5（sizeは「半径」ではなく「直径」を表すため）に従った光線をトレースします。横た
わったりスライドしたりする場合、彼らは自らを表面からthickness*0.5の距離のところに位置させ
ます（つまり薄いガラスの破片などはシミュレーションできます）。
パーティクルは、設定によってaccThrustとaccLiftパラメータのあるつり上げ力（翼があると仮定
した場合）の押し込みによって追加的加速を得ることができますが、これらはkAirResistanceを指
定しない限り使われません。そうでなければ、パーティクルは無限の速度を得ることになります。
パーティクルは空中にあるときに、オプションでスピンできます (particle_no_spinフラグによっ
てトグルされます)。スピンはパーティクルの直線運動から独立していて、衝撃もしくは表面からの落
下後のみ変更されます。
パーティクルは移動方向へ位置づけることができます（particle_no_path_alignmentフラグに
トグルされます）。これは、ロケットのようなオブジェクトに非常に有用です。この場合、エンティ
ティのY軸はヘッドに方向づけられ、Z軸はYと上方ポイント（「上」方向はパーティクルの重力と真
逆）の直角に設定されます。
表面上を移動しているとき、パーティクルはスライドしたり転がったりすることができます。転がり
は、particle_no_rollフラグによって無効化できます（急傾斜では自動的に無効化されます）。
転がりは、通常の方法で摩擦の取り扱いをする一方で、パーティクル素材の摩擦を減速として使いま
す。地面に触れるとき、パーティクルは（エンティティフレームで定義される）標準が表面標準と平
行となるように自分自身を位置しなおします。
パーティクルは、必ず最初の方向も維持し(particle_constant_orientation) 、最初の接触のあ
と完全に停止します (particle_single_contact)。minBounceVel は、接触の跳ね返り度が０以
上であるとしても、パーティクルが跳ねなかった後の低いほうの速度閾値を指定します。
連結型エンティティ固有の関数
連結型エンティティは、構造単位とよばれる連結した硬い物体から構成されます。各構造単位は、構
造親に接続する接合箇所があります。接続構造では、単一ルートを持つツリーを使用するべきです。
連結ループは許可されていません。
連結型エンティティフェザーストーンモードを使うことで環境に作用することなくボディー効果をシ
ミュレーションすることができ、さらに、複雑なボディー構造に硬い弾力をもたせられるような強
い衝撃を吸収できるエンティティとして微調整できます。連結型エンティティは、インタラクティブ
モードに共通のソルバを使用します。
Version 1.6
530
Lumberyard 開発者ガイド
連結型エンティティ固有の関数
pe_params_joint
pe_params_jointを使用して
• 連結型エンティティでボディー間の接合箇所を作成します。
• 存在する連結型エンティティのパラメータを変更します。
• GetParamsと使用された場合は、存在する連結型エンティティのパラメータを問い合わせします。
接合部は、ピボットポイント（エンティティフレーム内）のopパラメータで指定された２つのボ
ディー間で作成されます。ジオメトリが連結型エンティティに追加されるときに、ジオメトリが
（idbody内の)どのボディーに属するかを指定するのにpe_articgeomparamsを使います。idbody
は、あらゆる固有の数字をとることができ、各ボディーは複数のジオメトリを持つことができます。
接合箇所が作成される順序には制限がありませんが、すべてのエンティティ内のボディはシミュレー
ションが開始される前に接合していなければなりません。
接合部はEulerアングルを使って回転制限を定義します。angle0_で始まるフラグは、ゼロベースアン
グルインデックスで左へシフトすることで、各アングルごとに個別に指定されます。例えば、Z軸を
ロックするには、angle0_locked<<2とのフラグを使用することができます。子ボディは、割り当て
られた最初のエンティティ (ジオメトリ) から等位のフレームを継承します。
接合アングルリミットは、接合部が接合するボディ間の相対的なフレームによって定義されます。子
ボディのフレームは必要に応じて、q0、pMtx0、またはpMtx0Tを使った回転角度 (0,0,0) と一致するよ
うな子の方向を指定することでオフセットされます。Eulerアングルを使うことで、安定して存在する
制限の取得を手助けすることができます。
一般的な制限ルールは、上限と下限を少なくとも15から20度以上離れて制限し (シミュレーション設
定および接合速度の高さに依存)、Y軸制限をを-90..90度の範囲に維持することです (縁からの安全な
マージン内であればなお良い)。
Note
すべてのアングルは、パラメータ構造の半径で定義されます。
pe_params_joint は各ページのプロパティを定義する３つの値グループを表すために3Dベクトルを
使います。リミットに加えて、各アングルはアングルを０へ引っぱるばねと、アングルがリミットの
近づくにつれて移動を減速させるダッシュポットを持っています。ばねは加速条件で特定されます：
剛性と減速は質量の違うボディを接続する接合部については一定であり、減速は一致するアングルの
ためのauto_kdを指定することで決定的に減速したバネを出すために減速は自動的に計算されます。
joint_no_gravity は重力が接合部に影響を与えないようにし、重力に耐えうるデフォルト位置の
接合部を維持する力を加えているのであれば有用です。このフラグはフェザーストーンモードでサ
ポートされています。
joint_isolated_accelerations は、接合部がバネを加速のガイドラインとして使うような特殊
なモードを使用し、これは、骨組みへの効果をシミュレーションするのに推奨されています。このフ
ラグはフェザーストーンモードでサポートされています。
有効な接合部アングルは常にqとqextの合計になります。バネが実行中の場合、qを０に引き込もうと
します。これは、アニメーションからポーズを設定することを可能にし、それに相対的な物理的効果
を適用します。接続型エンティティでは、衝突はpSelfCollidingPartsで明示的に特定されたペア
のみについてチェックされます (この設定は、パーツごとではなく、ボディごともしくは接合部ごとで
す)。
pe_params_articulated_body
pe_params_articulated_bodyは接合型エンティティのシミュレーションモードパラメータをクエ
リまたは設定できるようにします。連結型エンティティは何かに付加するかもしくはフリーの状態に
Version 1.6
531
Lumberyard 開発者ガイド
ロープのエンティティ固有の関数
なることができ、bGroundedフラグによって設定されます。着地するとき、エンティティは次のこと
ができます:
• 添付しているエンティティからダイナミックなパラメータを取得します（bInreritVelが設定され
た場合、エンティティはpHostで指定されます）。
• a、wa、w、vパラメータを使用して設定します。
bCollisionResp はフェザーストーンモード (0) と制約モード (1)の 間で切り替わります。
bCheckCollisions 衝突検出をオンまたはオフにします。これは、制約モードでサポートされま
す。
iSimType はエンティティを構成するボディが変化する方法を定義するシミュレーションタイプを指
定します。有効な値:
• 0 –制限された一連の方向に対して子ボディの動きを投影することで共同ピボットは強化されます |
• 1 – ボディは別々に進化し、ソルバが接合部を強化することに対して依存します。２つめのモードは
フェザーモードでサポートされていません。制約モードでは、ボディーが十分に速く移動している
場合は自動的に有効化されます。
スローモーションを円滑に行うためこの値を1に設定することをお勧めします。
横たわりモード
連結型エンティティは、接触の数が指定された閾値 (nCollLyingMode)よりも大きい場合に横たわり
モードをサポートします。横たわりモードには、重力や減速など、別個のシミュレーションパラメー
タがあります。この機能はragdollsが簡単な方法、例えば、重力レベルを低い値に設定し減速を通常よ
り高いレベルに設定することで、人体の高度の減速をシミュレーションするのを助けるために設計さ
れました。
標準シミュレーション　対　自然落下パラメータ
標準シミューレーションは自然落下パラメータとは異なる場合があります。制約モードを使用する場
合は、連結型エンティティはbExpandHingesパラメータを設定することで（この値は、すべての接合
部に対するjoint_expand_hingeフラグに反映されるため、手動で接合部の値を設定する必要はあり
ません)２点間の制約として蝶つがい型接合部 (一つの軸による回転接合部) となるように試みます。
ロープのエンティティ固有の関数
ロープは、点の集合と繋がった同じ長さのスティック（「セグメント」）の鎖としてシミュレーショ
ンされます。各セグメントは環境と個々に衝突する可能性があります。ロープは、2つのエンティティ
をまとめて結ぶことができます。この場合、ロープは完全に伸びきって移動に影響を与えない場合、
エンティティに制約を加えます。
伸びきった状態で他のオブジェクトと衝突するには (必要なら、押すことによって) 、ロープはダイナ
ミックサブディビジョンモードを使用する必要があります (rope_subdivide_segsフラグで設定し
てください)。
pe_params_rope
ロープが機能している必要があるすべてのパラメータを指定します。
ロープのエンティティはジオメトリを必要としません。始点の場所を指定しない場合、ロープはエン
ティティの位置からぶらさがっているものとされます。始点の場所を指定すれば、セグメントはエ
ラーマージン内で同じ長さとなります。ロープは摩擦を特定するために、明確な摩擦値（マテリアル
ではない）を使用します。
Version 1.6
532
Lumberyard 開発者ガイド
ソフトエンティティ固有の関数
pe_params_ropeがGetParamsへ渡された時、pPointsは内部ロープ頂点構造の最初の頂点のポイン
ターとなり、iStrideはそのサイズを包摂します。
ソフトエンティティ固有の関数
ソフトエンティティには二つのタイプがあります: メッシュベースおよび四面体格子ベースの２つで
す。メッシュベースのエンティティは柔らかく、制限体に似たソルバで、布のオブジェクトである
ことが多いです。四面体格子ベースのエンティティはばねのソルバを使用して、ゼリーのようなオブ
ジェクトであることが多いです。
すべての三角形の長辺は必要に応じてsef_skip_longest_edgesフラグで廃棄することができま
す。
衝突は、頂点レベルのみで処理され(ただし頂点はカスタマイズできるだけの厚みがある)、メッシュ
よりも、原始的なジオメトリにの反発に対して最も良く機能します。
pe_params_softbody
これは動いているソフトエンティティを設定するメイン構造です (他のもう一つ
はpe_simulation_params)。
厚み
ソフトエンティティの厚さは頂点の衝突サイズです（つまり球として扱われます。）maxSafeStep以
上端が元の長さと異なる場合は、位置に特化した長さ強化が行われます。
減速
バネの減衰は、決定的に減衰された値との比率としてkdRatioとともに定義されます (全体として
はpe_simulation_paramsからの減速もサポートされます)。
風
ソフトエンティティは、風にairResistanceが０でなければ反応します（風が０の場
合、airResistance が０でないことは、風の抵抗が表面速度と風速度を均等化するように試みるた
め、エンティティがさらに減速しているように見えます。）
水
ソフトエンティティは、風に反応するのと同様に水に反応しますが、pe_params_buoyancyで指
定されるパラメータが代わりに使用されます。水没している頂点に行使されるアルキメデスの力
は、pe_simulation_paramsで明示的に定義されるエンティティの密度に依存することに留意して
ください（グリッドボディについても依存は同様で、waterDensityがdensityと等しい場合、アル
キメデスの力は０になります）。collTypes は、ent_ masks.を使った特定のシミュレーションタイ
プのエンティティとの衝突を有効にします。
pe_action_attach_points
ソフトエンティティの頂点を他の物理エンティティに添付するのに使用できます。
piVtx 頂点インデックスを指定します。
points ワールドスペース上の添付する位置を指定します。pointsの値が指定されなかった場合、現
在の頂点位置は添付ポイントです。
Collision クラス
collision クラスを使用して、2 つの物理的なエンティティ間での衝突をフィルタリングしま
す。collision クラスは 2 つの 32 ビット単位の type と ignore で構成されます。
Version 1.6
533
Lumberyard 開発者ガイド
設定
collision クラスを使用して、AI アクターが通過できてもプレイヤは通過できないオブジェクトである
"プレイヤのみが衝突" などのシナリオを実装できます。この機能は、衝突の種類に関係なく、物理的
なエンティティ間での衝突のフィルタリングを設定することができます。
設定
物理的なエンティティには 1 つ以上の collision クラスがあり、1 つ以上の collision クラスを無
視できます。物理的なエンティティで衝突を無視するように指定するには、次の例に示すよう
に、<Physics> エレメントの ignore_collision 属性を <SurfaceType> 定義で使用します。
SurfaceTypes.xml
<SurfaceType name="mat_nodraw_ai_passable">
<Physics friction="0" elasticity="0" pierceability="15"
ignore_collision="collision_class_ai"/>
</SurfaceType>
すべての物理的なエンティティの種類 (LivingEntity や ParticleEntity など) には
collision_class_living や collision_class_particle などのデフォルトの collision クラス
が提供されます。生きているエンティティは、ゲームに固有の追加の collision クラス (AI アクターの
collision_class_ai またはプレイヤの collision_class_player のいずれか) を 1 つ使用しま
す。
Player.lua
Player = {
...
physicsParams =
{
collisionClass=collision_class_player,
},
...
}
BasicAI.lua
BasicAI = {
...
physicsParams =
{
collisionClass=collision_class_ai,
},
...
}
コード
struct SCollisionClass
{
uint32 type;
// collision_class flags to identify the entity
uint32 ignore;
// another entity will be ignored if *any* of these bits
are set in its type
};
Version 1.6
534
Lumberyard 開発者ガイド
Types]
type は collision クラスが属するエンティティを特定します。
次のような collision クラスは CryPhysics で定義されます。
• collision_class_terrain
• collision_class_wheeled
• collision_class_living
• collision_class_articulated
• collision_class_soft
• collision_class_roped
• collision_class_particle
その他の collision クラスは collision_class_game ビットから開始
し、GamePhysicsSettings.h で定義されます。
#define GAME_COLLISION_CLASSES(f) \
f( gcc_player_capsule,
collision_class_game
f( gcc_player_body,
collision_class_game
f( gcc_pinger_capsule,
collision_class_game
f( gcc_pinger_body,
collision_class_game
f( gcc_vehicle,
collision_class_game
f( gcc_large_kickable,
collision_class_game
f( gcc_ragdoll,
collision_class_game
f( gcc_rigid,
collision_class_game
f( gcc_alien_drop_pod,
collision_class_game
f( gcc_vtol,
collision_class_game
<<
<<
<<
<<
<<
<<
<<
<<
<<
<<
0)
1)
2)
3)
4)
5)
6)
7)
8)
9)
\
\
\
\
\
\
\
\
\
\
これらのクラスはすべて自動的に Lua に公開されます。ブラシやほとんどのオブジェクトにはエディ
ターを介してプロパティで使用できる collision クラスがあります。
Types]
type には、多くのビットやゼロビットを設定できます。
次の例では、クラス LIVING、PLAYER、TEAM1 と TEAM2、AI、AI_1、AI_2、player1 が LIVING
エンティティクラス、PLAYER クラス、TEAM1 クラスに属しています。
SCollisionClass player1(0,0), player2(0,0), ai1(0,0), ai7(0,0), object1(0,0);
player1.type = LIVING|PLAYER|TEAM1;
player2.type = LIVING|PLAYER|TEAM2;
ai1.type = LIVING|AI|AI_1;
ai7.type = LIVING|AI|AI_2;
object1.type = 0;
衝突のフィルタリング
フィルタリングは 1 つのエンティティの type をもう 1 つのエンティティの ignore と確認すること
で行います。
これは両方の方法で行われ、ビットが重複すると衝突が無視されます。以下に例を示します。
bool ignoreCollision = (A->type & B->ignore) || (A->ignore & B->type);
Version 1.6
535
Lumberyard 開発者ガイド
インターフェイス
ai7 で AI_1 セットが含まれるものとの衝突をすべて無視する場合、次のように AI_1 を ignore フ
ラグに追加します。
ai7.ignore = AI_1
object1 で生きている物理的なエンティティをすべて無視する場合は、その ignore フラグを次のよ
うに設定します。
object1.ignore=LIVING
インターフェイス
• コードの詳細については、physinterface.h および GamePhysicsSettings.h を参照してくだ
さい。
• 物理的なエンティティにアクセスして collision クラスを設定するには、*pe_collision_class
struct SCollisionClass pe_params_collision_class を使用します。
• 追加の ignore マップを設定するヘルパーについては、GamePhysicsSettings.h を参照してくだ
さい。
• Lua の場合、SetupCollisionFiltering および ApplyCollisionFiltering を参照してくだ
さい。Lua スクリプトバインディングは SetPhysicParams(PHYSICPARAM_COLLISION_CLASS)
で行います。
世界エンティティに対する関数
エンティティまたは物理世界環境を変更するには、このセクションで説明している関数を使用しま
す。
物理世界の時間状態を進める
TimeStep 関数は、エンティティの状態を指定した時間間隔だけ進めます。
物理変数で timeGranularity が設定されている場合、時間間隔は、指定された細度を持つ整数値
にスナップされます (たとえば、timeGranularity が 0.001 であれば、時間間隔はミリ秒単位にス
ナップされます)。
flags パラメータの ent_ フラグを使用して、ステップを実行するエンティティをフィルタリングで
きます。
flags パラメータには、シミュレーションタイプ (p. 524) に対する ent_ マスクを含めることがで
きます。
flags パラメータにも ent_flagged_only フラグを含めることができます。このフラグによって、
エンティティに pef_update フラグが設定されている場合にのみ、そのエンティティが更新されま
す。
ent_deleted フラグを指定すると、物理オンデマンドが使用されている場合に、タイムアウトした
エンティティを世界が削除できるようになります。
ほとんどのエンティティでは、時間ステップの上限があります。それより長い時間ステップが必要で
あれば、エンティティで複数のサブステップを実行する必要があります。サブステップの数は物理変
数 nMaxSubstepsで制限できます。
Version 1.6
536
Lumberyard 開発者ガイド
重複する境界ダイアログボックス持つエンティティを返す
重複する境界ダイアログボックス持つエンティティ
を返す
GetEntitiesInBox 関数は、内部エンティティハッシュグリッドを使用して、指定したボックスボ
リュームと重複する境界ダイアログボックスを持つエンティティの数を返します。この関数では、シ
ミュレーションタイプ (p. 524) によるフィルタリングと、エンティティ量の昇順で出力リストを
ソートするオプションがサポートされています。
構文
virtual int GetEntitiesInBox(Vec3 ptmin,Vec3 ptmax, IPhysicalEntity **&pList,
int objtypes, int szListPrealloc=0) = 0;
呼び出しの例
IPhysicalEntity** entityList = 0;
int entityCount = gEnv->pPhysicalWorld->GetEntitiesInBox(m_volume.min,
m_volume.max, entityList,
ent_static | ent_terrain | ent_sleeping_rigid | ent_rigid);
パラメーター
パラメー
ター
説明
ptmin
必要なボックスボリュームを定義しているスペース内の最小ポイント。
ptmax
必要なボックスボリュームを定義しているスペース内の最大ポイント。
pList
この関数によって入力されたオブジェクトのリストへのポインタ。
objtypes クエリで考慮する必要のあるオブジェクトの型。
szListPrealloc
指定されている場合は、pList 配列に含まれるオブジェクトの最大数。
指定可能なオブジェクト型は、entity_query_flags 列挙子の physinterface.h ヘッダーファイ
ルに記載されています。その中のいくつかを次の表にリストしています。
エンティ
ティタイプ
のフラグ
説明
ent_static
静的エンティティ
ent_terrain 地形
ent_sleeping_rigid
休止している剛体
ent_rigid
剛体
この関数が完了した後は、次のコードで概要を示しているように、必要な操作を実行するために、エ
ンティティリストを使用して簡単に繰り返すことができます。
for (int i = 0; i < entityCount; \++i)
Version 1.6
537
Lumberyard 開発者ガイド
環境での射線のキャスト
{
IPhysicalEntity\* entity = entityList[i];
[...]
if (entity->GetType() == PE_RIGID)
{
[...]
}
[...]
}
ent_alloctate_list が指定されている場合、この関数はリスト用のメモリを割り当てます (そのメ
モリは、あとで pWorld->GetPhysUtils()->DeletePointer を呼び出して解放できます)。指定さ
れていない場合は、内部ポインタが返されます。
Note
物理システムでは、エンティティリストを形成する必要があるほとんどすべての操作でこの
ポインタが使用されるため、そのリストが使用中の場合はメモリを解放する呼び出しを行わ
ないでください。メモリ解放の呼び出しが必要であり、メモリ割り当てが望ましくない場合
は、事前割り当てしたローカル配列にそのリストをコピーしてから、操作を繰り返します。
環境での射線のキャスト
物理世界関数 RayWorldIntersection は環境に射線を当てます。
射線が当たるマテリアルと射線プロパティに応じて、ヒットは穿孔可能になったり隙間なく当たった
りします。
マテリアルの穿孔性が射線の穿孔性より高い場合に、穿孔可能ヒットになります。マテリアルの穿孔
性と射線の穿孔性は、material フラグと RayWorldIntersection フラグの最下位 4 ビットを占め
ています。
穿孔可能なヒットでは、光線は停止せずに、ヒット距離でソートされたリストとして累積されます。
呼び出し元は、ヒットの配列を使用する関数を提供します。ソリッドヒット (存在する場合) では、常
に インデックス 0 のスロットが使用され、穿孔可能ヒットでは 1 から最後までのスロットが使用され
ます。
オプションとして、この関数では "重要な" 穿孔可能ヒットと "重要ではない" 穿孔可能ヒットを分離で
き (重要度はマテリアルフラグの sf_important で表されます)、配列内のスペースの獲得を争う際
に、重要なヒットが重要でないヒットより高い優先度を持つように設定できます。
RayWorldIntersection はデフォルトでは、geom_colltype_ray フラグを持つエンティティパー
ツだけをチェックします。flags |= geom_colltype_mask<<rwi_colltype_bit を設定するこ
とによって、別のフラグやフラグの組み合わせを指定できます。そうする場合は、指定されたフラグ
をテストできるように、すべてのフラグをいくつかに分けて設定する必要があります。
RayTraceEntity は、より低レベルの関数であり、1 つのエンティティだけに対する射線のヒットを
チェックします。RayTraceEntity は直近のヒットのみを返します。
また、CollideEntityWithBeam は、指定した半径の球体内のスイープチェックを実行できます。衝
突を確実に検出するためには、指定する球体はオブジェクトの外側にある必要があります。org パラ
メータは球体の中心に相当します。
Version 1.6
538
Lumberyard 開発者ガイド
爆発の作成
爆発の作成
SimulateExplosion 関数は、物理世界での爆発をシミュレートするために使用されます。
物理システム内での爆発の効果は、その近隣オブジェクトに加えられる衝動だけです。単一の衝動
は、エリアフラグメントでの衝動の負荷をその面積をかけて積分することによって計算され、爆心方
向にスケーリングされます。
衝動の負荷は 1/distance2 に比例して減衰します。distance が rmin より小さい場合は、rmin に
固定されます。
impulsive_pressure_at_r は、距離 r での衝動の負荷です。
SimulateExplosion では、オプションで遮蔽キューブマップを構築して、爆発から遮蔽されるエ
ンティティを見つけることができます (この場合は 1 次元でのゼロ以外のキューブマップ解像度を
nOccRe_s に設定する必要があります)。最初に静的エンティティがキューブマップに描画され、次
に、iTypesで指定されているタイプの動的エンティティがそのマップに対してテストされます。その
ため、動的エンティティが互いに遮蔽することはありません。
nOccRes に -1 を渡すことによって、直近の呼び出しのキューブマップを再利用し、その直近の呼び
出しで処理されなかった動的エンティティのみを処理するように、この関数に指示します。これは、
爆発を作成するコードで、それ以降に新規エンティティ (がれきや死体など) を登場させ、遮蔽マップ
を再計算せずに爆発の衝動をそれらに追加する場合に便利です。
キューブマップの投影上の特質のため、爆心に非常に近い小さいオブジェクトは、通常より多く遮蔽
されることがあります。これに対処するために、遮蔽マップの構築時に環境から差し引かれる小さい
キューブの線寸法を rmin_occ に指定できます。これにより、小さなオブジェクトはクロップされ、
爆発が薄い壁を貫通するようにできます。そのためには、妥協できる寸法を使用する必要がありま
す。
nGrow では、動的エンティティが増大する、遮蔽キューブマップのセルの数 (1 次元で) を指定しま
す。これにより、制御可能な方法で爆発が隅々に達するようにできます。SimulateExplosion に対
する呼び出しが行われた後、物理システムは IsAffectedByExplosion を呼び出すことによって、
影響を受けた特定のエンティティの数を返すことができます。
IsAffectedByExplosion は、0 から 1 までの小数を返します。IsAffectedByExplosion 関数
は、保存されたエンティティリストのルックアップを実行しますが、キューブマップの再計算は行い
ません。衝動の生成に使用される爆発の爆心は、キューブマップの構築に使用される爆心とは異なる
爆心にすることができます。たとえば、物が横方向ではなく上方向に移動するように、地面の少し下
に爆発を作成できます。この関数では、geom_colltype_explosion を持つパーツだけが処理され
ることに注意してください。
Version 1.6
539
Lumberyard 開発者ガイド
プロファイラーのチュートリアル
プロファイラー
プロファイラーはプレビューリリースであり、変更される可能性があります。
プロファイラーは、ネットワークや CPU、VRAM の使用統計を採取し、保存、分析するための
Lumberyard のツールです。保存されたデータを使用してフレーム単位のネットワークの使用量を分析
し、ネットワーク帯域幅の利用上の問題を修正して、ゲームのパフォーマンスを最適化できます。
データを採取するために、プロファイラーは GridHub と連係して動作します。プロファイラーを起動
すると、GridHub がサポートバックグラウンドプロセスとして自動的に起動します。GridHub の詳細
については、「GridHub の使用 (p. 569)」を参照してください。
トピック
• プロファイラーのチュートリアル (p. 540)
• 注釈の作成と使用 (p. 550)
• ネットワーキング用プロファイラーの使用 (p. 554)
• CPU の利用率でのプロファイラーの使用 (p. 562)
• VRAM のプロファイラーの使用 (p. 566)
• GridHub の使用 (p. 569)
プロファイラーのチュートリアル
プロファイラーはプレビューリリースであり、変更される可能性があります。
GridHub にアプリケーションを登録し、プロファイラーを使用して、収集するデータをキャプチャ、
調査、再生、エクスポートできます。
トピック
• アプリケーションの登録 (p. 541)
• プロファイラーの起動 (p. 541)
• データのキャプチャ (p. 541)
• データの確認 (p. 543)
• データの再生 (p. 545)
• データのエクスポート (p. 550)
Version 1.6
540
Lumberyard 開発者ガイド
アプリケーションの登録
アプリケーションの登録
プロファイラーがアプリケーションから情報をキャプチャできるようにするに
は、まず GridHub にアプリケーションを登録する必要があります。そのために
は、AzFramework::TargetManagementComponent をアプリケーションの SystemComponent に
追加します。
注意: Lumberyard の組み込みのアプリケーションでは、このコンポーネントがデフォルトですでに追
加されています。
プロファイラーの起動
多くの Lumberyard ユーティリティとは異なり、それ自身の実行可能ファイルからプロファイラーを
起動します。
プロファイラーを起動するには
•
Lumberyard dev\Bin64\ ディレクトリから、Profiler.exe を実行します。
データのキャプチャ
プロファイラーで使用するモードは主に 2 つあります。キャプチャモードと検査モードです。
キャプチャモードを使用するには、以下の手順を実行します。
データをキャプチャするには
1.
[Target] をクリックします。
プロファイラーは、プロファイリングに使用できるアプリケーションを示します。
2.
ターゲットアプリケーションを選択します。
ターゲットを選択すると、ターゲットセレクタはターゲットとの接続の状態を示します。次回プ
ロファイラーを起動すると、自動的にターゲットを選択します (使用できる場合)。
Version 1.6
541
Lumberyard 開発者ガイド
データのキャプチャ
ウィンドウはプロファイラーのインスタンスに関連付けたチャネルに水平に分割されます。チャ
ネルは特定のシステムに関連するプロファイラーのインスタンスのコレクションです。
3.
チャネルの各プロファイラーのインスタンスには一意の色があります。プロファイラーのインス
タンスは、色が無地の場合にアクティブです。
プロファイラーのインスタンスの隣の色をクリックします。色は無地ではなく、プロファイラー
のインスタンスが非アクティブであることがわかります。
色を再度クリックして表示をオンにし、インスタンスを再度アクティブ化します。
4.
ターゲットを選択し、表示するプロファイラーのインスタンスを選択したら、[Capture] をクリッ
クします。
キャプチャが開始されると、データはチャネルの入力を開始します。
Version 1.6
542
Lumberyard 開発者ガイド
データの確認
5.
データキャプチャを停止するには、[Stop Capture] をクリックします。
6.
プロンプトが表示されたら、キャプチャしたデータをディスクに保管します。プロファイラーは
データを .drl 拡張子のバイナリ形式ファイルに保存し、ディスクから再ロードし、検査モード
に切り替えます。
Note
データを保存しなければ、破棄されます。
データの確認
プロファイラーを使用して、お客様が取得したデータを確認できます。
取得されたデータを確認するには
1.
プロファイラーでは、[File]、[Open Data] をクリックするか、Ctrl+O を押します。
2.
保存したデータを含む .drl ファイルに移動し、これを開きます。
プロファイラーのメイン画面では、システム情報のチャネルの概要を示します。この例で
は、1162 フレームのデータがあるファイルを使用します。
このメイン画面を使用して、チャネルでの異常を発見したり、関心のある特定の分野を高レベル
で調査したりできます。
Version 1.6
543
Lumberyard 開発者ガイド
データの確認
メインウィンドウを開くと、キャプチャされたデータの終わりで再生が停止したため、下部のス
クロールボックスは右側にあります。
赤い縦線が右側にあることに注意してください。
3.
ウィンドウのチャネルエリアをクリックします。
赤い縦線はクリックした場所に移動します。フレームのインジケータは赤い直線の新しい位置を
示します。詳しく確認したいすべてのフレームに、スクラバーという赤い直線を配置できます。
スクラバーの位置を細かく調整するために、[Frame] のインジケータに数字を入力できます。
スクラバーはそれに応じて移動します。
4.
スクラバーがあるフレームの詳細情報を表示するには、表示したいデータがあるプロファイラー
のインスタンスの隣の [Detailed Profiling Information] のアイコンをクリックします。
プロファイラーのインスタンスの情報は詳細ウィンドウに表示されます。
Version 1.6
544
Lumberyard 開発者ガイド
データの再生
個々のプロファイラーは異なる方法で詳細を表示するため、それぞれの詳細ウィンドウは外観が
異なる場合があります。プロファイラーのシステム固有の詳細ウィンドウについては、「ネッ
トワーキング用プロファイラーの使用 (p. 554)」、「CPU の利用率でのプロファイラーの使
用 (p. 562)」、および「VRAM のプロファイラーの使用 (p. 566)」を参照してください。
5.
検査モードからキャプチャモードに戻るには、[LIVE] タブをクリックします。
データの再生
取得されたデータのサブセットをマークし、再生できます。
初めてスクラバーを移動した後、データの終わりの右側に黄色い縦線が表示されることに注意してく
ださい。
Version 1.6
545
Lumberyard 開発者ガイド
データの再生
この黄色のマーカーは移動可能で、目的の再生範囲の終わりをマークします。これはデフォルトでは
取得されたデータの終わりですが、赤いスクラバーによって覆われる場合があります。
1.
ウィンドウを左のキャプチャ範囲の始まりまでスクロールします。
これで、黄色のマーカーはデータの最初にも表示されます。デフォルトではキャプチャ範囲の最
初と最後にあるこれら 2 つの黄色いマーカーを使用して、再生範囲を関心のあるデータの領域に
制限できます。これらはすぐに使用できます。
データのフレームが多い場合 (この例のように)、最初のビューはデフォルトではすべてのフレー
ムを表示しません。
2.
すべてのフレームをすぐに表示するには、[Frame Count Selector] (表示できるフレーム数を決定
する) をクリックし、[All frames] を選択します。
Version 1.6
546
Lumberyard 開発者ガイド
データの再生
これで、最初と最後が黄色のマーカーで示され、取得されたデータのすべての範囲を表示できま
す。
3.
2 つの黄色いマーカーを再生したいデータの領域までドラッグしてください。ここではスクラ
バーの位置を無視してかまいません。
Version 1.6
547
Lumberyard 開発者ガイド
データの再生
4.
[Play] をクリックし、再生を開始します。
データが再生されると、スクラバーは 1 番目の黄色のマーカーから 2 番目に移動し、次に 1 番目
にループバックします。
留意すべきヒントがいくつかあります。
• 再生速度があまりにも速すぎる場合 (デフォルトは 60)、[Playback Speed] オプションを使用し
て 1 ～ 60 の範囲で調整します。
• 再生中に再生ウィンドウの場所をクリックすると、再生が停止し、スクラバーはクリックした
場所に移動します。
• スクラバーを希望するフレームに配置し、プロファイラーのインスタンスの詳細ボタンをク
リックして、フレームの詳細ウィンドウを表示します。
• より便利で、見やすくするために、プロファイラーのインスタンスの詳細ウィンドウを開いた
ままにして、スクラバーがマーカー間でループするたびに詳細ウィンドウのデータが変わるの
を表示します。
Version 1.6
548
Lumberyard 開発者ガイド
データの再生
5.
[Stop] をクリックして、再生を停止します。
Version 1.6
549
Lumberyard 開発者ガイド
データのエクスポート
データのエクスポート
一部のプロファイラーのインスタンスには、.csv ファイルにデータを格納するために使用できるエク
スポートオプションがあります。
プロファイラーのインスタンスから .csv ファイルにデータをエクスポートするには
1.
保存したいデータがあるプロファイラーのインスタンスで、[Save to CSV] アイコンをクリックし
てください。
Note
すべてのプロファイラーにデータエクスポートオプションがあるわけではありません。
2.
エクスポートするフィールドを選択するには、[Export] ダイアログボックスの [Customize] をク
リックします。
注釈の作成と使用
プロファイラーはプレビューリリースであり、変更される可能性があります。
プロファイラーでは、注釈は、アプリケーションから取得したデータから、期間ごとのログ情報をハ
イライト表示する便利な方法です。注釈がプロファイラーでどのように使用されるかを理解したら、
プロファイラーに表示されるようにアプリケーションを変更できます。
トピック
Version 1.6
550
Lumberyard 開発者ガイド
注釈の使用
• 注釈の使用 (p. 551)
• 注釈の作成 (p. 552)
• トレースメッセージプロファイラーでの注釈の表示 (p. 553)
注釈の使用
Lumberyard のプロファイラーツールの注釈では、ログ情報が関連付けられている取得データ内の期間
にフラグ付けされます。デフォルトでは、注釈は無効になっています。
注釈の使用方法
1.
Lumberyard のプロファイラーツールで注釈を有効にするには、[Configure Annotations] をクリッ
クします。
[Configure Annotations] ダイアログボックスには、使用可能な注釈とその表示色のリストがあり
ます。アプリケーションに対して注釈を作成する方法については、「 注釈の作成 (p. 552)」を
参照してください。
2.
このダイアログボックスで注釈を選択すると、同じ色のマーカーと線がチャネル表示に表示され
ます。そのマーカーを見つけるには、水平にスクロールする必要があることがあります。
3.
期間内に現れる注釈の詳細を表示するには、注釈マーカーの上にマウスポインタを置きます。こ
の例の画像では、IP アドレスが加工されています。
Version 1.6
551
Lumberyard 開発者ガイド
注釈の作成
注釈の作成
注釈を作成するには、アプリケーションに 1 行または複数行の C++ のログ記録コードを追加します。
追加されたコードでは、キャプチャの一部として指定したログ記録情報を含めるように Lumberyard
のログ記録システムに指示します。そのログ記録されたメッセージは Lumberyard で注釈に変換され
ます。次に、プロファイラーで [Configure Annotations] をクリックし、どのシステム の注釈を表示す
るかを実際に選択します (たとえば、[GridMate] や [MultiplayerProject])。
注釈を作成するには、アプリケーションに次のような C++ コードの行を配置します。
AZ_TracePrintf("GridMate","Connection %s => %s (%s) (Connections=%d!\n")
最初のパラメーターはトレース (この場合は GridMate) のウィンドウ (つまり、システム) であり、2
番目のパラメーターは注釈として表示されるトレースの内容です。
この例では、次のような注釈テキストになります。
GridMate - Connection <IP_Address>|64090 => <IP_Address>|57455 (Client)
(Connections=1)!
プロファイラーで表示されるテキストは次のようになります。
AZ_TracePrintf の代替関数
コードでは、重要度に応じて、AZ_TracePrintf の代わりに AZ_Error または AZ_Warning を使用
できます。AZ_TracePrintf ではメッセージが常にログ記録されますが、検査の観点では最下位の懸
念事項です。
Version 1.6
552
Lumberyard 開発者ガイド
トレースメッセージプロファイラーでの注釈の表示
次の例では AZ_Error を使用しています。
if (networkTableContext.ReadValue(elementIndex,forcedDataSetIndex))
{
AZ_Error("ScriptComponent",forcedDataSetIndex >= 1 && forcedDataSetIndex
<= ScriptComponentReplicaChunk::k_maxScriptableDataSets,"Trying to
force Property (%s) to an invalid DataSetIndex(%i).",scriptProperty>m_name.c_str(),forcedDataSetIndex);
if (forcedDataSetIndex >= 1 && forcedDataSetIndex <=
ScriptComponentReplicaChunk::k_maxScriptableDataSets)
{
networkedTableValue.SetForcedDataSetIndex(forcedDataSetIndex);
}
}
else
{
AZ_Error("ScriptComponent",false,"Trying to force Property (%s) to
unknown DataSetIndex. Ignoring field.", scriptProperty->m_name.c_str());
}
この例では、いずれかのエラー状況が発生した場合に注釈が作成されます。
トレースメッセージプロファイラーでの注釈の表示
注釈が設定されていることを確認するもう一つの方法は、トレースメッセージプロファイラーを使用
することです。
プロファイラーの [Logging] チャネルで、Trace messages プロファイラーの詳細アイコンをクリック
して、現在実施されているログ記録システムを確認します。
Trace messages プロファイラーのインスタンスでは、キャプチャの開始時点から現在分析中の期間
までに生成されたすべてのトレースメッセージが表示されます。最も古いメッセージが最上部に表示
され、最も新しいメッセージが最下部に表示されます。
[Window Filter] を使用してシステムを表示したり、[Message Filter] を使用して関心のあるメッセージ
したりできます。
次の例では、アプリケーションに追加されたコード行によって指定されたメッセージが「GridMate」
でフィルタリングされて表示されています。
Version 1.6
553
Lumberyard 開発者ガイド
ネットワーキング用プロファイラーの使用
ネットワーキング用プロファイラーの使用
プロファイラーはプレビューリリースであり、変更される可能性があります。
Lumberyard のプロファイラーツールを使用して、ゲームでネットワーク帯域幅がどのように使用され
ているかを、GridMate キャリア接続やレプリカアクティビティも含めて調べることができます。ネッ
トワーク用のプロファイラーを使用して、特定のレプリカチャンク、RPC、およびデータセットのア
クティビティをさらに調べることができます。
前提条件
このトピックでは、Lumberyard ネットワーキングと Lumberyard プロファイラーツールについて精通
していることを前提としています。Lumberyard ネットワーキングの詳細については、「ネットワー
クシステム (p. 481)」を参照してください。プロファイラーツールの概要については、「プロファイ
ラー (p. 540)」を参照してください。
トピック
• キャリアプロファイラー (p. 554)
• レプリカアクティビティプロファイラー (p. 555)
キャリアプロファイラー
プロファイラーツールには、[キャリア] と [レプリカアクティビティ] のプロファイラーインスタン
スを持つ GridMate チャネルがあります。キャリアプロファイラーの詳細表示を使用して、選択した
GridMate キャリア接続の帯域幅の使用状況を調べることができます。
キャリアプロファイラーの詳細表示を開く方法
•
GridMate チャネルで、[キャリア] の [詳細プロファイル情報] アイコンをクリックします。
キャリアプロファイラーの詳細表示は次の図のようになっています。
Version 1.6
554
Lumberyard 開発者ガイド
レプリカアクティビティプロファイラー
この表示では、キャプチャセッションで取得されたすべてのデータを使用して、選択した接続で
の GridMate キャリアを経由した帯域幅の使用状況の概要が示されます。次の情報が含まれてい
ます。
• [総送信数]/[総受信数] – 選択した接続で送信された総バイト数と受信された総バイト数。
• [送信ユーザーデータ]/[受信ユーザーデータ] – 選択した接続で送信されたユーザーデータと受信
されたユーザーデータ。このデータには、キャリアまたは接続のメンテナンスに伴うオーバー
ヘッドは含まれません。
• [送信パケット数]/[受信パケット数] – 送信されたパケット数と受信されたパケット数。
• [往復時間 (レイテンシー)] – パケットの往復の所要時間 (秒)。
レプリカアクティビティプロファイラー
レプリカアクティビティプロファイラーを使用して、アプリケーションで使用されているレプリカ帯
域幅を確認できます。
レプリカアクティビティプロファイラーを開く方法
•
[レプリカアクティビティ] の [詳細プロファイル情報] アイコンをクリックします。
Version 1.6
555
Lumberyard 開発者ガイド
レプリカアクティビティプロファイラー
レプリカアクティビティプロファイラーの詳細表示では、上部に [Bytes Sent] と [Bytes
Received] のグラフのペア、中央に表示を制御するためのツールバー、下部にレプリカの表があ
ります。
この表示は、個々のエンティティで使用されている帯域幅や、特定のエンティティの特定のイベ
ントに応じてどのような情報が同期されるかを調べるのに役立ちます。
この表示には、[レプリカ] と [チャンク型] という、レプリカアクティビティ用の 2 つのメイン詳細表
示があります。この表示のデフォルトは [レプリカ] ですが、プロファイラーでは直近の選択内容が記
憶されていて、レプリカアクティビティの詳細の次回表示時にはそれが使用されます。
レプリカ表示の使用
レプリカ表示では、所定の期間に各レプリカで使用されたデータ量が表に示されます。
表示をレプリカに変更する方法
•
ツールバーで [レプリカ] を選択します。
Version 1.6
556
Lumberyard 開発者ガイド
レプリカアクティビティプロファイラー
各レプリカは、それに関連付けられている色でツールバーの上のグラフに表されます。レプリカ
表示には以下の情報が含まれています。
• [送信バイト数] – 所定の期間にオブジェクトによって送信されたバイト数で、帯域幅の使用量が
表されます。
• [受信バイト数] – 所定の期間にオブジェクトによって受信されたバイト数で、帯域幅の使用量が
表されます。
グラフで個々の線を表示または非表示にする方法
•
関連付けられている行をツリーでダブルクリックします。
ツールバーには以下のオプションもあります。
• [すべて非表示] – 表内のすべてのレプリカの折れ線グラフを非表示にします。
• [すべて表示] – 表内のすべてのレプリカの折れ線グラフを表示します。
• [選択項目を非表示] と [選択項目を表示] – Ctrl + クリックを使用して表内の個々のレプリカを選
択し、[選択項目を非表示] または [選択項目を表示] をクリックして、選択したレプリカのグラ
フの非表示と表示を切り替えます。
• [範囲を表示] – グラフに表示する期間を指定します。現在選択されている期間が中央に表示され
ます。このオプションを使用して、データの表示を拡大または縮小できます。
特定のレプリカのレプリカチャンクの詳細を表示する方法
•
そのレプリカの詳細アイコンをクリックします。
レプリカチャンク、データセット、および RCP で送信および受信されたバイト数がグラフに表
示されます。
Version 1.6
557
Lumberyard 開発者ガイド
レプリカアクティビティプロファイラー
この詳細表示を使用して、指定したレプリカで使用されているレプリカチャンク型、各レプリカ
チャンク型で使用されているデータ量、および個々のデータセットと RPC で使用されている帯
域幅を確認できます。
Tip
[すべて展開] をクリックすると、すべてのレプリカのすべてのレプリカチャンクのリスト、お
よび各レプリカチャンクでのすべてのデータセットとリモートプロシージャ呼び出し (RPC)
のリストが表示されます。
Version 1.6
558
Lumberyard 開発者ガイド
レプリカアクティビティプロファイラー
レプリカアクティビティプロファイラーのツリービューを使用する方法
•
次のいずれかを行います。
• グラフでハイライト表示する行を選択します。
• グラフを表示または非表示にする行をダブルクリックします。
以下の情報が表示されます。
• [表示名] – 表内の該当する行に関連付けられているデバッグ名。
• [送信バイト数] – 項目に対して送信されたバイト数 (その項目の子によって送信されたすべての
情報を含む)。
• [受信バイト数] – 項目で受信されたバイト数 (その項目の子によって受信されたすべての情報を
含む)。
Version 1.6
559
Lumberyard 開発者ガイド
レプリカアクティビティプロファイラー
チャンク型表示
チャンク型表示では、所定の期間に使用された各チャンク型のデータ量が表示されます。この表示
は、特定のシステムがすべてのエンティティ間で使用している可能性がある情報量を確認するのに役
立ちます。
チャンク型表示に変更する方法
•
[レプリカアクティビティ] のメイン詳細ページのツールバーで [チャンク型] を選択します。
チャンク型表示では、所定の期間に使用された特定のレプリカチャンク型のデータ量が表示され
ます。
チャンク型の詳細を調べる方法
•
そのチャンク型の詳細アイコンをクリックします。
Version 1.6
560
Lumberyard 開発者ガイド
レプリカアクティビティプロファイラー
この詳細ウィンドウには、チャンク型の帯域幅を使用しているレプリカ、そのレプリカで使用さ
れているデータ量、および個々のデータセットと RPC で使用されているデータ量が表示されま
す。
前と同様に、ツリー内の項目を展開して、各項目に関する詳細情報を確認できます。
Version 1.6
561
Lumberyard 開発者ガイド
CPU の利用率でのプロファイラーの使用
CPU の利用率でのプロファイラーの使用
プロファイラーはプレビューリリースであり、変更される可能性があります。
CPU のプロファイラーは、関数またはメソッドがどのくらいの時間実行されたか、何回実行された
か、誰に呼び出されたか、どのくらいのフレームが費やされたかについて、使用統計を収集します。
この情報を組み合わせてシステム全体の使用状況を取得するか、特定のスレッドに対するフィルタリ
ングを行うことによって特定のシステムを分離できます。
CPU のプロファイラーを使用するには
1.
CPU プロファイラーの詳細ビューを開くには、CPU プロファイラーのインスタンスの [Detailed
Profiling Information] アイコンをクリックします。
CPU 詳細ビューには、CPU の利用率、ツールバー、およびフレームで行われた呼び出しのツ
リービューのグラフがあります。ツリービューの各呼び出しの色は、グラフでの該当する行と同
じです。
Version 1.6
562
Lumberyard 開発者ガイド
ツリービューについて
2.
グラフ内の行にマウスを置くと、その行が表す呼び出しが表示され、カーソルの近くの領域にグ
ラフの特定の値が表示されます。
3.
ツリーの行のライングラフを表示するか非表示にするには、その行をダブルクリックします。
ツリービューについて
CPU のプロファイラーのツリービューは、プロファイラーのログポイントの呼び出し階層を表しま
す (フックと呼ばれる)。もう 1 つの呼び出しがアクティブな状態でアクティブになっているプロファ
イラーのフックは、最初のフックの子として表示されます。フックはスタックとして機能します。
スタックに最後にプッシュされたフックは、その前にスタックにプッシュされたフックの親です。ツ
リービューには以下の情報があります。
関数
プロファイラーのデータポイントが生成された関数宣言。
コメント
同じ関数の特定のイベントを区別するユーザー定義のメッセージ。
Excl. 時間 (マイクロ)
(排他時間)、この関数の実行で費やされる時間 (マイクロ秒) で、この関数によって呼び出される
他の関数は含めません。
Incl. 時間 (マイクロ)
(包括時間)、この関数およびこの関数によって呼び出される他の関数の実行で費やされる時間 (マ
イクロ秒)。
Excl. Pct
(排他パーセント) 全体の実行時間に対するパーセンテージとして表す排他時間。
Incl. Pct
(包括パーセント) 全体の実行時間に対するパーセンテージとして表す包括時間。
Version 1.6
563
Lumberyard 開発者ガイド
表示の制御
呼び出し
この関数に対する呼び出しの数。
子時間 (マイクロ)
この関数によって呼び出された関数の実行にかかった時間 (マイクロ秒)。
合計時間 (マイクロ)
この関数の内部で費やされた時間の総数 (マイクロ秒)。
子呼び出し
この関数が呼び出した関数の数。
呼び出しの合計
この関数が呼び出された回数の合計。
スレッド ID
この関数が実行されたスレッド
表示の制御
ツールバーを使用して、取得された CPU データをどのように表示するかを制御できます。
選択項目を非表示
ツリービューで選択されている行のグラフを非表示にします。
選択項目を表示
ツリービューで選択されている行のグラフを表示します。
すべて非表示
ツリービューのすべての行のグラフを非表示にします。
すべてを表示
ツリービューのすべての行のグラフを表示します。
Invert
ツリービューで非表示になっているすべての行のグラフを表示します。ツリービューで表示され
ているすべての行のグラフを非表示にします。
ツリーを展開
ツリービュー階層のすべての行を展開します。
ツールバーの右側にはその他のオプションがあります。
すべてのスレッド
スレッドのセレクタを使用して、どのスレッドをツリービューとグラフに表示するかを制御しま
す。
Version 1.6
564
Lumberyard 開発者ガイド
表示の制御
Incl. 時間
このセレクタを使用して、表示されている時間の意味を選択します。
• Incl. 時間 – (包括時間) この関数で包括的に使用される時間。
• Excl. 時間 – (排他時間) この関数で排他的に使用される時間。
• 呼び出し – フレームでこの関数が呼び出された回数。
• Acc. 時間 – (累積時間) 分析するフレームまでこの関数で使用された時間の合計。
• Acc. 呼び出し – (累積呼び出し) – 分析するフレームまでこの関数が呼び出された回数の合計。
<##> フレーム
このセレクタを使用して、グラフに履歴のフレームを表示する方法を選択します。
デルタ
未使用オプション。
自動ズーム
選択されている場合、グラフが変更されるたびにおよそのズームレベル (表示されるフレーム数)
を維持します。
フラットなビュー
次のイメージのように、関数呼び出しのツリーをフラットにします (階層インデントを削除しま
す)。
Version 1.6
565
Lumberyard 開発者ガイド
VRAM のプロファイラーの使用
VRAM のプロファイラーの使用
プロファイラーはプレビューリリースであり、変更される可能性があります。
ビデオメモリプロファイラー (VRAM のプロファイラー) を使用して、ゲームの実行時に VRAM の使
用量が最も多いリソースを判定できます。
VRAM のプロファイラーはゲームで使用されるビデオメモリの使用量を記録します。記録される情
報には、そのデータ採取期間中に発生したメモリの解放回数や割り当て回数が含まれます。この情報
は、レンダリングのパフォーマンスのボトルネックを追跡するのに役立ちます。
また、VRAM のプロファイラーからのメモリ使用量情報を使用して、ゲームで必要な最小 PC GPU
(グラフィック処理ユニット) メモリの要件や、コンソールまたはモバイルデバイスでメモリ不足が発
生するかどうかが判定できます。
トピック
• コメント (p. 566)
• 採取されるデータについて (p. 566)
• データの確認 (p. 567)
コメント
VRAM のプロファイラーには以下のような属性があります。
• VRAM のプロファイラーにはグラフ表示やツリー表示はありません。
• エクスポート形式は .csv のみサポートされます。プロファイラーのデータを .csv ファイルとし
て保存する手順については、「データのエクスポート」を参照してください。
• Lumberyard はさまざまなメモリプールスキームを使用しているため、実際に割り当てられる
VRAM 量は、報告される量よりわずかに多くなります。
採取されるデータについて
次の図は、保存した .csv ファイルがスプレッドシートアプリケーションでどのように表示されるか
を示しています。
Version 1.6
566
Lumberyard 開発者ガイド
データの確認
採取されたデータでは、主に次の 2 つの情報が表にまとめられています。1 つはメモリ割り当てと使
用量の概要 (テクスチャアセットとバッファアセットに分けられています) であり、もう 1 つはデータ
採取期間中に各リソースに割り当てられた VRAM 量の情報を記載したリソースのリストです。
各見出しについての詳細は次のとおりです。
カテゴリ
割り当てのタイプを示します。
• Texture – テクスチャアセット、動的に生成されたテクスチャ、およびフレームバッファが含ま
れています。
• Buffer – 頂点バッファとインデックスバッファ、定数バッファ、およびその他の実行時バッ
ファが含まれています。
Number of Allocations
記録された割り当てイベント数。データの採取が開始されると、すべてのアクティブな割り当て
数が開始時の数としてプロファイラーに送信されます。新しい割り当てまたは解放が発生する
と、この数が増加または減少されます。
Memory Usage
使用された VRAM の合計サイズ (バイト単位)。
リソース名
割り当てられたリソースの名前と完全パス。パスのないリソース名は通常、実行時エンジンリ
ソースを示します。
VRAM Allocation Size
割り当てのサイズ (バイト単位)。
データの確認
スプレッドシートを初めて開くと、データは順序付けがされていません。データをソートするには、
スプレッドシートアプリケーションを使用します。
Version 1.6
567
Lumberyard 開発者ガイド
データの確認
問題への寄与度が最も大きいアセットまたは実行時リソースをすばやく簡単に識別するには、VRAM
Allocation Size で降順にソートするか、Resource Name で A から Z の順にソートします。
負の VRAM 割り当てサイズ
次の図のように、いくつかのフィールドで VRAM Allocation Size に負数が表示されることがありま
す。
これらの発生は重要であり、データ採取期間中に VRAM の解放イベントが発生したことを示します。
短期間に大量の解放エントリが確認できる場合には、ゲームのパフォーマンスが著しく低下している
可能性があります。すべてのプラットフォームでゲームのパフォーマンスを改善するには、VRAM の
割り当てと解放のフレームごとのアイドルをできるだけ少なくするよう心がける必要があります。
一部のテクスチャが .csv ファイルで報告されない理由
StreamingTexturePool という名前の割り当てや、$TexturePool_9_0000000002C59248 など
のエントリが大量に表示される場合は、テクスチャストリーミングシステムがアクティブであること
を示します。テクスチャストリーミングシステムは、デフォルトでは、キャッシュされたさまざまな
テクスチャプールにすべてのテクスチャを割り当てます。VRAM のプロファイラーはアクティブな
ストリーミングプールのサイズは報告しますが、実際のテクスチャアセットの名前は報告しません。
割り当てられ、ロードされたテクスチャの名前とサイズを取得するには、システム設定ファイルに
r_TexturesStreaming=0 を設定し、別途データ採取を行います。この設定は、テクスチャストリー
ミングシステムを無効にして、正しいテクスチャ割り当てサイズが報告されるようにします。
Version 1.6
568
Lumberyard 開発者ガイド
GridHub の使用
Note
この場合、2 つのデータ採取を行うことをお勧めします。1 つは r_TexturesStreaming を
有効にして実施し、もう 1 つは無効にして実施します。テクスチャストリーミングが有効に
なると、テクスチャが削除され、より低解像度のミップマッピングレベルがロードされるた
め、VRAM 使用量が少なくなります。テクスチャストリーミングが有効になると、メモリレ
ポートがより正確になりますが、テクスチャストリーミングを無効にすると、最悪時のメモ
リ使用量がより明確に確認できます。
GridHub の使用
GridHub はプレビューリリースであり、変更される可能性があります。
GridHub は、Lumberyard のデバッグ用接続ハブです。GridHub は、指定したローカルクライアン
トが互いに接続し、情報を交換するための集中ハブとして機能します。Lumberyard の診断ツール
Profiler.exe またはデバッグツール LuaIDE.exe (存在場所は \dev\Bin64 ディレクトリ) を実行
すると、GridHub が Windows のバックグラウンドプロセスとして起動され、その機能が有効化されま
す。プロファイラーの詳細については、「プロファイラー (p. 540)」を参照してください。
Note
GridHub は、ループバックアドレス (127.0.0.1) で接続をリッスンするため、ターゲットア
プリケーションと同じコンピュータ上で実行する必要があります。
トピック
• GridHub へのアプリケーションの登録 (p. 569)
• GridHub の表示と設定 (p. 569)
• GridHub のトラブルシューティング (p. 571)
GridHub へのアプリケーションの登録
GridHub にアプリケーションを登録してプロファイラーがアプリケーションから
情報を取得できるようにするには、アプリケーションの SystemComponent に
AzFramework::TargetManagementComponent を追加します。
Note
注意: Lumberyard の組み込みのアプリケーションには、このコンポーネントがデフォルトで
すでに追加されています。
GridHub の表示と設定
Profiler.exe または LuaIDE.exe を起動すると、GridHub が自動的に開始され、Windows タスク
バーに地球儀アイコンが表示されます。
GridHub を表示および設定するには
1.
Windows タスクバーで、地球儀アイコンを右クリックして、[Show] を選択します。
Version 1.6
569
Lumberyard 開発者ガイド
GridHub の表示と設定
GridHub ウィンドウは、設定バー、接続ペイン、およびログメッセージ表示用ペインで構成され
ています。
2.
設定ツールバーで、GridHub の設定を表示または変更できます。
ツールバーには、次の各オプションがあります。
Session port – GridHub が検出リクエストをリッスンするポートを指定します。
Connection slots – 現在 GridHub に接続可能なアプリケーションの最大数を指定します。
Hub name – ハブの名前。デフォルトでは、ローカルコンピュータの名前が使用されます。
Note
ハブの名前は、TargetManagementComponent の接続先の隣接名にする必要がありま
す。
Enable Disconnection Detection – 送信元からの返信がない場合に、GridHub への接続を終了する
かどうかを指定します。
Add to Windows startup folder – Windows の起動時に GridHub を自動的に開始するかどうかを指
定します。
Log activity – ログを開始または終了します。
Start/Stop – GridHub を開始または終了します。GridHub がオフの場合、接続は検出または保持さ
れません。
3.
GridHub とターゲットアプリケーションがアクティブになると、GridHub の Connections リスト
にターゲットアプリケーションが表示されます。
Version 1.6
570
Lumberyard 開発者ガイド
GridHub のトラブルシューティング
[Connections] リストの各列には、以下の情報が表示されます。
ID – 接続済みアプリケーションの識別子。
Name – 接続済みアプリケーションの名前。
Connection ID – GridHub とアプリケーション間の接続の識別子。
IsHost – 接続が接続ホストかどうかを示します。
IsLocal – 接続がローカルかどうかを示します。
IsReady – アプリケーションが追加の接続を処理できる状態かどうかを示します。
4.
[Output] ウィンドウでは、GridHub が接続を管理する際に生成するログメッセージを確認できま
す。
GridHub が終了すると、GridHub によって確立されている接続も終了します。
GridHub のトラブルシューティング
GridHub の使用時に問題が発生した場合は、以下の項目をチェックしてください。
• TargetManagerComponent の隣接名が GridHub の隣接名と同じであることを確認します。
• GridHub がリッスンしているポートが、TargetManagementComponentに指定したのと同じポー
トであることを確認します。
• すべてのアプリケーションが同じコンピュータ上で実行されていることを確認します。GridHub の
ソケットは、ループバック アドレス (127.0.0.1) に結合されます。
Version 1.6
571
Lumberyard 開発者ガイド
ScriptBind エンジン関数
ScriptBind の参照
Lua スクリプトの ScriptBind 関数を使用して C++ で記述された既存のコードを呼び出すことがで
きます。詳細については、「Luaスクリプトの使用 (p. 468)」を参照してください。
トピック
• ScriptBind エンジン関数 (p. 572)
• ScriptBind アクション関数 (p. 735)
• ScriptBind_Boids (p. 782)
ScriptBind エンジン関数
Lua スクリプトから呼び出すことができる C++ エンジン関数をリストします。
トピック
• ScriptBind_AI (p. 572)
• ScriptBind_Entity (p. 642)
• ScriptBind_Movie (p. 696)
• ScriptBind_Particle (p. 698)
• ScriptBind_Physics (p. 701)
• ScriptBind_Script (p. 704)
• ScriptBind_Sound (p. 706)
• ScriptBind_System (p. 708)
ScriptBind_AI
Lua スクリプトから呼び出すことができる C++ の AI 関数をリストします。
AbortAction
指定されたアクションの実行を中止します。
構文
Version 1.6
572
Lumberyard 開発者ガイド
ScriptBind_AI
AI.AbortAction(userId [, actionId ])
パラメーター
説明
userId
エンティティの ID。
actionId
(optional)
中止するアクションの一意の ID。0 (または nil) の場合は、選択されたエ
ンティティのすべてのアクションを中止します。
AddAggressiveTarget
指定されたエンティティのリストに、積極的な標的候補としてターゲットを追加します。
構文
AI.AddAggressiveTarget(entityId, targetId)
追加に成功した場合に true を返します。
パラメーター
説明
entityId
エンティティの ID。
targetId
追加するターゲットのエンティティ ID。
AddCombatClass
新しい戦闘クラスを作成します。
構文
AI.AddCombatClass(int combatClass, SmartScriptTable pTable, const char*
szCustomSignal)
パラメーター
説明
combatClass
追加する戦闘クラス。
pTable
パラメーターテーブル。
szCustomSignal
オプションのカスタム OnSeen シグナルを指定します。
AddFormationPoint
フォーメーション記述子に追跡型ノードを追加します。
構文
AI.AddFormationPoint(name, sightangle, distance, offset, [unit_class
[,distanceAlt, offsetAlt]])
Version 1.6
573
Lumberyard 開発者ガイド
ScriptBind_AI
パラメーター
説明
name
フォーメーション記述子の名前。
sightangle
ノードの視野の角度 (-180,180; 0 = エンティティは前方を見ます)
distance
フォーメーションの所有者からの距離。
offset
追跡ラインからのオフセット (負 = 左、正 = 右)。
unit_class
兵士のクラス (IAgent.h の eSoldierClass の定義を参照)
DistanceAlt (オプション) : フォーメーション所有者からの直線距離
offsetAlt (オプション) : 直線オフセット。
AddFormationPointFixed
フォーメーション記述子に固定オフセットのノードを追加します。
構文
AI.AddFormationPointFixed(name, sightangle, x, y, z [,unit_class])
パラメーター
説明
name
フォーメーション記述子の名前。
sightangle
ノードの視野の角度 (-180,180; 0 = エンティティは前方を見ます)
x, y, z
フォーメーション所有者からオフセット。
unit_class
兵士のクラス (IAgent.h の eSoldierClass の定義を参照)
AddPatternBranch
指定ノードにブランチパターンを作成します。エンティティが指定されたノード (nodeName) に近づ
き、新しいポイントを選択するときに、この関数で定義されたルールを使用して新しいポイントが選
択されます。この関数は、複数のターゲットポイントと評価ルールを関連付けることができます。
構文
AI.AddPatternBranch(nodeName, method, branchNode1, branchNode2, ...,
branchNodeN)
パラメーター
説明
nodeName
ブランチに追加するノードの名前。
method
次のノードの選択に使用されるメソッド。有効な値を次に示します。
• AITRACKPAT_CHOOSE_ALWAYS – 順番にリストから次のポイントを選択
します。
Version 1.6
574
Lumberyard 開発者ガイド
ScriptBind_AI
パラメーター
説明
• AITRACKPAT_CHOOSE_LESS_DEFORMED – リストから変形が最小のポ
イントを選択します。各ノードには、物理ワールド内に収まるためにど
のくらい移動が必要かを示す変形値 (パーセント) が関連付けられていま
す。これらの変形値は階層の末端での変形が階層で把握できるように親
ノードに合計されます。
• AITRACKPAT_CHOOSE_RANDOM – リストからポイントをランダムに選択
します。
AddPatternNode
追跡パターンにポイントを追加します。
ポイントを検証するときに、このテストが開始位置から終了位置まで実行されます。開始位置はパ
ターン元の位置でも、親が存在する場合は親の位置でもかまいません。終了位置は、開始位置または
パターン元からの相対オフセットで、ノードフラグに基づいて選択されます。オフセットはテストメ
ソッドに基づいて物理ワールドに固定されています。ポイントは記述子に追加された順序で評価され
ます。システムで評価順序の修正を試みることはありません。階層が使用されている (親の名前が定義
されている) 場合は、親が参照される前に追加された順序でノードが作成されているかどうかはパター
ン作成者によります。
構文
AI.AddPatternNode(nodeName, offsetx, offsety, offsetz, flags, [parent],
[signalValue])
パラメーター
説明
nodeName
新しいポイントの名前。ポイント名は現在のパターン限定です。
offsetx, offsety,
offsetz
開始位置またはパターンの中心からのオフセッ
ト。AITRACKPAT_NODE_ABSOLUTE を参照してください。
flags
追跡パターン機能フラグ。
ノードの評価フラグ:
• AITRACKPAT_NODE_START – ノードをパターンの最初のノードとして
使用できます。開始ノードは複数でもかまいません。その場合は、最も
近いものを 1 つ選択します。
• AITRACKPAT_NODE_ABSOLUTE – オフセットをパターンの中心からのオ
フセットに変換します (その他の場合オフセットは開始位置からです)。
• AITRACKPAT_NODE_SIGNAL – ノードが到達したときにシグナル
"OnReachedTrackPatternNode" が送信されます。
• AITRACKPAT_NODE_STOP – 進行を停止しま
す。entity:ChangeAIParameter(AIPARAM_TRACKPATTERN_ADVANCE,
1) を呼び出すことで続行できます。
• AITRACKPAT_NODE_DIRBRANCH – 各パターンノードの方向に、ブラ
ンチノードの平均方向を使用します (その他の場合はノード位置からパ
ターンの中心への方向を使用します)。
parent (optional)
パターンの中心の代わりに開始位置として使用される親ノードパターン。
signalValue
(optional)
シグナルフラグが設定された場合、この値は data.iValue のシグナルハ
ンドラからアクセス可能なシグナルパラメーターとして渡されます。
Version 1.6
575
Lumberyard 開発者ガイド
ScriptBind_AI
AddPersonallyHostile
構文
AI.AddPersonallyHostile(ScriptHandle entityID, ScriptHandle hostileID)
AgentLookAtPos
指定されたエンティティが特定の位置を見るようにさせます。
構文
AI.AgentLookAtPos(entityId, Vec3 pos)
パラメーター
説明
entityId
エンティティの ID。
pos
見る Vec3 です。
AllowLowerBodyToTurn
構文
AI.AllowLowerBodyToTurn(entityID, bAllowLowerBodyToTurn)
パラメーター
説明
entityId
見る形式を設定するエージェントのエンティティ ID。
bAllowLowerBodyToTurn.
本体が振り替える動きを許可する場合は true、その他の場合は false で
す。
BeginTrackPattern
新しいトラックパターン記述子の定義を開始します。パターンは AI.AddPatternPoint() および
AI.AddPatternBranch() を呼び出すことで作成され、AI.EndTrackPattern() を呼び出してファ
イナライズされます。
構文
AI.BeginTrackPattern(patternName, flags, validationRadius,
[stateTresholdMin],
パラメーター
説明
patternName
新しいトラックパターン記述子の名前。
Version 1.6
576
Lumberyard 開発者ガイド
ScriptBind_AI
パラメーター
説明
flags
追跡パターン機能フラグ。
検証フラグは物理ワールドに適合するようにパターンを検証する方法を示
します。
• AITRACKPAT_VALIDATE_NONE – 検証しませ
ん。AITRACKPAT_VALIDATE_SWEPTSPHERE – スイープ球テストを使用
します。球体の半径が、検証半径とエンティティのパスの半径の合計に
等しくなります。
• AITRACKPAT_VALIDATE_RAYCAST – レイキャストを使用して検証しま
す。ヒット位置が検証半径とエンティティのパス半径の合計分だけ後ろ
に引かれます。
配列フラグは、使用されるパターンが選択されたときに、パターンの配列
がどのように変更できるかを示します。フラグは次の順序で評価されま
す。
• AITRACKPAT_ALIGN_TO_TARGET – 設定のたびに y 軸がターゲットの
方向を指すようにパターンを配列します。その時にエージェントに有
効な注意ターゲットがない場合は、パターンはワールドに合わせられま
す。
• AITRACKPAT_ALIGN_RANDOM – 設定されるたびにパターンをランダム
に配列します。ローテーション範囲は SetRandomRotation() を使用
して設定されます。
validationRadius
オフセットを伴うパターンを検証するときは、検証半径がエンティティパ
スの半径に追加されます。
stateTresholdMin
(optional)
パターンの状態が「隠ぺい」状態 (変形度高) であり、全体の変形が <
stateTresholdMin である場合、状態が露出状態になります。デフォルトは
0.35 です。
stateTresholdMax
(optional)
パターンの状態が「露出」状態 (変形度低) であり、全体の変形 >
stateTresholdMax である場合、状態が隠ぺい状態になります。デフォルト
は 0.4 です。
globalDeformTresholdパターン全体の変形が範囲 [0..1] で追跡されます。このしきい値は底値を
(optional)
固定するために使用できるため、範囲 [trhd..1] の値は [0..1] になります。
デフォルトは 0.0 です。
localDeformTreshold 各ノードの変形が範囲 [0..1] で追跡されます。このしきい値は底値を固
(optional)
定するために使用できるため、範囲 [trhd..1] の値は [0..1] になります。デ
フォルトは 0.0 です。
exposureMod
(optional)
ブランチするときに考慮するノードが露出することに対する重要度 (追跡
されているターゲットから見える度合)。有効範囲は [-1..1] です。-1 は視
認できないノード、1 は視認できる露出したノードを好む傾向になりま
す。デフォルトは 0 (効果なし) です。
randomRotAng
(optional)
設定されるごとにパターンをランダムにローテーションするかどうかを示
すフラグ。ローテーションは XYZ の順番で実行されます。このパラメー
ターは、各軸の回転角度 (度数) を定義します。
CanFireInStance
Version 1.6
577
Lumberyard 開発者ガイド
ScriptBind_AI
構文
AI.CanFireInStance(entityId, stance)
AI 現在の位置から指定された体勢でターゲットに対して射撃できる場合は true を返します。
パラメーター
説明
entityId
エンティティの ID。
stance.
スタンス ID (STANCE_*)。
CanMelee
AI が近接攻撃できるかどうかを判断します。
構文
AI.CanMelee(entityId)
true または false (1 または 0) を返します。
パラメーター
説明
entityId
エンティティの ID。
CanMoveStraightToPoint
指定されたエンティティが現在位置から指定されたポイントに直線で移動できるかどうかを決定しま
す。
構文
AI.CanMoveStraightToPoint(entityId, position)
パラメーター
説明
entityId
エンティティの ID。
position
パスを確認する位置。
ChangeFormation
指定されたエンティティのグループ (ある場合) の現在のフォーメーションのフォーメーション記述子
を変更します。
構文
AI.ChangeFormation(entityId, name [,scale])
Version 1.6
578
Lumberyard 開発者ガイド
ScriptBind_AI
フォーメーションの変更に成功した場合は true を返します。
パラメーター
説明
entityId
グループを識別するために使用する一意のエンティティ ID。
name
フォーメーション記述子の名前。
scale (optional)
フォーメーションのスケール係数 (1 = デフォルト)。
ChangeMovementAbility
指定されたエンティティの AI の移動能力パラメーターの値を変更します。
構文
AI.ChangeMovementAbility(entityId, paramEnum, paramValue)
パラメーター
説明
entityId
エンティティの ID。
paramEnum
変更するパラメーターのインデックス。有効な値を次に示します。
• AIMOVEABILITY_OPTIMALFLIGHTHEIGHT – パスを探す間の最適な飛
行高度。
• AIMOVEABILITY_MINFLIGHTHEIGHT – パスを探す間の最小飛行高度。
• AIMOVEABILITY_MAXFLIGHTHEIGHT – パスを探す間の最大飛行高度。
paramValue
指定したパラメーターの新しい値。
ChangeParameter
指定されたエンティティのパラメーター値を更新します。
構文
AI.ChangeParameter(entityId, paramEnum, paramValue)
パラメーター
説明
entityId
エンティティの ID。
paramEnum
パラメーターの enum。
paramValue
指定したパラメーターの新しい値。
CheckForFriendlyAgentsAroundPoint
構文
Version 1.6
579
Lumberyard 開発者ガイド
ScriptBind_AI
AI.CheckForFriendlyAgentsAroundPoint(ScriptHandle entityID, Vec3 point, float
radius)
CheckMeleeDamage
近接戦闘を実行している AI が実際にターゲットにヒットしているかどうかを決定します。
構文
AI.CheckMeleeDamage(entityId, targetId, radius, minheight, maxheight, angle)
近接戦闘が可能な場合はエンティティとターゲット間の (距離、角度) ペアを返し (度数)、その他の場
合は nil を返します
パラメーター
説明
entityId
エンティティの ID。
targetId
ターゲットのエンティティ ID。
radius.
ターゲットまでの最大距離 (2d)。
minheight.
高さの最小距離。
maxheight.
高さの最大距離。
angle.
ターゲットを含む FOV。
ClearAnimationTag
構文
AI.ClearAnimationTag(ScriptHandle entityID, const char* tagName)
パラメーター
説明
entityId
AI のエンティティ。
tagName.
ClearMovementContext
指定されたエンティティの移動コンテキストをリセットします。
構文
AI.ClearMovementContext(entityId)
パラメーター
説明
entityId
エンティティの ID。
Version 1.6
580
Lumberyard 開発者ガイド
ScriptBind_AI
パラメーター
説明
context.
コンテキスト値。
ClearPotentialTargets
指定されたエンティティの認識ハンドラからすべてのターゲット候補をクリアします。
構文
AI.ClearPotentialTargets(entityId)
パラメーター
説明
entityId
エンティティの ID。
ClearTempTarget
指定されたエンティティの一時的なターゲット候補を削除して、ターゲットの選択時に考慮しないよ
うにします。
構文
AI.ClearTempTarget(entityId)
更新に成功した場合に true を返します。
パラメーター
説明
entityId
エンティティの ID。
ConstrainPointInsideGenericShape
構文
AI.ConstrainPointInsideGenericShape(position, shapeName[, checkHeight])
指定されたシェイプ内で最も近いポイントを返します。
パラメーター
説明
position
チェックする位置。
shapeName
テストするシェイプの名前 (AI.GetEnclosingGenericShapeOfType で
返されます)。
checkHeight
(optional)
シェイプの高さをテストするかどうかを示すフラグ。(デフォルト
は false です)。true に設定した場合、テストで shape.aabb.min.z と
shape.aabb.min.z+shape.height 間の空間をチェックします。
Version 1.6
581
Lumberyard 開発者ガイド
ScriptBind_AI
CreateFormation
フォーメーション記述子を作成し、0,0,0 に固定ノードを追加します (所有者のノード)。
構文
AI.CreateFormation(name)
パラメーター
説明
name
新しいフォーメーション記述子の名前。
CreateGroupFormation
リーダーごと (またはリーダーを更新して) グループフォーメーションを作成します。
構文
AI.CreateGroupFormation(entityId, leaderId)
パラメーター
説明
entityId
AI のエンティティ。
leaderId.
新しいリーダー。
CreateStimulusEvent
指定されたエンティティにターゲット追跡刺激イベントを作成します。
構文
AI.CreateStimulusEvent(ScriptHandle ownerId, ScriptHandle targetId, const
char* stimulusName, SmartScriptTable pData)
パラメーター
説明
ownerId
イベントを所有し受け取るエンティティの一意の ID。
targetId
イベントを送信しターゲットとなるエンティティの一意の ID。
stimulusName
刺激イベントの名前。
pData
イベントデータ (TargetTrackHelpers::SStimulusEvent を参照)。
CreateTempGenericShapeBox
一時的なボックス型の汎用シェイプを作成します。この一時的なシェイプは、AI システムがリセット
されると破壊されます。
構文
Version 1.6
582
Lumberyard 開発者ガイド
ScriptBind_AI
AI.CreateTempGenericShapeBox(Vec3 center, float radius, float height, int
type)
シェイプ名を返します。
パラメーター
説明
center.
ボックスの中心ポイント。
radius.
ボックスの x および y 方向のサイズ。
height
ボックスの高さ。
type
ボックスのシェイプタイプ (AIAnchor)。
DebugReportHitDamage
ヒットダメージのデバッグレポートを作成します。
構文
AI.DebugReportHitDamage(pVictimEntity, pShooterEntity)
パラメーター
説明
pVictimEntity.
対象 ID。
pShooterEntity.
射撃者 ID。
DestroyAllTPSQueries
すべての戦術ポイントシステムのクエリを破壊します。
構文
AI2.DestroyAllTPSQueries()
DistanceToGenericShape
構文
AI.DistanceToGenericShape(Vec3 position, const char* shapeName[, int
checkHeight])
ポイントが指定されたシェイプの内部にあれば true を返します。
パラメーター
説明
position
チェックする位置。
Version 1.6
583
Lumberyard 開発者ガイド
ScriptBind_AI
パラメーター
説明
shapeName
テストするシェイプの名前 (AI.GetEnclosingGenericShapeOfType で
返されます)。
checkHeight
(optional)
シェイプの高さをテストするかどうかを示すフラグ。(デフォルト
は false です)。true に設定した場合、テストで shape.aabb.min.z と
shape.aabb.min.z+shape.height 間の空間をチェックします。
DropTarget
指定されたエンティティの認識ハンドラからターゲットをクリアします。
構文
AI.DropTarget(entityId, targetId)
パラメーター
説明
entityId
エンティティの ID。
targetId
ターゲットのエンティティ ID。
EnableCoverFire
FIREMODE_COVER が選択された場合に射撃を有効または無効にします。
構文
AI.EnableCoverFire(entityId, enable)
パラメーター
説明
entityId
エンティティの ID。
enable
Boolean.
EnableFire
射撃を有効または無効にします。
構文
AI.EnableFire(entityId, enable)
パラメーター
説明
entityId
エンティティの ID。
enable
Boolean.
Version 1.6
584
Lumberyard 開発者ガイド
ScriptBind_AI
EnableUpdateLookTarget
構文
AI.EnableUpdateLookTarget(ScriptHandle entityID, bool bEnable)
EnableWeaponAccessory
特定の武器アクセサリの使用を有効または無効にします。
構文
AI.EnableWeaponAccessory(entityId, int accessory, bool state)
パラメーター
説明
entityId
エンティティの ID。
accessory
有効にするアクセサリの enum。使用できる値 (IAgent.h ファイルの enum
EAIWeaponAccessories 参照):
AIWEPA_NONE = 0,
AIWEPA_LASER = 0x0001
AIWEPA_COMBAT_LIGHT = 0x0002
AIWEPA_PATROL_LIGHT = 0x0004
state
true または false に設定して有効または無効にします。
EndTrackPattern
トラックパターン定義をファイナライズします。パターンをファイナライズするには、常にこの関数
を呼び出す必要があります。これを実行しないと、挙動が不安定になります。
構文
AI.EndTrackPattern()
エラー
システムで処理されない例外が発生した場合に使用されるフォールバックのエラーメッセージ。エ
ディタで実行されていた場合は、問題の原因が修正できるように、以下のコードが続きます。ただ
し、ゲームで実行されていた場合は、実行が停止されます。
構文
AI.Error(szMessage)
パラメーター
説明
szMessage
ログに書き込むメッセージ。
Version 1.6
585
Lumberyard 開発者ガイド
ScriptBind_AI
EvalPeek
指定されたエンティティが現在の位置から覗き見できるかどうかを決定します。
構文
AI.EvalPeek(entityId [, bGetOptimalSide])
以下のいずれかの値が返されます。
• -1 – 覗き見る必要がない
• 0 – 覗き見できない
• 1 – 左から覗き見できる
• 2 – 右から覗き見できる
• 3 – 左右から覗き見できる
パラメーター
説明
entityId
エンティティの ID。
bGetOptimalSide
(optional)
AI オブジェクトが両側から覗き見できる場合、注意ターゲットの現在位置
に最も適した側を示すフラグ。デフォルト: false。
ExecuteAction
一連の参加者に対してアクションを実行します。
構文
AI.ExecuteAction(action, participant1 [, participant2 [, ... ,
participantN ] ])
パラメーター
説明
action
スマートオブジェクトのアクション名または ID。
participant1
アクションの最初の参加者のエンティティ ID。
participant2..N
(optional)
追加参加者のエンティティ ID。
FindObjectOfType
指定されたエンティティまたは位置の周辺エリアで指定されたタイプの AIObject を検索します。見つ
かった AIObject は重要度が下げられ、一定秒数の間は再度発見されることはありません (フラグがオ
フにならない限り)。
構文
Version 1.6
586
Lumberyard 開発者ガイド
ScriptBind_AI
AI.FindObjectOfType(entityId, radius, AIObjectType, flags [,returnPosition
[,returnDirection]]) AI.FindObjectOfType(position, radius, AIObjectType,
[,returnPosition [,returnDirection]])
発見した AIObject の名前を返します。
パラメーター
説明
entityId
検索の中心位置を決定するために使用する一意のエンティティ ID。
position
検索の中心位置を指定するベクトル。
radius
検索エリアの半径。
AIObjectType
検索する AIObject のタイプ (AIObject タイプの完全なリストは
ScriptBindAI.cpp および Scripts/AIAnchor.lua を参照)。
flags.
以下の検索フィルタフラグの組み合わせ。
• AIFAF_VISIBLE_FROM_REQUESTER – オブジェクトに対して、それに
対して視線を向けることをリクエストしている人物を要求します。
• AIFAF_VISIBLE_TARGET– ターゲットとアンカー間の視線を要求しま
す。
• AIFAF_INCLUDE_DEVALUED – 重要度が下げられたオブジェクトを含め
ます。
• AIFAF_INCLUDE_DISABLED – 無効オブジェクトを含めます。
returnPosition
(optional)
発見したオブジェクトの位置。
returnDirection
(optional)
発見したオブジェクトの方向。
FindStandbySpotInShape
構文
AI.FindStandbySpotInShape(centerPos, targetPos, anchorType)
FindStandbySpotInSphere
構文
AI.FindStandbySpotInSphere(centerPos, targetPos, anchorType)
FreeSignal
位置周辺の指定された半径内にいるユーザーにシグナルを送信します。
構文
AI.FreeSignal(signalType, signalText, position, radius [, entityID
[,signalExtraData]])
Version 1.6
587
Lumberyard 開発者ガイド
ScriptBind_AI
パラメーター
説明
signalType
「AI.Signal」を参照してください。
signalText
「AI.Signal」を参照してください。
position
シグナルが送信された中心点 ({x,y,z} 座標)
radius
シグナルが送信されたエリアの内半径。
entityID
オプション。シグナルを受け取らないグループのメンバーのエンティティ
の ID。所属するグループ ID が指定された値であるエンティティにはシグ
ナルが送信されません。
signalExtraData
オプション。「AI.Signal」を参照してください。
GetAIObjectPosition
指定された AIObject の位置を取得します。
構文
AI.GetAIObjectPosition(entityId | AIObjectName)
AI オブジェクトの位置ベクトル {x,y,z} を返します。
パラメーター
説明
entityId |
AIObjectName
一意のエンティティ ID または AIObject 名。
GetAnchor
指定されたエンティティの周辺エリアで指定されたタイプのアンカーのうち最も近いものを検索しま
す。見つかったアンカーは重要度が下げられ、一定秒数の間は再度発見されることはありません (フラ
グがオフにならない限り)。
構文
AI.GetAnchor(entityId, radius, AIAnchorType, searchType [,returnPosition
[,returnDirection]])
発見されたアンカーの名前を返します。
パラメーター
説明
entityId
検索の中心位置を決定するために使用する一意のエンティティ ID。
radius
検索エリアの半径。検索範囲 (最小 =minRad、最大 =maxRad) で指定する
こともできます。
AIAnchorType
検索するアンカータイプ。利用可能なアンカータイプの完全なリストにつ
いては、Scripts/AIAnchor.lua を参照してください。
Version 1.6
588
Lumberyard 開発者ガイド
ScriptBind_AI
パラメーター
説明
searchType
以下の検索フィルタフラグの組み合わせ。
• AIANCHOR_NEAREST – 指定されたタイプのアンカーで最も近いもの (デ
フォルト)。
• AIANCHOR_NEAREST_IN_FRONT – エンティティの前方円錐形内の指定
したタイプのアンカーのうち最も近いもの。
• AIANCHOR_NEAREST_FACING_AT – エンティティの注意ターゲットに向
けて方向づけられた指定タイプのアンカーのうち最も近いもの。
• AIANCHOR_RANDOM_IN_RANGE – 指定されたタイプのアンカーのうちラ
ンダム
• AIANCHOR_NEAREST_TO_REFPOINT – エンティティの参照ポイントに
最も近い指定されたタイプのアンカー。
(optional)
returnPosition
発見したオブジェクトの位置。
(optional)
returnDirection
発見したオブジェクトの方向。
GetAttentionTargetAIType
指定されたエンティティの注意ターゲットの AI タイプ (AIOBJECT_*) を取得します。
構文
AI.GetAttentionTargetAIType(entityId)
注意ターゲットの AI タイプを返します。ターゲットがない場合は AIOBJECT_NONE を返します。
パラメーター
説明
entityId
エンティティの ID。
GetAttentionTargetDirection
指定されたエンティティの注意ターゲットの方向を取得します。
構文
AI.GetAttentionTargetDirection(entityId, returnDir)
戻り値として渡された注意ターゲットの方向ベクトル {x,y,z} を返します。
パラメーター
説明
entityId
エンティティの ID。
GetAttentionTargetDistance
指定されたエンティティからその注意ターゲットまでの距離を取得します。
Version 1.6
589
Lumberyard 開発者ガイド
ScriptBind_AI
構文
AI.GetAttentionTargetDistance(entityId)
注意ターゲットまでの距離を取得します。
パラメーター
説明
entityId
エンティティの ID。
GetAttentionTargetEntity
指定されたエンティティの注意ターゲットエンティティを返します (指定されたエンティティである
場合)。または、ダミーオブジェクトの注意ターゲットの所有者エンティティを返します (所有者エン
ティティがある場合)。
構文
AI.GetAttentionTargetEntity(ScriptHandle entityID)
注意ターゲットのエンティティを返します。
パラメーター
説明
entityId
エンティティの ID。
GetAttentionTargetOf
指定されたエンティティの注意ターゲットを取得します。
構文
AI.GetAttentionTargetOf(entityId)
注意ターゲットの名前を返します。ターゲットがない場合は Null です。
パラメーター
説明
entityId
エンティティの ID。
GetAttentionTargetPosition
指定されたエンティティの注意ターゲットの位置を取得します。
構文
AI.GetAttentionTargetPosition(entityId, returnPos)
戻り値 () として渡された注意ターゲットの位置ベクトル {x,y,z} を返します。
Version 1.6
590
Lumberyard 開発者ガイド
ScriptBind_AI
パラメーター
説明
entityId
エンティティの ID。
GetAttentionTargetThreat
構文
AI.GetAttentionTargetThreat(ScriptHandle entityID)
GetAttentionTargetType
指定されたエンティティの注意ターゲットのタイプ (AITARGET_*) を取得します。
構文
AI.GetAttentionTargetType(entityId)
注意ターゲットのタイプを返します。ターゲットがない場合は AITARGET_NONE を返します。
パラメーター
説明
entityId
エンティティの ID。
GetAttentionTargetViewDirection
指定されたエンティティの注意ターゲットの視覚方向を取得します。
構文
AI.GetAttentionTargetViewDirection(entityId, returnDir)
戻り値として渡された注意ターゲットの視覚方向ベクトル {x,y,z} を返します。
パラメーター
説明
entityId
エンティティの ID。
GetBeaconPosition
選択されたエンティティ/オブジェクトのグループのビーコン位置を取得します。
構文
AI.GetBeaconPosition(entityId | AIObjectName, returnPos)
ビーコンが検出され位置が設定された場合は true を返します。
Version 1.6
591
Lumberyard 開発者ガイド
ScriptBind_AI
パラメーター
説明
entityId |
AIObjectName
一意のエンティティ ID または AI オブジェクト名。
returnPos
ビーコン位置ベクトル {x,y,z}。
GetBehaviorBlackBoard
指定された AIActor の現在の動作のブラックボード (Lua テーブル) を取得します。
構文
AI.GetBehaviorBlackBoard(entity)
ブラックボードがある場合はそれを返し、ない場合は nil を返します。
パラメーター
説明
entityId or
entityName.
AIActor 識別子。
GetBehaviorVariable
指定されたアクターの動作変数を返します。
構文
AI.GetBehaviorVariable(ScriptHandle entityId, const char* variableName)
GetBiasedDirection
特定のポイントの偏差方向を取得します。
構文
AI.GetBiasedDirection(entityId)
パラメーター
説明
entityId
エンティティの ID。
GetCurrentHideAnchor
エンティティが現在遮へい物に使用しているアンカーの名前を取得します。
構文
AI.GetCurrentHideAnchor(entityId)
Version 1.6
592
Lumberyard 開発者ガイド
ScriptBind_AI
パラメーター
説明
entityId
エンティティの ID。
GetDirectAnchorPos
指定されたエンティティがその注意ターゲットへの直接攻撃に使用できる遮へいポイントの位置を取
得します。
構文
AI.GetDirectAttackPos(entityId, searchRange, minAttackRange)
ポイント値を返します。使用できる攻撃ポイントがない場合は none を返します。
パラメーター
説明
entityId
エンティティの ID。
AIAnchorType
アンカータイプ (アンカータイプの完全なリストについては Scripts/
AIAnchor.lua を参照)。
maxDist
検索範囲の最大サイズ。
GetDirLabelToPoint
指定されたポイントの方向ラベル (前面 = 0、背面 = 1、左 = 2、右_3、上方 = 4、-1 = 無効) を取得し
ます。
構文
AI.GetDirLabelToPoint(entityId, point)
パラメーター
説明
entityId
エンティティの ID。
point
評価するポイント。
GetEnclosingSpace
周囲の移動可能空間の概算をメートルで返します。
構文
AI.GetEnclosingSpace(entityId, Vec3 pos, float rad)
パラメーター
説明
entityId
エンティティの ID。
Version 1.6
593
Lumberyard 開発者ガイド
ScriptBind_AI
パラメーター
説明
pos
位置を確認します。
rad
半径を確認します。
GetDistanceAlongPath
最初のエンティティのパスに沿って、1 番目と 2 番目エンティティ間の距離を取得します。
構文
AI.GetDistanceAlongPath(entityId1, entityid2)
パスに沿った距離を返します。2 番目のエンティティがパスの前方にある場合は値が負になります。
パラメーター
説明
entityId1
1 番目のエンティティの ID。
entityId2
2 番目のエンティティの ID。
GetDistanceToClosestGroupMember
構文
AI.GetDistanceToClosestGroupMember(ScriptHandle entityId)
GetEnclosingGenericShapeOfType
指定されたポイントを囲む特定のタイプの最初のシェイプを取得します。
構文
AI.GetEnclosingGenericShapeOfType(position, type[, checkHeight])
シェイプ名を返します。
パラメーター
説明
position
遮へいされたシェイプを検索するポイント。
type
検索するシェイプタイプ (アンカータイプを使用)。
checkHeight
(optional)
シェイプの高さをテストするかどうかを示すフラグ。(デフォルト
は false です)。true に設定した場合、テストで shape.aabb.min.z と
shape.aabb.min.z+shape.height 間の空間をチェックします。
GetExtraPriority
指定された敵エンティティの追加優先順位値を取得します。
構文
Version 1.6
594
Lumberyard 開発者ガイド
ScriptBind_AI
AI.GetExtraPriority(enemyEntityId)
パラメーター
説明
enemyEntityId.
エンティティの ID。
GetFactionOf
指定されたエンティティのファクションを取得します。
構文
AI.GetFactionOf(ScriptHandle entityID)
指定されたエンティティのファクションを返します。
パラメーター
説明
entityId
ファクションが返されるエンティティの ID。
GetFormationLookingPoint
フォーメーション内の注視ポイントの位置を取得します。
構文
AI.GetFormationLookingPoint(entityId)
v3 を返します – 注視ポイント位置を保存する {x,y,z} 形式のテーブル
パラメーター
説明
entityId
AI のエンティティ。
GetFormationPointClass
フォーメーション記述子に追跡型ノードを追加します。
構文
AI.GetFormationPointClass(name, position)
フォーメーションポイントのクラスを返します (見つからない場合は -1)。
パラメーター
説明
name
フォーメーション記述子の名前。
position
フォーメーションのポイントインデックス (1..N).
Version 1.6
595
Lumberyard 開発者ガイド
ScriptBind_AI
GetFormationPointPosition
エンティティのフォーメーションポイント位置を取得します。
構文
AI.GetFormationPointPosition(entityId, pos)
フォーメーションポイントが見つかった倍は true を返します。
パラメーター
説明
entityId
エンティティの ID。
pos
エンティティのフォーメーションポイントの位置の値を返します。
GetFormationPosition
フォーメーション内の相対位置を取得します。
構文
AI.GetFormationPosition(entityId)
v3 を返します – 相対位置を保存する {x,y,z} 形式のテーブル
パラメーター
説明
entityId
AI のエンティティ。
GetGroupAveragePosition
グループのメンバーの平均位置を取得します。
構文
AI.GetGroupAveragePosition(entityId, properties, returnPos)
平均位置を返します。
パラメーター
説明
entityId
グループを決定するために使用する一意のエンティティ ID。
unitProperties
攻撃がリクエストされるユニットのプロパティタイプの以下の形式のバイ
ナリマスク。
UPR_* + UPR* (UPR_COMBAT_GROUND + UPR_COMBAT_FLIGHT)
ユニットのプロパティ UPR_* については、IAgent.h を参照してくださ
い。
Version 1.6
596
Lumberyard 開発者ガイド
ScriptBind_AI
GetGroupCount
指定されたエンティティグループのメンバーの数を取得します。
構文
AI.GetGroupCount(entityId, flags, type)
指定されたグループのメンバーの数を返します。
パラメーター
説明
entityId
エンティティまたはグループ ID。
flags
次の 1 つ以上のフラグの組み合わせ。
• GROUP_ALL – グループのすべてのエージェントをカウントします (デ
フォルト)。
• GROUP_ENABLED – 有効化されたエージェントのみをカウントします (all
との組み合わせを除く)。
• GROUP_MAX – ゲーム中のエージェントの最大メンバー数を含めます (all
または enabled と組み合わせることができます)。
type
フィルタする AI オブジェクトのタイプ。指定されたタイプの AI オブジェ
クトのみをカウントします。このパラメーターは GROUP_MAX とともに使
用することはできません。
GetGroupMember
指定されたグループの指定されたインデックス位置にあるエンティティを返します。
構文
AI.GetGroupMember(entityId|groupId, idx, flags, type)
リクエストされたエンティティのスクリプトハンドラを返します。リクエストされたインデックス値
が範囲外の場合は null を返します。
パラメーター
説明
entityId|groupId
エンティティ ID またはグループ ID。
idx
インデックス内の 1 から n までの位置。
flags
次の 1 つ以上のフラグの組み合わせ。
• GROUP_ALL – グループのすべてのエージェントをカウントします (デ
フォルト)。
• GROUP_ENABLED – 有効化されたエージェントのみをカウントします (all
との組み合わせを除く)。
type
フィルタする AI オブジェクトのタイプ。指定されたタイプの AI オブジェ
クトのみを返します。このパラメーターは GROUP_MAX とともに使用する
ことはできません。
Version 1.6
597
Lumberyard 開発者ガイド
ScriptBind_AI
GetGroupOf
指定されたエンティティ ID のグループ ID を取得します。
構文
AI.GetGroupOf(entityId)
指定されたエンティティのグループ ID を返します。
パラメーター
説明
entityId
グループ ID を返すエンティティの ID。
GetGroupScopeUserCount
構文
AI.GetGroupScopeUserCount(ScriptHandle entityIdHandle, const char*
groupScopeName)
グループ範囲内のアクターの数がゼロ以上の場合には数を返し、エラーが発生した場合は nil を返しま
す。
パラメーター
説明
entityId
アクセスするグループ範囲のエージェントのエンティティ ID。
groupScopeName.
グループ範囲名。
GetGroupScriptTable
構文
AI.GetGroupScriptTable(int groupID)
GetGroupTarget
指定されたエンティティのグループ内の AI エージェントのうちで、最も脅威となる注意ターゲットを
取得します。アラートステータスについては、IAgent.h を参照してください。
構文
AI.GetGroupTarget(entityId [,bHostileOnly [,bLiveOnly]])
パラメーター
説明
entityId
グループを決定するために使用する一意のエンティティ ID。
Version 1.6
598
Lumberyard 開発者ガイド
ScriptBind_AI
パラメーター
説明
bHostileOnly
(optional)
グループ内の敵ターゲットのみを含めるかどうかを示すフラグ。
bLiveOnly
(optional)
グループ内の生存ターゲットのみを含めるかどうかを示すフラグ。
GetGroupTargetCount
指定されたエンティティのグループ内の AI エージェントのうち注意ターゲットの数を取得します。
構文
AI.GetGroupTargetCount(entityId [,bHostileOnly [,bLiveOnly]])
パラメーター
説明
entityId
グループを決定するために使用する一意のエンティティ ID。
bHostileOnly
(optional)
グループ内の敵ターゲットのみを含めるかどうかを示すフラグ。
bLiveOnly
(optional)
グループ内の生存ターゲットのみを含めるかどうかを示すフラグ。
GetGroupTargetEntity
構文
AI.GetGroupTargetEntity(int groupID)
GetGroupTargetThreat
構文
AI.GetGroupTargetThreat(int groupID)
GetGroupTargetType
構文
AI.GetGroupTargetType(int groupID)
GetLastUsedSmartObject
指定されたユーザーが最後に使用したスマートオブジェクトを取得します。
構文
Version 1.6
599
Lumberyard 開発者ガイド
ScriptBind_AI
AI.GetLastUsedSmartObject(userEntityId)
最後に使用したスマートオブジェクトがない場合、またはエラーが発生する場合は、nil を返します。
それ以外の場合は、指定されたユーザーが最後に使用したスマートオブジェクトのエンティティのス
クリプトテーブルを返します。
パラメーター
説明
userEntityId
最後に使用したスマートオブジェクトをクエリするユーザーのエンティ
ティ ID。
GetLeader
指定されたグループのリーダーの名前を取得します。
構文
AI.GetLeader(groupID | entityID)
リーダー名を返します。
パラメーター
説明
groupID
一意のグループ ID。
entityID
エンティティの ID。
GetMemoryFireType
構文
AI.GetMemoryFireType(entityId)
パペットがメモリターゲットに対する射撃に使用する方法を返します。
パラメーター
説明
entityId
エンティティの ID。
GetNavigationType
指定されたエンティティの位置でのナビゲーションタイプを取得します。
構文
AI.GetNavigationType(entityId)
Version 1.6
600
Lumberyard 開発者ガイド
ScriptBind_AI
次のようなナビゲーションタイプを返しま
す。NAV_TRIANGULAR、NAV_WAYPOINT_HUMAN、NAV_ROAD、NAV_VOLUME、NAV_WAYPOINT_3DSURFACE、NAV_FLIG
完全なリストについては、IAISystem::ENavigationType の定義を参照してください。
パラメーター
説明
entityId
エンティティの ID。
GetNearestEntitiesOfType
構文
AI.GetNearestEntitiesOfType(entityId|objectname|position, AIObjectType,
maxObjects, returnList [,objectFilter [,radius]])
発見したエンティティの数を返します。
パラメーター
説明
entityId |
objectname |
position.
検索の中心位置を特定するために使用する一意のエンティティ ID、AI オ
ブジェクト名、または位置。
radius
検索エリアの半径。
AIObjectType
検索する AIObject のタイプ (AIObject タイプの完全なリストは
ScriptBindAI.cpp および Scripts/AIAnchor.lua を参照)。
maxObjects
検索するオブジェクトの最大数。
return list
発見したエンティティのリストを保持する Lua テーブル (Lua ハンドラ)
(optional)
objectFilter
以下の検索フィルタフラグの組み合わせ。
• AIOBJECTFILTER_SAMEFACTION – クエリしているオブジェクトと同じ
種類の AI オブジェクトのみを含めます。
• AIOBJECTFILTER_SAMEGROUP – クエリしているオブジェクトと同じグ
ループの AI オブジェクトのみを含めます (またはグループなし)。
• AIOBJECTFILTER_NOGROUP – グループ ID が AI_NOGROUP の AI オブ
ジェクトのみを含めます。
• AIOBJECTFILTER_INCLUDEINACTIVE – 非アクティブなオブジェクト
を含めます。
GetNearestHidespot
指定された範囲内で指定されたエンティティに最も近い隠れポイントを取得します。
構文
AI.GetNearestHidespot(entityId, rangeMin, rangeMax [, center])
見つかった場合のポイント位置を返します。
Version 1.6
601
Lumberyard 開発者ガイド
ScriptBind_AI
パラメーター
説明
entityId
エンティティの ID。
rangeMin
検索エリアの最小範囲。
rangeMax
検索エリアの最大範囲
centre (optional)
検索エリアの中心ポイント。指定されない場合、エンティティの現在の位
置が使用されます。
GetNearestPathOfTypeInRange
指定されたエンティティ用の指定されたポイントに最も近いパスのタイプを取得します。パスはアン
カーと同じ型を使用し、パスのプロパティで指定されます。この関数ではエンティティのナビゲー
ションキャップに一致するパスのみを返します。ナビゲーションたプもパスのプロパティで指定され
ます。
構文
AI.GetNearestPathOfTypeInRange(entityId, pos, range, type [, devalue,
useStartNode])
パラメーター
説明
entityId
エンティティの ID。
pos
対象ポイント方向を指定するベクトル。
range
検索範囲。
type
検索するパスのタイプ。
devalue (オプション)
返されたパスが occupied とマークされる時間。
useStartNode (オプ
ション)
範囲内にポイントがあるパス (useStartNode=0)、または範囲内に開始ノー
ドがあるパス (useStartNode=0) を見るかどうかを示すフラグ。
GetNearestPointOnPath
指定された位置に最も近いパスのポイントを見つけます。
構文
AI.GetNearestPointOnPath(entityId, pathname, vPos)
パラメーター
説明
entityId
エンティティの ID。
pathname
パス名。
vPos
測定する起点位置。
Version 1.6
602
Lumberyard 開発者ガイド
ScriptBind_AI
GetObjectBlackBoard
指定されたオブジェクトのブラックボード (Lua テーブル) を取得します。
構文
AI.GetObjectBlackBoard(entity)
ブラックボードがある場合はそれを返し、ない場合は nil を返します。
パラメーター
説明
entityId or
entityName.
AI エンティティーの識別子。
GetObjectRadius
指定された AI オブジェクトの半径を取得します。
構文
AI.GetObjectRadius(entityId)
半径サイズを返します。
パラメーター
説明
entityId
エンティティの ID。
GetParameter
指定されたエンティティの列挙型 AI パラメーターの値を取得します。
構文
AI.GetParameter(entityId, paramEnum)
設定パラメーターの値を返します。
パラメーター
説明
entityId
エンティティの ID。
paramEnum
取得するパラメーターのインデックス。詳細な一覧については、
「AI.ChangeParameter()」を参照してください。
GetPathLoop
Version 1.6
603
Lumberyard 開発者ガイド
ScriptBind_AI
構文
AI.GetPathLoop(entityId, pathname)
パスが正常にループしている場合は true を返します。
パラメーター
説明
entityId
エンティティの ID。
pathname
パスの名前。
GetPathSegNoOnPath
構文
AI.GetPathSegNoOnPath(entityId, pathname, vPos)
セグメント比 (0.0 が開始点、100.0 が終了点) を返します。
パラメーター
説明
entityId
エンティティの ID。
pathname
パス名。
vPos
Position.
GetPeakThreatLevel
構文
AI.GetPeakThreatLevel(ScriptHandle entityID)
GetPeakThreatType
構文
AI.GetPeakThreatType(ScriptHandle entityID)
GetPointOnPathBySegNo
構文
AI.GetPointOnPathBySegNo(entityId, pathname, segNo)
セグメント比 (0.0 が開始点、100.0 が終了点) でポイントを返します。
Version 1.6
604
Lumberyard 開発者ガイド
ScriptBind_AI
パラメーター
説明
entityId
エンティティの ID。
pathname
パス名。
segNo
セグメント比率。
GetPosturePriority
指定されたエンティティの姿勢の優先順位を設定します。
構文
AI.GetPosturePriority(ScriptHandle entityId, const char* postureName)
GetPotentialTargetCount
指定されたエンティティのターゲット候補の総数を取得します。
構文
AI.GetPotentialTargetCount(ScriptHandle entityID)
パラメーター
説明
entityId
エンティティの ID。
GetPotentialTargetCountFromFaction
エンティティのターゲット候補で指定されたファクションに所属するものの数を取得します。
構文
AI.GetPotentialTargetCountFromFaction(ScriptHandle entityID, const char*
factionName)
パラメーター
説明
entityId
エンティティの ID。
name
ファクション名
GetPredictedPosAlongPath
指定された時刻におけるパス沿いの AI エージェントの予測位置を取得します。
構文
AI.GetPredictedPosAlongPath(entityId, time, retPos)
Version 1.6
605
Lumberyard 開発者ガイド
ScriptBind_AI
成功した場合に true を返します。
パラメーター
説明
entityId
エンティティの ID。
time
予測位置までの時間 (秒) です。
retPos
予測位置のポイント値を返します。
GetPreviousBehaviorName
構文
AI.GetPreviousBehaviorName(ScriptHandle entityID)
GetPreviousPeakThreatLevel
構文
AI.GetPreviousPeakThreatLevel(ScriptHandle entityID)
GetPreviousPeakThreatType
構文
AI.GetPreviousPeakThreatType(ScriptHandle entityID)
GetProbableTargetPosition
指定されたエンティティの予測ターゲット位置を取得します。
構文
AI.GetProbableTargetPosition(entityId)
パラメーター
説明
entityId
エンティティの ID。
GetRefPointDirection
指定されたエンティティの参照ポイント方向を取得します。
構文
AI.GetRefPointDirection(entityId)
スクリプトベクトル (x,y,z) 参照ポイントの方向を返します。
Version 1.6
606
Lumberyard 開発者ガイド
ScriptBind_AI
パラメーター
説明
entityId
エンティティの ID。
GetRefPointPosition
指定されたエンティティの参照ポイントの「ワールド」位置を取得します。
構文
AI.GetRefPointPosition(entityId)
スクリプトベクトル (x,y,z) 参照ポイントの位置を返します。
パラメーター
説明
entityId
エンティティの ID。
GetRefShapeName
指定されたエンティティの参照シェイプの名前を取得します。
構文
AI.GetRefShapeName(entityId)
参照シェイプ名を返します。
パラメーター
説明
entityId
エンティティの ID。
GetSoundPerceptionDescriptor
選択されたエンティティが音声タイプを感知する方法についての情報を取得します。
構文
AI.GetSoundPerceptionDescriptor(entityId, soundType, descriptorTable)
情報が正常に返された場合 true を返します。
パラメーター
説明
entityId
認識データを取得するエンティティ。
soundType
データを取得する音声刺激のタイプ。
descriptorTable
取得したデータを保存する場所。
Version 1.6
607
Lumberyard 開発者ガイド
ScriptBind_AI
GetStance
指定されたエンティティの体勢を取得します。
構文
AI.GetStance(entityId)
エンティティの体勢を返します (STANCE_*)
パラメーター
説明
entityId
エンティティの ID。
GetSubTypeOf
指定されたエンティティのサブタイプを取得します。
構文
AI.GetSubTypeOf(entityId)
エンティティのサブタイプ (IAgent.h で定義されています) を返します。
パラメーター
説明
entityId
エンティティの ID。
GetTacticalPoints
指定されたエンティティに関連している、説明に一致するポイントを取得します。ポイントの形式は
{ x,y,z } です。
構文
AI.GetTacticalPoints(entityId, tacPointSpec, point)
有効なポイントがある場合は true を返します。それ以外の場合は false を返します。
パラメーター
説明
entityId
AI のエンティティ。
tacPointSpec.
必要なポイントを指定するテーブル。
point
見つかったポイントの座標。
GetTargetSubType
指定されたエンティティの現在の注意ターゲットのサブタイプを取得します。
Version 1.6
608
Lumberyard 開発者ガイド
ScriptBind_AI
構文
AI.GetTargetSubType(entityId)
注意ターゲットのサブタイプを返します。ターゲットタイプの定義のリストについては、IAgent.h
を参照してください。
パラメーター
説明
entityId
エンティティの ID。
GetTargetType
指定されたエンティティの現在の注意ターゲットのタイプを取得します。
構文
AI.GetTargetType(entityId)
次のような注意ターゲットのタイプを返しま
す。AITARGET_NONE、AITARGET_MEMORY、AITARGET_BEACON、AITARGET_ENEMY。ターゲットタ
イプの定義のリストについては、IAgent.h を参照してください。
パラメーター
説明
entityId
エンティティの ID。
GetTotalLengthOfPath
指定されたパスの全長を取得します。
構文
AI.GetTotalLengthOfPath(entityId, pathname)
パラメーター
説明
entityId
エンティティの ID。
pathname
パス名。
GetTypeOf
指定されたエンティティのタイプを取得します。
構文
AI.GetTypeOf(entityId)
Version 1.6
609
Lumberyard 開発者ガイド
ScriptBind_AI
エンティティのタイプ (IAgent.h で定義されています) を返します。
パラメーター
説明
entityId
エンティティの ID。
GetUnitCount
リーダーが認識しているユニット数を取得します。リーダーはエンティティのグループ ID に基づいて
識別されます。
構文
AI.GetUnitCount(entityId, unitProperties)
パラメーター
説明
entityId
エンティティの ID。
unitProperties
攻撃がリクエストされるユニットのプロパティタイプの以下の形式のバイ
ナリマスク。
UPR_* + UPR* (UPR_COMBAT_GROUND + UPR_COMBAT_FLIGHT)
ユニットのプロパティ UPR_* については、IAgent.h を参照してくださ
い。
GetUnitInRank
指定されたグループ内で指定されたランク位置を保持するエンティティを取得します。
構文
AI.GetUnitInRank(groupID [,rank])
ランク付けされたユニットのエンティティスクリプトテーブルを返します。
パラメーター
説明
groupID
取得するエンティティを含むグループの ID。
rank
取得するエンティティのランク位置。null またはゼロ以下の値が指定され
た場合は、エンティティのうちでもっとも高いランクのエンティティを取
得します。もっとも高いランクの値は 1 です。
GoTo
指定されたエンティティが所定の方向に移動できるようにします。
構文
AI.GoTo(entityId, vDestination)
Version 1.6
610
Lumberyard 開発者ガイド
ScriptBind_AI
パラメーター
説明
entityId
AI のエンティティ。
vDestination.
Hostile
2 つのエンティティが敵対しているかどうかを決定します。
構文
AI.Hostile(entityId, entity2Id|AIObjectName)
エンティティが敵である場合は true を返します。
パラメーター
説明
entityId
最初の AI エンティティの ID。
entity2Id |
AIObjectName
2 番目の AI エンティティの ID、または AIobject 名。
IgnoreCurrentHideObject
現在の非表示オブジェクトを到達不可能としてマークします。今後の隠れ場所の選択肢から除外され
ます。
構文
AI.IgnoreCurrentHideObject(entityId)
パラメーター
説明
entityId
エンティティの ID。
IntersectsForbidden
指定された線が禁止リージョンにあるかどうかを決定します。
構文
AI.IntersectsForbidden(Vec3 start, Vec3 end)
交差位置または終了 (黄砂がない場合) を返します。
パラメーター
説明
start
{x,y,z} 形式のベクトル。
Version 1.6
611
Lumberyard 開発者ガイド
ScriptBind_AI
パラメーター
説明
end
{x,y,z} 形式のベクトル。
IsAgentInAgentFOV
あるエンティティが別のエンティティの視界にあるかどうかを決定します。
構文
AI.IsAgentInAgentFOV(entityId, entityId2)
エージェントがエンティティ FOV 内にある場合、最初の値に true を返します。エージェントがエン
ティティのプライマリ FOV 内に存在する場合、2 番目の値に true を返します。エージェントがエン
ティティのセカンダリ FOV 内にある場合は false を返します。
パラメーター
説明
entityId
FOV を確認する AI エンティティ。
entityId2.
エージェントのエンティティ ID。
IsAgentInTargetFOV
エンティティが注意ターゲットの FOV にあるかどうかを決定します。
構文
AI.IsAgentInTargetFOV(entityId, fov)
注意ターゲットの FOV 内の場合は true を返します。それ以外の場合は false を返します。
パラメーター
説明
entityId
エンティティの ID。
fov
敵の FOV (度数)。
IsAimReady
構文
AI.IsAimReady(ScriptHandle entityIdHandle)
IsCoverCompromised
構文
AI.IsCoverCompromised(entityId)
Version 1.6
612
Lumberyard 開発者ガイド
ScriptBind_AI
遮へい物が発覚した場合は true を返します。それ以外の場合は nil を返します。
パラメーター
説明
entityId
AI のエンティティ。
IsEnabled
エンティティで AI が有効化されていることを確認します。
構文
AI.IsEnabled(entityId)
パラメーター
説明
entityId
エンティティの ID。
IsFireEnabled
AI が発砲を許可されているかどうかを決定します。
構文
AI.IsFireEnabled(entityId)
AI が発砲できる場合は true を返します
パラメーター
説明
entityId
エンティティの ID。
IsInCover
エージェントが遮へい物を使用しているかどうかを決定します。
構文
AI.IsInCover(entityId)
IsLowHealthPauseActive
構文
AI.IsLowHealthPauseActive(ScriptHandle entityID)
IsLowOnAmmo
Version 1.6
613
Lumberyard 開発者ガイド
ScriptBind_AI
構文
AI.IsLowOnAmmo(entityId)
パラメーター
説明
entityId
AI のエンティティ。
threshold
弾薬率のしきい値。
IsMoving
エージェントが移動を求めているかどうかを決定します。
構文
AI.IsMoving(entityId)
パラメーター
説明
entityId
エンティティの ID。
IsMovingInCover
構文
AI.IsMovingInCover(entityId)
エージェントから遮へい物内で移動する場合は true を返します。そうでない場合は nil を返します。
パラメーター
説明
entityId
AI のエンティティ。
IsMovingToCover
エージェントが遮へい物に向かって走るかどうかを決定します。
構文
AI.IsMovingToCover(entityId)
パラメーター
説明
entityId
AI のエンティティ。
Version 1.6
614
Lumberyard 開発者ガイド
ScriptBind_AI
IsOutOfAmmo
構文
AI.IsOutOfAmmo(entityId)
指定されたエンティティが弾薬切れの場合に true を返します。それ以外の場合は nil を返します。
パラメーター
説明
entityId
AI エンティティの ID。
IsPersonallyHostile
構文
AI.IsPersonallyHostile(ScriptHandle entityID, ScriptHandle hostileID)
IsPointInFlightRegion
指定されたポイントが飛行リージョンにあるかどうかを決定します。
構文
AI.IsPointInFlightRegion(point)
ポイントが飛行リージョンにある場合は true を返します。
パラメーター
説明
point
{x,y,z} 形式のベクトル。
IsPointInsideGenericShape
ポイントが指定されたシェイプの内側であるかどうかを決定します。
構文
AI.IsPointInsideGenericShape(position, shapeName[, checkHeight])
パラメーター
説明
position
チェックする位置。
shapeName
テストするシェイプの名前 (AI.GetEnclosingGenericShapeOfType で
返されます)。
checkHeight
(optional)
シェイプの高さをテストするかどうかを示すフラグ。(デフォルト
は false です)。true に設定した場合、テストで shape.aabb.min.z と
shape.aabb.min.z+shape.height 間の空間をチェックします。
Version 1.6
615
Lumberyard 開発者ガイド
ScriptBind_AI
IsPointInWaterRegion
ポイントが水リージョンにあるかどうかを決定します。
構文
AI.IsPointInWaterRegion(point)
水または地面のレベルを示す値を返します。0 より大きい値は水を意味します。
IsPunchableObjectValid
叩くことができるオブジェクトが有効かどうかを決定します。
構文
AI.IsPunchableObjectValid(userId, objectId, origPos)
パラメーター
説明
userId.
ユーザー ID
objectId.
オブジェクト ID。
origPos.
ワールドでのオブジェクトの位置。
IsTakingCover
構文
AI.IsTakingCover(entityId, [distanceThreshold])
指定されたエージェントが遮へい物に隠れているか遮へい物に向かって走っている場合は true を返し
ます。それ以外の場合は nil を返します。
パラメーター
説明
entityId
AI のエンティティ。
distanceThreshold. (オプション) 遮へい物に向かって走っているエージェントがまた遮へい物
に隠れていないと考えられる距離。
LoadBehaviors
構文
AI.LoadBehaviors(const char* folderName, const char* extension)
LogComment
デバッグ用に追加情報をログに書き込みます。
Version 1.6
616
Lumberyard 開発者ガイド
ScriptBind_AI
構文
AI.LogComment(szMessage)
パラメーター
説明
szMessage
ログに書き込むメッセージ。
LogEvent
デバッグ用にイベント駆動型情報をログに書き込みます。イベントは、フレーム単位で発生する場合
も AI 更新ベースで発生する場合もあります。
構文
AI.LogEvent(szMessage)
パラメーター
説明
szMessage
ログに書き込むメッセージ。
LogProgress
ログに進行状況メッセージを書き込みます。
構文
AI.LogProgress(szMessage)
パラメーター
説明
szMessage
ログに書き込むメッセージ。
MeleePunchableObject
構文
AI.MeleePunchableObject(entityId, objectId, origPos)
パラメーター
説明
entityId
AI エンティティの ID。
objectId
オブジェクト ID。
Version 1.6
617
Lumberyard 開発者ガイド
ScriptBind_AI
パラメーター
説明
origPos
近接戦闘で叩くことができるオブジェクトの位置。
ModifySmartObjectStates
選択されたエンティティのスマートオブジェクトの状態を追加または削除します。
構文
AI.ModifySmartObjectStates(entityId, listStates)
パラメーター
説明
entityId
エンティティの ID。
listStates
追加または削除する状態名のリスト (「Closed, Locked」、「Open,
Unlocked, Busy」など)。
ParseTables
構文
AI.ParseTables(int firstTable, bool parseMovementAbility, IFunctionHandler*
pH, AIObjectParams& aiParams, bool& updateAlways)
パラメーター
説明
firstTable
プロパティのテーブル。
parseMovementAbility移動能力を解析するには true、それ以外の場合は false。
aiParams
AI パラメーター。
updateAlways
常に更新する場合は true、それ以外の場合は false。
PlayCommunication
AI エージェントの通信を再生します。
構文
AI.PlayCommunication(ScriptHandle entityId, const char* commName, const char*
channelName, float contextExpiry)
パラメーター
説明
entityId
エンティティの ID。
commName
再生する通信の名前。
Version 1.6
618
Lumberyard 開発者ガイド
ScriptBind_AI
パラメーター
説明
channelName
通信を再生するチャネルの名前。
PlayReadabilitySound
AI エージェントで読み上げ音声を再生します。これを呼び出すと、シグナルを使用して読み上げを再
生するようなフィルタリングを使用しません。
構文
AI.PlayReadabilitySound(entityId, soundName)
パラメーター
説明
entityId
エンティティの ID。
soundName
再生する読み上げ音声シグナルの名前。
stopPreviousSounds 現在再生されている読み上げがこのために停止される場合は true。
(Optional)
responseDelayMin
(Optional)
再生する応答読み上げの最小 (または最大がない場合は正確な) 遅延。
repsonseDelayMax
(Optional)
再生する応答読み上げの最大遅延。
ProcessBalancedDamage
プロセスによって分散されるダメージ。
構文
AI.ProcessBalancedDamage(pShooterEntity, pTargetEntity, damage, damageType)
パラメーター
説明
pShooterEntity
射撃者 ID。
pTargetEntity
ターゲット ID.
damage
ヒットダメージ。
damageType
ヒットダメージのタイプ。
QueueBubbleMessage
構文
AI.QueueBubbleMessage(ScriptHandle entityID, const char* message)
Version 1.6
619
Lumberyard 開発者ガイド
ScriptBind_AI
RecComment
AI Debug Recorder を使用してコメントを記録します。AI Debug Recorder については、「AI Debug
Recorder の使用」を参照してください。
構文
AI.RecComment(szMessage)
パラメーター
説明
szMessage
レコーダービューに表示されるメッセージ行。
RegisterDamageRegion
ダメージが発生する球形リージョンを登録します (パス探索で避ける必要があります)。所有者のエン
ティティの位置がリージョンの中心として使用されます。この関数は、リージョンの位置を更新する
ために複数回呼び出されます。
構文
AI.RegisterDamageRegion(entityId, radius)
パラメーター
説明
entityId
エンティティの ID。
radius
球形リージョンの半径。ゼロ以下の場合、リージョンは無効です。
RegisterInterestedActor
対象システムを持つ対象アクターを登録します。エラーが発生するとエラーログに記録されます。
構文
AI.RegisterInterestedActor(ScriptHandle entityId, float fInterestFilter,
float fAngleInDegrees)
有効な更新が実行された場合は true を返します。それ以外の場合は nil です。対象システムが無効の
場合、またはパラメーターが無効の場合に nil を返すことがあります。
パラメーター
説明
entityId
AI エンティティの ID。
RegisterInterestingEntity
対象システムを持つ指定されたエンティティを登録します。エラーが発生するとエラーログに記録さ
れます。
構文
Version 1.6
620
Lumberyard 開発者ガイド
ScriptBind_AI
AI.RegisterInterestingEntity(ScriptHandle entityId, float radius, float
baseInterest, const char* actionName, Vec3 offset, float pause, int shared)
有効な更新が実行された場合は true を返します。それ以外の場合は nil です。対象システムが無効の
場合、またはパラメーターが無効の場合に nil を返すことがあります。
パラメーター
説明
entityId
エンティティの ID。
RegisterTacticalPointQuery
指定された戦術ポイントクエリのクエリ ID を取得します。
構文
AI.RegisterTacticalPointQuery(querySpecTable)
戻り値が > 0 – クエリが正常に解析された場合。0 – その他
パラメーター
説明
querySpecTable
クエリを指定するテーブル。詳細については、「AI タクティカルポイント
システム (p. 21)」を参照してください。
RegisterTargetTrack
ターゲットの選択に指定されたターゲット追跡設定を使用するように AI エンティティを登録します。
パラメーター ai_TargetTracking を "2" に設定する必要があります。
構文
AI.RegisterTargetTrack(entityId, configuration, targetLimit, classThreat)
登録が成功した場合に true を返します。
パラメーター
説明
entityId
エンティティの ID。
configuration
ターゲット追跡設定。
targetLimit
任意の指定時間 (0 から無限) に AI をターゲットできるエージェントの
数。
classThreat
(optional)
初期クラスの脅威値。
RemovePersonallyHostile
構文
Version 1.6
621
Lumberyard 開発者ガイド
ScriptBind_AI
AI.RemovePersonallyHostile(ScriptHandle entityID, ScriptHandle hostileID)
RequestAttack
リーダーがいるグループで、リーダーがグループに対して敵に対する攻撃動作をリクエストを発信で
きます。このリクエスト後、Cleader がリーダー攻撃アクション (CLeaderAction_Attack_*) を作
成する場合があります。
構文
AI.RequestAttack(entityId, unitProperties, attackTypeList [,duration])
パラメーター
説明
entityId
グループリーダーを決定するために使用する一意のエンティティ ID。
unitProperties
攻撃がリクエストされるユニットのプロパティタイプの以下の形式のバイ
ナリマスク。
UPR_* + UPR* (UPR_COMBAT_GROUND + UPR_COMBAT_FLIGHT)
ユニットのプロパティ UPR_* については、IAgent.h を参照してくださ
い。
attackTypeList
優先される攻撃戦略 (リーダーアクションサブタイプ) の優先順位リストを
含む Lua テーブル。リストは、次のような形式になります。
{LAS_*, LAS_*,..} (LAS_ATTACK_ROW,LAS_ATTACK_FLANK)
最初は Attack_row アクションを試み、失敗した場合は attack_flank をとる
ことを意味します。
LeaderActionSubtype (LAS_*) アクションタイプについては、IAgent.h
を参照してください。
duration
(optional)
最大持続時間 (秒) (デフォルトは 0)。
RequestToStopMovement
構文
AI.RequestToStopMovement(ScriptHandle entityId)
ResetAgentLookAtPos
指定されたエンティティの以前の AgentLookAtPos() の呼び出しをリセットします。
構文
AI.ResetAgentLookAtPos(entityId)
パラメーター
説明
entityId
エンティティの ID。
Version 1.6
622
Lumberyard 開発者ガイド
ScriptBind_AI
ResetAgentState
「lean」のようなエージェントの特定の状態をリセットします。
構文
AI.ResetAgentState(ScriptHandle entityId, const char * stateLabel)
nil を返します。
パラメーター
説明
entityId
AI エンティティの ID。
stateLabel
デフォルトにリセットする必要がある状態を説明する文字列。
ResetParameters
指定されたエンティティのすべてのパラメーターをリセットします。
構文
AI.ResetParameters(entityId, bProcessMovement, PropertiesTable,
PropertiesInstanceTable)
パラメーター
説明
entityId
パラメーターをリセットするエンティティの ID。
bProcessMovement
移動データをリセットする場合は true、それ以外の場合は false。
PropertiesTable
エンティティのプロパティを含む Lua テーブル。
PropertiesInstanceTable
インスタンス固有のエンティティプロパティを含む Lua テーブル。
ResetPersonallyHostiles
構文
AI.ResetPersonallyHostiles(ScriptHandle entityID, ScriptHandle hostileID)
ScaleFormation
指定されたエンティティのフォーメーション (ある場合) のスケール係数を変更します。
構文
AI.ScaleFormation(entityId, scale)
フォーメーションのスケーリングが成功した場合は true を返します。
Version 1.6
623
Lumberyard 開発者ガイド
ScriptBind_AI
パラメーター
説明
entityId
エンティティの ID。
scale
スケール係数。
SequenceBehaviorReady
構文
AI.SequenceBehaviorReady(ScriptHandle entityId)
SequenceInterruptibleBehaviorLeft
構文
AI.SequenceInterruptibleBehaviorLeft(ScriptHandle entityId)
SequenceNonInterruptibleBehaviorLeft
構文
AI.SequenceNonInterruptibleBehaviorLeft(ScriptHandle entityId)
SetAlarmed
エンティティを「perception alarmed」として設定します。
構文
AI.SetAlarmed(entityId)
SetAnimationTag
マネキンアニメーションのタグを設定します。
構文
AI.SetAnimationTag(ScriptHandle entityID, const char* tagName)
デフォルトの結果コードを返します (Lua では: ボイド)。
パラメーター
説明
entityId
アニメーションのタグを設定する AI エンティティの ID。
tagName
設定するアニメーションのタグ名 (大文字と小文字を区別しません)。
SetAssesmentMultiplier
指定された AIObject タイプに評価乗数係数を設定します。
Version 1.6
624
Lumberyard 開発者ガイド
ScriptBind_AI
構文
AI.SetAssesmentMultiplier(AIObjectType, multiplier)
パラメーター
説明
AIObjectType
AIObject のタイプ。AIObject タイプの完全なリストについては
ScriptBindAI.cpp を参照してください。
multiplier
評価乗数係数。
SetAttentiontarget
新しい注意ターゲットを設定します。
構文
AI.SetAttentiontarget(entityId, targetId)
パラメーター
説明
entityId
エンティティの ID。
targetId
ターゲットのエンティティ ID。
SetBeaconPosition
選択されたエンティティ/オブジェクトのグループのビーコン位置を設定します。
構文
AI.SetBeaconPosition(entityId | AIObjectName, pos)
パラメーター
説明
entityId |
AIObjectName
一意のエンティティ ID または AI オブジェクト名。
pos
ビーコン位置を設定するベクトル {x,y,z}。
SetBehaviorTreeEvaluationEnabled
構文
AI.SetBehaviorTreeEvaluationEnabled(ScriptHandle entityID, bool enable)
SetBehaviorVariable
指定されたアクターに動作変数を設定します。
Version 1.6
625
Lumberyard 開発者ガイド
ScriptBind_AI
構文
AI.SetBehaviorVariable(ScriptHandle entityId, const char* variableName, bool
value)
SetCollisionAvoidanceRadiusIncrement
構文
AI.SetCollisionAvoidanceRadiusIncrement(ScriptHandle entityId, float radius)
SetContinuousMotion
構文
AI.SetContinuousMotion(ScriptHandle entityID, bool continuousMotion)
SetCoverCompromised
構文
AI.SetCoverCompromised(entityId)
パラメーター
説明
entityId
AI エンティティの ID。
SetEntitySpeedRange
構文
AI.SetEntitySpeedRange(userEntityId, urgency, defaultSpeed, minSpeed,
maxSpeed, stance = all)
オペレーションが成功すると true、それ以外の場合は false を返します。
パラメー
ター
説明
usedEntityId
最後に使用したスマートオブジェクトが必要なユーザーのエンティティ ID。
urgency
移動の緊急性を指定する整数値
(AgentMovementSpeeds::EAgentMovementUrgency を参照)。
defaultSpeed
デフォルトの速度を指定する浮動小数点値。
minSpeed
最低速度を指定する浮動小数点値。
Version 1.6
626
Lumberyard 開発者ガイド
ScriptBind_AI
SetExtraPriority
指定された敵エンティティに追加の優先順位値を設定します。
構文
AI.SetExtraPriority(enemyEntityId, increment)
パラメーター
説明
enemyEntityId
エンティティの ID。
float increment
ターゲットの優先度に追加する値。
SetFactionOf
指定されたエンティティが属するファクションを設定します。
構文
AI.SetFactionOf(ScriptHandle entityID, const char* factionName)
パラメーター
説明
entityId
ファクションが返されるエンティティの ID。
factionName
指定されたエンティティに割り当てられるファクションの名前。
SetFactionThreatMultiplier
指定された種類の脅威の乗数係数を設定します。戻り値が 0 の場合、その種類が他のどの種類に対し
ても敵ではないことを示します。
構文
AI.SetFactionThreatMultiplier(nSpecies, multiplier)
SetFireMode
即座に射撃モードを設定します。
構文
AI.SetFireMode(entityId, mode)
パラメーター
説明
entityId
エンティティの ID。
firemode
新しい射撃モード。
Version 1.6
627
Lumberyard 開発者ガイド
ScriptBind_AI
SetFormationAngleThreshold
フォーメーション内の相対位置を設定します。
構文
AI.SetFormationAngleThreshold(entityId, fAngleThreshold)
パラメーター
説明
entityId
AI エンティティの ID。
fAngleThreshold
新しいリーダーの方向の角度を度数で出力します。
SetFormationLookingPoint
フォーメーション内の注視ポイントの相対位置を設定します。
構文
AI.SetFormationLookingPoint(entityId, v3RelativePosition)
パラメーター
説明
entityId
AI エンティティの ID。
v3RelativePosition 新しい相対注視ポイントを保存した {x,y,z} 形式のテーブル。
SetFormationPosition
フォーメーション内の相対位置を設定します。
構文
AI.SetFormationPosition(entityId, v2RelativePosition)
パラメーター
説明
entityId
AI エンティティの ID。
v2RelativePosition 新しい相対位置を保存した {x,y,z} 形式のテーブル。
SetFormationUpdate
指定されたエンティティのフォーメーション (ある場合) の更新フラグを設定します。このフラグが
false の場合、フォーメーションは更新されなくなります。
構文
AI.SetFormationUpdate(entityId, update)
Version 1.6
628
Lumberyard 開発者ガイド
ScriptBind_AI
リクエストが成功した場合に true を返します。
パラメーター
説明
entityId
エンティティの ID。
update
フラグを更新する場合は true、それ以外の場合は false。
SetFormationUpdateSight
指定されたエンティティのフォーメーション視界方向にランダムな角度のローテーションを設定しま
す。
構文
AI.SetFormationUpdateSight(entityId, range, minTime, maxTime)
パラメーター
説明
entityId
エンティティの ID。
range
デフォルトの視覚方向のローテーション角度 (0,360)。
minTime
(optional)
方向を変更する最小タイムスパン (デフォルト = 2)。
maxTime
(optional)
方向を変更する最小タイムスパン (デフォルト = minTime)。
SetIgnorant
指定された AI エンティティがシステムシグナル、視覚刺激、聴覚刺激を無視するように設定します。
構文
AI.SetIgnorant(entityId, ignorant)
パラメーター
説明
entityId
AI エンティティの ID。
ignorant
エンティティがシステムシグナルを無視するかどうかを示すフラグ。0 を
指定すると無視しません。1 を指定すると無視します。
SetInCover
構文
AI.SetInCover(entityId, bool inCover)
Version 1.6
629
Lumberyard 開発者ガイド
ScriptBind_AI
パラメーター
説明
entityId
AI エンティティの ID。
inCover
エンティティが遮へい物に隠れるように設定されるかどうかを指定しま
す。
SetLeader
指定されたエンティティをグループリーダーとして設定します。このアクションにより、CLeader オ
ブジェクトがエンティティと関連付けられます。存在しない場合は作成されます。リーダーはグルー
プごとに 1 人のみ設定できます。
構文
AI.SetLeader(entityID)
成功した場合に true を返します。
パラメーター
説明
entityID
リーダーとして設定されるエンティティの一意の ID。
SetMemoryFireType
AI エージェントがメモリターゲットに対する射撃を処理する方法を設定します。
構文
AI.SetMemoryFireType(entityId, type)
パラメーター
説明
entityId
エンティティの ID。
type
メモリ射撃タイプ。有効な値は IAgent.h の enum EMemoryFireType
からです。
eMFT_Disabled = 0,
// Never allowed to fire at
memory
eMFT_UseCoverFireTime,
// Can fire at memory using
the weapon's cover fire time
eMFT_Always,
// Always allowed to fire at
memory
SetMovementContext
指定されたエンティティの移動コンテキストを設定します。
構文
Version 1.6
630
Lumberyard 開発者ガイド
ScriptBind_AI
AI.SetMovementContext(ScriptHandle entityId, int context)
パラメーター
説明
entityId
エンティティの ID。
context
コンテキスト値。
SetPathAttributeToFollow
指定されたエンティティのパスの属性を設定します。
構文
AI.SetPathAttributeToFollow(entityId, flag)
パラメーター
説明
entityId
エンティティの ID。
flag
設定する属性。
SetPathToFollow
選択されたエンティティが従うパスを設定します。
構文
AI.SetPathToFollow(entityId, pathName)
パラメーター
説明
entityId
エンティティの ID。
pathName
従うパスの名前。
SetPFBlockerRadius
構文
AI.SetPFBlockerRadius(entityId, blocker, radius)
パラメーター
説明
entityId
エンティティの ID。
Version 1.6
631
Lumberyard 開発者ガイド
ScriptBind_AI
SetPointListToFollow
指定されたエンティティのパスのポイントリストを設定します。
構文
AI.SetPointListToFollow(entityId, pointlist, howmanypoints, bspline [,
navtype])
パラメーター
説明
entityId
エンティティの ID。
pointList
エンティティがたどるポイントのリストを一連のローカルベクトルで表わ
します。{{x=0.0, y=0.0, z=0.0},。
howmanypoints
リスト内のポイントの数。
bspline
スプライン補間を使用してパスラインを再計算するかどうかを示すフラ
グ。
navtype
(オプション) ナビゲーションタイプ (デフォルト =
IAISystem::NAV_FLIGHT).
SetPosturePriority
指定されたエンティティの姿勢の優先順位を設定します。
構文
AI.SetPosturePriority(ScriptHandle entityId, const char* postureName, float
priority)
SetPostures
指定されたエンティティの姿勢を設定します。
構文
AI.SetPostures(ScriptHandle entityId, SmartScriptTable postures)
パラメーター
説明
entityId
エンティティの ID。
postures
姿勢のテーブル。
SetRefPointAtDefensePos
指定されたエンティティの、エンティティの注意ターゲットと指定されたポイント間の中間距離への
参照ポイント位置を設定します。
Version 1.6
632
Lumberyard 開発者ガイド
ScriptBind_AI
構文
AI.SetRefPointAtDefensePos(entityId, point2defend, distance)
パラメーター
説明
entityId
エンティティの ID。
point2defend
防御するポイント。
distance
参照ポイントと防御するポイント間の最大距離。
SetRefPointDirection
指定されたエンティティの参照ポイント方向を設定します。
構文
AI.SetRefPointDirection(vRefPointDir)
パラメーター
説明
vRefPointDir
(スクリプト) ベクトルの (x,y,z) 値で表わされる方向。
SetRefPointPosition
指定されたエンティティの参照点の「ワールド」位置を設定します。
構文
AI.SetRefPointPosition(entityId, vRefPointPos)
パラメーター
説明
entityId
エンティティの ID。
vRefPointPos
(スクリプト) ベクトルの (x,y,z) 値で表わされるワールド位置。
SetRefPointRadius
指定されたエンティティの参照ポイント半径を設定します。
構文
AI.SetRefPointRadius(entityId, radius)
パラメーター
説明
entityId
エンティティの ID。
Version 1.6
633
Lumberyard 開発者ガイド
ScriptBind_AI
パラメーター
説明
radius
参照ポイントの半径。
SetRefpointToAnchor
アンカーに参照ポイントを設定します。
構文
AI.SetRefpointToAnchor(entityId, rangeMin, rangeMax, findType, findMethod)
パラメーター
説明
entityId
AI エンティティの ID。
rangeMin
最小範囲。
rangeMax
最大範囲。
findType
検索タイプ。
findMethod
検索方法。
SetRefpointToPunchableObject
叩くことができるオブジェクトに参照ポイントを設定します。
構文
AI.SetRefpointToPunchableObject(entityId, range)
パラメーター
説明
entityId
AI エンティティの ID。
range
叩くことができるオブジェクトの範囲。
SetRefShapeName
指定されたエンティティの参照シェイプの名前を設定します。
構文
AI.SetRefShapeName(entityId, name)
パラメーター
説明
entityId
エンティティの ID。
Version 1.6
634
Lumberyard 開発者ガイド
ScriptBind_AI
パラメーター
説明
name
参照シェイプの名前。
SetSmartObjectState
単一のスマートオブジェクトの状態を設定して、他のすべての状態を置き換えます。
構文
AI.SetSmartObjectState(entityId, stateName)
パラメーター
説明
entityId
エンティティの ID。
stateName
スマートオブジェクトに設定する新しい状態の名前 (「idle」など)。
SetSoundPerceptionDescriptor
選択されたエンティティが音声タイプを感知する方法についての情報を設定します。
構文
AI.SetSoundPerceptionDescriptor(entityId, soundType, descriptorTable)
情報が正常に保存された場合は true を返します。
パラメーター
説明
entityId
認識データを設定するエンティティ。
soundType
データを設定する音声刺激のタイプ。
descriptorTable
保存する認識データ。
SetSpeed
エンティティの現在の速度 (緊急度) を設定します。
構文
AI.SetSpeed(entityId, urgency)
パラメーター
説明
entityId
AI のエンティティ。
urgency
移動の緊急度を指定する浮動小数点値
(AgentMovementSpeeds::EAgentMovementUrgency を参照)。
Version 1.6
635
Lumberyard 開発者ガイド
ScriptBind_AI
SetStance
指定されたエンティティの体勢を設定します。
構文
AI.SetStance(entityId, stance)
パラメーター
説明
entityId
エンティティの ID。
stance
体勢の値 (STANCE_*)。
SetTargetTrackClassThreat
指定されたエンティティのターゲットの攻撃についてのクラス脅威を設定します。
構文
AI.SetTargetTrackClassThreat(entityId, classThreat)
パラメーター
説明
entityId
エンティティの ID。
classThreat
新しいクラス脅威値。
SetTempTargetPriority
指定されたエンティティの、ターゲット候補に対する一時的ターゲットの選択優先順位を設定しま
す。
構文
AI.SetTempTargetPriority(entityId, priority)
更新に成功した場合に true を返します。
パラメーター
説明
entityId
エンティティの ID。
priority
新しい優先順位値。
SetTerritoryShapeName
指定された AI エンティティのテリトリーシェイプを設定します。
Version 1.6
636
Lumberyard 開発者ガイド
ScriptBind_AI
構文
AI.SetTerritoryShapeName(entityId, shapeName)
パラメーター
説明
entityId
エンティティの ID。
shapeName
設定するシェイプの名前。
SetUnitProperties
ユニットの戦闘能力についてのリーダーの知識を設定します。リーダーはエンティティのグループ ID
に基づいて識別されます。
構文
AI.SetUnitProperties(entityId, unitProperties)
パラメーター
説明
entityId
エンティティの ID。
unitProperties
次の形式のユニットのプロパティのバイナリマスク。
UPR_* + UPR* (UPR_COMBAT_GROUND + UPR_COMBAT_FLIGHT)
UPR_* ユニットのプロパティについては、IAgent.h を参照してくださ
い。
SetUseSecondaryVehicleWeapon
車両のガンナーシートから射撃が可能な場合に、AI オブジェクトの補助火器の使用を有効または無効
にします。
構文
AI.SetUseSecondaryVehicleWeapon(entityId, bUseSecondary)
パラメーター
説明
entityId
エンティティの ID。
bUseSecondary
補助火器を使用するには true、それ以外の場合は false を指定します。
通知
同じテキストの別のシグナルが存在する場合で絵も、送信者のシグナルキューにシグナルを追加しま
す。
構文
Version 1.6
637
Lumberyard 開発者ガイド
ScriptBind_AI
AI.Signal(signalFilter, signalType, signalText, senderId [, signalExtraData])
パラメーター
説明
signalFilter
シグナルフィルタ。
signalType
シグナルタイプ。
signalText
テキストと同じ名前の Lua コールバック、または CAIObject で直接、レ
シーバーが処理するシグナルテキストです。
senderId
送信者の ID。
signalExtraData
オプション。追加データを含む Lua テーブル。以下のデータ型を含めるこ
とができます。
• point – 形式 {x,y,z} のベクトル。
• point2 – 形式 {x,y,z} のベクトル。
• ObjectName – 文字列。
• id – エンティティ ID。
• fValue – 浮動小数点値。
• iValue – 整数値。
• iValue2 – 2 番目の整数値。
SmartObjectEvent
スマートアクションを実行します。
構文
AI.SmartObjectEvent(actionName, userEntityId, objectEntityId [, vRefPoint])
スマートオブジェクトのルールが見つからないか、アクションを実行する際にゼロ以外の ID が挿入さ
れた場合は 0 を返します。
パラメーター
説明
actionName
スマートアクションの名前。
usedEntityId
スマートアクションを実行するユーザーのエンティティ ID。ユーザーが不
明な場合はなし。
objectEntityId
スマートアクションが実行されるオブジェクトのエンティティ ID。オブ
ジェクトが不明な場合はなし。
vRefPoint
オプション。ユーザーの注意ターゲット位置の代わりに使用される参照ポ
イント。
SoundEvent
AI システムの指定されたパラメーターを使用して音声イベントを生成します。
構文
Version 1.6
638
Lumberyard 開発者ガイド
ScriptBind_AI
AI.SoundEvent(position, radius, threat, interest, entityId)
パラメーター
説明
position
音声イベントの原点。
radius
音声イベントを効くことができるエリア。
threat
音声イベントのプロパティ。
interest
音声イベントのプロパティ。
entityId
音声イベントを生成する一意のエンティティ ID。
StopCommunication
指定された通信を停止します。
構文
AI.StopCommunication(ScriptHandle playID)
パラメーター
説明
playID
停止する通信の ID。
手榴弾を投げる
射撃モードを中断せずに手榴弾をターゲットタイプに対して投げます。
構文
AI.ThrowGrenade(entityId, grenadeType, regTargetType)
パラメーター
説明
entityId
エンティティの ID。
grenadeType
リクエストされた手榴弾の種類 (ERequestedGrenadeType を参照)。
regTargetType
手榴弾のターゲットタイプ (see AI_REG_*)。
UnregisterInterestedActor
対象システムを持つエンティティを登録解除します。エラーはエラーログに記録されます。
構文
AI.UnregisterInterestedActor(ScriptHandle entityId)
Version 1.6
639
Lumberyard 開発者ガイド
ScriptBind_AI
パラメーター
説明
entityId
エンティティの ID。
UnregisterInterestingEntity
対象システムを持つ指定されたエンティティを登録解除します。エラーはエラーログに記録されま
す。
構文
AI.UnregisterInterestingEntity(ScriptHandle entityId)
パラメーター
説明
entityId
エンティティの ID。
UnregisterTargetTrack
ターゲット追跡マネージャーから AI オブジェクトを登録解除します。パラメーター
ai_TargetTracking を "2" に設定する必要があります。
構文
AI.UnregisterTargetTrack(entityId)
登録解除が成功した場合に true を返します。
パラメーター
説明
entityId
エンティティの ID。
UpdateGlobalPerceptionScale
構文
AI.UpdateGlobalPerceptionScale(float visualScale, float audioScale)
UpdateTempTarget
指定されたエンティティの一時ターゲット候補の位置を更新します。
構文
AI.UpdateTempTarget(entityId, vPos)
更新に成功した場合に true を返します。
Version 1.6
640
Lumberyard 開発者ガイド
ScriptBind_AI
パラメーター
説明
entityId
エンティティの ID。
vPos
一時ターゲットの新しい位置。
UpTargetPriority
指定されたターゲットが指定されたエンティティのターゲットリストにある場合、ターゲットに対す
るエンティティのターゲット優先順位値を変更します。
構文
AI.UpTargetPriority(entityId, targetId, increment)
パラメーター
説明
entityId
エンティティの ID。
targetId
ターゲットのエンティティ ID。
increment
ターゲットの優先順位の新しい値。
VisualEvent
AI システムの指定されたパラメーターを使用して視覚イベントを生成します。
構文
AI.VisualEvent(entityId, targetId)
パラメーター
説明
entityId
視覚イベントを受け取るエンティティの ID。
targetId
視覚ターゲット (エンティティが見ている) の ID。
警告
データまたはスクリプトのエラーに関するログを警告メッセージに書き込みます。
構文
AI.Warning(szMessage)
パラメーター
説明
szMessage
ログに書き込むメッセージ。
Version 1.6
641
Lumberyard 開発者ガイド
ScriptBind_Entity
ScriptBind_Entity
エンティティ関連 Lua スクリプトに依存する関数の一覧です。
有効化
エンティティをアクティブ化または非アクティブ化します。Activate は更新ポリシーを無視し、エ
ンティティを強制的にアクティブ化または非アクティブ化します。実行中のすべてのエンティティ
は、フレームごとに更新されます。
Warning
アクティブなエンティティが多すぎると、パフォーマンスに影響を与えることあります。
構文
Entity.Activate(int bActive)
パラメーター
パラメーター
説明
bActive
エンティティをアクティブにするには true、非
アクティブにするには false を指定します。
ActivateOutput
構文
Entity.ActivateOutput()
ActivatePlayerPhysics
構文
Entity.ActivatePlayerPhysics(bool bEnable)
AddConstraint
構文
Entity.AddConstraint()
AddImpulse
エンティティに衝撃を適用します。線形力積を加えるには、少なくとも 4 つのパラメーターが必要で
す。その他の角力積の場合は、少なくとも 7 つのパラメーターを指定する必要があります。
構文
Entity.AddImpulse(ipart, position, direction, linearImpulse,
linearImpulseScale, angularAxis, angularImpulse, massScale)
Version 1.6
642
Lumberyard 開発者ガイド
ScriptBind_Entity
パラメーター
パラメーター
説明
ipart
衝撃を受けるパートのインデックス。
position
衝撃が適用されるポイント (ワールド座標)。ここを (0、0、0) に設定すると、
無視されます。
direction
衝撃が適用される方向。
linearImpulse
線形力積の力。
linearImpulseScale
線形力積のスケーリング。(デフォルト: 1.0)
angularAxis
角力積が適用される軸。
angularImpulse 角力積の力。
massScale
角力積の質量スケーリング。(デフォルト: 1.0)
AttachChild
構文
Entity.AttachChild(ScriptHandle childEntityId, int flags)
AttachSurfaceEffect
構文
Entity.AttachSurfaceEffect(int nSlot, const char *effect, bool countPerUnit,
const char *form, const char *typ, float countScale, float sizeScale)
AuxAudioProxiesMoveWithEntity
AuxAudioProxies がエンティティとともに移動するかどうかを設定します。
構文
Entity.AuxAudioProxiesMoveWithEntity(bool const bCanMoveWithEntity)
戻り値: nil
パラメーター
パラメーター
説明
bCanMoveWithEntity
有効または無効にするブール型パラメーター
AwakeCharacterPhysics
構文
Version 1.6
643
Lumberyard 開発者ガイド
ScriptBind_Entity
Entity.AwakeCharacterPhysics(int nSlot,const char *sRootBoneName,int nAwake)
AwakeEnvironment
構文
Entity.AwakeEnvironment()
AwakePhysics
構文
Entity.AwakePhysics(int nAwake)
BreakToPieces
スロット 0 の静的ジオメトリをサブオブジェクトに分割してパーティクルまたはエンティティとして
スポーンさせます。
構文
Entity.BreakToPieces(int nSlot, int nPiecesSlot, float fExplodeImp, Vec3
vHitPt, Vec3 vHitImp, float fLifeTime, bool bSurfaceEffects)
CalcWorldAnglesFromRelativeDir
構文
Entity.CalcWorldAnglesFromRelativeDir(Vec3 dir)
CancelSubpipe
構文
Entity.CancelSubpipe()
ChangeAttachmentMaterial
構文
Entity.ChangeAttachmentMaterial(const char *attachmentName, const char
*materialName)
CharacterUpdateAlways
構文
Entity.CharacterUpdateAlways(int characterSlot, bool updateAlways)
Version 1.6
644
Lumberyard 開発者ガイド
ScriptBind_Entity
CharacterUpdateOnRender
構文
Entity.CharacterUpdateOnRender(int characterSlot, bool bUpdateOnRender)
CheckCollisions
構文
Entity.CheckCollisions()
CheckShaderParamCallbacks
エンティティの現在の状態でレンダープロキシにある現在設定されているすべてのシェーダーパラ
メーターのコールバックを確認します。
構文
Entity.UpdateShaderParamCallback()
CloneMaterial
スロットのマテリアルをマテリアルのクローンされたバージョンで置き換えます。クローンされたマ
テリアルはこのエンティティ専用に自由に変更できます。
構文
Entity.CloneMaterial(int slot)
パラメーター
パラメーター
説明
slot
マテリアルをクローンするスロットの ID。
sSubMaterialName
ここが空の文字列以外の場合、固有のサブマテ
リアルがクローンされます。
CopySlotTM
スロットの TM (変換マトリックス) をコピーします。
構文
Entity.CopySlotTM(int destSlot, int srcSlot, bool includeTranslation)
パラメーター
パラメーター
説明
destSlot
宛先スロットの識別子。
Version 1.6
645
Lumberyard 開発者ガイド
ScriptBind_Entity
パラメーター
説明
srcSlot
ソーススロットの識別子。
includeTranslation
変換方法を含める場合は true、そうでない場合
は false。
CountLinks
エンティティのすべての出力リンクをカウントします。
構文
Entity.CountLinks()
戻り値: 出力リンクの数。
CreateAuxAudioProxy
EntityAudioProxy で管理される追加の AudioProxy を作成します。作成された AuxAudioProxy は、親
EntityAudioProxy とともに移動および回転します。
構文
Entity.CreateAuxAudioProxy()
戻り値: 追加で作成された AudioProxy の ID を返します。
CreateBoneAttachment
構文
Entity.CreateBoneAttachment(int characterSlot, const char *boneName, const
char *attachmentName)
CreateCameraComponent
エンティティのカメラコンポーネントを作成します。エンティティが、エンティティに割り当てられ
たマテリアルのカメラソースとして使用できるようになります。
構文
Entity.CreateCameraComponent()
CreateDRSProxy
動的レスポンスシステムプロキシを作成します
構文
Entity.CreateDRSProxy()
Version 1.6
646
Lumberyard 開発者ガイド
ScriptBind_Entity
戻り値: 作成したプロキシの ID を返します。
CreateLink
このエンティティに対する新しい出力リンクを作成します。
構文
Entity.CreateLink(const char *name)
戻り値: なし
パラメーター
パラメーター
説明
name
リンクの名前。このエンティティのすべてのリ
ンクで一意である必要はありません。同じ名前
の複数のリンクが共存できます。
(optional) targetId
指定した場合、リンクが対象にするエンティ
ティの ID。指定されない場合または 0 の場合
は、リンクは何も対象にしません。デフォルト
値: 0
CreateRenderComponent
エンティティのレンダリングコンポーネントオブジェクトを作成します。アセットをロードせずすぐ
にエンティティをレンダリングできます。
構文
Entity.CreateRenderComponent()
CreateSkinAttachment
構文
Entity.CreateSkinAttachment(int characterSlot, const char *attachmentName)
Damage
構文
Entity.Damage()
DeleteParticleEmitter
3dengine からパーティクルのエミッタを削除します。
構文
Version 1.6
647
Lumberyard 開発者ガイド
ScriptBind_Entity
Entity.DeleteParticleEmitter(int slot)
パラメーター
パラメーター
説明
slot
スロット番号
DeleteThis
現在のエンティティを削除します。
構文
Entity.DeleteThis()
DestroyAttachment
構文
Entity.DestroyAttachment(int characterSlot, const char *attachmentName)
DestroyPhysics
構文
Entity.DestroyPhysics()
DetachAll
構文
Entity.DetachAll()
DetachThis
構文
Entity.DetachThis()
DisableAnimationEvent
構文
Entity.DisableAnimationEvent(int nSlot,const char *sAnimation)
DrawSlot
エンティティの指定スロットでオブジェクトまたはキャラクターの描画を有効/無効にします。
Version 1.6
648
Lumberyard 開発者ガイド
ScriptBind_Entity
構文
Entity.DrawSlot(int nSlot,int nEnable)
パラメーター
パラメーター
説明
nSlot
スロット識別子。
nEnable
1 - 描画を有効にする、0 - 描画を無効にする。
EnableBoneAnimation
構文
Entity.EnableBoneAnimation(int characterSlot, int layer, const char
*boneName, bool status)
EnableBoneAnimationAll
構文
Entity.EnableBoneAnimationAll(int characterSlot, int layer, bool status)
EnableDecals
デカールを有効にします。
構文
Entity.EnableDecals(int slot, bool enable)
EnableInheritXForm
エンティティで親からの変形の継承を有効/無効にします。
構文
Entity.EnableInheritXForm(bool bEnable)
EnableMaterialLayer
構文
Entity.EnableMaterialLayer(bool enable, int layer)
EnablePhysics
構文
Version 1.6
649
Lumberyard 開発者ガイド
ScriptBind_Entity
Entity.EnablePhysics(bool bEnable)
EnableProceduralFacialAnimation
構文
Entity.EnableProceduralFacialAnimation(bool enable)
ExecuteAudioTrigger
指定された音声トリガーを実行し、エンティティにアタッチします。作成された音声オブジェクトは
エンティティとともに移動および回転します。
構文
Entity.ExecuteAudioTrigger(ScriptHandle const hTriggerID, ScriptHandle const
hAudioProxyLocalID)
戻り値: nil
パラメーター
パラメーター
説明
hTriggerID
音声トリガー ID のハンドル
hAudioProxyLocalID
EntityAudioProxy 専用の AuxAudioProxy の
ID。デフォルトの AuxAudioProxy を指定する
には、1 を渡します。すべての AuxAudioProxy
インスタンスを指定するには、0 を渡します。
FadeGlobalDensity
フェードのグローバル密度を設定します。
構文
Entity.FadeGlobalDensity(int nSlot, float fadeTime, float newGlobalDensity)
パラメーター
パラメーター
説明
nSlot
nSlot 識別子。
fadeTime
newGlobalDensity
ForceCharacterUpdate
構文
Version 1.6
650
Lumberyard 開発者ガイド
ScriptBind_Entity
Entity.ForceCharacterUpdate(int characterSlot, bool updateAlways)
ForwardTriggerEventsTo
構文
Entity.ForwardTriggerEventsTo(ScriptHandle entityId)
FreeAllSlots
エンティティの各スロットパートのすべてのオブジェクトを削除します。
構文
Entity.FreeAllSlots()
FreeSlot
指定されたスロットからのオブジェクトをすべて削除します。
構文
Entity.FreeSlot(int nSlot)
パラメーター
パラメーター
説明
nSlot
スロット識別子。
GetAIName
構文
Entity.GetAIName()
GetAllAuxAudioProxiesID
親 EntityAudioProxy のすべての AuxAudioProxy を指すために使用される ID を返します。
構文
Entity.GetAllAuxAudioProxiesID()
戻り値: 親 EntityAudioProxy のすべての AuxAudioProxy を指すために使用される ID を返します。
GetAngles
エンティティの角度を取得します。
Version 1.6
651
Lumberyard 開発者ガイド
ScriptBind_Entity
構文
Entity.GetAngles()
GetAnimationLength
構文
Entity.GetAnimationLength(int characterSlot, const char *animation)
GetAnimationTime
構文
Entity.GetAnimationTime(int nSlot,int nLayer)
GetArchetype
エンティティのアーキタイプを取得します。
構文
Entity.GetArchetype()
戻り値: エンティティアーキタイプの名前。アーキタイプがない場合は nil。
GetAttachmentBone
構文
Entity.GetAttachmentBone(int characterSlot, const char *attachmentName)
GetAttachmentCGF
構文
Entity.GetAttachmentCGF(int characterSlot, const char *attachmentName)
GetBoneAngularVelocity
構文
Entity.GetBoneAngularVelocity(int characterSlot, const char *boneName)
GetBoneDir
構文
Entity.GetBoneDir()
Version 1.6
652
Lumberyard 開発者ガイド
ScriptBind_Entity
GetBoneLocal
構文
Entity.GetBoneLocal(const char *boneName, Vec3 trgDir)
GetBoneNameFromTable
構文
Entity.GetBoneNameFromTable()
GetBonePos
構文
Entity.GetBonePos()
GetBoneVelocity
構文
Entity.GetBoneVelocity(int characterSlot, const char *boneName)
GetCenterOfMassPos
エンティティの重心の位置を取得します。
構文
Entity.GetCenterOfMassPos()
GetCharacter
指定されたスロットにキャラクターがあれば、それを取得します。
構文
Entity.GetCharacter(int nSlot)
GetChild
構文
Entity.GetChild(int nIndex)
GetChildCount
構文
Version 1.6
653
Lumberyard 開発者ガイド
ScriptBind_Entity
Entity.GetChildCount()
GetCurAnimation
構文
Entity.GetCurAnimation()
GetDefaultAuxAudioProxyID
親 EntityAudioProxy のデフォルト AudioProxy の ID を返します。
構文
Entity.GetDefaultAuxAudioProxyID()
戻り値: 親 EntityAudioProxy のデフォルト AudioProxy の ID を返します。
GetDirectionVector
構文
Entity.GetDirectionVector()
GetDistance
構文
float Entity.GetDistance(entityId)
戻り値: entityId/ で指定されたエンティティからの距離
GetEntitiesInContact
構文
Entity.GetEntitiesInContact()
GetEntityMaterial
構文
Entity.GetEntityMaterial()
GetExplosionImpulse
構文
Entity.GetExplosionImpulse()
Version 1.6
654
Lumberyard 開発者ガイド
ScriptBind_Entity
GetExplosionObstruction
構文
Entity.GetExplosionObstruction()
GetFlags
構文
Entity.GetFlags()
GetFlagsExtended
構文
Entity.GetFlagsExtended()
GetGeomCachePrecachedTime
現在の再生位置からフレーム再生の準備ができている最後尾までの時間差分を取得します。
構文
Entity.GetGeomCachePrecachedTime()
GetGravity
構文
Entity.GetGravity()
GetHelperAngles
構文
Entity.GetHelperAngles()
GetHelperDir
構文
Entity.GetHelperDir()
GetHelperPos
構文
Entity.GetHelperPos()
Version 1.6
655
Lumberyard 開発者ガイド
ScriptBind_Entity
GetLink
指定されたインデックスにあるリンクを返します。
構文
Entity.GetLink()
戻り値: i 番目のリンクが対象とするエンティティのスクリプトテーブル。指定されたインデックスが
範囲外の場合は nil。
パラメーター
パラメーター
説明
ith
返されるリンクのインデックス。
GetLinkName
指定された ID のエンティティを対象としているリンクの名前を返します。
構文
Entity.GetLinkName(ScriptHandle targetId)
戻り値: 指定されたエンティティを対象としている i 番目のリンクの名前。そのようなリンクが存在し
ない場合は nil。
パラメーター
パラメーター
説明
targetId
リンク名を参照するエンティティの ID。
(optional) ith
指定した場合、指定されたエンティティを対象
とする i 番目のリンク。デフォルト値: 0 (1 番目
のエンティティ)
GetLinkTarget
指定されたリンクが対象にしているエンティティの ID を返します。
構文
Entity.GetLinkTarget(const char *name)
戻り値: リンクが対象にしているエンティティの ID。そのようなリンクが存在しない場合は nil。
パラメーター
パラメーター
説明
name
リンクの名前。
Version 1.6
656
Lumberyard 開発者ガイド
ScriptBind_Entity
パラメーター
説明
(optional) ith
指定した場合、参照する対象エンティティとし
て指定された名前を持つ i 番目のリンク。デフォ
ルト値: 0 (指定された名前を持つ 1 番目のリン
ク)
GetLocalAngles
構文
Vec3 Entity.GetLocalAngles(vAngles)
GetLocalBBox
構文
Entity.GetLocalBBox()
GetLocalPos
構文
Vec3 Entity.GetLocalPos()
GetLocalScale
構文
float Entity.GetLocalScale()
GetLodRatio
構文
Entity.GetLodRatio()
GetMass
構文
Entity.GetMass()
GetMaterial
構文
Entity.GetMaterial()
Version 1.6
657
Lumberyard 開発者ガイド
ScriptBind_Entity
GetMaterialFloat
マテリアルのパラメーターを変更します。
構文
Entity.GetMaterialFloat(int slot,int nSubMtlId,const char *sParamName)
戻り値: マテリアルのパラメーター値。
パラメーター
パラメーター
説明
slot
そのスロットのマテリアル ID を変更するスロッ
トの ID。
nSubMtlId
ID でサブマテリアルを指定します。
sParamName
マテリアルのパラメーターの名前。
GetMaterialVec3
構文
Entity.GetMaterialVec3(int slot,int nSubMtlId,const char *sParamName)
GetName
構文
Entity.GetName()
GetParent
構文
Entity.GetParent()
GetParentSlot
構文
Entity.GetParentSlot(int child)
GetPhysicalStats
追加の関連する物理演算。
構文
Version 1.6
658
Lumberyard 開発者ガイド
ScriptBind_Entity
Entity.GetPhysicalStats()
GetPos
エンティティの位置を取得します。
構文
Entity.GetPos()
GetProjectedWorldBBox
構文
Entity.GetProjectedWorldBBox()
GetRawId
raw 数値形式の entityId を返します。
構文
Entity.GetRawId()
GetScale
エンティティのスケーリング値を取得します。
構文
Entity.GetScale()
GetSlotAngles
スロットの角度を取得します。
構文
Entity.GetSlotAngles(int nSlot)
パラメーター
パラメーター
説明
nSlot
nSlot 識別子。
GetSlotCount
スロットの数を取得します。
Version 1.6
659
Lumberyard 開発者ガイド
ScriptBind_Entity
構文
Entity.GetSlotCount()
GetSlotHelperPos
構文
Entity.GetSlotHelperPos(int slot, const char *helperName, bool objectSpace)
GetSlotPos
スロットの位置を取得します。
構文
Entity.GetSlotPos(int nSlot)
パラメーター
パラメーター
説明
nSlot
nSlot 識別子。
GetSlotScale
スロットのスケール量を取得します。
構文
Entity.GetSlotScale(int nSlot)
パラメーター
パラメーター
説明
nSlot
nSlot 識別子。
GetSlotWorldDir
スロットのワールド方向を取得します。
構文
Entity.GetSlotWorldDir(int nSlot)
パラメーター
パラメーター
説明
nSlot
スロット識別子。
Version 1.6
660
Lumberyard 開発者ガイド
ScriptBind_Entity
GetSlotWorldPos
スロットのワールド位置を取得します。
構文
Entity.GetSlotWorldPos(int nSlot)
パラメーター
パラメーター
説明
nSlot
スロット識別子。
GetSpeed
構文
Entity.GetSpeed()
GetState
構文
Entity.GetState()
GetSubmergedVolume
構文
Entity.GetSubmergedVolume(int slot, Vec3 planeNormal, Vec3 planeOrigin)
GetTimeOfDayHour
構文
Entity.GetTimeOfDayHour()
戻り値: 浮動小数点値での現在の時刻。
GetTimeSinceLastSeen
構文
Entity.GetTimeSinceLastSeen()
GetTouchedPoint
剛体の衝突ポイントを取得します。
Version 1.6
661
Lumberyard 開発者ガイド
ScriptBind_Entity
構文
Entity.GetTouchedPoint()
GetTouchedSurfaceID
構文
Entity.GetTouchedSurfaceID()
GetTriggerBBox
構文
Entity.GetTriggerBBox()
GetUpdateRadius
構文
Entity.GetUpdateRadius()
GetVelocity
構文
Entity.GetVelocity()
GetVelocityEx
構文
Entity.GetVelocityEx()
GetViewDistanceMultiplier
ビュー距離の乗数を取得します。
構文
Entity.GetViewDistanceMultiplier()
GetVolume
構文
Entity.GetVolume(int slot)
Version 1.6
662
Lumberyard 開発者ガイド
ScriptBind_Entity
GetWorldAngles
構文
Vec3 Entity.GetWorldAngles(vAngles)
GetWorldBBox
構文
Entity.GetWorldBBox()
GetWorldBoundsCenter
エンティティのワールド bbox の中心を取得します (bbox が存在しない場合はエンティティ位置がデ
フォルト)。
構文
Entity.GetWorldBoundsCenter()
GetWorldDir
構文
Vec3 Entity.GetWorldDir()
GetWorldPos
構文
Vec3 Entity.GetWorldPos()
GetWorldScale
構文
float Entity.GetWorldScale()
GotoState
構文
Entity.GotoState(const char *sState)
HasFlags
構文
Version 1.6
663
Lumberyard 開発者ガイド
ScriptBind_Entity
Entity.HasFlags(int flags)
HasFlagsExtended
構文
Entity.HasFlagsExtended(int flags)
Hide
構文
Entity.Hide()
HideAllAttachments
構文
Entity.HideAllAttachments(int characterSlot, bool hide, bool hideShadow)
HideAttachment
構文
Entity.HideAttachment(int characterSlot, const char *attachmentName, bool
hide, bool hideShadow)
HideAttachmentMaster
構文
Entity.HideAttachmentMaster(int characterSlot, bool hide)
IgnorePhysicsUpdatesOnSlot
スロットの位置を更新するときに物理演算を無視します。
構文
Entity.IgnorePhysicsUpdatesOnSlot(int nSlot)
パラメーター
パラメーター
説明
nSlot
スロット識別子。
InsertSubpipe
構文
Version 1.6
664
Lumberyard 開発者ガイド
ScriptBind_Entity
Entity.InsertSubpipe()
IntersectRay
構文
Entity.IntersectRay(int slot, Vec3 rayOrigin, Vec3 rayDir, float maxDistance)
InvalidateTrigger
構文
Entity.InvalidateTrigger()
IsActive
エンティティのアクティブステータスを取得します。
構文
Entity.IsActive(bActivate)
戻り値: true - エンティティはアクティブです。false - エンティティはアクティブではありません。
IsAnimationRunning
構文
Entity.IsAnimationRunning(int characterSlot, int layer)
戻り値: nil または not nil
パラメーター
パラメーター
説明
characterSlot
キャラクタースロットのインデックス。
layer
アニメーションレイヤーのインデックス。
IsColliding
構文
Entity.IsColliding()
IsEntityInside
構文
Version 1.6
665
Lumberyard 開発者ガイド
ScriptBind_Entity
float Entity.IsEntityInside(entityId)
IsEntityInsideArea
構文
Entity.IsEntityInsideArea(int areaId, ScriptHandle entityId)
IsFromPool
エンティティがエンティティプールからのものである場合に戻ります。
構文
Entity.IsFromPool()
戻り値: true - エンティティはプールからです。(ブックマーク付き) false - エンティティはプールから
ありません。(ブックマークなし)
IsGeomCacheStreaming
構文
Entity.IsGeomCacheStreaming()
戻り値: geom のキャッシュがストリーミングであれば true。
IsHidden
構文
Entity.IsHidden()
IsInState
構文
Entity.IsInState(const char *sState)
IsPointInsideArea
構文
Entity.IsPointInsideArea(int areaId, Vec3 point)
IsSlotCharacter
スロットがキャラクターかどうかを確認します。
Version 1.6
666
Lumberyard 開発者ガイド
ScriptBind_Entity
構文
Entity.IsSlotCharacter(int slot)
パラメーター
パラメーター
説明
slot
スロット識別子。
IsSlotGeometry
スロットがジオメトリかどうかを確認します。
構文
Entity.IsSlotGeometry(int slot)
パラメーター
パラメーター
説明
slot
スロット識別子。
IsSlotLight
スロットがライトかどうかを確認します。
構文
Entity.IsSlotLight(int slot)
パラメーター
パラメーター
説明
slot
スロット識別子。
IsSlotParticleEmitter
スロットがパーティクルエミッタかどうかを確認します。
構文
Entity.IsSlotParticleEmitter(int slot)
パラメーター
パラメーター
説明
slot
スロット識別子。
Version 1.6
667
Lumberyard 開発者ガイド
ScriptBind_Entity
IsSlotValid
スロットが有効かどうかを確認します。
構文
Entity.IsSlotValid(int nSlot)
パラメーター
パラメーター
説明
nSlot
スロット識別子。
IsUsingPipe
構文
Entity.IsUsingPipe()
戻り値: エンティティが goalpipe を実行しているか goalpipe が挿入されている場合は true、それ以外
は false。
KillTimer
構文
Entity.KillTimer()
LoadCharacter
エンティティスロットに CGF ジオメトリをロードします。
構文
Entity.LoadCharacter(int nSlot,const char *sFilename)
パラメーター
パラメーター
説明
nSlot
スロット識別子。
sFilename
CGF ジオメトリのファイル名。
LoadCloud
エンティティスロットにクラウド XML ファイルをロードします。
構文
Entity.LoadCloud(int nSlot, const char *sFilename)
Version 1.6
668
Lumberyard 開発者ガイド
ScriptBind_Entity
パラメーター
パラメーター
説明
nSlot
スロット識別子。
sFilename
Filename.
LoadFogVolume
エンティティスロットに霧のボリュームの XML ファイルをロードします。
構文
Entity.LoadFogVolume(int nSlot, SmartScriptTable table)
パラメーター
パラメーター
説明
nSlot
スロット識別子。
table
霧のボリュームのプロパティがあるテーブル。
LoadGeomCache
エンティティスロットに geom キャッシュをロードします。
構文
Entity.LoadGeomCache(int nSlot,const char *sFilename)
パラメーター
パラメーター
説明
nSlot
スロット識別子。
sFilename
CAX ファイル名。
LoadLight
エンティティスロットに CGF ジオメトリをロードします。
構文
Entity.LoadLight(int nSlot,SmartScriptTable table)
パラメーター
パラメーター
説明
nSlot
スロット識別子。
Version 1.6
669
Lumberyard 開発者ガイド
ScriptBind_Entity
パラメーター
説明
table
すべてのライト情報を含むテーブル。
LoadObject
エンティティスロットに CGF ジオメトリをロードします。
構文
Entity.LoadObject(int nSlot,const char *sFilename)
パラメーター
パラメーター
説明
nSlot
スロット識別子。
sFilename
CGF ジオメトリのファイル名。
LoadObjectLattice
エンティティスロットに格子をロードします。
構文
Entity.LoadObjectLattice(int nSlot)
LoadObjectWithFlags
エンティティスロットに CGF ジオメトリをロードします。
構文
Entity.LoadObjectWithFlags(int nSlot,const char *sFilename, const int nFlags)
パラメーター
パラメーター
説明
nSlot
スロット識別子。
sFilename
CGF ジオメトリのファイル名。
nFlags
エンティティのロードフラグ
LoadParticleEffect
エンティティスロットに CGF ジオメトリをロードします。
構文
Version 1.6
670
Lumberyard 開発者ガイド
ScriptBind_Entity
Entity.LoadParticleEffect(int nSlot, const char *sEffectName,
SmartScriptTable table)
パラメーター
パラメーター
説明
nSlot
スロット識別子。
sEffectName
パーティクル効果の名前 (例: "explosions/
rocket")。
(optional) bPrime
効果が平衡状態になる前に完全に開始されるか
どうか。
(optional) fPulsePeriod
パーティクル効果が再スタートするまでの間
隔。
(optional) fScale
パーティクルに適用するサイズのスケール
(optional) fCountScale
パーティクルに適用する数値の乗数
(optional) bScalePerUnit
アタッチメントの範囲でのサイズのスケール
(optional) bCountPerUnit
アタッチメントの範囲での数のスケール
(optional) sAttachType
EGeomType の文字列
(optional) sAttachForm
EGeomForm の文字列
LoadSubObject
エンティティスロットに 1 つの CGF ノードのジオメトリをロードします。
構文
Entity.LoadSubObject(int nSlot,const char *sFilename,const char *sGeomName)
パラメーター
パラメーター
説明
nSlot
スロット識別子。
sFilename
CGF ジオメトリのファイル名。
sGeomName
CGF ジオメトリ内のノードの名前。
LoadVolumeObject
ボリュームオブジェクトをロードします。
構文
Entity.LoadVolumeObject(int nSlot, const char* sFilename)
Version 1.6
671
Lumberyard 開発者ガイド
ScriptBind_Entity
パラメーター
パラメーター
説明
nSlot
スロット識別子。
sFilename
ボリュームオブジェクトのファイル名。
LookAt
エンティティを、ワールドスペースの位置を見るように方向づけます。
構文
Entity.LookAt(Vec3 target, Vec3 axis, float angle)
パラメーター
パラメーター
説明
target
見る対象の位置。
axis
修正軸。quat 型はサポートされていません。
angle
修正角度の内弧度。quat 型はサポートされていません。
MultiplyWithSlotTM
スロットの TM (変換マトリックス) を使用した乗数。
構文
Entity.MultiplyWithSlotTM(int slot, Vec3 pos)
パラメーター
パラメーター
説明
slot
スロット識別子。
pos
位置のベクトル。
NetPresent
構文
Entity.NetPresent()
NoBulletForce
構文
Entity.NoBulletForce(bool state)
Version 1.6
672
Lumberyard 開発者ガイド
ScriptBind_Entity
NoExplosionCollision
構文
Entity.NoExplosionCollision()
PassParamsToPipe
構文
Entity.PassParamsToPipe()
Physicalize
指定されたエンティティスロットから物理エンティティを作成します。
構文
Entity.Physicalize(int nSlot,int nPhysicsType,SmartScriptTable physicsParams)
パラメーター
パラメーター
説明
nSlot
物理化するエンティティのスロット識別子。-1 を指定するとすべての
スロットからのジオメトリを使用します。
nPhysicsType
作成する物理エンティティの型。可能な値については、このセクショ
ンで後述する nPhysicsType キーのテーブルを参照してください。
physicsParams
物理化パラメーターのテーブル。詳細については、このセクションで
後述する physicsParams テーブルキーを参照してください。
nPhysicsType キー
物理現象の型
意味
PE_AREA
物理エリア (球体、ボックス、ジオメトリ、シェイプ)。
PE_ARTICULATED ジョイントで接続された剛体で構成されたラグドールまたはその他の連結型物
理エンティティ。
PE_LIVING
物理ワールド内を移動しワールドを操作できる、生きている物理エンティ
ティ。
PE_NONE
物理演算がありません。
PE_PARTICLE
質量および半径のみをもつ物理パーティクルエンティティ。
PE_RIGID
剛体物理エンティティ。質量は無限 (質量を 0 に指定する) にすることもできま
す。
PE_ROPE
ロープの物理表現。ロープは自由につるしたり、2 つの物理エンティティを接
続したりできます。
Version 1.6
673
Lumberyard 開発者ガイド
ScriptBind_Entity
物理現象の型
意味
PE_SOFT
環境に作用することができる、ゆるく接続された頂点のシステム。布のシミュ
レーションなど、柔らかいボディの物理演算に使用されます。
PE_STATIC
静的な動かない物理エンティティ。
PE_WHEELEDVEHICLE
車輪がある物理車両。
Note
物理エンティティのタイプの詳細については、「物理的なエンティティ (p. 523)」を参照して
ください。
physicsParams テーブルキー
物理パラ
メーター
説明
area
このテーブルは物理タイプが PE_AREA のときに設定する必要があります。詳細につい
ては、このセクションで後述する Area テーブルキーを参照してください。
density
オブジェクトの密度。質量が未指定または -1 の場合以外でのみ使用されます。
flags
物理エンティティのフラグ。
living
このテーブルは物理タイプが PE_LIVING のときに設定する必要があります。詳細につ
いては、このセクションで後述する Living テーブルキーを参照してください。
mass
オブジェクトの質量。密度が未指定または -1 の場合以外でのみ使用されます。
particle このテーブルは物理タイプが PE_PARTICLE のときに設定する必要があります。詳細に
ついては、このセクションで後述する Particle テーブルキーを参照してください。
partid
新しい物理エンティティを添付する、連結されたボディ部位のインデックス。
stiffness_scale
キャラクターのジョイントの剛さのスケール (エクスポートされたモデルから指定され
た硬さ値で乗算)
Particle テーブルキー
パーティクルのパ
ラメーター
説明
accel_lift
パーティクルを現在の速度で持ち上げる加速度
accel_thrust
移動方向に沿った加速度
air_resistance
空気抵抗の係数、F = kv
constant_orientation
(0,1) 一定の方向を維持します。
gravity
空中への重力ベクトル
mass
パーティクル質量
min_bounce_vel
パーティクルが表面で跳ねる最低速度
no_path_alignment(0,1) パーティクルの方向を移動パスに合わせません。
Version 1.6
674
Lumberyard 開発者ガイド
ScriptBind_Entity
パーティクルのパ
ラメーター
説明
no_roll
(0,1) パーティクルが地形で転がりません。
no_spin
(0,1) パーティクルが空中で回転しません。
radius
パーティクルの擬似半径
single_contact
(0,1) 最初の接触 1 回のみを計算します。
thickness
表面に横たわっている場合の厚さ (0 の場合は半径が使用されます)
velocity
速度の方向と大きさのベクトル
water_gravity
水中での重力ベクトル
water_resistance 水力抵抗の係数。F = kv
Living テーブルキー
Living のパラ
メーター
説明
air_resistance空中制御係数 0..1、1 - 特殊な値 (移動の合計制御)
gravity
垂直重力の大きさ
head_radius
頭の半径
height
衝突ジオメトリの中心の垂直オフセット
height_eye
カメラの垂直オフセット
height_head
頭の垂直オフセット
height_pivot
エンティティの中心とみなされる中央地面の位置からのオフセット
inertia
慣性係数。値が大きくなるほど慣性は小さくなり、0 は慣性なしを意味します。
mass
プレイヤーの質量 (kg)
max_climb_angle
プレイヤーはこの角度 (ラジアン) よりも急な斜面を登ることができません。
max_jump_angleこの角度を超える (ラジアン) 場合、プレイヤーは地面に向かってジャンプするこ
とができません。
max_vel_groundプレイヤーは、この値 (ラジアン) よりも速く移動する表面に立てません。
min_fall_angle斜面がこの値 (ラジアン) よりも急な場合、プレーヤーは落下し始めます
min_slide_angle
斜面がこの角度よりも急な場合、プレイヤーは滑落し始めます (ラジアン)
size
衝突シリンダーのディメンションのベクトル (x,y,z)。
Area テーブルキー
Area のパラ
メーター
説明
box_max
境界ボックスの最大ベクトル。タイプが AREA_BOX の場合に指定する必要があります
Version 1.6
675
Lumberyard 開発者ガイド
ScriptBind_Entity
Area のパラ
メーター
説明
box_min
境界ボックスの最小ベクトル。タイプが AREA_BOX の場合に指定する必要があります
falloff
楕円形の減衰ディメンション。0,0,0 は減衰なしの指定です。
gravity
物理エリア内の重力ベクトル
height
2D エリア (AREA_SHAPE) の高さ。ポイントテーブルの最小 Z からの相対値です
points
エリアの 2D シェイプを定義するローカルエンティティスペースでのベクトルのイン
デックス付きコレクションを含むテーブル (AREA_SHAPE)
radius
エリア球形の半径。タイプが AREA_SPHERE の場合に指定する必要があります。
type
エリアのタイプ。有効な値は次のとおりです:
AREA_SPHERE、AREA_BOX、AREA_GEOMETRY、または AREA_SHAPE
uniform
各ポイントで同じ方向、または常に中心をポイントします。
PhysicalizeAttachment
構文
Entity.PhysicalizeAttachment(int characterSlot, const char* attachmentName,
bool physicalize)
PhysicalizeSlot
構文
Entity.PhysicalizeSlot(int slot, SmartScriptTable physicsParams)
PlayFacialAnimation
構文
Entity.PlayFacialAnimation(char* name, bool looping)
PreLoadParticleEffect
パーティクル効果をあらかじめロードします。
構文
Entity.PreLoadParticleEffect(const char *sEffectName)
パラメーター
パラメーター
説明
sEffectName
パーティクル効果の名前 (例: "explosions/
rocket")。
Version 1.6
676
Lumberyard 開発者ガイド
ScriptBind_Entity
ProcessBroadcastEvent
構文
Entity.ProcessBroadcastEvent()
RagDollize
構文
Entity.RagDollize(int slot)
ReattachSoftEntityVtx
構文
Entity.ReattachSoftEntityVtx(ScriptHandle entityId, int partId)
RedirectAnimationToLayer0
構文
Entity.RedirectAnimationToLayer0(int characterSlot, bool redirect)
RegisterForAreaEvents
このエンティティのエリアイベントを受信できるようにプロキシスクリプトを登録します。
構文
Entity.RegisterForAreaEvents(int enable)
パラメーター
パラメーター
説明
enable
無効にするには 0 を、有効にするには他の値を
指定します。
RemoveAllLinks
エンティティのすべてのリンクを削除します。
構文
Entity.RemoveAllLinks()
戻り値: なし
Version 1.6
677
Lumberyard 開発者ガイド
ScriptBind_Entity
RemoveAuxAudioProxy
親 EntityAudioProxy から渡された ID に対応する AuxAudioProxy を削除します。
構文
Entity.RemoveAuxAudioProxy(ScriptHandle const hAudioProxyLocalID)
戻り値: nil
パラメーター
パラメーター
説明
hAudioProxyLocalID
親 EntityAudioProxy から削除する
AuxAudioProxy の ID。
RemoveDecals
構文
Entity.RemoveDecals()
RemoveLink
エンティティから出力リンクを削除します。
構文
Entity.RemoveLink(const char *name)
戻り値: なし
パラメーター
パラメーター
説明
name
削除するリンクの名前。
(optional) ith
指定した場合、指定された名前を持つ <i> 番目
のリンクが削除されます。デフォルト値: 0 (指定
された名前を持つ 1 番目のリンク)
RenderAlways
レンダリングノードで、「常にレンダリング」を有効にし、すべての種類のカリングをスキップしま
す。
構文
Entity.RenderAlways(int enable)
Version 1.6
678
Lumberyard 開発者ガイド
ScriptBind_Entity
パラメーター
パラメーター
説明
enable
無効にするには 0 を、有効にするには他の値を
指定します。
RenderShadow
構文
Entity.RenderShadow()
ReplaceMaterial
構文
Entity.ReplaceMaterial(int slot, const char *name, const char *replacement)
ResetAnimation
構文
Entity.ResetAnimation(int characterSlot, int layer)
ResetAttachment
構文
Entity.ResetAttachment(int characterSlot, const char *attachmentName)
ResetMaterial
構文
Entity.ResetMaterial(int slot)
ResetPhysics
構文
Entity.ResetPhysics()
SelectPipe
構文
Entity.SelectPipe()
Version 1.6
679
Lumberyard 開発者ガイド
ScriptBind_Entity
SetAIName
構文
Entity.SetAIName()
SetAngles
エンティティの角度を設定します。
構文
Entity.SetAngles(Ang3 vAngles)
パラメーター
パラメーター
説明
vAngles
角度のベクトル。
SetAnimateOffScreenShadow
構文
Entity.SetAnimateOffScreenShadow(bool bAnimateOffScreenShadow)
SetAnimationBlendOut
構文
Entity.SetAnimationBlendOut(int characterSlot, int layer, float blendOut)
SetAnimationEvent
構文
Entity.SetAnimationEvent(int nSlot,const char *sAnimation)
SetAnimationFlip
構文
Entity.SetAnimationFlip(int characterSlot, Vec3 flip)
SetAnimationKeyEvent
構文
Version 1.6
680
Lumberyard 開発者ガイド
ScriptBind_Entity
Entity.SetAnimationKeyEvent(nSlot, sAnimation, nFrameID, sEvent)
SetAnimationSpeed
構文
Entity.SetAnimationSpeed(int characterSlot, int layer, float speed)
SetAnimationTime
構文
Entity.SetAnimationTime(int nSlot,int nLayer,float fTime)
SetAttachmentAngles
構文
Entity.SetAttachmentAngles(int characterSlot, const char *attachmentName,
Vec3 angles)
SetAttachmentCGF
構文
Entity.SetAttachmentCGF(int characterSlot, const char *attachmentName, const
char* filePath)
SetAttachmentDir
構文
Entity.SetAttachmentDir(int characterSlot, const char *attachmentName, Vec3
dir, bool worldSpace)
SetAttachmentEffect
構文
Entity.SetAttachmentEffect(int characterSlot, const char *attachmentName,
const char *effectName, Vec3 offset, Vec3 dir, float scale, int flags)
SetAttachmentLight
構文
Entity.SetAttachmentLight(int characterSlot, const char *attachmentName,
SmartScriptTable lightTable, int flags)
Version 1.6
681
Lumberyard 開発者ガイド
ScriptBind_Entity
SetAttachmentObject
構文
Entity.SetAttachmentObject(int characterSlot, const char *attachmentName,
ScriptHandle entityId, int slot, int flags)
SetAttachmentPos
構文
Entity.SetAttachmentPos(int characterSlot, const char *attachmentName, Vec3
pos)
SetAudioEnvironmentID
エンティティがその中のエンティティに対して指定する音声環境の ID を設定します。
構文
Entity.SetAudioEnvironmentID(ScriptHandle const hAudioEnvironmentID)
戻り値: nil
パラメーター
パラメーター
説明
hAudioEnvironmentID
音声環境 ID
SetAudioObstructionCalcType
基礎となる GameAudioObject に基づいて音声の障害/オクルージョン演算タイプを設定します。
構文
Entity.SetAudioObstructionCalcType(int const nObstructionCalcType,
ScriptHandle const hAudioProxyLocalID)
戻り値: nil
パラメーター
パラメーター
説明
nObstructionCalcType
障害/オクルージョン演算タイプ。指定可能な値:
0 - 障害/オクルージョンを無視 1 - 単一の物理レ
イを使用 2 - 複数の物理レイを使用 (現行はオブ
ジェクトあたり 5 つ)
hAudioProxyLocalID
EntityAudioProxy 専用の AuxAudioProxy の
ID。デフォルトの AuxAudioProxy を指定する
には、1 を渡します。すべての AuxAudioProxy
インスタンスを指定するには、0 を渡します。
Version 1.6
682
Lumberyard 開発者ガイド
ScriptBind_Entity
SetAudioProxyOffset
エンティティにアタッチされた音声プロキシのオフセットを設定します。
構文
Entity.SetAudioProxyOffset(Vec3 const vOffset, ScriptHandle const
hAudioProxyLocalID)
戻り値: nil
パラメーター
パラメーター
説明
vOffset
オフセットのベクトル
hAudioProxyLocalID
EntityAudioProxy 専用の AuxAudioProxy の
ID。デフォルトの AuxAudioProxy を指定する
には、1 を渡します。すべての AuxAudioProxy
インスタンスを指定するには、0 を渡します。
SetAudioRtpcValue
現在のエンティティで指定された音声 RTPC を指定された値に設定します。
構文
Entity.SetAudioRtpcValue(ScriptHandle const hRtpcID, float const fValue,
ScriptHandle const hAudioProxyLocalID)
戻り値: nil
パラメーター
パラメーター
説明
hRtpcID
音声 RTPC ID のハンドル
fValue
RTPC 値
hAudioProxyLocalID
EntityAudioProxy 専用の AuxAudioProxy の
ID。デフォルトの AuxAudioProxy を指定する
には、1 を渡します。すべての AuxAudioProxy
インスタンスを指定するには、0 を渡します。
SetAudioSwitchState
現在のエンティティで指定された音声スイッチを指定された状態に設定します。
構文
Entity.SetAudioSwitchState(ScriptHandle const hSwitchID, ScriptHandle const
hSwitchStateID, ScriptHandle const hAudioProxyLocalID)
Version 1.6
683
Lumberyard 開発者ガイド
ScriptBind_Entity
戻り値: nil
パラメーター
パラメーター
説明
hSwitchID
音声スイッチ ID のハンドル
hSwitchStateID
スイッチ状態 ID のハンドル
hAudioProxyLocalID
EntityAudioProxy 専用の AuxAudioProxy の
ID。デフォルトの AuxAudioProxy を指定する
には、1 を渡します。すべての AuxAudioProxy
インスタンスを指定するには、0 を渡します。
SetCharacterPhysicParams
構文
Entity.SetCharacterPhysicParams()
SetCloudMovementProperties
雲の動きのプロパティを設定します。
構文
Entity.SetCloudMovementProperties(int nSlot, SmartScriptTable table)
パラメーター
パラメーター
説明
nSlot
スロット識別子。
table
雲の動きのテーブルプロパティ。
SetColliderMode
構文
Entity.SetColliderMode(int mode)
SetCurrentAudioEnvironments
正しい音声環境量をワールド内のエンティティの位置に基づいて設定します。
構文
Entity.SetCurrentAudioEnvironments()
戻り値: nil
Version 1.6
684
Lumberyard 開発者ガイド
ScriptBind_Entity
SetDefaultIdleAnimations
構文
Entity.SetDefaultIdleAnimations()
SetDirectionVector
構文
Entity.SetDirectionVector(Vec3 dir)
SetEnvironmentFadeDistance
このエンティティですべての近づいてくるエンティティに対して音声環境がフェードする距離を設定
します。
構文
Entity.SetEnvironmentFadeDistance(float const fEnvironmentFadeDistance)
戻り値: nil
パラメーター
パラメーター
説明
fEnvironmentFadeDistance
フェード距離 (メートル)。
SetFadeDistance
このエンティティがフェード計算を実行する距離を設定します。
構文
Entity.SetFadeDistance(float const fFadeDistance)
戻り値: nil
パラメーター
パラメーター
説明
fFadeDistance
フェード距離 (メートル)。
SetFlags
モード: 0: または 1: および 2: xor
構文
Entity.SetFlags(int flags, int mode)
Version 1.6
685
Lumberyard 開発者ガイド
ScriptBind_Entity
SetFlagsExtended
モード: 0: または 1: および 2: xor
構文
Entity.SetFlagsExtended(int flags, int mode)
SetGeomCacheDrawing
geom キャッシュの描画をアクティブ化または非アクティブ化します。
構文
Entity.SetGeomCacheDrawing(bool active)
SetGeomCacheParams
ジオメトリキャッシュのパラメーターを設定します。
構文
Entity.SetGeomCacheParams(bool looping, const char *standIn, const
char *standInMaterial, const char *firstFrameStandIn, const char*
firstFrameStandInMaterial, const char* lastFrameStandIn, const char*
lastFrameStandInMaterial, float standInDistance, float streamInDistance)
SetGeomCachePlaybackTime
再生時刻を設定します。
構文
Entity.SetGeomCachePlaybackTime(float time)
SetGeomCacheStreaming
geom キャッシュのストリーミングをアクティブ化/非アクティブ化します。
構文
Entity.SetGeomCacheStreaming(bool active, float time)
SetLightColorParams
既存の光の色関連パラメーターを変更します。
構文
Entity.SetLightColorParams(int nSlot, Vec3 color, float specular_multiplier)
Version 1.6
686
Lumberyard 開発者ガイド
ScriptBind_Entity
SetLinkTarget
既存のリンクが対象にするエンティティを指定します。既存のリンクの対象を変更するには、この関
数を使用します。
構文
Entity.SetLinkTarget(const char *name, ScriptHandle targetId)
戻り値: なし
パラメーター
パラメーター
説明
name
指定されたエンティティを対象にするリンクの
名前。
targetId
リンクが対象にするエンティティの
ID。NULL_ENTITY を渡すと、リンクがエンティ
ティを対象としなくなります。
(optional) ith
指定した場合、指定されたエンティティを対象
にする指定された名前を持つ <i> 番目のリンク
です。デフォルト値: 0 (指定された名前を持つ 1
番目のリンク)
SetLocalAngles
構文
Entity.SetLocalAngles(Ang3 vAngles)
SetLocalBBox
構文
Entity.SetLocalBBox(Vec3 vMin,Vec3 vMax)
SetLocalPos
構文
Entity.SetLocalPos(Vec3 vPos)
SetLocalScale
構文
Entity.SetLocalScale(float fScale)
Version 1.6
687
Lumberyard 開発者ガイド
ScriptBind_Entity
SetLodRatio
構文
Entity.SetLodRatio()
SetMaterial
構文
Entity.SetMaterial()
SetMaterialFloat
マテリアルのパラメーターを変更します。
構文
Entity.SetMaterialFloat(int slot,int nSubMtlId,const char *sParamName,float
fValue)
パラメーター
パラメーター
説明
slot
マテリアルを変更するスロットの ID。
nSubMtlId
ID でサブマテリアルを指定します。
sParamName
マテリアルのパラメーターの名前。
fValue
新しいマテリアルのパラメーター値。
SetMaterialVec3
構文
Entity.SetMaterialVec3(int slot,int nSubMtlId,const char *sParamName,Vec3
fValue)
SetName
構文
Entity.SetName()
SetParentSlot
構文
Version 1.6
688
Lumberyard 開発者ガイド
ScriptBind_Entity
Entity.SetParentSlot(int child, int parent)
SetPhysicParams
構文
Entity.SetPhysicParams()
SetPos
エンティティの位置を設定します。
構文
Entity.SetPos(Vec3 vPos)
パラメーター
パラメーター
説明
vPos
位置のベクトル。
SetPublicParam
シェーダーパラメーターを設定します。
構文
Entity.SetPublicParam()
パラメーター
パラメーター
説明
paramName
シェーダーパラメーターの名前。
value
パラメーターの新しい値。
SetRegisterInSectors
構文
Entity.SetRegisterInSectors()
SetScale
エンティティのスケーリング値を設定します。
構文
Entity.SetScale(float fScale)
Version 1.6
689
Lumberyard 開発者ガイド
ScriptBind_Entity
パラメーター
パラメーター
説明
fScale
スケール量。
SetScriptUpdateRate
構文
Entity.SetScriptUpdateRate(int nMillis)
SetSelfAsLightCasterException
エンティティのレンダリングノードを nLightSlot にロードされたライトのキャストの例外にしま
す。
構文
Entity.SetSelfAsLightCasterException(int nLightSlot)
パラメーター
パラメーター
説明
nLightSlot
ライトがロードされるスロット。
SetSlotAngles
スロットの角度を設定します。
構文
Entity.SetSlotAngles(int nSlot, Ang3 v)
パラメーター
パラメーター
説明
nSlot
nSlot 識別子。
v
設定する角度。
SetSlotHud3D
3D HUD エンティティとして使用するためのフラグを設定します。
構文
Entity.SetSlotHud3D(int nSlot)
Version 1.6
690
Lumberyard 開発者ガイド
ScriptBind_Entity
パラメーター
パラメーター
説明
nSlot
スロット識別子。
SetSlotPos
スロットの位置を設定します。
構文
Entity.SetSlotPos(int slot,Vec3 v)
パラメーター
パラメーター
説明
slot
スロット識別子。
v
設定する位置.
SetSlotPosAndDir
スロットの位置と方向を設定します。
構文
Entity.SetSlotPosAndDir(int nSlot, Vec3 pos, Vec3 dir)
パラメーター
パラメーター
説明
nSlot
nSlot 識別子。
pos
設定する位置.
dir
設定する方向。
SetSlotScale
スロットのスケール量を設定します。
構文
Entity.SetSlotScale(int nSlot,float fScale)
パラメーター
パラメーター
説明
nSlot
スロット識別子。
Version 1.6
691
Lumberyard 開発者ガイド
ScriptBind_Entity
パラメーター
説明
fScale
スロットのスケール量。
SetSlotWorldTM
スロットのワールド TM (変換マトリックス) を設定します。
構文
Entity.SetSlotWorldTM(int nSlot, Vec3 pos, Vec3 dir)
パラメーター
パラメーター
説明
nSlot
スロット識別子。
pos
位置のベクトル。
dir
方向ベクトル。
SetStateClientside
構文
Entity.SetStateClientside()
SetTimer
構文
Entity.SetTimer()
SetTriggerBBox
構文
Entity.SetTriggerBBox(Vec3 vMin,Vec3 vMax)
SetUpdatePolicy
エンティティの更新ポリシーを変更します。更新ポリシーはエンティティがアクティブまたは非アク
ティブになるタイミングを制御します (たとえば、視認可能になったときや近接したとき)。
Note
アクティブなエンティティはすべてフレームごとに更新されるため、アクティブなエンティ
ティの数が多すぎるとパフォーマンスに営業する場合があります。
Version 1.6
692
Lumberyard 開発者ガイド
ScriptBind_Entity
構文
Entity.SetUpdatePolicy(int nUpdatePolicy)
パラメーター
パラメーター
説明
nUpdatePolicy
更新ポリシーの定数。使用できる値について
は、次の表を参照してください。
nUpdatePolicy に使用できる値
ポリシーの更新
意味
ENTITY_UPDATE_NEVER
このエンティティを更新しません。
ENTITY_UPDATE_IN_RANGE指定された半径内にある場合にエンティティをアクティブにします。
ENTITY_UPDATE_POT_VISIBLE
視認される可能性がある場合にエンティティをアクティブにします。
ENTITY_UPDATE_VISIBLE 円錐台内で視認できる場合にエンティティをアクティブにします。
ENTITY_UPDATE_PHYSICS 物理演算が有効な場合にエンティティをアクティブにし、物理演算が
休止している場合は非アクティブにします。
ENTITY_UPDATE_PHYSICS_VISIBLE
ENTITY_UPDATE_PHYSICS と同じですが、視認できる場合もアク
ティブにします。
ENTITY_UPDATE_ALWAYS
エンティティは常にアクティブで、フレームごとに更新されます。
Note
範囲が必要な更新ポリシーの場合は、SetUpdateRadius (p. 693) を使用してください。
SetUpdateRadius
構文
Entity.SetUpdateRadius()
SetVelocity
構文
Entity.SetVelocity(Vec3 velocity)
SetVelocityEx
構文
Entity.SetVelocityEx(Vec3 velocity, Vec3 angularVelocity)
Version 1.6
693
Lumberyard 開発者ガイド
ScriptBind_Entity
SetViewDistanceMultiplier
ビュー距離の乗数を設定します。
構文
Entity.SetViewDistanceMultiplier()
SetViewDistUnlimited
構文
Entity.SetViewDistUnlimited()
SetVolumeObjectMovementProperties
ボリュームオブジェクトの動作のプロパティを設定します。
構文
Entity.SetVolumeObjectMovementProperties(int nSlot, SmartScriptTable table)
パラメーター
パラメーター
説明
nSlot
スロット識別子。
table
ボリュームオブジェクトのプロパティがある
テーブル。
SetWorldAngles
構文
Entity.SetWorldAngles(Ang3 vAngles)
SetWorldPos
構文
Entity.SetWorldPos(Vec3 vPos)
SetWorldScale
構文
Entity.SetWorldScale(float fScale)
Version 1.6
694
Lumberyard 開発者ガイド
ScriptBind_Entity
StartAnimation
構文
Entity.StartAnimation()
StopAnimation
構文
Entity.StopAnimation(int characterSlot, int layer)
StopAudioTrigger
このエンティティで、指定された ID のトリガーによって生成された音声イベントを停止します。
構文
Entity.StopAudioTrigger(ScriptHandle const hTriggerID, ScriptHandle const
hAudioProxyLocalID)
戻り値: nil
パラメーター
パラメーター
説明
hTriggerID
音声トリガー ID のハンドル
hAudioProxyLocalID
EntityAudioProxy 専用の AuxAudioProxy の
ID。デフォルトの AuxAudioProxy を指定する
には、1 を渡します。すべての AuxAudioProxy
インスタンスを指定するには、0 を渡します。
ToGlobal
構文
Entity.ToGlobal(int slotId, Vec3 point)
ToLocal
構文
Entity.ToLocal(int slotId, Vec3 point)
TriggerEvent
構文
Entity.TriggerEvent()
Version 1.6
695
Lumberyard 開発者ガイド
ScriptBind_Movie
UnSeenFrames
構文
Entity.UnSeenFrames()
UpdateAreas
構文
Entity.UpdateAreas()
UpdateLightClipBounds
連結エンティティからライトのクリップ境界を更新します。
構文
Entity.UpdateLightClipBounds(int nSlot)
パラメーター
パラメーター
説明
nSlot
スロット識別子。
UpdateSlotPhysics
構文
Entity.UpdateSlotPhysics(int slot)
VectorToGlobal
構文
Entity.VectorToGlobal(int slotId, Vec3 dir)
VectorToLocal
構文
Entity.VectorToLocal(int slotId, Vec3 dir)
ScriptBind_Movie
Lua スクリプトから呼び出すことができる C++ のムービー関数をリストします。
Version 1.6
696
Lumberyard 開発者ガイド
ScriptBind_Movie
AbortSequence
指定されたシーケンスを中止します。
構文
Movie.AbortSequence(const char *sSequenceName)
パラメーター
説明
sSequenceName
Sequence name.
PauseSequences
すべてのシーケンスを一時停止します。
構文
Movie.PauseSequences()
PlaySequence
指定されたシーケンスを再生します。
構文
Movie.PlaySequence(const char *sSequenceName)
パラメーター
説明
sSequenceName
Sequence name.
ResumeSequences
すべてのシーケンスを再開します。
構文
Movie.ResumeSequences()
StopAllCutScenes
すべてのカットシーンを停止します。
構文
Movie.StopAllCutScenes()
Version 1.6
697
Lumberyard 開発者ガイド
ScriptBind_Particle
StopAllSequences
すべてのビデオシーケンスを停止します。
構文
Movie.StopAllSequences()
StopSequence
指定されたシーケンスを停止します。
構文
Movie.StopSequence(const char *sSequenceName)
パラメーター
説明
sSequenceName
Sequence name.
ScriptBind_Particle
Lua スクリプトから呼び出すことができる C++ パーティクル関数をリストします。
アタッチ
効果をアタッチします。
構文
Particle.Attach()
CreateDecal
指定されたパラメーターでデカールを作成します。
構文
Particle.CreateDecal(Vec3 pos, Vec3 normal, float size, float lifeTime, const
char *textureName)
パラメーター
説明
pos
デカールの位置ベクトル。
normal
デカールの法線ベクトル。
size
浮動小数点で示されるデカールのサイズ。
lifeTime
浮動小数点で示されるデカールの持続時間。
textureName
テクスチャの名前。
Version 1.6
698
Lumberyard 開発者ガイド
ScriptBind_Particle
CreateEffect
パーティクル効果を作成します。
構文
Particle.CreateEffect(const char *name, SmartScriptTable params)
パラメーター
説明
name
パーティクル効果の名前。
params
効果パラメーターの SmartScriptTable。
CreateMatDecal
マテリアルデカールを作成します。
構文
Particle.CreateMatDecal(Vec3 pos, Vec3 normal, float size, float lifeTime,
const char *materialName)
パラメーター
説明
pos
デカールの位置ベクトル。
normal
デカールの法線ベクトル。
size
浮動小数点で示されるデカールのサイズ。
lifeTime
浮動小数点で示されるデカールの持続時間。
materialName
マテリアルの名前。
DeleteEffect
指定されたパーティクル効果を削除します。
構文
Particle.DeleteEffect(const char *name)
パラメーター
説明
name
削除するパーティクル効果の名前。
デタッチ
効果をデタッチします。
Version 1.6
699
Lumberyard 開発者ガイド
ScriptBind_Particle
構文
Particle.Detach()
IsEffectAvailable
指定したパーティクル効果を使用できるかどうかを確認します。
構文
Particle.IsEffectAvailable(const char *name)
パラメーター
説明
name
使用できるかどうかを確認するパーティクル効
果の名前。
SpawnEffect
効果をスポーンさせます。
構文
Particle.SpawnEffect(const char *effectName, Vec3 pos, Vec3 dir)
パラメーター
説明
effectName
スポーンさせる効果の名前。
pos
効果の位置ベクトル。
dir
効果の方向ベクトル。
SpawnEffectLine
効果ラインをスポーンさせます。
構文
Particle.SpawnEffectLine(const char *effectName, Vec3 startPos, Vec3 endPos,
Vec3 dir, float scale, int slices)
パラメーター
説明
effectName
効果の名前。
startPos
効果の開始位置。
endPos
効果の終了位置。
dir
効果の方向。
Version 1.6
700
Lumberyard 開発者ガイド
ScriptBind_Physics
パラメーター
説明
scale
浮動小数点で示される効果のスケール値。
slices
スライスの数。
SpawnParticles
パーティクル効果をスポーンさせます。
構文
Particle.SpawnParticles(SmartScriptTable params, Vec3 pos, Vec3 dir)
パラメーター
説明
params
パーティクル効果パラメーターの
SmartScriptTable。
pos
パーティクル効果の位置ベクトル。
dir
パーティクル効果の方向ベクトル。
ScriptBind_Physics
Lua スクリプトから呼び出すことができる C++ 物理関数をリストします。
RayTraceCheck
射線セグメントがソースから宛先までの間で何かに交差するかどうかをチェックします。
構文
Physics.RayTraceCheck(Vec3 src,Vec3 dst,ScriptHandle
skipEntityId1,ScriptHandle skipEntityId2)
パラメーター
説明
src
射線セグメントの原点。
dst
射線セグメントの終点。
skipEntityId1
交差を確認するときにスキップするエンティ
ティ ID。
skipEntityId2
交差を確認するときにスキップするエンティ
ティ ID。
RayWorldIntersection
射線セグメントがソースから宛先までの間で何かに交差するかどうかをチェックします。
Version 1.6
701
Lumberyard 開発者ガイド
ScriptBind_Physics
構文
Physics.RayWorldIntersection(Vec3 vPos, Vec3 vDir, int nMaxHits, int
iEntTypes [, skipEntityId1 [, skipEntityId2]])
パラメーター
説明
vPos
射線の原点。
vDir
射線の方向。
nMaxHits
戻される最大ヒット数。最も近いものから最も
遠いものの順序でソートされます。
iEntTypes
物理エンティティのタイプのビットマスク。射
線が、マスクが指定するエンティティとのみ交
差します (ent_all…)。
skipEntityId1
オプション。交差を確認するときにスキップす
るエンティティ ID。
skipEntityId2
オプション。交差を確認するときにスキップす
るエンティティ ID。
RegisterExplosionCrack
破壊可能なオブジェクトに新しいひびを登録します。
構文
Physics.RegisterExplosionCrack(const char *sGeometryFile,int nIdMaterial)
パラメーター
説明
sGeometryFile
ひびの静的ジオメトリファイルの名前 (CGF)。
nMaterialId
ひびが適用されている破壊可能マテリアルの
ID。
RegisterExplosionShape
静的ジオメトリから新しい爆発シェイプを登録します。
Note
RegisterExplosionShape は物理的な力にのみ適用され、ゲームに関連する爆発ダメージ
には適用されません。
構文
Physics.RegisterExplosionShape(RegisterExplosionShape(IFunctionHandler
*pH,const char *sGeometryFile,float fSize,int nIdMaterial,float
Version 1.6
702
Lumberyard 開発者ガイド
ScriptBind_Physics
fProbability,const char *sSplintersFile, float fSplintersOffset, const char
*sSplintersCloudEffect)
パラメーター
説明
sGeometryFile
静的ジオメトリファイル (CGF) の名前。
fSize
静的ジオメトリのスケール。
nIdMaterial
シェイプが適用されている破壊可能マテリアル
の ID。
fProbability
他の登録シェイプではなくこのシェイプを使用
する傾向率。
sSplintersFile
断面に配置される物理化されていない追加の裂
片を含む CGF ファイルの名前。
fSplintersOffset
上の裂片に対する下の裂片の位置。
sSplintersCloudEffect
裂片の拘束が破壊されたときのパーティクル効
果。
SamplePhysEnvironment
球体に触れている物理エンティティを見つけます。
構文
Physics.SamplePhysEnvironment(pt, r [, objtypes])
パラメーター
説明
pt
球体の中心。
r
球体の半径。
objtypes
オプション。球体が触れている物理エンティ
ティのタイプ。
SimulateExplosion
物理爆発をシミュレートします。
Note
SimulateExplosion は物理的な力にのみ適用され、ゲームに関連する爆発ダメージには適
用されません。
構文
Physics.SimulateExplosion(SmartScriptTable explosionParams)
Version 1.6
703
Lumberyard 開発者ガイド
ScriptBind_Script
explosionParams は以下のような要素を持つ SmartScriptTable です。
explosionParams 要素
パラメーター
説明
pos
爆発の震央。
radius
爆発の半径。
direction
爆発の衝撃の方向。
impulse_pos
爆発の衝撃の位置。この値は、爆発の震央とは異なってもかまいません。
impulse_presure
震央から指定された半径における爆発の衝撃の圧力。
rmin
爆発の最小半径。個の半径には全圧力が適用されます。
rmax
爆発の最大半径。この半径では、衝撃の圧力はゼロに近くなります。
hole_size
爆発によって破壊可能オブジェクトに作成される穴のサイズ。
ScriptBind_Script
Lua スクリプトから呼び出すことができる C++ スクリプト関連関数をリストします。
DumpLoadedScripts
すべてのロードされたスクリプトをダンプします。
構文
Script.DumpLoadedScripts()
KillTimer
Script.SetTimer 関数によって設定されたタイマーを停止します。
構文
Script.KillTimer(ScriptHandle nTimerId)
パラメーター
説明
nTimerId
Script.SetTimer 関数によって返されるタイ
マーの ID です。
LoadScript
指定されたスクリプトをロードします。
構文
Script.LoadScript(scriptName)
Version 1.6
704
Lumberyard 開発者ガイド
ScriptBind_Script
パラメーター
説明
scriptName
ロードするスクリプトの名前。
ReloadEntityScript
指定されたエンティティスクリプトを再ロードします。
構文
Script.ReloadEntityScript(const char *className)
パラメーター
説明
className
エンティティスクリプトの名前。
ReloadScript
スクリプトを再ロードします。
構文
Script.ReloadScript(scriptName)
パラメーター
説明
scriptName
再ロードするスクリプトの名前。
ReloadScripts
すべてのスクリプトを再ロードします。
構文
Script.ReloadScripts()
SetTimer
スクリプトのタイマーを設定します。タイマーが終了すると、SetTimer は指定された Lua 関数を呼
び出します。
構文
Script.SetTimer(int nMilliseconds, HSCRIPTFUNCTION hFunc)
タイマーに割り当てられた ID を返します。ID が指定されていない場合は nil を返します。
パラメーター
説明
nMilliseconds
トリガーの遅延をミリ秒で設定します。
Version 1.6
705
Lumberyard 開発者ガイド
ScriptBind_Sound
パラメーター
説明
luaFunction
呼び出す Lua 関数。userData を指定する場合、luaFunction は次の形式であ
る必要があります。
LuaCallback = function(userData,nTimerId)
-- function body
end;
.
userData を指定しない場合、luaFunction は次の形式である必要がありま
す。
LuaCallback = function(nTimerId)
-- function body
end;
userData
オプション。ユーザー定義のテーブルを指定します。userData を指定する場
合、テーブルはコールバック関数の最初の引数として渡されます。
bUpdateDuringPause
オプション。ゲームが一時停止モードにあってもタイマーが更新されトリガーさ
れます。
SetTimerForFunction
指定された関数のタイマーを設定します。
構文
Script.SetTimerForFunction(int nMilliseconds, const char *sFunctionName)
タイマーに割り当てられた ID を返します。ID が指定されていない場合は nil を返します。
この関数には SetTimer 関数と同じパラメーターがあります。
UnloadScript
指定されたスクリプトをアンロードします。
構文
Script.UnloadScript(scriptName)
パラメーター
説明
scriptName
アンロードするスクリプトの名前。
ScriptBind_Sound
Lua スクリプトから呼び出すことができる C++ のサウンド関数をリストします。
Version 1.6
706
Lumberyard 開発者ガイド
ScriptBind_Sound
GetAudioEnvironmentID
音声環境 TAudioEnvironmentID を取得します (ScriptHandle 内に含まれています)。
構文
Sound.GetAudioEnvironmentID(const char* const sEnvironmentName)
戻り値: TAudioEnvironmentID 値を伴う ScriptHandle、または sEnvironmentName が見つから
ない場合は nil。
パラメーター
説明
sEnvironmentName
音声環境の一意の名前。
GetAudioRtpcID
RTPC TAudioControlID を取得します (ScriptHandle 内に含まれています)。
構文
Sound.GetAudioRtpcID(const char* const sRtpcName)
戻り値: TAudioControlID 値を伴う ScriptHandle、または sRtpcName が見つからない場合は
nil。
パラメーター
説明
sRtpcName
音声 RTPC の一意の名前。
GetAudioSwitchID
スイッチ TAudioControlID を取得します (ScriptHandle 内に含まれています)。
構文
Sound.GetAudioSwitchID(const char* const sSwitchName)
戻り値: TAudioControlID 値を伴う ScriptHandle、または sSwitchName が見つからない場合は
nil。
パラメーター
説明
sSwitchName
音声スイッチの一意の名前。
GetAudioSwitchStateID
SwitchState TAudioSwitchStatelID を取得します (ScriptHandle 内に含まれています)。
構文
Version 1.6
707
Lumberyard 開発者ガイド
ScriptBind_System
Sound.GetAudioSwitchStateID(const ScriptHandle hSwitchID, const char* const
sSwitchStateName)
戻り値: TAudioSwitchStateID 値を伴う ScriptHandle、または sSwitchStateName が見つから
ない場合は nil。
パラメーター
説明
sSwitchStateName
音声スイッチ状態の一意の名前。
GetAudioTriggerID
トリガー TAudioControlID を取得します (ScriptHandle 内に含まれています)。
構文
Sound.GetAudioTriggerID(const char* const sTriggerName)
戻り値: TAudioControlID 値を伴う ScriptHandle、または sTriggerName が見つからない場合は
nil。
パラメーター
説明
sTriggerName
音声トリガーの一意の名前。
SetAudioRtpcValue
指定された音声 RTPC を指定された値に全体設定します。
構文
Sound.SetAudioRtpcValue( hRtpcID, fValue )
戻り値: nil
パラメーター
説明
hRtpcID
音声 RTPC ID のハンドル。
fValue
RTPC 値。
ScriptBind_System
このクラスはシステム機能を表示する Lua スクリプト関数を実装します。
ActivatePortal
ポータルをアクティブ化または非アクティブ化します。
Version 1.6
708
Lumberyard 開発者ガイド
ScriptBind_System
構文
System.ActivatePortal(Vec3 vPos, bool bActivate, ScriptHandle nID)
パラメーター
パラメーター
説明
vPos
位置のベクトル。
bActivate
ポータルをアクティブ化する場合は true、非ア
クティブ化する場合は false。
nID
エンティティー識別子。
AddCCommand
システムに C コマンドを追加します。
構文
System.AddCCommand(const char* sCCommandName, const char* sCommand, const
char* sHelp)
パラメーター
パラメーター
説明
sCCommandName
C コマンド名。
sCommand
コマンド文字列。
sHelp
コマンドの使用に関するヘルプ。
ApplicationTest
指定されたパラメーターでアプリケーションをテストします。
構文
System.ApplicationTest(const char* pszParam)
パラメーター
パラメーター
説明
pszParam
パラメーター.
休憩
致命的なエラーメッセージでアプリケーションを停止します。
構文
Version 1.6
709
Lumberyard 開発者ガイド
ScriptBind_System
System.Break()
BrowseURL
URL アドレスを参照します。
構文
System.BrowseURL(const char* szURL)
パラメーター
パラメーター
説明
szURL
URL 文字列。
CheckHeapValid
ヒープの有効性をチェックします。
構文
System.CheckHeapValid(const char* name)
パラメーター
パラメーター
説明
name
名前の文字列。デフォルト: <noname>。
ClearConsole
コンソールをクリアします。
構文
System.ClearConsole()
ClearKeyState
キーの状態をクリアします。
構文
System.ClearKeyState()
CreateDownload
構文
System.CreateDownload()
Version 1.6
710
Lumberyard 開発者ガイド
ScriptBind_System
DebugStats
構文
System.DebugStats(bool cp)
DeformTerrain
地形を変形させます。
構文
System.DeformTerrain()
DeformTerrainUsingMat
マテリアルを使用して地形を変形します。
構文
System.DeformTerrainUsingMat()
Draw2DLine
2D の線を描画します。
構文
System.Draw2DLine(p1x, p1y, p2x, p2y, float r, float g, float b, float alpha)
パラメーター
パラメー
ター
説明
p1x
線の開始点の X 値。
p1y
線の開始点の Y 値。
p2x
線の終端点の X 値。
p2y
線の終端点の Y 値。
r
ラベルの色の赤コンポーネント。デフォルトは1です。
g
ラベルの色の緑コンポーネント。デフォルトは1です。
b
ラベルの色の青コンポーネント。デフォルトは1です。
alpha
ラベルの色のアルファコンポーネント。デフォルトは1です。
DrawLabel
指定されたパラメーターでラベルを描画します。
Version 1.6
711
Lumberyard 開発者ガイド
ScriptBind_System
構文
System.DrawLabel(Vec3 vPos, float fSize, const char* text [, float r [, float
g [, float b [, float alpha]]]])
パラメーター
パラメーター
説明
vPos
位置のベクトル。
fSize
ラベルのサイズ。
text
ラベルの色。
r
ラベルの色の赤コンポーネント。デフォルトは1です。
g
ラベルの色の緑コンポーネント。デフォルトは1です。
b
ラベルの色の青コンポーネント。デフォルトは1です。
alpha
ラベルの色のアルファコンポーネント。デフォルトは1です。
DrawLine
線を描画します。
構文
System.DrawLine(Vec3 p1, Vec3 p2, float r, float g, float b, float alpha)
パラメーター
パラメー
ター
説明
p1
線の開始位置。
p2
線の終端位置。
r
ラベルの色の赤コンポーネント。デフォルトは1です。
g
ラベルの色の緑コンポーネント。デフォルトは1です。
b
ラベルの色の青コンポーネント。デフォルトは1です。
alpha
ラベルの色のアルファコンポーネント。デフォルトは1です。
DrawText
テキストを描画します。
構文
System.DrawText(float x, float y, const char* text, const char* fontName,
float size, float r, float g, float b, float alpha)
Version 1.6
712
Lumberyard 開発者ガイド
ScriptBind_System
パラメーター
パラメー
ター
説明
x
テキストの X 位置。デフォルトは 0 です。
y
テキストの Y 位置。デフォルトは 0 です。
text
表示するテキスト。デフォルトは空の文字列です。
fontName フォント名。デフォルト: default。
size
テキストのサイズ。デフォルトは 16 です。
r
ラベルの色の赤コンポーネント。デフォルトは1です。
g
ラベルの色の緑コンポーネント。デフォルトは1です。
b
ラベルの色の青コンポーネント。デフォルトは1です。
alpha
ラベルの色のアルファコンポーネント。デフォルトは1です。
DumpMemoryCoverage
メモリカバレッジをダンプします。
構文
System.DumpMemoryCoverage()
この関数はメモリ断片化の調査に役立ちます。#System.DumpMemoryCoverage() がコンソールか
ら呼び出されると、DumpMemoryCoverage は MemoryCoverage.bmp ファイルに行を追加します。
これは行数が初めて最大になったときに生成されます。
DumpMemStats
メモリ統計をダンプします。
構文
System.DumpMemStats(bUseKB)
パラメーター
パラメーター
説明
bUseKB
KB を使用する場合は true、その他の場合は
false。デフォルト: false。
DumpMMStats
MM 統計をダンプします。
構文
Version 1.6
713
Lumberyard 開発者ガイド
ScriptBind_System
System.DumpMMStats()
DumpWinHeaps
ウィンドウヒープをダンプします。
構文
System.DumpWinHeaps()
EnableOceanRendering
海洋のレンダリングを有効/無効にします。
構文
System.EnableOceanRendering()
パラメーター
パラメーター
説明
bOcean
海洋のレンダリングをアクティブ化するには true、非アクティブ化するには
false。
EnumAAFormats
マルチサンプルアンチエイリアス形式を列挙します。
構文
System.EnumAAFormats()
EnumDisplayFormats
表示形式を列挙します。
構文
System.EnumDisplayFormats()
エラー
エラー重大度付きのメッセージテキストを表示します。
構文
System.Error(const char* sParam)
Version 1.6
714
Lumberyard 開発者ガイド
ScriptBind_System
パラメーター
パラメーター
説明
sParam
記録するテキスト。デフォルトは空の文字列で
す。
ExecuteCommand
コマンドを実行します。
構文
System.ExecuteCommand(const char* szCmd)
パラメーター
パラメーター
説明
szCmd
コマンド文字列。
GetConfigSpec
config の仕様を取得します。
構文
System.GetConfigSpec()
GetCurrAsyncTime
現在の非同期時刻を取得します。
構文
System.GetCurrAsyncTime()
GetCurrTime
現在の時刻を取得します。
構文
System.GetCurrTime()
GetCVar
コンソール変数の値を取得します。
構文
System.GetCVar(const char* sCVarName)
Version 1.6
715
Lumberyard 開発者ガイド
ScriptBind_System
パラメーター
パラメーター
説明
sCVarName
変数の名前。
GetEntities
現在レベルに存在するすべてのエンティティを含むテーブルを返します。
構文
System.GetEntities(Vec3 center, float radius)
パラメーター
パラメーター
説明
center
エンティティを取得するエリアの中心位置ベクトル。デフォルトは (0, 0, 0) で
す。
radius
エリアの半径。デフォルトは 0 です。
GetEntitiesByClass
指定されたクラスのすべてのエンティティを取得します。
構文
System.GetEntitiesByClass(const char* EntityClass)
パラメーター
パラメーター
説明
EntityClass
エンティティクラス名。
GetEntitiesInSphere
指定された球体内に含まれるすべてのエンティティを取得します。
構文
System.GetEntitiesInSphere(Vec3 center, float radius)
パラメーター
パラメーター
説明
center
エンティティを参照する球体の中心位置ベクト
ル。
radius
球体の半径.
Version 1.6
716
Lumberyard 開発者ガイド
ScriptBind_System
GetEntitiesInSphereByClass
特定のクラス名の指定された球体内に含まれるすべてのエンティティを取得します。
構文
System.GetEntitiesInSphereByClass(Vec3 center, float radius, const char*
EntityClass)
パラメーター
パラメーター
説明
center
エンティティを参照する球体の中心位置ベクト
ル。
radius
球体の半径.
EntityClass
エンティティクラス名。
GetEntity
ID からエンティティを取得します。
構文
System.GetEntity(entityId)
パラメーター
パラメーター
説明
entityId
エンティティ識別子 (svtNumber または
ScriptHandle)。
GetEntityByName
指定された名前の最初のエンティティのエンティティテーブルを取得します。同じ名前の複数のエン
ティティがある場合は、最初のものを返します。
構文
System.GetEntityByName(const char *sEntityName)
パラメーター
パラメーター
説明
sEntityName
検索するエンティティの名前。
GetEntityClass
ID からエンティティクラスを取得します。
Version 1.6
717
Lumberyard 開発者ガイド
ScriptBind_System
構文
System.GetEntityClass(entityId)
パラメーター
パラメーター
説明
entityId
エンティティ識別子 (svtNumber または
ScriptHandle)。
GetEntityIdByName
指定された名前の最初のエンティティのエンティティ ID を取得します。同じ名前の複数のエンティ
ティがある場合は、最初のものを返します。
構文
System.GetEntityIdByName(const char *sEntityName)
パラメーター
パラメーター
説明
sEntityName
検索するエンティティの名前。
GetFrameID
フレーム識別子を取得します。
構文
System.GetFrameID()
GetFrameTime
フレームの時間を取得します。
構文
System.GetFrameTime()
GetHDRDynamicMultiplier
HDR の動的乗数を取得します。
構文
System.GetHDRDynamicMultiplier()
GetLocalOSTime
ローカルオペレーティングシステムの時刻を取得します。
Version 1.6
718
Lumberyard 開発者ガイド
ScriptBind_System
構文
System.GetLocalOSTime()
GetNearestEntityByClass
指定されたクラスの最も近いエンティティを取得します。
構文
System.GetNearestEntityByClass(Vec3 center, float radius, const char
*className)
パラメーター
パラメーター
説明
center
エンティティを参照するエリアの中心位置ベク
トル。
radius
球体の半径.
className
エンティティクラス名。
GetOutdoorAmbientColor
屋外のアンビエント色を取得します。
構文
System.GetOutdoorAmbientColor()
GetPhysicalEntitiesInBox
指定されたエリア内に含まれるすべてのエンティティを取得します。
構文
System.GetPhysicalEntitiesInBox(Vec3 center, float radius)
パラメーター
パラメーター
説明
center
エンティティを参照するエリアの中心位置ベク
トル。
radius
球体の半径.
GetPhysicalEntitiesInBoxByClass
特定のクラス名の指定されたエリア内に含まれるすべてのエンティティを取得します。
構文
Version 1.6
719
Lumberyard 開発者ガイド
ScriptBind_System
System.GetPhysicalEntitiesInBoxByClass(Vec3 center, float radius, const char
*className)
パラメーター
パラメーター
説明
center
エンティティを参照するエリアの中心位置ベク
トル。
radius
球体の半径.
className
エンティティクラス名。
GetPostProcessFxParam
後処理効果のパラメーター値を取得します。
構文
System.GetPostProcessFxParam(const char* pszEffectParam, value)
パラメーター
パラメーター
説明
pszEffectParam
後処理効果のパラメーター。
value
パラメーターの値 (浮動小数点または文字列)。
GetScreenFx
後処理効果のパラメーター値を取得します。
Note
これは GetPostProcessFxParam に簡便性を持たせるラッパー関数です。
構文
System.GetScreenFx(const char* pszEffectParam, value)
パラメーター
パラメーター
説明
pszEffectParam
後処理効果のパラメーター。
value
パラメーターの値 (浮動小数点または文字列)。
GetSkyColor
空の色 (屋外アンビエント色) を取得します。
Version 1.6
720
Lumberyard 開発者ガイド
ScriptBind_System
構文
Vec3 System.GetSkyColor()
戻り値: {x,y,z} ベクトル (x=r,y=g,z=b) で表わされる空の色。
GetSkyHighlight
空のハイライト部分のパラメーターを取得します。パラメーターの説明については、
「SetSkyHighlight (p. 732)」を参照してください。
構文
System.GetSkyHighlight(SmartScriptTable params)
GetSunColor
屋外での太陽の色を取得します。
構文
Vec3 System.GetSunColor()
戻り値: {x,y,z} ベクトル (x=r,y=g,z=b) で表わされる太陽の色。
GetSurfaceTypeIdByName
表面タイプの識別子を名前で取得します。
構文
System.GetSurfaceTypeIdByName(const char* surfaceName)
パラメーター
パラメーター
説明
surfaceName
表面名。
GetSurfaceTypeNameById
表面タイプの名前を識別子で取得します。
構文
System.GetSurfaceTypeNameById(int surfaceId)
パラメーター
パラメーター
説明
surfaceId
表面の識別子。
Version 1.6
721
Lumberyard 開発者ガイド
ScriptBind_System
GetSystemMem
システムのメモリ量を取得します。
構文
System.GetSystemMem()
GetTerrainElevation
指定された位置の地形の標高を取得します。
構文
System.GetTerrainElevation(Vec3 v3Pos)
パラメーター
パラメーター
説明
v3Pos
確認する地形の位置。
GetUserName
このマシンのユーザー名を取得します。
構文
System.GetUserName()
GetViewCameraAngles
ビューカメラの角度を取得します。
構文
System.GetViewCameraAngles()
GetViewCameraDir
ビューカメラの方向を取得します。
構文
System.GetViewCameraDir()
GetViewCameraFov
ビューカメラの FOV を取得します。
構文
System.GetViewCameraFov()
Version 1.6
722
Lumberyard 開発者ガイド
ScriptBind_System
GetViewCameraPos
ビューカメラの位置を取得します。
構文
System.GetViewCameraPos()
GetViewCameraUpDir
ビューカメラの上向き方向を取得します。
構文
System.GetViewCameraUpDir()
GetWind
風向を取得します。
構文
System.SetWind()
IsDevModeEnable
ゲームが、特定のスクリプト関数機能 (神モード、飛行モードなど) を有効にする開発者モード (チー
トモード) で実行されているかどうかを確認します。
構文
System.IsDevModeEnable()
IsEditing
システムが純粋なエディタモード (エディタゲームモードではない) になっているかどうかを確認しま
す。
構文
System.IsEditing()
IsEditor
システムがエディタかどうかを確認します。
構文
System.IsEditor()
IsHDRSupported
HDR がサポートされているかどうかを確認します。
Version 1.6
723
Lumberyard 開発者ガイド
ScriptBind_System
構文
System.IsHDRSupported()
IsMultiplayer
ゲームがマルチプレイヤーかどうかを確認します。
構文
System.IsMultiplayer()
IsPointIndoors
ポイントが屋内かどうかを確認します。
構文
System.IsPointIndoors(Vec3 vPos)
パラメーター
パラメーター
説明
vPos
位置のベクトル。デフォルトは (0, 0, 0) です。
IsPointVisible
指定されたポイントが表示されているかどうかを確認します。
構文
System.IsPointVisible(Vec3 point)
パラメーター
パラメーター
説明
point
ポイントのベクトル。
IsPS20Supported
PS20 がサポートされているかどうかを確認します。
構文
System.IsPS20Supported()
IsValidMapPos
位置が有効なマップ位置であるかどうかを確認します。
構文
Version 1.6
724
Lumberyard 開発者ガイド
ScriptBind_System
System.IsValidMapPos(Vec3 v)
パラメーター
パラメーター
説明
v
位置のベクトル。デフォルトは (0, 0, 0) です。
LoadFont
フォントをロードします。
構文
System.LoadFont(const char* pszName)
パラメーター
パラメーター
説明
pszName
フォント名。
LoadLocalizationXml
テキストとダイアログのローカリゼーションデータを含む Excel にエクスポートされた XML ファイル
をロードします。
構文
System.LoadLocalizationXml(const char *filename)
ログ
メッセージをログファイルとコンソールに記録します。
構文
System.Log(const char* sText)
パラメーター
パラメーター
説明
sText
記録するテキスト。
LogAlways
詳細設定が 0 の場合でもデータを記録します。
構文
System.LogAlways(const char* sText)
Version 1.6
725
Lumberyard 開発者ガイド
ScriptBind_System
パラメーター
パラメーター
説明
sText
記録するテキスト。
LogToConsole
コンソールにメッセージを記録します。
構文
System.LogToConsole(const char* sText)
パラメーター
パラメーター
説明
sText
記録するテキスト。
PrepareEntityFromPool
指定されたブックマークが付けられたエンティティをプールから持ってきて準備します。
構文
System.PrepareEntityFromPool(entityId)
パラメーター
パラメーター
説明
entityId
エンティティ識別子 (番号または
ScriptHandle)。
bPrepareNow
(オプション) 別のエンティティの準備がすで
に進行中の場合、プール内のエンティティを
キューに入れずにすぐに準備するかどうかを指
定します。
ProjectToScreen
画面に射影します (レンダラー外で使用する場合、機能は保証されません)。
構文
System.ProjectToScreen(Vec3 vec)
パラメーター
パラメーター
説明
vec
位置のベクトル。
Version 1.6
726
Lumberyard 開発者ガイド
ScriptBind_System
終了
プログラムを終了します。
構文
System.Quit()
QuitInNSeconds
指定された秒数でアプリケーションを修了します。
構文
System.QuitInNSeconds(float fInNSeconds)
パラメーター
パラメーター
説明
fInNSeconds
終了までの秒数。
RayTraceCheck
ワールドと静的オブジェクトを確認します。
構文
System.RayTraceCheck(Vec3 src, Vec3 dst, int skipId1, int skipId2)
RayWorldIntersection
ワールドにレイを発射します。
構文
System.RayWorldIntersection(Vec3 vPos, Vec3 vDir, int nMaxHits, int
iEntTypes)
パラメーター
パラメーター
説明
vPos
位置のベクトル。デフォルトは (0, 0, 0) です。
vDir
方向ベクトル。デフォルトは (0, 0, 0) です。
nMaxHits
最大ヒット数。
iEntTypes
RemoveEntity
指定されたエンティティを削除します。
Version 1.6
727
Lumberyard 開発者ガイド
ScriptBind_System
構文
System.RemoveEntity(ScriptHandle entityId)
パラメーター
パラメーター
説明
entityId
エンティティー識別子。
ResetPoolEntity
エンティティのブックマークされたメモリをリセットしてメモリを開放します。
構文
System.ResetPoolEntity(entityId)
パラメーター
パラメーター
説明
entityId
エンティティ識別子 (svtnumber または
ScriptHandle)。
ReturnEntityToPool
構文
System.ReturnEntityToPool(entityId)
戻り値: プールにブックマークされたエンティティを返し、それを破棄します。
パラメーター
パラメーター
説明
entityId
エンティティ識別子 (svtnumber または
ScriptHandle)。
SaveConfiguration
設定を保存します。
構文
System.SaveConfiguration()
ScanDirectory
ディレクトリをスキャンします。
Version 1.6
728
Lumberyard 開発者ガイド
ScriptBind_System
構文
System.ScanDirectory(const char* pszFolderName, int nScanMode)
パラメーター
パラメーター
説明
pszFolderName
フォルダー名。
nScanMode
フォルダのスキャンモード。次のように設定で
きます。SCANDIR_ALL (0)、SCANDIR_FILES
(1)、または SCANDIR_SUBDIRS (2)。
ScreenToTexture
構文
System.ScreenToTexture()
SetBudget
システム予算を設定します。
構文
System.SetBudget(int sysMemLimitInMB, int videoMemLimitInMB, float
frameTimeLimitInMS, int soundChannelsPlayingLimit, int soundMemLimitInMB,
int soundCPULimitInPercent, int numDrawCallsLimit)
パラメーター
パラメーター
説明
sysMemLimitInMB
システムュメモリ量の制限 (MB)。デフォルトは 512 です。
videoMemLimitInMB
ビデオメモリ量の制限 (MB)。デフォルトは 256 です。
frameTimeLimitInMS
フレーム時間の制限 (MS)。デフォルトは 50.0f です。
soundChannelsPlayingLimit
音声チャネル再生数の制限。デフォルトは 64 です。
soundMemLimitInMB
音声メモリの制限 (MB)。デフォルトは 64 です。
soundCPULimitInPercent
音声の CPU 使用率の制限 (パーセント)。デフォルトは 5 です。
numDrawCallsLimit
描画呼び出し数の制限。デフォルトは 2000 です。
SetConsoleImage
コンソールイメージを設定します。
構文
System.SetConsoleImage(const char* pszName, bool bRemoveCurrent)
Version 1.6
729
Lumberyard 開発者ガイド
ScriptBind_System
パラメーター
パラメーター
説明
pszName
テクスチャイメージの名前。
bRemoveCurrent
現在のイメージを削除するには true、それ以外
の場合は false。
SetCVar
コンソール変数の値を設定します。
構文
System.SetCVar(const char* sCVarName, value)
パラメーター
パラメーター
説明
sCVarName
変数の名前。
value
変数の値 (浮動小数点または文字列)。
SetGammaDelta
ガンマ/デルタ値を設定します。
構文
System.SetGammaDelta(float fDelta)
パラメーター
パラメーター
説明
fDelta
デルタ値。デフォルトは 0 です。
SetOutdoorAmbientColor
屋外のアンビエント色を設定します。
構文
System.GetOutdoorAmbientColor(v3Color)
パラメーター
パラメーター
説明
v3Color
屋外アンビエント色の値。
Version 1.6
730
Lumberyard 開発者ガイド
ScriptBind_System
SetPostProcessFxParam
後処理効果のパラメーター値を設定します。
構文
System.SetPostProcessFxParam(const char* pszEffectParam, value)
パラメーター
パラメーター
説明
pszEffectParam
後処理効果のパラメーター。
value
パラメーターの値 (svtNumber、svtObject ま
たは svtString)。
SetScissor
シザリング画面領域を設定します。
構文
System.SetScissor(float x, float y, float w, float h)
SetScreenFx
後処理効果のパラメーター値を設定します。
Note
これは SetPostProcessFxParam に簡便性を持たせるラッパー関数です。
構文
System.SetScreenFx(pszEffectParam, value)
パラメーター
パラメーター
説明
pszEffectParam
後処理効果のパラメーター。
value
パラメーターの値 (svtNumber、svtObject ま
たは svtString)。
SetSkyColor
空の色 (屋外アンビエント色) を設定します。
構文
System.SetSkyColor(Vec3 vColor)
Version 1.6
731
Lumberyard 開発者ガイド
ScriptBind_System
パラメーター
パラメーター
説明
vColor
{x,y,z} ベクトル (x=r,y=g,z=b) で表わされる空
の色。
SetSkyHighlight
空のハイライト部分のパラメーター。
構文
System.SetSkyHighlight(SmartScriptTable params)
パラメーター
パラメーター
説明
params
空のハイライト部分のパラメーターのテーブ
ル。
Params テーブルパラメーター
ハイライトのパラメーター
説明
color
空のハイライト色
direction
空のハイライトのワールド空間での方向。
pos
空のハイライトのワールド空間での位置。
size
空のハイライトのスケール。
SetSunColor
屋外のみに関連する太陽の色を設定します。
構文
System.SetSunColor(Vec3 vColor)
パラメーター
パラメーター
説明
vColor
{x,y,z} ベクトル (x=r,y=g,z=b) で表わされる太
陽の色。
SetViewCameraFov
ビューカメラの FOV を設定します。
Version 1.6
732
Lumberyard 開発者ガイド
ScriptBind_System
構文
System.SetViewCameraFov(float fov)
SetVolumetricFogModifiers
ボリューメトリックフォグの修飾子を設定します。
構文
System.SetVolumetricFogModifiers(float gobalDensityModifier, float
atmosphereHeightModifier)
パラメーター
パラメーター
説明
gobalDensityModifier
グローバル密度の修飾子。
atmosphereHeightModifier
大気の高さの修飾子。
SetWaterVolumeOffset
SetWaterLevel は今のところ 3D エンジンではサポートされていません。
構文
System.SetWaterVolumeOffset()
SetWind
風向を設定します。
構文
System.SetWind(Vec3 vWind)
パラメーター
パラメーター
説明
vWind
風向。デフォルト値は (0, 0, 0) です。
ShowConsole
コンソールを表示または非表示にします。
構文
System.ShowConsole(int nParam)
Version 1.6
733
Lumberyard 開発者ガイド
ScriptBind_System
パラメーター
パラメーター
説明
nParam
1 でコンソールを表示、0 で非表示にします。デ
フォルトは 0 です。
ShowDebugger
デバッガーを表示します。
構文
System.ShowDebugger()
SpawnEntity
エンティティがスポーンされます。
構文
System.SpawnEntity(SmartScriptTable params)
パラメーター
パラメーター
説明
params
エンティティのパラメーター。
ViewDistanceGet
ビュー距離を取得します。
構文
System.ViewDistanceSet()
ViewDistanceSet
ビュー距離を設定します。
構文
System.ViewDistanceSet(float fViewDist)
パラメーター
パラメーター
説明
fViewDist
表示 距離.
Version 1.6
734
Lumberyard 開発者ガイド
ScriptBind アクション関数
警告
警告重大度付きのメッセージテキストを表示します。
構文
System.Warning(const char* sParam)
パラメーター
パラメーター
説明
sParam
記録するテキスト。デフォルト値は空の文字列
です。
ScriptBind アクション関数
Lua スクリプトから呼び出すことができる C++ のアクション関数をリストします。
トピック
• ScriptBind_Action (p. 735)
• ScriptBind_ActionMapManager (p. 749)
• ScriptBind_ActorSystem (p. 752)
• ScriptBind_GameStatistics (p. 752)
• ScriptBind_GameToken (p. 754)
• ScriptBind_Inventory (p. 755)
• ScriptBind_ItemSystem (p. 757)
• ScriptBind_Network (p. 760)
• ScriptBind_UIAction (p. 760)
• ScriptBind_Vehicle (p. 772)
• ScriptBind_VehicleSeat (p. 779)
• ScriptBind_VehicleSystem (p. 781)
ScriptBind_Action
アクション関連 Lua スクリプトに依存する関数をリストします。パラメーターが存在する場合、署名
に示されるデータ型は基礎となる C++ 関数のデータ型を反映しています。
ActivateEffect
指定された効果をアクティブ化します。
構文
Action.ActivateEffect(const char * name)
パラメーター
説明
name
アクティブ化する効果を指定します。
Version 1.6
735
Lumberyard 開発者ガイド
ScriptBind_Action
ActivateExtensionForGameObject
ゲームオブジェクトの指定された拡張子をアクティブ化します。
構文
Action.ActivateExtensionForGameObject(ScriptHandle entityId, const char
*extension, bool activate)
パラメーター
説明
entityId
エンティティの識別子。
extension
拡張機能の名前。
activate
true を指定して拡張子をアクティブ化する、ま
たは false を指定して非アクティブ化します。
AddAngleSignal
シグナルの角度を追加します。
構文
Action.AddAngleSignal(ScriptHandle entityId, float fAngle, float
fFlexibleBoundary, const char *sSignal)
パラメーター
説明
entityId
エンティティの識別子。
fAngle
角度の値。
fFlexibleBoundary
フレキシブルな境界のサイズ。
sSignal
シグナルの文字列。
AddRangeSignal
シグナルの範囲を追加します。
構文
Action.AddRangeSignal(ScriptHandle entityId, float fRadius, float
fFlexibleBoundary, const char *sSignal)
パラメーター
説明
entityId
エンティティの識別子。
fRadius
範囲エリアの半径。
fFlexibleBoundary
フレキシブルな境界のサイズ。
Version 1.6
736
Lumberyard 開発者ガイド
ScriptBind_Action
パラメーター
説明
sSignal
シグナルの文字列。
AddTargetRangeSignal
指定されたパラメーターがあるターゲット範囲シグナルを追加します。
構文
Action.AddTargetRangeSignal(ScriptHandle entityId, ScriptHandle targetId,
float fRadius, float fFlexibleBoundary, const char *sSignal)
パラメーター
説明
entityId
エンティティの識別子。
targetId
ターゲットの識別子。
fRadius
範囲エリアの半径。
fFlexibleBoundary
フレキシブルな境界のサイズ。
sSignal
シグナルの文字列。
BanPlayer
指定されたプレーヤーをバンします。
構文
Action.BanPlayer(ScriptHandle entityId, const char* message)
パラメーター
説明
entityId
エンティティの識別子。
message
バンのメッセージ。
BindGameObjectToNetwork
指定されたゲームオブジェクトをネットワークに結合します。
構文
Action.BindGameObjectToNetwork(ScriptHandle entityId)
パラメーター
説明
entityId
ネットワークに結合するエンティティの識別
子。
Version 1.6
737
Lumberyard 開発者ガイド
ScriptBind_Action
CacheItemGeometry
項目ジオメトリをキャッシュします。
構文
Action.CacheItemGeometry(const char *itemName)
パラメーター
説明
itemName
項目の文字列名。
CacheItemSound
項目の音声をキャッシュします。
構文
Action.CacheItemSound(const char *itemName)
パラメーター
説明
itemName
項目の文字列名。
ClearEntityTags
指定されたエンティティのタグをクリアします。
構文
Action.ClearEntityTags(ScriptHandle entityId)
パラメーター
説明
entityId
エンティティの識別子。
ClearStaticTag
指定されたエンティティの指定された静的タグをクリアします。
構文
Action.ClearStaticTag(ScriptHandle entityId, const char *staticId)
パラメーター
説明
entityId
エンティティの識別子。
Version 1.6
738
Lumberyard 開発者ガイド
ScriptBind_Action
パラメーター
説明
staticId
静的タグの識別子。
ConnectToServer
指定されたサーバーに接続します。
構文
Action.ConnectToServer(char* server)
パラメーター
説明
server
接続サーバーを指定する文字列。
CreateGameObjectForEntity
指定されたエンティティ ID のゲームオブジェクトを作成します。
構文
Action.CreateGameObjectForEntity(ScriptHandle entityId)
パラメーター
説明
entityId
エンティティの識別子。
DestroyRangeSignaling
範囲シグナリングを削除します。
構文
Action.DestroyRangeSignaling(ScriptHandle entityId)
パラメーター
説明
entityId
エンティティの識別子。
DisableSignalTimer
シグナルタイマーを無効にします。
構文
Action.DisableSignalTimer(ScriptHandle entityId, const char *sText)
Version 1.6
739
Lumberyard 開発者ガイド
ScriptBind_Action
パラメーター
説明
entityId
エンティティの識別子。
sText
シグナルのテキスト。
DontSyncPhysics
指定されたエンティティの物理演算をエンジンが同期しないように指示します。
構文
Action.DontSyncPhysics(ScriptHandle entityId)
パラメーター
説明
entityId
エンティティの識別子。
EnableRangeSignaling
指定されたエンティティの範囲シグナリングを有効または無効にします。
構文
Action.EnableRangeSignaling(ScriptHandle entityId, bool bEnable)
パラメーター
説明
entityId
エンティティの識別子。
bEnable
範囲シグナリングを有効または無効にします。
EnableSignalTimer
シグナルタイマーを有効にします。
構文
Action.EnableSignalTimer(ScriptHandle entityId, const char *sText)
パラメーター
説明
entityId
エンティティの識別子。
sText
シグナルのテキスト。
ForceGameObjectUpdate
ゲームオブジェクトを強制的に更新します。
Version 1.6
740
Lumberyard 開発者ガイド
ScriptBind_Action
構文
Action.ForceGameObjectUpdate(ScriptHandle entityId, bool force)
パラメーター
説明
entityId
エンティティの識別子。
force
強制的に更新するには true、そうでない場合は
false を指定します。
GetClassName
指定された classId があればそのクラス名を返します。
構文
Action.GetClassName(int classId)
GetPlayerList
現在のプレーヤーのリストを取得します。
構文
Action.GetPlayerList()
GetServer
指定された番号に対応するサーバーを取得します。
構文
Action.GetServer(int number)
パラメーター
説明
number
サーバーの数。
GetServerTime
サーバーの現在の時刻を取得します。
構文
Action.GetServerTime()
GetWaterInfo
指定された位置の水についての情報を取得します。
Version 1.6
741
Lumberyard 開発者ガイド
ScriptBind_Action
構文
Action.GetWaterInfo(Vec3 pos)
パラメーター
説明
pos
情報が返される位置。
HasAI
エンティティに関連付けられた AI オブジェクトがあり AI システムに登録されている場合は true を
返します。
構文
Action.HasAI(ScriptHandle entityId)
IsChannelOnHold
指定されたチャネルが保留かどうかを確認します。
構文
Action.IsChannelOnHold(int channelId)
パラメーター
説明
channelId
チャネルの識別子。
IsChannelSpecial
チャネルが特殊な場合は true を返します。
構文
Action.IsChannelSpecial()
IsClient
現在のスクリプトがクライアントで実行される場合は true を返します。
構文
Action.IsClient()
IsGameObjectProbablyVisible
指定されたオブジェクトが表示されやすい場合は true を返します。
Version 1.6
742
Lumberyard 開発者ガイド
ScriptBind_Action
構文
Action.IsGameObjectProbablyVisible(ScriptHandle gameObject)
パラメーター
説明
gameObject
表示されやすさを確認するゲームオブジェク
ト。
IsGameStarted
ゲームが開始されている場合は true を返します。
構文
Action.IsGameStarted()
IsImmersivenessEnabled
大規模マルチプレイヤーが有効になっている場合は true を返します。
構文
Action.IsImmersivenessEnabled()
IsRMIServer
現在のスクリプトが RMI (リモートメソッドインボケーション) サーバーで実行されている場合は
true を返します。
構文
Action.IsRMIServer()
IsServer
現在のスクリプトがサーバーで実行される場合は true を返します。
構文
Action.IsServer()
LoadXML
指定されたファイルから XML データをロードします。詳細については、「Lua XML ローダーの使
用 (p. 477)」を参照してください。
構文
Action.LoadXML(const char * definitionFile, const char * dataFile)
Version 1.6
743
Lumberyard 開発者ガイド
ScriptBind_Action
パラメーター
説明
definitionFile
dataFile に含まれるデータの種類を宣言する XML ファイル
の名前。
dataFile
definitionFile に記述された Lua データを含む XML ファ
イルの名前。
PauseGame
ゲームを一時停止モードにします。
構文
Action.PauseGame(bool pause)
パラメーター
説明
pause
ゲームを一時停止モードに設定するには true を
指定します。ゲームを再開するには false を指
定します。
Persistent2DText
永続的な 2D テキストを追加します。
構文
Action.Persistent2DText(const char* text, float size, Vec3 color, const char*
name, float timeout)
パラメーター
説明
text
表示するテキスト。
size
2D テキストのサイズ。
color
2D テキストの色。
name
2D テキストに割り当てられた名前。
timeout
2D テキストのタイムアウト。
PersistentArrow
ワールドに永続的な矢印を追加します。
構文
Action.PersistentArrow(Vec3 pos, float radius, Vec3 dir, Vec3 color, const
char* name, float timeout)
Version 1.6
744
Lumberyard 開発者ガイド
ScriptBind_Action
パラメーター
説明
pos
矢印の位置。
radius
矢印の半径。
dir
矢印の方向。
color
矢印の色。
name
矢印に割り当てられた名前。
timeout
矢印のタイムアウト。
PersistentEntityTag
永続的なエンティティのタグを追加します。
構文
Action.PersistentEntityTag(ScriptHandle entityId, const char *text)
パラメーター
説明
entityId
エンティティの識別子。
text
エンティティのタグのテキスト。
PersistentLine
ワールドに永続的な線を追加します。
構文
Action.PersistentLine(Vec3 start, Vec3 end, Vec3 color, const char* name,
float timeout)
パラメーター
説明
start
線の開始位置。
end
線の終了位置。
color
線の色。
name
線に割り当てられた名前。
timeout
線のタイムアウト。
PersistentSphere
ワールドに永続的な球体を追加します。
Version 1.6
745
Lumberyard 開発者ガイド
ScriptBind_Action
構文
Action.PersistentSphere(Vec3 pos, float radius, Vec3 color, const char* name,
float timeout)
パラメーター
説明
pos
球体の位置。
radius
球体の半径。
color
球体の色。
name
球体に割り当てられた名前。
timeout
球体のタイムアウト。
PreLoadADB
この関数を使用して ADB ファイルを事前キャッシュします。
構文
Action.PreLoadADB(const char* adbFileName)
パラメーター
説明
adbFileName
プリロードするアニメーション ADB ファイルの
パスとファイル名。
RefreshPings
すべてのサーバーで ping を更新します。
構文
Action.RefreshPings()
RegisterWithAI
エンティティを AI システムに登録し、これに関連付けられる AI オブジェクトを作成します。
構文
Action.RegisterWithAI()
ResetRangeSignaling
範囲シグナリングをリセットします。
構文
Version 1.6
746
Lumberyard 開発者ガイド
ScriptBind_Action
Action.ResetRangeSignaling(ScriptHandle entityId)
パラメーター
説明
entityId
エンティティの識別子。
ResetSignalTimer
シグナルのタイマーのレートをリセットします。
構文
Action.ResetSignalTimer(ScriptHandle entityId, const char *sText)
パラメーター
説明
entityId
エンティティの識別子。
sText
シグナルのテキスト。
ResetToNormalCamera
カメラを最後に保存された有効なビューにリセットします。
構文
Action.ResetToNormalCamera()
SaveXML
指定された XML データをファイルシステムに保存します。
構文
Action.SaveXML(const char * definitionFile, const char * dataFile,
SmartScriptTable dataTable)
パラメーター
説明
definitionFile
dataFile に含まれるデータの種類を宣言する
XML ファイルの名前。詳細については、「Lua
XML ローダーの使用 (p. 477)」を参照してくだ
さい。
dataFile
definitionFile に記述された Lua データを含
む XML ファイルの名前。
dataTable
データテーブルの名前。
Version 1.6
747
Lumberyard 開発者ガイド
ScriptBind_Action
SendGameplayEvent
ゲームプレイのイベントを送信します。
構文
Action.SendGameplayEvent(ScriptHandle entityId, int event)
パラメーター
説明
entityId
エンティティの識別子。
event
イベントの整数。
SetAimQueryMode
AI プロキシに照準クエリモードを設定します。デフォルトでは、キャラクターが照準を合わせている
場合、AI プロキシは移動コントローラーにクエリを送信します。mode パラメーターに別のキーワー
ドを使用して、この動作をオーバーライドできます。
構文
Action.SetAimQueryMode(ScriptHandle entityId, int mode)
パラメーター
説明
entityId
エンティティの識別子。
mode
以下の値のいずれかを指定します。QueryAimFromMovementController
(デフォルト)、OverriddenAndAiming、または
OverriddenAndNotAiming
SetNetworkParent
ネットワークの親を設定します。
構文
Action.SetNetworkParent(ScriptHandle entityId, ScriptHandle parentId)
パラメーター
説明
entityId
エンティティの識別子。
parentID
親ネットワークの識別子。
SetSignalTimerRate
シグナルのタイマーのレートを設定します。
Version 1.6
748
Lumberyard 開発者ガイド
ScriptBind_ActionMapManager
構文
Action.SetSignalTimerRate(ScriptHandle entityId, const char *sText, float
fRateMin, float fRateMax)
パラメーター
説明
entityId
エンティティの識別子。
sText
シグナルのテキスト。
fRateMin
シグナルのタイマーの最小レート。
fRateMax
シグナルのタイマーの最大レート。
SetViewCamera
前回の有効なビューを保存して、現在のカメラ設定でオーバーライドします。
構文
Action.SetViewCamera()
ScriptBind_ActionMapManager
アクションマップマネージャーは、ゲーム内の入力コントロールを処理するための高レベルインター
フェイスを提供します。アクションマップとは、特定のゲームモード (ヘリコプターの操縦など) 用の
キーまたはボタンのマッピングのセットです。詳細については、「コントローラデバイスとゲームの
入力 (p. 335)」を参照してください。
EnableActionFilter
指定されたアクションフィルタを有効または無効にします。アクションフィルタを使用し
て、moveleft や moveright のようなアクションを成功または失敗にできます。詳細については、
「アクションフィルタ (p. 340)」を参照してください。
構文
ActionMapManager.EnableActionFilter( name, enable )
パラメーター
説明
name
フィルタの名前。
enable
true を指定するとフィルタが有効にな
り、false で無効になります。
EnableActionMap
アクションマップを有効または無効にします。
Version 1.6
749
Lumberyard 開発者ガイド
ScriptBind_ActionMapManager
構文
ActionMapManager.EnableActionMap(const char *name, bool enable)
パラメーター
説明
name
有効または向こうにするアクションマップの名
前。
enable
true を指定するとアクションマップが有効にな
り、false で無効になります。
EnableActionMapManager
アクションマップマネージャーを有効または無効にします。
構文
ActionMapManager.EnableActionMapManager( enable, resetStateOnDisable )
パラメーター
説明
enable
アクションマップマネージャーを有効または無
効にします。true を指定するとアクションマッ
プマネージャーが有効になり、false で無効に
なります。
resetStateOnDisable
アクションマップマネージャーが無効になった
ときにアクションの状態をリセットします。
GetDefaultActionEntity
現在設定されているデフォルトのアクションエンティティを取得します。
構文
ActionMapManager.GetDefaultActionEntity()
InitActionMaps
指定されたファイル内で見つかったアクションマップとフィルタを初期化します。
構文
ActionMapManager.InitActionMaps( path )
パラメーター
説明
path
XML ファイルのパス。
Version 1.6
750
Lumberyard 開発者ガイド
ScriptBind_ActionMapManager
IsFilterEnabled
指定されたフィルタが現在有効かどうかのクエリ。
構文
ActionMapManager.IsFilterEnabled( filterName )
パラメーター
説明
filterName
ステータスを確認するフィルタの名前。
LoadControllerLayoutFile
指定されたコントローラーレイアウトをアクションマップマネージャーにロードします。
構文
ActionMapManager.LoadControllerLayoutFile( layoutName )
パラメーター
説明
layoutName
レイアウトの名前。
LoadFromXML
XML ファイルから情報をロードします。
構文
ActionMapManager.LoadFromXML(const char *name)
パラメーター
説明
name
ロードする XML ファイルの名前。
SetDefaultActionEntity
新しいデフォルトのアクションエンティティを設定します。アクションマップマネージャーは新しい
アクションマップをデフォルトとして設定したエンティティに割り当てます。
構文
ActionMapManager.SetDefaultActionEntity( id, updateAll )
パラメーター
説明
id
デフォルトになるアクションエンティティの
EntityId を設定します。
Version 1.6
751
Lumberyard 開発者ガイド
ScriptBind_ActorSystem
パラメーター
説明
updateAll
すべての既存のアクションマップの割り当てを
更新します。
ScriptBind_ActorSystem
Lua スクリプトから呼び出すことができる C++ のアクターシステム関数をリストします。
CreateActor
アクターを作成します。
構文
ActorSystem.CreateActor(ScriptHandle channelId, SmartScriptTable actorParams)
パラメーター
説明
channelId
ネットワークチャネルの識別子。
actorParams
アクターのパラメーター。
ScriptBind_GameStatistics
Lua スクリプトから呼び出すことができる C++ のゲーム統計関数をリストします。
AddGameElement
指定範囲にゲーム要素を追加します。
構文
GameStatistics.AddGameElement(scopeID, elementID, locatorID, locatorValue [,
table])
パラメーター
説明
scopeID
範囲の識別子。
elementID
追加される要素の識別子。
locatorID
ロケーターの識別子。
locatorValue
ロケーターの値。
table
オプション。要素のテーブル。
BindTracker
構文
Version 1.6
752
Lumberyard 開発者ガイド
ScriptBind_GameStatistics
GameStatistics.BindTracker(name, tracker)
パラメーター
説明
name
結合するトラッカーの名前。
tracker
結合される IStatsTracker*。
CurrentScope
現在の範囲の ID を返します。スタックが空の場合は -1 を返します。
構文
GameStatistics.CurrentScope()
イベント
構文
GameStatistics.Event()
PopGameScope
スタックの最上部から範囲を削除します。
構文
GameStatistics.PopGameScope([checkScopeId])
パラメーター
説明
checkScopeId
オプション。スタックの最上部から削除される
範囲の識別子。
PushGameScope
スタックの最上部に範囲をプッシュします。
構文
GameStatistics.PushGameScope(scopeID)
パラメーター
説明
scopeID
スタックの最上部に配置する範囲の識別子。
Version 1.6
753
Lumberyard 開発者ガイド
ScriptBind_GameToken
RemoveGameElement
指定範囲から指定されたパラメーター値を持つ要素を削除します。
構文
GameStatistics.RemoveGameElement(scopeID, elementID, locatorID, locatorValue)
パラメーター
説明
scopeID
範囲の識別子。
elementID
削除される要素の識別子。
locatorID
ロケーターの識別子。
locatorValue
ロケーターの値。
StateValue
構文
GameStatistics.StateValue()
UnbindTracker
構文
GameStatistics.UnbindTracker(name, tracker)
パラメーター
説明
name
結合解除するトラッカーの名前。
tracker
結合解除される IStatsTracker*。
ScriptBind_GameToken
Lua スクリプトから呼び出すことができる C++ のゲームトークン関数をリストします。
DumpAllTokens
ログにすべてのゲームトークンとその値をダンプします。
構文
GameToken.DumpAllTokens()
GetToken
ゲームトークンの値を取得します。
Version 1.6
754
Lumberyard 開発者ガイド
ScriptBind_Inventory
構文
GameToken.GetToken(const char *sTokenName)
パラメーター
説明
sTokenName
値を取得するゲームトークンの名前。
SetToken
ゲームトークンの値を設定します。
構文
GameToken.SetToken(const char* tokenName, any tokenValue)
パラメーター
説明
tokenName
トークンの名前。
tokenValue
設定する値。
ScriptBind_Inventory
Lua スクリプトから呼び出すことができる C++ のインベントリ管理関数をリストします。
クリア
インベントリをクリアします。
構文
Inventory.Clear()
Destroy
インベントリを破壊します。
構文
Inventory.Destroy()
Dump
インベントリをダンプします。
構文
Inventory.Dump()
Version 1.6
755
Lumberyard 開発者ガイド
ScriptBind_Inventory
GetAmmoCapacity
指定された弾薬の容量を取得します。
構文
Inventory.GetAmmoCapacity(const char *ammoName)
パラメーター
説明
ammoName
弾薬の名前。
GetAmmoCount
指定された弾薬名の量を取得します。
構文
Inventory.GetAmmoCount(const char *ammoName)
パラメーター
説明
ammoName
弾薬の名前。
GetCurrentItem
現在の項目を取得します。
構文
Inventory.GetCurrentItem()
GetCurrentItemId
現在の項目の識別子を取得します。
構文
Inventory.GetCurrentItemId()
GetGrenadeWeaponByClass
クラス名での手榴弾武器を取得します。
構文
Inventory.GetGrenadeWeaponByClass(const char *className)
Version 1.6
756
Lumberyard 開発者ガイド
ScriptBind_ItemSystem
パラメーター
説明
className
クラスの名前。
GetItemByClass
クラス名で項目を取得します。
構文
Inventory.GetItemByClass(const char *className)
パラメーター
説明
className
クラスの名前。
HasAccessory
インベントリに指定のアクセサリが含まれているかどうかを確認します。
構文
Inventory.HasAccessory(const char *accessoryName)
パラメーター
説明
accessoryName
アクセサリーの名前。
SetAmmoCount
指定された弾薬の量を設定します
構文
Inventory.SetAmmoCount(const char *ammoName, int count)
パラメーター
説明
ammoName
弾薬の名前。
count
弾薬の数。
ScriptBind_ItemSystem
アクター項目とパックの項目用に Lua スクリプトから呼び出すことができる C++ 関数をリストしま
す。
Version 1.6
757
Lumberyard 開発者ガイド
ScriptBind_ItemSystem
GetPackItemByIndex
パックのインデックスから項目を取得します。
構文
ItemSystem.GetPackItemByIndex(const char *packName, int index)
パラメーター
説明
packName
パックの名前。
index
取得する項目のインデックスです。
GetPackNumItems
指定されたパックの項目数を取得します。
構文
ItemSystem.GetPackNumItems(const char* packName)
パラメーター
説明
packName
項目数を取得するパックの名前。
GetPackPrimaryItem
指定されたパックのプライマリ項目を取得します。
構文
ItemSystem.GetPackPrimaryItem(const char *packName)
パラメーター
説明
packName
プライマリ項目を取得するパックの名前。
GiveItem
指定された項目を渡します。
構文
ItemSystem.GiveItem(const char *itemName)
パラメーター
説明
itemName
項目の名前。
Version 1.6
758
Lumberyard 開発者ガイド
ScriptBind_ItemSystem
GiveItemPack
指定された項目パックを指定されたアクターに渡します。
構文
ItemSystem.GiveItemPack(ScriptHandle actorId, const char *packName)
パラメーター
説明
actorId
アクターの識別子。
packName
パックの名前。
元に戻す
項目システムをリセットします。
構文
ItemSystem.Reset()
SerializePlayerLTLInfo
プレーヤーレベルをレベル (LTL) 情報にシリアル化します。
構文
ItemSystem.SerializePlayerLTLInfo(bool reading)
パラメーター
説明
reading
ブール値。
SetActorItem
アクター項目を設定します。
構文
ItemSystem.SetActorItem(ScriptHandle actorId, ScriptHandle itemId, bool
keepHistory)
パラメーター
説明
actorId
アクターの識別子。
itemId
項目の識別子です。
keepHistory
履歴を保持する場合は true、それ以外の場合は
false です。
Version 1.6
759
Lumberyard 開発者ガイド
ScriptBind_Network
SetActorItemByName
アクター項目を名前で設定します。
構文
ItemSystem.SetActorItemByName(ScriptHandle actorId, const char *name, bool
keepHistory)
パラメーター
説明
actorId
アクターの識別子。
name
アクター項目の名前。
keepHistory
履歴を保持する場合は true、それ以外の場合は
false です。
ScriptBind_Network
Lua スクリプトから呼び出すことができる C++ ネットワーク関数をリストします。
Expose
構文
Network.Expose()
ScriptBind_UIAction
CallFunction
UI フラッシュアセットまたは UIEventSystem の関数を呼び出します。
構文
UIAction.CallFunction(elementName, instanceID, functionName, [arg1], [arg2],
[...])
パラメーター
説明
elementName
XML で定義された UI 要素の名前または.cpp
ファイルで定義された UIEventSystem 名。
instanceID
インスタンスの ID (指定された ID のインスタン
スがない場合は作成されます)。-1 で全インスタ
ンスを指定します。UIEventSystem で使用す
る場合、インスタンス ID は無視されません。
functionName
関数名またはイベント名。
args
引数のリスト (オプション)。
Version 1.6
760
Lumberyard 開発者ガイド
ScriptBind_UIAction
DisableAction
UI アクションを無効にします。
構文
UIAction.DisableAction(actionName)
パラメーター
説明
actionName
UI アクション名。
EnableAction
UI アクションを有効にします。
構文
UIAction.EnableAction(actionName)
パラメーター
説明
actionName
UI アクション名。
EndAction
UI アクションを終了します。これは UIAction Lua スクリプト内でのみ使用できます。
構文
UIAction.EndAction(table, disable, arguments)
パラメーター
説明
table
self を指定してください。
disable
true の場合、このアクションが終了すると無効
になります。
arguments
このアクションで返された引数。
GetAlpha
移動クリップのアルファ値を取得します。
構文
UIAction.GetAlpha(elementName, instanceID, mcName)
Version 1.6
761
Lumberyard 開発者ガイド
ScriptBind_UIAction
パラメーター
説明
elementName
XML で定義された UI 要素名。
instanceID
インスタンスの ID (指定された ID のインスタン
スがない場合は作成されます)。-1 で全インスタ
ンスを指定します。
mcName
XML で定義されたムービークリップ名。
GetArray
配列の値を含むテーブルを返します。
構文
UIAction.GetArray(elementName, instanceID, arrayName)
パラメーター
説明
elementName
XML で定義された UI 要素名。
instanceID
インスタンスの ID (指定された ID のインスタン
スがない場合は作成されます)。-1 で全インスタ
ンスを指定します。
arrayName
XML で定義された配列名。
GetPos
ムービークリップの位置を取得します。
構文
UIAction.GetPos(elementName, instanceID, mcName)
パラメーター
説明
elementName
XML で定義された UI 要素名。
instanceID
インスタンスの ID (指定された ID のインスタン
スがない場合は作成されます)。-1 で全インスタ
ンスを指定します。
mcName
XML で定義されたムービークリップ名。
GetRotation
ムービークリップのローテーションを取得します。
構文
Version 1.6
762
Lumberyard 開発者ガイド
ScriptBind_UIAction
UIAction.GetRotation(elementName, instanceID, mcName)
パラメーター
説明
elementName
XML で定義された UI 要素名。
instanceID
インスタンスの ID (指定された ID のインスタン
スがない場合は作成されます)。「-1」 で全イン
スタンスを指定します。
mcName
XML で定義されたムービークリップ名。
GetScale
ムービークリップのスケールを取得します。
構文
UIAction.GetScale(elementName, instanceID, mcName)
パラメーター
説明
elementName
XML で定義された UI 要素名。
instanceID
インスタンスの ID (指定された ID のインスタン
スがない場合は作成されます)。-1 で全インスタ
ンスを指定します。
mcName
XML で定義されたムービークリップ名。
GetVariable
UI フラッシュアセットの変数を取得します。
構文
UIAction.GetVariable(elementName, instanceID, varName)
パラメーター
説明
elementName
XML で定義された UI 要素名。
instanceID
インスタンスの ID (指定された ID のインスタン
スがない場合は作成されます)。-1 で全インスタ
ンスを指定します。
varName
XML で定義された変数名。
GotoAndPlay
ムービークリップに GotoAndPlay を呼び出します。
Version 1.6
763
Lumberyard 開発者ガイド
ScriptBind_UIAction
構文
UIAction.GotoAndPlay(elementName, instanceID, mcName, frameNum)
パラメーター
説明
elementName
XML で定義された UI 要素名。
instanceID
インスタンスの ID (指定された ID のインスタン
スがない場合は作成されます)。-1 で全インスタ
ンスを指定します。
mcName
XML で定義されたムービークリップ名。
frameNum
フレーム番号。
GotoAndPlayFrameName
ムービークリップにフレーム名で GotoAndPlay を呼び出します。
構文
UIAction.GotoAndPlayFrameName(elementName, instanceID, mcName, frameName)
パラメーター
説明
elementName
XML で定義された UI 要素名。
instanceID
インスタンスの ID (指定された ID のインスタン
スがない場合は作成されます)。-1 で全インスタ
ンスを指定します。
mcName
XML で定義されたムービークリップ名。
frameName
フレームの名前。
GotoAndStop
ムービークリップに GotoAndStop を呼び出します。
構文
UIAction.GotoAndStop(elementName, instanceID, mcName, frameNum)
パラメーター
説明
elementName
XML で定義された UI 要素名。
instanceID
インスタンスの ID (指定された ID のインスタン
スがない場合は作成されます)。-1 で全インスタ
ンスを指定します。
mcName
XML で定義されたムービークリップ名。
Version 1.6
764
Lumberyard 開発者ガイド
ScriptBind_UIAction
パラメーター
説明
frameNum
フレーム番号。
GotoAndStopFrameName
ムービークリップにフレーム名で GotoAndStop を呼び出します。
構文
UIAction.GotoAndStopFrameName(elementName, instanceID, mcName, frameName)
パラメーター
説明
elementName
XML で定義された UI 要素名。
instanceID
インスタンスの ID (指定された ID のインスタン
スがない場合は作成されます)。-1 で全インスタ
ンスを指定します。
mcName
XML で定義されたムービークリップ名。
frameName
フレームの名前。
HideElement
UI フラッシュアセットを非表示にします。
構文
UIAction.HideElement(elementName, instanceID)
パラメーター
説明
elementName
XML で定義された UI 要素名。
instanceID
インスタンスの ID (指定された ID のインスタン
スがない場合は作成されます)。-1 で全インスタ
ンスを指定します。
IsVisible
ムービークリップの表示状態を取得します。
構文
UIAction.IsVisible(elementName, instanceID, mcName)
パラメーター
説明
elementName
XML で定義された UI 要素名。
Version 1.6
765
Lumberyard 開発者ガイド
ScriptBind_UIAction
パラメーター
説明
instanceID
インスタンスの ID (指定された ID のインスタン
スがない場合は作成されます)。-1 で全インスタ
ンスを指定します。
mcName
XML で定義されたムービークリップ名。
RegisterActionListener
UIAction イベントのコールバック関数を登録します。コールバック関数は次の形式である必要があ
ります。CallbackName(actionName, eventName, argTable)
構文
UIAction.RegisterActionListener(table, actionName, eventName,
callbackFunctionName)
パラメーター
説明
table
コールバックを取得するスクリプト (self で現
在のスクリプトを参照できます)。
actionName
UI アクション名。
eventName
UI アクションから発生するイベントの名前
(OnStart または OnEnd を指定できます)
Warning
空の文字列を指定すると、すべてのイベ
ントを受け取ります。
コールバックを受け取るスクリプト関数の名
前。
callbackFunctionName
RegisterElementListener
UIElement イベントのコールバック関数を登録します。コールバック関数は次の形式である必要があ
ります。CallbackName(elementName, instanceId, eventName, argTable)
構文
UIAction.RegisterElementListener(table, elementName, instanceID, eventName,
callbackFunctionName)
パラメーター
説明
table
コールバックを取得するスクリプト (self で現
在のスクリプトを参照できます)。
elementName
XML で定義された UI 要素名。
Version 1.6
766
Lumberyard 開発者ガイド
ScriptBind_UIAction
パラメーター
説明
instanceID
インスタンスの ID (指定された ID のインスタン
スがない場合は作成されます)。-1 で全インスタ
ンスを指定します。
eventName
UI 要素から発生するイベントの名前。空の文字
列を指定すると、すべてのイベントを受け取り
ます。
callbackFunctionName
コールバックを受け取るスクリプト関数の名
前。
RegisterEventSystemListener
UIEventSystem イベントのコールバック関数を登録します。コールバック関数は次の形式である必
要があります。CallbackName(actionName, eventName, argTable)
構文
UIAction.RegisterEventSystemListener(table, eventSystem, eventName,
callbackFunctionName)
パラメーター
説明
table
コールバックを取得するスクリプト (self で現
在のスクリプトを参照できます)。
eventSystem
UI イベントシステム名。
eventName
UIEventSystem から発生するイベントの名
前。空の文字列を指定すると、すべてのイベン
トを受け取ります。
callbackFunctionName
コールバックを受け取るスクリプト関数の名
前。
ReloadElement
UI フラッシュアセットを再ロードします。
構文
UIAction.ReloadElement(elementName, instanceID)
パラメーター
説明
elementName
XML で定義された UI 要素名。
instanceID
インスタンスの ID (指定された ID のインスタン
スがない場合は作成されます)。-1 で全インスタ
ンスを指定します。
Version 1.6
767
Lumberyard 開発者ガイド
ScriptBind_UIAction
RequestHide
フェードアウトシグナルを UI フラッシュアセットに送ります。
構文
UIAction.RequestHide(elementName, instanceID)
パラメーター
説明
elementName
XML で定義された UI 要素名。
instanceID
インスタンスの ID (指定された ID のインスタン
スがない場合は作成されます)。-1 で全インスタ
ンスを指定します。
SetAlpha
ムービークリップのアルファ値を設定します。
構文
UIAction.SetAlpha(elementName, instanceID, mcName, fAlpha)
パラメーター
説明
elementName
XML で定義された UI 要素名。
instanceID
インスタンスの ID (指定された ID のインスタン
スがない場合は作成されます)。-1 で全インスタ
ンスを指定します。
mcName
XML で定義されたムービークリップ名。
fAlpha
アルファ値 (0-1)。
SetArray
UI フラッシュアセットの配列を設定します。
構文
UIAction.SetArray(elementName, instanceID, arrayName, values)
パラメーター
説明
elementName
XML で定義された UI 要素名。
instanceID
インスタンスの ID (指定された ID のインスタン
スがない場合は作成されます)。-1 で全インスタ
ンスを指定します。
Version 1.6
768
Lumberyard 開発者ガイド
ScriptBind_UIAction
パラメーター
説明
arrayName
XML で定義された配列名。
values
配列の値のテーブル。
SetPos
ムービークリップの位置を設定します。
構文
UIAction.SetPos(elementName, instanceID, mcName, vPos)
パラメーター
説明
elementName
XML で定義された UI 要素名。
instanceID
インスタンスの ID (指定された ID のインスタン
スがない場合は作成されます)。-1 で全インスタ
ンスを指定します。
mcName
XML で定義されたムービークリップ名。
vPos
position.
SetRotation
ムービークリップのローテーションを設定します。
構文
UIAction.SetRotation(elementName, instanceID, mcName, vRotation)
パラメーター
説明
elementName
XML で定義された UI 要素名。
instanceID
インスタンスの ID (指定された ID のインスタン
スがない場合は作成されます)。-1 で全インスタ
ンスを指定します。
mcName
XML で定義されたムービークリップ名。
vRotation
ローテーション。
SetScale
ムービークリップのスケールを設定します。
構文
Version 1.6
769
Lumberyard 開発者ガイド
ScriptBind_UIAction
UIAction.SetScale(elementName, instanceID, mcName, vScale)
パラメーター
説明
elementName
XML で定義された UI 要素名。
instanceID
インスタンスの ID (指定された ID のインスタン
スがない場合は作成されます)。-1 で全インスタ
ンスを指定します。
mcName
XML で定義されたムービークリップ名。
vScale
scale.
SetVariable
UI フラッシュアセットの変数を設定します。
構文
UIAction.SetVariable(elementName, instanceID, varName, value)
パラメーター
説明
elementName
XML で定義された UI 要素名。
instanceID
インスタンスの ID (指定された ID のインスタン
スがない場合は作成されます)。-1 で全インスタ
ンスを指定します。
varName
XML で定義された変数名。
value
設定する値。
SetVisible
ムービークリップの表示状態を設定します。
構文
UIAction.SetVisible(elementName, instanceID, mcName, bVisible)
パラメーター
説明
elementName
XML で定義された UI 要素名。
instanceID
インスタンスの ID (指定された ID のインスタン
スがない場合は作成されます)。-1 で全インスタ
ンスを指定します。
mcName
XML で定義されたムービークリップ名。
bVisible
visible.
Version 1.6
770
Lumberyard 開発者ガイド
ScriptBind_UIAction
ShowElement
UI フラッシュアセットを表示します。
構文
UIAction.ShowElement(elementName, instanceID)
パラメーター
説明
elementName
XML で定義された UI 要素名。
instanceID
インスタンスの ID (指定された ID のインスタン
スがない場合は作成されます)。-1 で全インスタ
ンスを指定します。
StartAction
UI アクションを開始します。
構文
UIAction.StartAction(actionName, arguments)
パラメーター
説明
actionName
UI アクション名。
arguments
このアクションに渡す引数。
UnloadElement
UI フラッシュアセットをアンロードします。
構文
UIAction.UnloadElement(elementName, instanceID)
パラメーター
説明
elementName
XML で定義された UI 要素名。
instanceID
インスタンスの ID (指定された ID のインスタン
スがない場合は作成されます)。-1 で全インスタ
ンスを指定します。
UnregisterActionListener
UIAction イベントのコールバック関数を登録解除します。
Version 1.6
771
Lumberyard 開発者ガイド
ScriptBind_Vehicle
構文
UIAction.UnregisterActionListener(table, callbackFunctionName)
パラメーター
説明
table
コールバックを取得するスクリプト (self で現
在のスクリプトを参照できます)。
callbackFunctionName
コールバックを受け取るスクリプト関数の名
前。"" を指定した場合、このスクリプトのすべ
てのコールバックが削除されます。
UnregisterElementListener
UIElement イベントのコールバック関数を登録解除します。
構文
UIAction.UnregisterElementListener(table, callbackFunctionName)
パラメーター
説明
table
コールバックを取得するスクリプト (self で現
在のスクリプトを参照できます)。
callbackFunctionName
コールバックを受け取るスクリプト関数の名
前。"" を指定した場合、このスクリプトのすべ
てのコールバックが削除されます。
UnregisterEventSystemListener
UIEventSystem イベントのコールバック関数を登録解除します。
構文
UIAction.UnregisterEventSystemListener(table, callbackFunctionName)
パラメーター
説明
table
コールバックを取得するスクリプト (self で現
在のスクリプトを参照できます)。
callbackFunctionName
コールバックを受け取るスクリプト関数の名
前。"" を指定した場合、このスクリプトのすべ
てのコールバックが削除されます。
ScriptBind_Vehicle
Lua スクリプトから呼び出すことができる C++ のヴィークルシステム関数をリストします。
Version 1.6
772
Lumberyard 開発者ガイド
ScriptBind_Vehicle
AddSeat
車両に座席を追加します。
構文
Vehicle.AddSeat(SmartScriptTable paramsTable)
パラメーター
説明
paramsTable
SmartScriptTable 形式の座席パラメーター。
ChangeSeat
車両内でアクターに座席を変更させます。
構文
Vehicle.ChangeSeat(ScriptHandle actorHandle, int seatId, bool
isAnimationEnabled)
パラメーター
説明
actorHandle
アクターの識別子。
seatId
座席の識別子。
isAnimationEnabled
アニメーションが有効になっている場合は
true、それ以外の場合は false。
Destroy
車両を破壊します。
構文
Vehicle.Destroy()
DisableEngine
車両のエンジンを無効または有効にします。
構文
Vehicle.DisableEngine(bool disable)
パラメーター
説明
disable
true でエンジンを無効にします。false で有効に
します。
Version 1.6
773
Lumberyard 開発者ガイド
ScriptBind_Vehicle
EnableMovement
車両の移動を有効または無効にします。
構文
Vehicle.EnableMovement(bool enable)
パラメーター
説明
enable
true で移動を有効にします。false で無効にしま
す。
EnterVehicle
指定したアクターが車両に乗り込みます。
構文
Vehicle.EnterVehicle(ScriptHandle actorHandle, int seatId, bool
isAnimationEnabled)
パラメーター
説明
actorHandle
アクターの識別子。
seatId
座席の識別子。
isAnimationEnabled
アニメーションが有効になっている場合は
true、それ以外の場合は false。
ExitVehicle
アクターが車両を離れます。
構文
Vehicle.ExitVehicle(ScriptHandle actorHandle)
パラメーター
説明
actorHandle
アクターの識別子。
GetComponentDamageRatio
指定されたコンポーネントのダメージ率を取得します。
構文
Vehicle.GetComponentDamageRatio(const char* pComponentName)
Version 1.6
774
Lumberyard 開発者ガイド
ScriptBind_Vehicle
パラメーター
説明
pComponentName
コンポーネントの名前。
GetHelperDir
ヘルパーの方向を取得します。
構文
Vehicle.GetHelperDir(const char* name, bool isInVehicleSpace)
パラメーター
説明
name
ヘルパーの名前。
isInVehicleSpace
ヘルパーが車両空間内にある場合は true、それ
以外の場合は false。
GetHelperPos
ヘルパーの位置を取得します。
構文
Vehicle.GetHelperPos(const char* name, bool isInVehicleSpace)
パラメーター
説明
name
ヘルパーの名前。
isInVehicleSpace
ヘルパーが車両空間内にある場合は true、それ
以外の場合は false。
GetHelperWorldPos
ワールド座標でヘルパーの位置を取得します。
構文
Vehicle.GetHelperWorldPos(const char* name)
パラメーター
説明
name
ヘルパーの名前。
GetSeatForPassenger
指定された乗客の車両座席 ID を返します。
Version 1.6
775
Lumberyard 開発者ガイド
ScriptBind_Vehicle
構文
Vehicle.GetSeatForPassenger(ScriptHandle passengerId)
パラメーター
説明
passengerId
乗客 ID。
GetVehicle
車両の識別子を取得します。
構文
Vehicle.GetVehicle()
HasHelper
車両に指定されたヘルパーがあるかどうかを確認します。
構文
Vehicle.HasHelper(const char* name)
パラメーター
説明
name
ヘルパーの名前。
IsDestroyed
車両が破壊されたかどうかを確認します。
構文
Vehicle.IsDestroyed()
IsInsideRadius
車両が指定された半径内にあるかどうかを確認します。
構文
Vehicle.IsInsideRadius(Vec3 pos, float radius)
パラメーター
説明
pos
{x,y,z} 位置ベクトル。
Version 1.6
776
Lumberyard 開発者ガイド
ScriptBind_Vehicle
パラメーター
説明
radius
浮動小数点で示される半径。
IsUsable
車両をユーザーが使用できるかどうかを確認します。
構文
Vehicle.IsUsable(ScriptHandle userHandle)
パラメーター
説明
userHandle
ユーザー識別子。
MultiplyWithWorldTM
ワールド変換マトリックスで乗算します。
構文
Vehicle.MultiplyWithWorldTM(Vec3 pos)
パラメーター
説明
pos
{x,y,z} 位置ベクトル。
OnHit
車両がヒットされた後に発生するイベントをトリガーします。
構文
Vehicle.OnHit(ScriptHandle targetId, ScriptHandle shooterId, float damage,
Vec3 position, float radius, int hitTypeId, bool explosion)
パラメーター
説明
targetId
ターゲットの識別子。
shooterId
射撃者の識別子。
damage
浮動小数点で示されるダメージ量。
position
{x,y,z} 位置ベクトル。
radius
浮動小数点で示されるヒット半径。
hitTypeId
整数で示されるダメージの種類。
Version 1.6
777
Lumberyard 開発者ガイド
ScriptBind_Vehicle
パラメーター
説明
explosion
ヒットにより爆発が発生する場合は true、それ
以外の場合は false。
OnSpawnComplete
車両のスポーンが完了したときのゲームコードにコールバックします。
構文
Vehicle.OnSpawnComplete()
OnUsed
ユーザーが指定された車両を使用するとイベントをトリガーします。
構文
Vehicle.OnUsed(ScriptHandle userHandle, int index)
パラメーター
説明
userHandle
ユーザー識別子。
index
座席の識別子。
ProcessPassengerDamage
乗客のダメージを処理します。
構文
Vehicle.ProcessPassengerDamage(ScriptHandle passengerId, float actorHealth,
float damage, int hitTypeId, bool explosion)
パラメーター
説明
passengerId
乗客の識別子。
actorHealth
アクターのヘルス。
damage
ダメージ量。
hitTypeId
ダメージの種類。
explosion
爆発する場合は true、それ以外の場合は false。
元に戻す
車両をリセットします。
Version 1.6
778
Lumberyard 開発者ガイド
ScriptBind_VehicleSeat
構文
Vehicle.Reset()
ResetSlotGeometry
構文
Vehicle.ResetSlotGeometry(int slot, const char* filename, const char*
geometry)
パラメーター
説明
slot
スロットの数。
filename
ファイル名。
geometry
スロットジオメトリ。
ScriptBind_VehicleSeat
Lua スクリプトから呼び出すことができる C++ のヴィークルシート関数をリストします。
GetPassengerId
乗客の識別子を取得します。
構文
VehicleSeat.GetPassengerId()
GetVehicleSeat
車両の座席の識別子を取得します。
構文
VehicleSeat.GetVehicleSeat()
GetWeaponCount
この座席で使用できる武器数を取得します。
構文
VehicleSeat.GetWeaponCount()
GetWeaponId
武器の識別子を取得します。
Version 1.6
779
Lumberyard 開発者ガイド
ScriptBind_VehicleSeat
構文
VehicleSeat.GetWeaponId(int weaponIndex)
パラメーター
説明
weaponIndex
武器の識別子。
IsDriver
座席が運転席であるかどうかを確認します。
構文
VehicleSeat.IsDriver()
IsFree
座席が空席であるかどうかを確認します。
構文
VehicleSeat.IsFree(ScriptHandle actorHandle)
パラメーター
説明
actorHandle
乗客の識別子。
IsGunner
座席が射撃手席であるかどうかを確認します。
構文
VehicleSeat.IsGunner()
元に戻す
車両の座席をリセットします。
構文
VehicleSeat.Reset()
SetAIWeapon
武器の人工知能を設定します。
構文
Version 1.6
780
Lumberyard 開発者ガイド
ScriptBind_VehicleSystem
VehicleSeat.SetAIWeapon(ScriptHandle weaponHandle)
パラメーター
説明
weaponHandle
武器の識別子。
ScriptBind_VehicleSystem
Lua スクリプトから呼び出すことができる C++ のヴィークルシステム関数をリストします。
GetOptionalScript
指名された車両用の (オプション) スクリプトを取得します。
構文
VehicleSystem.GetOptionalScript(char* vehicleName)
GetVehicleImplementations
実装されているすべての車両のテーブルを取得します。
構文
VehicleSystem.GetVehicleImplementations()
ReloadSystem
デフォルト値を使用して車両システムを再ロードします。
構文
VehicleSystem.ReloadSystem()
SetTpvDistance
第三者視点のカメラ距離。
構文
VehicleSystem.SetTpvDistance(float distance)
SetTpvHeight
第三者視点のカメラ高度。
構文
VehicleSystem.SetTpvHeight(float height)
Version 1.6
781
Lumberyard 開発者ガイド
ScriptBind_Boids
ScriptBind_Boids
これらの関数は、鳥のようなオブジェクトまたは動物の模擬群体 (ボイド) を作成し、動作を制御しま
す。
CanPickup
構文
ボイドを拾うことができるかどうかを確認します。
Boids.CanPickup(flockEntity, boidEntity)
パラメーター
説明
flockEntity
群れを含む有効なエンティティのテーブル。
boidEntity
ボイドを含む有効なエンティティのテーブル。
CreateBugsFlock
虫の群れを作成し指定されたエンティティにバインドします。
構文
Boids.CreateBugsFlock(entity,paramsTable)
パラメーター
説明
entity
有効なエンティティのテーブル。
paramTable
群れのパラメーターを含むテーブル (サンプルス
クリプトを参照)。
CreateFishFlock
魚の群れを作成し指定されたエンティティにバインドします。
構文
Boids.CreateFishFlock(entity,paramsTable)
パラメーター
説明
entity
有効なエンティティのテーブル。
paramTable
群れのパラメーターを含むテーブル (サンプルス
クリプトを参照)。
Version 1.6
782
Lumberyard 開発者ガイド
CreateFlock
CreateFlock
ボイドの群れを作成し指定されたエンティティにバインドします。
構文
Boids.CreateFlock(entity,paramsTable)
パラメーター
説明
entity
有効なエンティティのテーブル。
nType
群れのタイプ。想定される値
は、Boids.FLOCK_BIRDS、Boids.FLOCK_FISH、および
Boids.FLOCK_BUGS です。
paramTable
群れのパラメーターを含むテーブル (サンプルスクリプトを参照)。
EnableFlock
エンティティ内の群れを有効または無効にします。
構文
Boids.EnableFlock(entity,paramsTable)
パラメーター
説明
entity
群れを含む有効なエンティティのテーブル。
bEnable
群れを有効にするには true、無効にするには
false を指定します。
GetUsableMessage
指定された群れについて適切なローカライズ済み UI メッセージを取得します。
構文
Boids.GetUsableMessage(flockEntity)
パラメーター
説明
flockEntity
群れを含む有効なエンティティのテーブル。
OnBoidHit
ボイドがヒットすると発生するイベント。
Version 1.6
783
Lumberyard 開発者ガイド
OnPickup
構文
Boids.OnBoidHit(flockEntity,boidEntity,hit)
パラメーター
説明
flockEntity
群れを含む有効なエンティティのテーブル。
boidEntity
ボイドを含む有効なエンティティのテーブル。
hit
ヒット情報が含まれる有効なエンティティテー
ブル。
OnPickup
ボイドオブジェクトに、適切な拾い上げアクションを送信します。
構文
Boids.OnPickup(flockEntity, boidEntity, bPickup, fThrowSpeed)
パラメーター
説明
flockEntity
群れを含む有効なエンティティのテーブル。
boidEntity
ボイドを含む有効なエンティティのテーブル。
bPickup
拾い上げるか、落とすまたは投げます。
fThrowSpeed
投げる速度を指定します。デフォルトでは、5.f
より大きな値でボイドを殺します。これは拾い
上げアクションには影響しません。
SetAttractionPoint
ボイドに 1 回限りの注意ポイントを設定します。
構文
Boids.SetAttractionPoint(entity,paramsTable)
パラメーター
説明
entity
群れを含む有効なエンティティのテーブル。
point
1 回限りの注意ポイント。
SetFlockParams
指定されたエンティティの群れのパラメーターを設定します。
Version 1.6
784
Lumberyard 開発者ガイド
SetFlockPercentEnabled
構文
Boids.SetFlockParams(entity, paramsTable)
パラメーター
説明
entity
群れを含む有効なエンティティのテーブル。
paramTable
群れのパラメーターを含むテーブル (サンプルス
クリプトを参照)。
SetFlockPercentEnabled
群れの中でレンダリングされるボイドオブジェクトの比率を指定します。これを使用して群れを徐々
に有効にすることもできます。
構文
Boids.SetFlockPercentEnabled(entity, paramsTable)
パラメーター
説明
entity
群れを含む有効なエンティティのテーブル。
nPercent
有効な値は 0 から 100 です。0 にするとボイドはレンダリングされません。100
ですべてのボイドがレンダリングされます。
Version 1.6
785
Lumberyard 開発者ガイド
メモリ処理
システム
このセクションには、メモリ処理、ストリーミング、ローカリゼーションなどのシステムの一般的な
問題に関するトピックが含まれています。ログ記録とコンソールツールについても説明しています。
トピック
• メモリ処理 (p. 786)
• ストリーミングシステム (p. 789)
• テキストのローカリゼーションと Unicode のサポート (p. 799)
• CryLog (p. 803)
• CryConsole (p. 805)
メモリ処理
この記事では、ゲーム開発に関連するメモリおよびストレージに関するいくつかの考慮事項について
説明します。
ハードウェアのメモリ制限
ゲームコンソールの開発は、メモリ制限のために困難になることがあります。生産の観点から見れ
ば、それほど高性能でないハードウェアをコンソールに使用したい気持ちになりますが、競争がます
ます激しくなっている市場において、一般的に、コンソールの品質に対する期待は高くなっていま
す。
ターゲットとするプラットフォームの選択
生産時に複数のプラットフォームをターゲットとする場合でも、1 つの開発プラットフォームのみを
選択したほうが効率的である場合が少なくありません。メモリ要件の低いプラットフォームを選択
すると、長期的には生産が容易になりますが、他のプラットフォームの品質が低下する場合がありま
す。グローバルコード調整 (TIF 設定の "globalreduce"、TIF プリセット設定の [don't use highest LOD]
など) を使用するとメモリ使用量を減らすのに有効な場合がありますが、TIF の "reduce" 設定の使用
など、よりアセット固有の調整がしばしば必要になります。これらの調整では不十分な場合には、
まったく異なるアセットが必要です (あるオブジェクトのすべての LOD がコンソールと PC で異な
るなど)。これは、CryPak 機能を使用して実現できます。複数の pak ファイルをパスにバインドし
て、それらが階層化されているように動作させることができます。これにより、いくつかのプラット
フォームをカスタマイズして、異なるアセットを使用することができます。複数レイヤーを使用する
プラットフォームでは、(メモリ、パフォーマンス、I/O の) オーバーヘッドが増加するため、より強力
なハードウェアで複数レイヤーを使用することをお勧めします。
Version 1.6
786
Lumberyard 開発者ガイド
予算
予算
基本的にメモリの予算はゲームによって異なります。これは、すべての種類のメモリ (ビデオ、システ
ム、ディスクなど) が複数のアセット間で共有され、ゲームごとにメモリの使い方が異なるためです。
似たタイプのアセットには、ある一定の容量のメモリを割り当てることをお勧めします。たとえば、
すべての武器で同じ容量のメモリを使用する場合、指定された数の武器にかかるコストを予測でき、
また生産を注意深く計画することにより、問題の原因となる恐れがある、後になってからの予算削減
を避けることができます。
複数のモジュールとスレッドによる割り当て戦略
Lumberyard メモリマネージャーは、サイズが同じくらいの小さい割り当てをグループ化して、断片化
を最小限に抑えようとします。これにより、メモリを節約でき、割り当てと割り当て解除が迅速化さ
れ、複数スレッド (バケットごとの同期プリミティブ) 間の競合を最小化できます。より大きな割り当
ては、OS によって実行されるため、かなり効率的です。メインスレッド以外にメモリを割り当てる
こともできますが、コードの読みやすさに悪影響を及ぼす可能性があります。あるモジュールに割り
当てられたメモリは、同じモジュール内で割り当てを解除する必要があります。状況によっては、こ
のルールに違反しても問題ない場合がありますが、モジュールあたりの割り当て統計が適切に得られ
なくなります。シンプルな Release() メソッドを使用すると、オブジェクトを同じモジュール内で
確実に解放できます。文字列クラス (CryString) にはこの動作が組み込まれているため、メモリを
どこで解放する必要があるかをプログラマーが判断する必要がありません。
計算データのキャッシュ
一般的に、キャラクターのスキニング (ジョイントに基づく頂点変換) は、GPU 上で実行することを
お勧めします。通常、GPU は必要な計算を CPU よりも高速に実行できます。スキン結果のキャッ
シュもできますが、計算に強い傾向があるグラフィックハードウェアでは、多くの場合はメモリが限
られています。このような条件の場合は、すべてのパスでデータを再計算し、キャッシュメモリを管
理する必要性を排除するほうが合理的です。動的なゲームシーンではキャラクター数が大きく変化す
るため、このアプローチが有効です。
圧縮
特定タイプのデータの場合に効率的に機能する非可逆および可逆圧縮の手法が多数あります。手法に
よって、複雑さ、圧縮および解凍時間が異なり、非対称である場合もあります。圧縮によりレイテン
シーが増加する場合があります。また、パケット損失やビットフリップなど壊れたデータを処理する
ことができる手法はわずかです。
ディスクのサイズ
最新のゲームを PC にインストールするのは、時間がかかる場合があります。インストールを回避し
てゲームを DVD から直接実行するのは、魅力的な選択肢ですが、特にランダムなアクセスパターン
の場合、DVD のパフォーマンスはハードドライブのパフォーマンスよりも大きく劣ります。コンソー
ルの場合、ゲームの起動時間に制限があり、通常、ディスクメモリの容量が限られているかディスク
メモリがまったくない状況にゲーム側で対処する必要があります。ゲームが大きすぎてメモリが足り
ない場合は、ストリーミングが必要です。
合計サイズ
ビルドの合計サイズを小さくするには、アセットの数と品質を適正化することが必要です。最終製品
向けには、すべてのテクスチャを 2 倍の解像度で作成し、リソースコンパイラ を使用してコンテンツ
をダウンサンプルするのが合理的です。これは、クロスプラットフォーム開発の場合に有効であり、
高品質のコンテンツを後からリリースできます。また、高解像度でアセットを作成することの多い
アート担当者のワークフローが簡単になります。高解像度のコンテンツを利用できると、必要に応じ
Version 1.6
787
Lumberyard 開発者ガイド
アドレス空間
て (ビデオを作成する場合など)、最高品質のカットシーンをエンジンでレンダリングすることもでき
ます。
多くのメディアには容量を最大化するフォーマットがありますが、大きなフォーマットを使用する
と、小さなフォーマットよりもコストがかかる場合があります (たとえば、DVD の別レイヤーの使
用)。冗長性によって、シーク時間を最小限に抑えられる場合もあります (たとえば、1 つのブロック
に同じレベルのアセットをすべて保存する)。
アドレス空間
一部のオペレーティングシステム (OS) は依然として 32 ビットです。これは、メインメモリのアドレ
スが 32 ビットであり、アドレス指定できるメモリが 4 GB であることを意味します。残念ながら、
相対アドレス指定を使用する場合、最上位ビットが失われるため、アプリケーションには 2 GB しか
残されていません。一部の OS では、大きなアドレスを認識できるアプリケーションをコンパイルす
ることにより、より多くのメモリを解放し、この制限を取り除くことができます。ただし、OS では
GPU メモリなどの領域もメモリ空間にマッピングするため、4 GB をすべて使用することはできませ
ん。そのメモリを管理するときに、別の課題が生じます。合計 1 GB のメモリが空いていても、仮想
アドレス空間では 200 MB の連続ブロックを利用できない場合があります。この問題を避けるには、
メモリを注意深く管理する必要があります。以下の方法が有効です。
• 一定サイズのスタックのメモリをお勧めします (SPU のスタックサイズは小さい)。
• alloca() を使用して動的サイズのスタックから割り当てることもできます (SPU 上でも) が、発見
するのが難しいバグの原因になります。
• 小さなオブジェクトを大きなチャンクに割り当てます (フライウェイト設計パターン)。
• 再割り当てを避けます (たとえば、最大の大きさを確保し、それを超えない)。
• フレーム処理中の割り当てを避けます (シンプルなパラメーターの受け渡しでも割り当てが発生する
場合がある)。
• 1 つのレベルを処理後、メモリが必要以上に断片化されていないことを確認します (テストケース:
複数のレベルを 1 つずつロード)。
64 ビットアドレス空間は、この問題に有効な解決策です。これには、64 ビット OS と 64 ビットバー
ジョンのアプリケーションを実行する必要があります。32 ビットのアプリケーションを 64 ビット
OS で実行しても、解決にはなりません。64 ビット向けのコンパイルを行うと、実行可能ファイルの
サイズが大きくなり、場合によっては逆効果になることに注意してください。
帯域幅
メモリ帯域幅の使用率を減らすには、キャッシュの活用、ローカルメモリアクセスパターンの使用、
適切なデータを近くに配置、または小さいデータ構造の使用が有効です。もう 1 つのオプションは、
データを保存して後で読み出す代わりに、オンデマンドで再計算し、すべてのメモリアクセスを避け
ることです。
レイテンシー
メモリのタイプごとに、アクセスパフォーマンス特性が異なります。データの格納場所を注意深く計
画することにより、パフォーマンスを向上させることができます。たとえば、実行アニメーションで
のアニメーションのブレンドでは、数分の 1 フレーム以内にアクセスできる必要があり、またメモリ
内でアクセスできる必要があります。これとは対照的に、カットシーンアニメーションはディスクに
保存できます。大きなレイテンシーを回避するには、追加のコーディングが必要になる場合もありま
す。場合によっては、手間に見合う効果が得られない可能性もあります。
配置
一部の CPU では、データアクセスのために適切なデータ配置が必要です (たとえば、浮動小数点数
を読み取るには、4 の倍数のアドレスが必要になります)。他の CPU では、データが適切に並んでい
Version 1.6
788
Lumberyard 開発者ガイド
仮想メモリ
ないと処理速度が低下します (正しく配置されていないデータへのアクセス)。サイズの増加に応じて
キャッシュが動作するため、新しいサイズに合わせてデータを配置することは利点があります。新し
い機能を作成するとき、それらの構造のサイズについて考慮する必要があります。そうしないと、そ
の機能が十分なパフォーマンスを発揮できないか、まったく動作しない可能性があります。
仮想メモリ
ほとんどのオペレーティングシステムでは、次にどのメモリリクエストが発生するかわからないた
め、メモリを控えめに処理しようとします。一定時間使用されないコードやデータは、ハードドライ
ブにページアウトされる可能性があります。ゲームの場合、このページングにより、ランダムに停止
が発生する可能性があるため、多くのコンソールではスワッピングを回避します。
ストリーミング
ゲームでストリーミングを使用すると、利用できる容量に限界があるメモリでは通常実現できない大
きな世界をシミュレートできます。セカンダリ (通常は低速の) ストレージメディアが必要であり、限
られたリソースをキャッシュとして使用します。ストリーミングが実現する理由は、アセットセット
がゆっくりと変化する傾向があり、また任意の時点でコンテンツの一部のみが必要になるからです。
メモリに保持されるアセットセットは、使用可能なハードウェアの制限に従う必要があります。メ
モリ使用量は、部分的にはコードで決まりますが、アセットの配置、使用、再利用、オクルージョン
やストリーミングのヒントの使用に関するデザイナーの判断も、必要なメモリ容量を決定する上で重
要です。必要なアセットセットを大規模に変更することが必要になると、ストリーミングのレイテン
シーが問題になる場合があります。DVD、ブルーレイ、CD などの他の多くのストレージメディアに
比べ、ハードドライブのシーク時間は短くなります。アセットを並べ替え、アセットの冗長コピーを
保持すると、パフォーマンスの向上に役立ちます。
分割画面や一般的なマルチカメラをサポートする場合、ストリーミングシステムの課題がさらに増え
ます。このような状況で必要なアセットセットを追跡するのは、ますます困難になります。この場
合、複数のセットを同じハードウェア上でサポートする必要があるため、シークパフォーマンスは悪
化する可能性があります。ストリーミングシステムが正しく機能するように、ゲームプレイを制限す
るのが賢明な方法です。ストリーミングシステムが最も適切に動作するのは、必要なアセットが事前
にわかっている場合です。アセットを最初に登録せずにオンデマンドでロードするゲームコードで
は、ストリーミングが適切に動作しません。すべてのアセットアクセスをハンドルでラップし、起動
フェーズ時にのみハンドルの登録と作成を許可することをお勧めします。これにより、必要最低限の
ビルド (必要なアセットのみで構成される最小のビルド) を簡単に作成できます。
ストリーミングシステム
Lumberyard ストリーミングエンジンはメッシュ、テクスチャ、音楽、音およびアニメーションのスト
リーミング処理を行います。
低レベルストリーミングシステム
CryCommon インターフェイスと構造体
CryCommonの IStreamEngine.h ファイルには、残りのエンジンによって使用されるすべての重要
なインターフェイスと構造体が含まれます。
初めに、IStreamEngine があります。 アプリケーションには、ひとつの IStreamingEngine のみ
があり、利用可能なすべての I/O ストリームを制御します。 次の情報の大部分はコード内のドキュメ
ントから直接得ることができるため、不足している情報に関しては、 IStreamEngine.h ファイル内
の実際のコードを読むことをお勧めします。
Version 1.6
789
Lumberyard 開発者ガイド
低レベルストリーミングシステム
IStreamEngine の最も重要な関数は、ストリーミングリクエストを開始するのに用いられる
StartRead 関数です。
IStreamEngine.h
UNIQUE_IFACE struct IStreamEngine
{
public:
// Description:
//
Starts asynchronous read from the specified file (the file may be on
a
//
virtual file system, in pak or zip file or wherever).
//
Reads the file contents into the given buffer, up to the given size.
//
Upon success, calls success callback. If the file is truncated or
for other
//
reason can not be read, calls error callback. The callback can be
NULL
//
(in this case, the client should poll the returned IReadStream
object;
//
the returned object must be locked for that)
// NOTE: the error/success/progress callbacks can also be called from
INSIDE
//
this function
// Return Value:
//
IReadStream is reference-counted and will be automatically deleted
if
//
you don't refer to it; if you don't store it immediately in an autopointer,
//
it may be deleted as soon as on the next line of code,
//
because the read operation may complete immediately inside
StartRead()
//
and the object is self-disposed as soon as the callback is called.
virtual IReadStreamPtr StartRead (const EStreamTaskType tSource, const
char* szFile, IStreamCallback* pCallback = NULL, StreamReadParams* pParams =
NULL) = 0;
};
現在サポートされているストリーミングタスクタイプは次のとおりです。 新しいオブジェクトタイプ
をストリーミングするには、この ENUM を拡張する必要があります。
IStreamEngine.h
enum EStreamTaskType
{
eStreamTaskTypeCount
eStreamTaskTypePak
eStreamTaskTypeFlash
eStreamTaskTypeVideo
eStreamTaskTypeReadAhead
prediction
eStreamTaskTypeShader
eStreamTaskTypeSound
eStreamTaskTypeMusic
eStreamTaskTypeFSBCache
eStreamTaskTypeAnimation
(dba, caf, ..)
=
=
=
=
=
13,
12,
11,
10,
9,
=
=
=
=
=
8,
7,
6,
5,
4,
//
//
//
//
Pak file itself
Flash file object
Video data (when streamed)
Read ahead data used for file reading
// Shader combination data
// Complete FSB file
// All the possible animations types
Version 1.6
790
Lumberyard 開発者ガイド
低レベルストリーミングシステム
eStreamTaskTypeTerrain
eStreamTaskTypeGeometry
eStreamTaskTypeTexture
not streamed)
};
= 3,
= 2,
= 1,
// Partial terrain data
// Mesh or mesh lods
// Texture mip maps (currently mip0 is
StartStream 関数では、ストリーミングリクエストの完了を通知するためのコールバックオブジェ
クトを指定できます。コールバックオブジェクトは、次の StreamAsyncOnComplete 関数および
StreamOnComplete 関数を実装する必要があります。
IStreamEngine.h
class IStreamCallback
{
public:
// Description:
//
Signals that reading the requested data has completed (with or
without error).
//
This callback is always called, whether an error occurs or not, and
is called
//
from the async callback thread of the streaming engine, which
happens
//
directly after the reading operation
virtual void StreamAsyncOnComplete (IReadStream* pStream, unsigned
nError) {}
// Description:
//
Same as the StreamAsyncOnComplete, but this function is called from
the main
//
thread and is always called after the StreamAsyncOnComplete
function.
virtual void StreamOnComplete (IReadStream* pStream, unsigned nError) =
0;
};
読み取りリクエストの開始時に、次のコードに示されるオプションのパラメーターを指定することも
できます。
IStreamEngine.h
struct StreamReadParams
{
public:
// The user data that'll be used to call the callback.
DWORD_PTR dwUserData;
// The priority of this read
EStreamTaskPriority ePriority;
// Description:
//
The buffer into which to read the file or the file piece
//
if this is NULL, the streaming engine will supply the buffer.
// Notes:
//
DO NOT USE THIS BUFFER during read operation! DO NOT READ from it,
it can lead to memory corruption!
void* pBuffer;
Version 1.6
791
Lumberyard 開発者ガイド
低レベルストリーミングシステム
// Description:
//
Offset in the file to read; if this is not 0, then the file read
//
occurs beginning with the specified offset in bytes.
//
The callback interface receives the size of already read data as
nSize
//
and generally behaves as if the piece of file would be a file of its
own.
unsigned nOffset;
// Description:
//
Number of bytes to read; if this is 0, then the whole file is read,
//
if nSize == 0 && nOffset != 0, then the file from the offset to the
end is read.
//
If nSize != 0, then the file piece from nOffset is read, at most
nSize bytes
//
(if less, an error is reported). So, from nOffset byte to nOffset +
nSize - 1 byte in the file.
unsigned nSize;
// Description:
//
The combination of one or several flags from the stream engine
general purpose flags.
// See also:
//
IStreamEngine::EFlags
unsigned nFlags;
};
StartRead 関数の戻り値は、必要に応じてクライアントに保管できる IReadStream オブジェクトで
す。IReadStream オブジェクトでは、内部で参照カウントが行われます。読み取り操作が終了する
前にコールバックオブジェクトが破棄される可能性がある場合、readstream を別途保管し、その停止
を要求する必要があります。これによりすべての読み取りリクエストは内部で消去され、非同期およ
び同期のコールバック関数が呼び出されます。
Wait 関数を使用することにより、ストリーミングエンジンにおける読み取りリクエストをブロックで
きます。この関数は、Lumberyard ストリーミングシステムを使用して実際の読み取りを行う非同期読
み取りスレッドから使用できます。
IStreamEngine.h
class IReadStream : public CMultiThreadRefCount
{
public:
virtual void Abort() = 0;
virtual void Wait( int nMaxWaitMillis=-1 ) = 0;
};
読み取りリクエストの内部フロー
Lumberyard ストリームエンジンは、追加のワーカーおよび IO スレッドを使用します。可能なすべ
ての IO インプットのために、他から独立して実行可能な、別の StreamingIOThread が作成されま
す。
現在ストリームエンジンには次の IO スレッドがあります：
• Optical – 光学式データドライブからのストリーミング。
• Hard disk drive (HDD) – ハードディスクドライブにインストールされたデータからのストリーミン
グ (完全にインストールされたゲーム、またはシャドウコピーされたデータである場合があります)
Version 1.6
792
Lumberyard 開発者ガイド
低レベルストリーミングシステム
• Memory – わずかな IO のみを必要とするパッケージ化されたメモリ内ファイルからのストリーミン
グ
ストリーミングエンジンで読み取りリクエストが実行された場合、まず最初にどの IO スレッドを使用
すべきか確認し、それからソートキーを計算します。そのリクエストは次に StreamingIOThread オ
ブジェクトのひとつに挿入されます。
読み取り操作が終了すると、そのリクエストはデータが圧縮されている場合は解凍スレッドのひとつ
に転送された後、非同期コールバックスレッドに転送されます。非同期コールバックスレッドの量
はプラットフォームに応じて異なり、非同期コールバックスレッドのあるものはジオメトリやテクス
チャといった特定のストリーミングリクエストタイプのために確保されます。非同期コールバックが
処理された後、完了したストリーミングリクエストはメインスレッドで処理されるためにストリーム
エンジンに追加されます。メインスレッドからのストリーミングエンジンに関する次の更新は、同期
コールバック (StreamOnComplete) を呼び出し、必要に応じて一時的に割り当てられたメモリを消去
します。
IO/WorkerThread については、StreamingIOThread および StreamingWorkerThread をご確認く
ださい。
読み取りリクエストソート
ストリーミングエンジンへのリクエストは、リクエストされたのと同じ順序で処理されるわけでは あ
りません。データの読み取り帯域幅を最大化するため、システムは内部的に読み取り順序の最適化を
試行します。
光ディスクからデータを読み込む場合、シークの量を減らすことが重要です (光ディスクほどではあり
ませんが、ハードディスクドライブから読み込む場合も同様です)。単一のシークは 100 ミリ秒以上か
かりますが、実際の読み取り時間は数ミリ秒しかかからない場合があります。360 XDK に関する公式
の統計は次のとおりです。
• 外径スループット: 12x (1 秒あたり約 15 MB)
• 内径スループット: 5x (1 秒あたり 6.8 MB)
• 平均シーク (3 分の 1 ストローク) 時間: 通常 110 ms、最大 140 ms
• フルストロークシーク時間: 通常 180 ms、最大 240 ms
• レイヤースイッチ時間: 75 ms
内部ソートアルゴリズムは、次の順序によって以下のルールを考慮に入れます。
• リクエストの優先度 – 高い優先度のリクエストは常に優先されますが、そのようなリクエストが多
すぎる場合、過剰な追加シークが発生することになります。
• 時間グループ化 – 特定の時間内に行われるリクエストはグループ化され、各時間グループに関して
連続的なディスクの読み取り操作が行われます。デフォルト値は 2 秒ですが、次の cvar を使用し
て変更することができます: sys_streaming_requests_grouping_time_period。時間による
グループ化は、平均リクエスト完了時間に大きな影響を及ぼします。これにより、グループ化しな
い場合は短い読み取りリクエストの時間が長くなりますが、ストリーミングリクエストの大部分は
ディスクのランダムな場所から来るものであるため、全体的な完了時間を大幅に減少させることが
できます。
• ディスクにおける実際のオフセット – ソート時に実際のディスクオフセットが計算され、使用さ
れます。より高いオフセットを有するファイルにより高い優先度が付与されるため、望ましいスト
リーミング順序となるようにディスクのレイアウトを整理することが重要です。
ソートに関する情報は、StreamAsyncFileRequest::ComputeSortKey() のソースコードをご参
照ください。必要となるソートコードは次のとおりです。
CAsyncIOFileRequest::ComputeSortKey
Version 1.6
793
Lumberyard 開発者ガイド
低レベルストリーミングシステム
void CAsyncIOFileRequest::ComputeSortKey(uint64 nCurrentKeyInProgress)
{
.. compute the disc offset (can be requested using CryPak)
// group items by priority, then by snapped request time, then sort by
disk offset
m_nDiskOffset += m_nRequestedOffset;
m_nTimeGroup = (uint64)(gEnv->pTimer->GetCurrTime() / max(1,
g_cvars.sys_streaming_requests_grouping_time_period));
uint64 nPrioriry = m_ePriority;
int64 nDiskOffsetKB = m_nDiskOffset >> 10; // KB
m_nSortKey = (nDiskOffsetKB) | (((uint64)m_nTimeGroup) << 30) |
(nPrioriry << 60);
}
ストリーミング統計
GetStreamingStatistics() 関数を使用してストリーミングエンジンのストリーミング統計を記録
することができます。
統計情報の多くは 2 つのグループに分類でき、1 つは最後の瞬間に収集されたもので、もう 1 つは最
後のリセット (通常はレベルのロード中に行われます) から収集されたものです。統計情報は、ゲーム
中にも強制的にリセットすることができます。
SMediaTypeInfo 構造体は、IO 入力システム (ハードディスクドライブ、光ディスク、メモリ) ごと
に情報を提供します。
IStreamEngine.h
struct SMediaTypeInfo
{
// stats collected during the last second
float fActiveDuringLastSecond;
float fAverageActiveTime;
uint32 nBytesRead;
uint32 nRequestCount;
uint64 nSeekOffsetLastSecond;
uint32 nCurrentReadBandwidth;
uint32 nActualReadBandwidth;
// only taking actual reading time into
account
// stats collected since last reset
uint64 nTotalBytesRead;
uint32 nTotalRequestCount;
uint64 nAverageSeekOffset;
uint32 nSessionReadBandwidth;
uint32 nAverageActualReadBandwidth; // only taking actual read time into
account
};
SRequestTypeInfo 構造体は、ジオメトリ、テクスチャおよびアニメーションといった各ストリー
ミングリクエストタイプに関する情報を提供します。
IStreamEngine.h
struct SRequestTypeInfo
Version 1.6
794
Lumberyard 開発者ガイド
低レベルストリーミングシステム
{
int nOpenRequestCount;
int nPendingReadBytes;
// stats collected during the last second
uint32 nCurrentReadBandwidth;
// stats collected since last reset
uint32 nTotalStreamingRequestCount;
uint64 nTotalReadBytes;
// compressed data
uint64 nTotalRequestDataSize;
// uncompressed data
uint32 nTotalRequestCount;
uint32 nSessionReadBandwidth;
float fAverageCompletionTime;
// Average time it takes to fully
complete a request
float fAverageRequestCount; // Average amount of requests made per second
};
次の例は、すべての収集データを含む全体統計を示しています。
IStreamEngine.h
struct SStatistics
{
SMediaTypeInfo hddInfo;
SMediaTypeInfo memoryInfo;
SMediaTypeInfo opticalInfo;
SRequestTypeInfo typeInfo[eStreamTaskTypeCount];
uint32 nTotalSessionReadBandwidth; // Average read bandwidth in total
from reset - taking full time into account from reset
uint32 nTotalCurrentReadBandwidth; // Total bytes/sec over all types and
systems.
int nPendingReadBytes;
// How many bytes still need to be read
float fAverageCompletionTime;
// Time in seconds on average takes to
complete read request.
float fAverageRequestCount; // Average requests per second being done to
streaming engine
int nOpenRequestCount;
// Amount of open requests
uint64 nTotalBytesRead;
uint32 nTotalRequestCount;
streaming engine.
// Read bytes total from reset.
// Number of request from reset to the
uint32 nDecompressBandwidth;
int nMaxTempMemory;
system
};
// Bytes/second for last second
// Maximum temporary memory used by the streaming
ストリーミングデバッグ情報
次の CVar を使用して、異なるタイプのデバッグ情報をリクエストすることができます:
sys_streaming_debug x 。
Version 1.6
795
Lumberyard 開発者ガイド
ストリーミングおよび Levelcache Pak ファイル
ストリーミングおよび Levelcache Pak ファイル
前述のとおり、光メディアドライブから読み取りを行う場合、シークおよびシーク距離の最小化が非
常に重要となります。そのため、このビルドシステムは、ストリーミングのために内部データレイア
ウトを最適化して設計されています。
最も簡単で速い方法は、IO を全く行わず、メモリ内の圧縮データからデータを読み取ることです。そ
のために、起動のための小さな pak および各レベルが作成されます。これらはレベルのロード中にメ
モリにロードされます。ある pak は、レベルの最後までメモリに保持されます。その他の pak は、レ
ベルのロードを高速化するためにのみ使用されます。すべての小さなファイルや小さな読み取りリク
エストを、これらの pak に向かわせることが理想的と言えます。
特別な RC_Job ビルドファイルはこれらの pak を生成するために使用されます: Bin32/rc/
RCJob_PerLevelCache.xml。これらの pak は、正常なビルドパイプラインにおいて生成されま
す。エンジンの内部管理は CResourceManager クラスによって行われ、それは pak を事前ロードま
たはアンロードするためにグローバル SystemEventsを使用します。
現在、レベルのロード中に次の pak がメモリにロードされます (sys_PakLoadCache) 。
• level.pak – すべての実際のレベルデータを保管しており、レベルのロード後は触れない状態にする
必要があります。
• xml.pak
• dds0.pak – そのレベルにおけるすべてのテクスチャのすべての最低ミップを保管します。
• cgf.pak および cga.pak – CGF ストリーミングが有効となった場合にのみロードする。
次の pak は、レベルのロードプロセス中にメモリに保管されます (sys_PakStreamCache) 。
• dds_cache.pak 6 KB より小さいすべての dds ファイルを保管します (dds.0 ファイルを除く) 。
• cgf_cache.pak 32 KB より小さいすべての cgf ファイルを保管します (CGF ストリーミングが有効な
場合のみ) 。
Important
これらの pak が利用可能であることを確認します。それらがなければ、レベルのロードは最
大で数分かかり、ストリーミングパフォーマンスは大きく低下します。
単一レベルのすべてのリソースに関する情報は、resourcelist.txt および
auto_resourcelist.txt に保管されています。各レベルをロードし、事前に録画したプレイを実行
する自動テストシステムによってこれらのファイルが生成されます。これらの resourcelist ファイ
ルは、レベル pak を生成するためにビルドフェーズ中に使用されます。
メモリ pak 内のそれらのファイルに含まれないすべてのデータは、光学式ドライブまたはハードディ
スクドライブにおける IO を通して処理されます。シークの量もここで減少させることをお勧めしま
す。この最適化フェーズも、リソースコンパイラを使用してビルドプロセス中に行われます。
ストリーム可能なすべてのデータは、すべてのレベルのすべてのソースリストから抽出され、デフォ
ルト pak ファイルから削除され (例えば、objects.pak 、 textures.pak 、 animations.pak)、
ストリーミングフォルダ内のストリーミングのために新しく最適化された pak 内に置かれます。
ストリーミング pak の作成は次のルールによって行われます:
• 拡張 による分割: 異なる拡張ファイルは、異なる pak 内 (例えば、dds、caf dba、cgf) に置かれ、同
じタイプのファイルが近い場所に置かれるようにします。これにより、それらのファイルは一気に
読み取られます。また、pak はディスクオフセットを使用してリクエストソート中に特定のファイ
ルタイプの優先度を上げるためにも使用されます。
Version 1.6
796
Lumberyard 開発者ガイド
単一スレッド IO アクセスおよび無効なファイルアクセス
• DDS タイプ による分割: 異なる dds タイプは、異なるタイプの優先度を上げるために別々にソート
されます (例えば、拡散マップは法線マップよりも高い優先度となります)。pak における実際の距
離がリクエストのソート中に使用されます。
• DDS ミップ による分割: 最も高いミップは別の pak ファイルに置かれます。それらは通常、すべ
てのより小さなミップのサイズの 60% を超え、より低い優先度でのストリーミングが可能となり
ます。これにより、より小さなテクスチャを読み取るために必要な平均シーク時間が大幅に減りま
す。テクスチャストリーミングシステムは、これら分割テクスチャデータを反映させるために内部
で読み取りを最適化します。
• アルファベット順 のソート: データの一部 (MP レベルロード中の CGF データ等) がアルファベット
順にロードされるため、デフォルトのアルファベット順ソートが必要となります。このソート順を
変更することは、ロード時間に大きな影響を及ぼす可能性があります。
実際のソートコードはリソースコンパイラにおいてハードコーディングされ、Code\Tools\RC
\ResourceCompiler\PakHelpers.cpp から入手できます。
Important
リソースコンパイラのソート演算子に変更を加える場合、テクスチャストリーミングおよび
ストリーミングエンジンソート演算子に必ず同様の変更を加えるようにしてください。
単一スレッド IO アクセスおよび無効なファイルア
クセス
重要な点として、一度にひとつのスレッドのみが特定の IO デバイスにアクセスするようにします。同
じ IO デバイスから同時に複数のスレッドが読み取りを行う場合、読み取り速度も 2 分の 1 未満とな
り、ほんの数 KB を読み取るために何秒も必要となることがあります。これは、IO 読み取りヘッドが
部分的にひとつのスレッドのために数 KB を読み取り、他のスレッドのために他の数 KB を読み取る
一方で、常に両者間で負担のかかるシークを実行していることから生じます。
解決策は、ゲームプレイ中に StreamingIOThreads からのみ読み取りを行うことです。Lumberyard
はデフォルト設定により、間違ったスレッドからデータを読み取った場合、左上隅に [Invalid File
Access (ファイルへの無効なアクセス)] 警告を表示します。また、光学式ドライブから読み取ってい
る場合に、実際の停止をエミュレートするために 3 秒間意図的に停止します。
高レベルストリーミングエンジンの使用
ストリーミングエンジンを使用することにより、非常に簡単に現在のストリーミング機能を拡張する
ことができます。このセクションでは、小さなクラスの例によって新しいストリーミングタイプを追
加する方法を説明します。
最初に、ストリーミングの完了を通知する IStreamCallback インターフェイスからクラスを作成
し、そしてファイルを読み取るための基本的な機能を追加します。このファイルは直接またはスト
リーミングエンジンを使用して読み取ることができます。データを直接読み取った場合、ロードされ
たデータを解析するための ProcessData 関数が呼び出されます。この関数はまた async コールバッ
クからも呼び出されます。メインスレッドでの実行ではないため、ここで必要に応じてデータに何ら
かの処理を行うことができます。
ストリーミングエンジンにおける読み取りリクエストを開始する場合、デフォルトのパラメーターを
使用することができます。ストリーミングエンジンによる動的割り当ての数を減らすために、最終的
なデータストレージを指定することもできます。
このクラスはまた、ストリーミングリクエストに関する情報を得るために、または、コールバックが
破棄された場合にリクエストをキャンセルできるようにするために読み取りストリームオブジェクト
Version 1.6
797
Lumberyard 開発者ガイド
高レベルストリーミングエンジンの使用
を保管します。同期コールバックの後、ポインタはもはやストリーミングエンジンよって参照されな
くなり、リセットされます。
CNewStreamingType
#include
class CNewStreamingType : public IStreamCallback
{
public:
CNewStreamingType() : m_pReadStream(0), m_bIsLoaded(false) {}
~CNewStreamingType()
{
if (m_pReadStream)
m_pReadStream->Abort();
}
// Start reading some data
bool ReadFile(const char* acFilename, bool bUseStreamingEngine)
{
if (bUseStreamingEngine)
{
StreamReadParams params;
params.dwUserData = eLoadFullData;
params.ePriority = estpNormal;
params.nSize = 0; // read the full file
params.pBuffer = NULL; // don't provide any buffer, but copy data
when streaming is done
m_pReadStream = g_pISystem->GetStreamEngine()>StartRead(eStreamTaskTypeNewType, acFilename, this, &params);
}
else
{
// old way of reading file in a sync way (blocking call!)
const char* acData = 0;
size_t stSize = 0;
.. read file directly using CryPak or fopen/fread
ProcessData(acData, stSize);
m_bIsLoaded = true;
}
return m_bIsLoaded;
}
// Check if the data is ready and loaded
bool IsLoaded() const { return m_bIsLoaded; }
protected:
// implement the IStreamCallback function
void StreamAsyncOnComplete(IReadStream* pStream, unsigned nError)
{
if(nError)
{
return;
}
Version 1.6
798
Lumberyard 開発者ガイド
テキストのローカリゼーションと Unicode のサポート
const char* acData = (char*)pStream->GetBuffer();
size_t stSize= pStream->GetBytesRead();
ProcessData(acData, stSize);
m_bIsLoaded = true;
}
void StreamOnComplete (IReadStream* pStream, unsigned nError)
{
m_pReadStream = 0;
}
// process the actual loaded data
void ProcessData(const char* acData, size_t stSize);
// store the stream callback object to be sure it can be canceled when
the object is destroyed
IReadStreamPtr m_pReadStream;
// Extra flag used to check if the data is ready
bool m_bIsLoaded;
}
テキストのローカリゼーションと Unicode のサ
ポート
ゲームは通常、さまざまな言語にローカライズされるため、ゲームでは多くの言語に対応したテキス
トデータを使用することが必要になる場合があります。
このドキュメントは、Lumberyard 特有のローカライズ情報を含む、ローカライズに関するプログラミ
ング関連の情報を提供します。
用語
次の表では、ローカリゼーションおよびテキスト処理に関連するいくつかの重要な用語について簡単
に説明します。
期間
説明
文字
テキストデータの単位。文字にはグリフまたはフォーマット指標を指定できます。
グリフが 1 つの表示可能な単位を必ずしも形成しないことに注意してください。た
とえば、発音区別符 [´] および文字 [a] は別々のグリフ (および文字) ですが、重ねて
文字 [á] を形成することができます。
Unicode
ユニコードコンソーシアムによって管理される、テキストと言語の標準化を扱うス
タンダードです。
UCS
ユニバーサル文字セット、Unicode スタンダードの標準化された文字セット (また
は ISO-10646)。
(UCS) コード
ポイント
UCS によって定義された範囲内の単一文字に対する整数識別子であり、たとえ
ば、U+12AB のように U プレフィックスの後に 16 進数が付きます。
(テキスト) エ
ンコード
コード単位のシーケンスへの UCS (のサブセット) のマッピング方法、またはエン
コードを適用するプロセス。
Version 1.6
799
Lumberyard 開発者ガイド
どのエンコードを使用すべきか
期間
説明
コード単位
コードポイントのエンコードに使用される、エンコード固有の単位の整数識別子。
多くのコード単位を使用して 1 つのコードポイントを表す場合があります。
ASCII
7 または 8 ビットコード単位を使用して、UCS 空間の最初の 128 個のコードポイ
ントをカバーする標準化エンコード。
(ANSI) コード
ページ
8 ビットコード単位を使用する際に上位 128 個の値に追加の意味を割り当てること
で ASCII を拡張した、標準化エンコードです。非常に多くのコードページがあり、
それらの一部ではマルチバイトシーケンスを使用してコードポイントをエンコード
します。
UTF
UCS Transformation Format、UCS 空間全体をカバーする標準化エンコード。
UTF-8
8 ビットコード単位を使用する UTF の特定のインスタンス。各コードポイントは 1
から 4 (を含む) コード単位を使用します。
UTF-16
16 ビットコード単位を使用する UTF の特定のインスタンス。各コードポイントは
1 または 2 コード単位を使用します。
UTF-32
32 ビットコード単位を使用する UTF の特定のインスタンス。各コードポイント
は、1 つのコード単位に直接マッピングされます。
バイト順
CPUがマルチバイト値の解釈時にバイトのシーケンスを処理する方法。バイト順は
通常、リトルエンディアンまたはビッグエンディアン形式のいずれかです。
エンコードの
エラー
コードポイントを形成しないコード単位のシーケンス (または Unicode スタンダー
ドによって定義される無効なコードポイント)。
どのエンコードを使用すべきか
テキストをエンコードする方法が多くあるため、特に小さいテキストを処理する場合に「これをどの
エンコードで保存するか」という疑問が生じます。コード単位のシーケンスのエンコードを誤った方
法で行うと、エンコードエラー、さらに有効なデコードによる誤ったコンテンツの生成につながるた
め、これは重要な疑問です。
次の表は、一般的なエンコードについていくつか説明します。
エンコード
コード単位
のサイズ
コードポイ
ントのサイ
ズ
UCS 空間全
体のマッピ
ング
エンコード/
デコードが
容易
バイト順の
違いへの影
響なし
主なユー
ザー
ASCII
7 ビット
1 バイト
いいえ
はい
はい
多くの英語
のみのアプ
リケーショ
ン
(ANSI) コー
ドページ
8 ビット
さまざまで
すが、通常
は 1 バイト
いいえ
さまざまで
すが、通常
は、はい
はい
古い OS 組
み込み関数
UTF-8
8 ビット
1 ～ 4 バイ
ト
はい
いいえ
はい
インター
ネット上
のほとん
どのテキス
ト、XML
Version 1.6
800
Lumberyard 開発者ガイド
どのエンコードを使用すべきか
エンコード
コード単位
のサイズ
コードポイ
ントのサイ
ズ
UCS 空間全
体のマッピ
ング
エンコード/
デコードが
容易
バイト順の
違いへの影
響なし
主なユー
ザー
UTF-16
16 ビット
2 ～ 4 バイ
ト
はい
はい
いいえ
Windows
"ワイド"
API、Qt
UCS-2
16 ビット
2 バイト
いいえ
はい
いいえ
なし
(UTF-16 と
置き換え)
UTF-32
UCS-4
32 ビット
4 バイト
はい
はい
いいえ
Linux "ワイ
ド" API
"最適な" エンコードは 1 つではないため、選択する際に使用するシナリオについて常に検討してくだ
さい。
従来、オペレーティングシステムおよびソフトウェアパッケージが異なると、選択されるサポート対
象のエンコードのセットが異なります。C++ でさえも、異なるプラットフォームの異なるルールに従
います。たとえば、"ワイド文字" wchar_t は Windows では 16 ビットですが、Linux では 32 ビット
です。
Lumberyard 製品は多くのプラットフォームのさまざまな言語で使用できるため、完全な UCS のカバ
レッジが望ましいです。次の表に、Lumberyard で使用されるいくつかの規則を示します。
テキスト
データ型
エンコー
ド
理由
ソースコー
ド
ASCII
コードを英語で作成している、つまり ASCII で十分であることを意味しま
す。
テキストア
セット
UTF-8
アセットは、バイト順が異なり、多くの言語のテキストを含む可能性があ
るマシン間で転送されます。
ランタイム
変数
UTF-8
テキストデータの UTF-8 との変換には費用がかかるため、データをでき
るだけ UTF-8 にしておきます。別のエンコードが必要なライブラリやオ
ペレーティングシステムとのやりとりを行う際に、例外が発生します。こ
のような場合、すべての変換はその呼び出しサイトで行われる必要があり
ます。
ファイルお
よびパスの
名前
ASCII
ファイル名は、ファイルシステムによって定義される大文字と小文字の区
別に関する特殊なケースです。Unicode は 3 つのケースを定義し、それら
の間の変換はロケール固有です。さらに、標準化形式は通常、ファイルシ
ステムと API では (すべては) 説明されません。一部の専門ファイルシス
テムは ASCII のみを受け入れます。この組み合わせは、最も基本的な、
ポータブルなサブセットを使用することが望ましく、必要な場合にのみ
UTF-8 が使用されることを意味します。
一般的な原則
• ソースコードで ASCII 以外の文字を使用しないようにします。ASCII 以外のリテラルが必要である
場合、エスケープシーケンスの使用を検討します。
• 絶対パスを使用しないようにします。開発者が制御するパスのみが入力されるようにします。可能
であれば、game フォルダ、root フォルダ、および user フォルダの ASCII 相対パスを使用します。
これが可能ではない場合、インストールフォルダ内のコンテンツのように、ユーザーが制御できる
ASCII 以外のコンテンツを注意深く検討してください。
Version 1.6
801
Lumberyard 開発者ガイド
コード作成時の影響
コード作成時の影響
シングルバイトのコード単位が一般的であるため (ダブルバイトのコード単位も使用する言語であっ
ても)、シングルバイトの文字列型はほぼ共通で使用されます。さらに、Lumberyard は ANSI コード
ページを使用しないため、すべてのテキストは ASCII または UTF-8 のいずれかである必要がありま
す。
次のプロパティは、ASCII および UTF-8 の両方を保持します。
• NULL バイト (整数値 0) が発生するのは、NULL バイトが意図される場合のみです (UTF-8 は複数バ
イトシーケンスの一部として NULL バイトを生成しません)。これは、C スタイルのヌル終端文字列
が同様に振る舞い、strlen のような CRT 組み込み関数は想定どおりに動作しますが、例外として
これは文字ではなくコード単位をカウントすることを指します。
• ASCII 範囲のコードポイントには UTF-8 でエンコードされた同じ値が含まれます。これは、英語の
文字列リテラルをコードに入力して、それらを変換なしで UTF-8 として扱うことができるという意
味です。また、ASCII 範囲内の文字を UTF-8 のコンテンツと直接比較できます (つまり、英語また
は ASCII 記号サブストリングを検索する場合)。
• UTF-8 シーケンス (ゼロまたはコードポイント全体を含む) にはコンテキストは含まれません。これ
は、テキストのコンテンツを変更しないで相互に追加すると安全であるという意味です。
コード単位の位置および長さ (string::length()、strlen()、および同様の組み込み関数により
報告される) と、コードポイント内の一致する位置と長さの違いの大部分には関連性がありません。こ
れは、シーケンスの意味が通常抽象的であり、バイトの意味が問題になるのはテキストが解釈または
表示される場合のみであるためです。ただし、次の点に注意してください。
• 文字列の分割 – 文字列を分割する場合、次のいずれかを行うことが重要です。
1. 分割後に分割された部分をテキストとして解釈せずに (つまり、転送のためにチャンクに分割せ
ずに)、部分を同じ順で再結合します。
2. コードポイント間の境界で分割を実行します。ASCII 文字の直前直後の位置は常に安全です。
• API 境界 – API が文字列を受け入れるか返す場合、API が使用するエンコードが何かを知ることは
重要です。API が文字列を不透明として扱わない (つまり、テキストとして解釈する) 場合、UTF-8
を渡すと、バイト文字列を受け入れてそれらを ASCII または ANSI として解釈する API にとって問
題となる場合があります。UTF-8 API が利用できない場合、他の Unicode API を代わりに使用しま
す (UTF-16 または UTF-32)。最後の手段として、ASCII に変換しますが、変換は非可逆的であり、
変換された文字列から復元することはできません。どのテキストエンコードが想定されるかを確認
するために常に API のドキュメントを読み、必要な変換を実行します。すべての UTF エンコード
は、両方向に可逆的に変換されます。そのため UTF 形式を受け入れる API を見つけると UTF エン
コードを使用する方法がわかります。
• 識別子 – 標準化形式とロケール依存ルールのために UTF の "同一性" の概念が複雑であるため、コ
レクションで、または比較目的で文字列を "キー" として使用する場合、非 ASCII シーケンスをキー
として使用しないようにします。ただし、コードポイントの観点から同一性のみを重視する場合
(コードポイントとコード単位のマッピングは 1:1 であるため)、UTF-8 文字列をバイト単位で比較
すると安心です。
• ソート – ソートに文字列を使用する場合、テキストの順序についてのロケール固有のルールは複雑
であることに注意してください。ほとんどの場合、UI がこれを処理してもかまいません。一般に、
文字列のセットのソート方法の前提はありません。ただし、UTF-8 文字列を ASCII のようにソート
すると、実際にはコードポイントでソートすることになります。std::map 検索で必要なものが任
意の固定順序のみである場合はこれでかまいませんが、UI にこの順序でコンテンツを表示すると、
別の順序を想定するエンドユーザーにとってはわかりにくい可能性があります。
一般に、可能であればテキストを解釈するのは避けてください。それ以外の場合は、ASCII のサブ
セットを操作して、すべてのその他のテキストの部分を不透明な分割できないシーケンスとして扱い
ます。"長さ" または "サイズ" の概念を扱う場合、コードポイントではなくコード単位を使用すること
を検討してください。なぜなら、これらのオペレーションでは計算コストがさらに削減されるためで
Version 1.6
802
Lumberyard 開発者ガイド
テキストアセット処理時の影響
す。実際、Unicode シーケンスの "長さ" の概念は複雑であり、コードポイントと実際に表示されるも
のの間では、多対多マッピングが行われます。
テキストアセット処理時の影響
一般的には、常に次のような操作を行います。
• UTF-8 エンコードでテキストアセットを保存します。
• Unicode NFC (標準化形式 C) で保存します。これは、テキスト編集ツールで最も一般的な保存形式
であり、他のものを使用するよい理由がない限り、この形式を使用することが最適です。
• テキストを正しい大文字/小文字 (つまり、表示されるテキスト) で保存します。大文字/小文字変換
は、さまざまな言語で複雑なトピックであり、回避するようにします。
CryCommon で提供されるユーティリティ
Lumberyard は、いくつかのユーティリティを提供しており、Unicode エンコードの間でテキ
ストの可逆的かつ安全な変換を容易に行うことができます。UnicodeFunctions.h および
UnicodeIterator.h ユーティリティで公開されるヘッダーファイルで技術的詳細が提供されます。
最も一般的なユースケースは次のとおりです。
string utf8;
wstring wide;
Unicode::Convert(utf8, wide); // Convert contents of wide string and store
into UTF-8 string
Unicode::Convert(wide, utf8); // Convert contents of UTF-8 string to wide
string
string ascii;
Unicode::Convert<Unicode::eEncoding_ASCII, Unicode::eEncoding_UTF8>(ascii,
utf8); // Convert UTF-8 to ASCII (lossy!)
Important
上記の組み込み関数は、入力テキストがすでに有効にエンコードされていることを前提とし
ています。正しい形式ではないユーザー入力または破損している可能性のある入力から保護
するには、Unicode::ConvertSafe 組み込み関数の使用を検討してください。
詳細情報
Unicode の概要については、The Absolute Minimum Every Software Developer Absolutely, Positively
Must Know About Unicode and Character Sets (No Excuses!)を参照してください。
Unicode の公式情報については、The Unicode Consortiumを参照してください。
CryLog
CryLog ログ作成機能
Lumberyard には、次のグローバル関数を使用してログインできます。
• CryLog (eMessage)
Version 1.6
803
Lumberyard 開発者ガイド
詳細レベルと色
• CryLogAlways (eAlways)
• CryError (eError)
• CryWarning (eWarning)
• CryComment (eComment)
より詳細な制御が必要な場合は、次の構文で ILog インターフェイスを直接使用することができま
す。
gEnv->pLog->LogToFile("value %d",iVal);
詳細レベルと色
ログ作成の詳細レベルは、コンソール変数 log_Verbosity および log_FileVerbosity で制御で
きます。
次の表は、詳細レベルと色の使用規則を示します。コンソールでは、警告は黄色で表示され、エラー
は赤で表示されます。
メッセージ
詳細レベル
0
詳細レベル
1
詳細レベル 2
詳細レベル
3
詳細レベル
4
コンソール
内の表示色
eAlways
X
X
X
X
X
eErrorAlways X
X
X
X
X
red
eWarningAlways
X
X
X
X
X
黄色
eInput
?
?
?
?
eInputResponse
?
?
?
?
?
eError
X
X
X
X
red
eWarning
–
–
X
X
X
黄色
eMessage
–
–
X
X
eComment
–
–
–
–
X
?
キー
• X – メッセージタイプがコンソールまたはファイルにログ出力されます。
• ? – 特別なロジックが使用されます。
Tip
log_Verbosity 4 を使用して、ログのフル出力 (コンソールとファイルに出力) を有効にす
ることもできます。
ログファイル
次の各ログファイルソースは、示されたログファイルに出力されます。
Version 1.6
804
Lumberyard 開発者ガイド
コンソール変数
送信元
ログファイル
Lumberyard エディタ
Editor.log
Game
game.log (デフォルト)
エラーメッセージ
Error.log
コンソール変数
ログ作成に関連するコンソール変数は次のとおりです。
log_IncludeTime
Toggles time stamping of log entries.
Usage: log_IncludeTime [0/1/2/3/4/5]
0=off (default)
1=current time
2=relative time
3=current+relative time
4=absolute time in seconds since this mode was started
5=current time+server time
ai_LogFileVerbosity
None = 0, progress/errors/warnings = 1, event = 2, comment = 3
log_Verbosity DUMPTODISK
defines the verbosity level for log messages written to console
-1=suppress all logs (including eAlways)
0=suppress all logs(except eAlways)
1=additional errors
2=additional warnings
3=additional messages
4=additional comments
CryConsole
コンソールは、コンソールコマンドとコンソール変数を処理するユーザーインターフェイスシステム
です。また、ログメッセージを出力して入出力履歴を保存します。
色コーディング
ゲームコンソールは、$ 文字で始まる色インデックス 0 ～ 9 を使用して色コーディングをサポートし
ます。コードは、コンソールに出力されるテキストでは非表示です。テキストをコンソールに送信す
るために、ILog インターフェイスを介してシンプルなログメッセージを使用します。
This is normal $1one$2two$3three and so on
Version 1.6
805
Lumberyard 開発者ガイド
すべてのコンソールコマンドおよび変数のダンプ
前の例では、1 は赤色で、2 は緑色で、3 (および残りのテキスト) は青色で描画します。
すべてのコンソールコマンドおよび変数のダンプ
すべてのコンソールコマンドとコンソール 変数は、コマンド DumpCommandsVars を使用してファイ
ルに記録されます。デフォルトのファイル名は consolecommandsandvars.txt です。
ダンプする必要がある変数を制限するには、サブストリングパラメーターを渡します。たとえば、コ
マンド
DumpCommandsVars i_
は、サブストリング "i_" から始まるすべてのコマンドと変数を記録します (たとえ
ば、i_giveallitems および i_debug_projectiles)。
コンソール変数
コンソール変数によって、ユーザーがランタイムにコンソールに入力するか、アプリケーションを起
動する前にコマンドライン引数として渡すことで、変数を容易に変更して公開できます。
コマンドライン引数の使用方法の詳細については、Command Line Argumentsの記事を参照してくだ
さい。
コンソール変数は、一般的にコードベースでは CVar と呼ばれます。
新しいコンソール変数の登録
整数または浮動ベースのコンソール変数の場合は、IConsole::Register() 組み込み関数を使用し
て C++ 変数をコンソール変数として公開することをお勧めします。
新しい文字列コンソール変数を宣言するには、IConsole::RegisterString() 組み込み関数を使用
します。
C++ のコンソール変数へのアクセス
コンソール変数は、ICVar インターフェイスを使用して公開されます。このインターフェイスを取得
するには、IConsole::GetCVar() 組み込み関数を使用します。
コンソール変数の値を読み取る効率的な方法は、コンソール変数プロキシにバインドされている C++
変数に直接アクセスすることです。
新しいコンソールコマンドの追加
新しいコンソールコマンドを使用して、コンソールを簡単に拡張できます。新しいコンソールコマン
ドは、ConsoleCommandFunc 型に従う静的組み込み関数として C++ に実装できます。このコンソー
ルコマンドの引数は、IConsoleCmdArgs インターフェイスを使用して渡されます。
次のコードは、コンソールコマンドのスケルトンの実装を示しています。
static void RequestLoadMod(IConsoleCmdArgs* pCmdArgs);
void RequestLoadMod(IConsoleCmdArgs* pCmdArgs)
{
if (pCmdArgs->GetArgCount() == 2)
Version 1.6
806
Lumberyard 開発者ガイド
コンソール変数グループ
{
const char* pName = pCmdArgs->GetArg(1);
// ...
}
else
{
CryLog("Error, correct syntax is: g_loadMod modname");
}
}
次のコードは、コンソールシステムを使用してコマンドを登録します。
IConsole* pConsole = gEnv->pSystem->GetIConsole();
pConsole->AddCommand("g_loadMod", RequestLoadMod);
コンソール変数グループ
コンソール変数グループは、事前定義された設定を複数のコンソール変数に一度に適用するのに便利
です。
コンソール変数は、一般的にコードベースでは CVarGroup と呼ばれます。コンソール変数グループ
は、他のコンソール変数を変更してさらに高い階層を構築できます。
Warning
割り当て内でサイクルが検出されず、クラッシュを引き起こす可能性があります。
新しい変数グループの登録
新しい変数グループを登録するには、新しい .cfg テキストファイルを GameSDK\config
\CVarGroups ディレクトリに追加します。
sys_spec_Particles.cfg
[default]
; default of this CVarGroup
= 4
e_particles_lod=1
e_particles_max_emitter_draw_screen=64
[1]
e_particles_lod=0.75
e_particles_max_emitter_draw_screen=1
[2]
e_particles_max_emitter_draw_screen=4
[3]
e_particles_max_emitter_draw_screen=16
これによって、sys_spec_Particles という名前の、整数のコンソール変数のように動作する新し
い変数グループが作成されます。デフォルトでは、この変数の状態は 4 です (例では、コメントの次
の行で設定されています)。
Version 1.6
807
Lumberyard 開発者ガイド
コマンドラインのコンソールコマンドの遅延実行
変数の変更で、新しい状態が適用されます。.cfg ファイルで指定されていないコンソール変数は設定
できません。すべてのコンソール変数は、デフォルトセクションの一部である必要があります。この
ルールに違反した場合は、エラーメッセージが出力されます。
コンソールの変数がカスタムセクションで指定されていない場合、デフォルトセクションで指定され
た値が適用されます。
コンソール変数グループのドキュメント
コンソール変数グループのドキュメントは、自動的に生成されます。
sys_spec_Particles
Console variable group to apply settings to multiple variables
sys_spec_Particles [1/2/3/4/x]:
... e_particles_lod = 0.75/1/1/1/1
... e_particles_max_screen_fill = 16/32/64/128/128
... e_particles_object_collisions = 0/1/1/1/1
... e_particles_quality = 1/2/3/4/4
... e_water_ocean_soft_particles = 0/1/1/1/1
... r_UseSoftParticles = 0/1/1/1/1
コンソール変数グループの値が、制御する変数の状態を表して
いるかどうかを確認
コンソールから
コンソールで、コンソール変数グループ名を入力してタブを押します。変数の値が示されない場合
は、RealState の値が出力されます。
sys_spec_Particles=2 [REQUIRE_NET_SYNC] RealState=3
sys_spec_Sound=1 [REQUIRE_NET_SYNC] RealState=CUSTOM
sys_spec_Texture=1 [REQUIRE_NET_SYNC]
コンソールコマンド sys_RestoreSpec を呼び出すことで、sys_spec_ 変数によって正しい状態が
示されない理由を確認できます。
C++ コードから
コードからメンバー組み込み関数 GetRealIVal() を使用して、その戻り値を ICVar の GetIVal()
の結果と比較できます。
コマンドラインのコンソールコマンドの遅延実行
コマンドラインを介して + プレフィックスを使用して渡されるコマンドは、それ以外のコンソールコ
マンドとは異なる別のリストに保存されます。
このリストは、アプリケーションがすべてを一度に実行するのではなく、これらのコマンドの実行を
いくつかのフレームに分散させることができるようにします。
例
次の の例を考えます。
Version 1.6
808
Lumberyard 開発者ガイド
CVar Turorial
--- autotest.cfg -hud_startPaused = "0"
wait_frames 100
screenshot autotestFrames
wait_seconds 5.0
screenshot autotestTime
-- console -crysis.exe -devmode +map island +exec autotest +quit
例では、以下のオペレーションが行われました。
• 諸島のマップをロードします。
• 100 個のフレームを待ちます。
• autotestFrames というスクリーンショットを取得します。
• 5 秒待ちます。
• autotestTime というスクリーンショットを取得します。
• アプリケーションを終了します。
詳細
ブロッカーと正常の 2 つのコマンドのカテゴリが定義されています。
フレームごとに、遅延コマンドリストは先入れ先出しで処理されます。このリストの要素は、正常な
コマンドが発生する限り消費されます。
ブロッカーがリストから消費され、実行されると、次のフレームまで処理は遅延します。たとえ
ば、map および screenshot のようなコマンドはブロッカーです。
コンソールコマンド (コマンドまたは変数のいずれか) には、宣言内で VF_BLOCKFRAME フラグを使
用してブロッカーとしてタグ付けすることができます。
次の同期コマンドがサポートされています。
オプションタイトル
コマンド
型
説明
wait_frames num:
<int>
リストの実行が再開されるまで
num フレームを待ちます。
wait_seconds sec:
<float>
リストの実行を再開するまで
sec 秒待ちます。
CVar Turorial
このチュートリアルでは、存在するコンソール変数（CVars）の調整と作成の仕方を説明しま
す。CVarsは多くの設定可能な動作を制御するのに使用できます Lumberyard。ゲームにおいてもこれ
らを使用できます。
Note
この短いチュートリアルは、プログラマーを対象としています。コンテンツのほとんどは
コードを使用します。
Version 1.6
809
Lumberyard 開発者ガイド
CVar Turorial
CVarsの作成
コンソール変数を作るには
1.
コードエディターで、すべてのゲーム固有のCVarsを宣言する、Code\GameSDK\GameDll
\GameCVars.hファイルを開きます。
2.
SCVarsstructを見つけます。struct内で、次の例のように、新しい変数を宣言します。
struct SCVars
{
int g_tutorialVar; //add this line
//... pre-existing code ...
};
追加した変数は、変数の現在の値を保存するのに使用されます。分数を保存する必要がある場合
は、そのタイプの変数を追加できますfloat。
次に、値がコンソールを使用して変更できるように、CVarをゲームエンジンと共に登録します。
3.
同じCode\GameSDK\GameDll\GameCVars.cppファイル内で、InitCVars 組み込み関数を探し
ます。
void SCVars::InitCVars(IConsole *pConsole)
{
m_releaseConstants.Init( pConsole );
REGISTER_CVAR(g_tutorialVar, 42, VF_NULL, "This CVar was added using the
tutorial on CVars"); //add this line
//... pre-existing code ...
}
4.
初期値と変数のヘルプテキストを指定します。ヘッダーファイルで変数が宣言されたタイプにつ
いて有効な任意の値で変数を初期化できます。前の例では、デフォルト値として42を指定し、ヘ
ルプテキストがユーザーに表示されます。
5.
ゲームがをアンロードするとき、変数を登録からはずすことを確認してください。次に示す例の
ように、同じCode\GameSDK\GameDll\GameCVars.cppファイル内で、ReleaseCVars 組み込
み関数を探し、使用します。
void SCVars::ReleaseCVars()
{
IConsole* pConsole = gEnv->pConsole;
pConsole->UnregisterVariable("g_tutorialVar", true); //add this line
//... pre-existing code ...
}
6.
変更完了したら、コードをコンパイルすることを忘れないでください。
CVarを使用する
ここでは、コンソールと.cfgファイルを使用して作成したCVarの値を##できます。
コードから
Version 1.6
810
Lumberyard 開発者ガイド
CVar Turorial
ゲーム コードの変数の値にアクセスするには、次の例に示すようにg_pGameCVarsポインターを使い
ます。
int myTutorialVar = g_pGameCVars->g_tutorialVar;
コンソールから
コンソールからcvarの値を変更するには、この構文を使用します：cvar_name=cvar_value。次の例
は、g_tutorialVarコンソールの変数の値を1337に設定します。
g_tutorialVar = 1337
.cfgファイルから
.cfgファイルの一つからデフォルトのCVar値を変更することもできます。CVar値が割り当てられた場
合には、以前の値は破棄されます。したがって、最後の割り当ては現在のものです。
次のリストでは、コンソール変数の初期化の順序を示します。
1. が使用されるときのGameCVars.cppファイルで特定された値REGISTER_CVAR (ここの変更はコン
パイルが必要です。)
2. ファイルsystem.cfgで指定された値。
3. ユーザーファイルuser.cfgで指定された値。
4. ゲームのランタイムに割り当てられた値。
Tip
コンパイルを必要とせずに現在存在するCVarのデフォルト値を変更するときは、デフォルト
をオーバーライドするためにsystem.cfg ファイルにラインを追加します。
Version 1.6
811
Lumberyard 開発者ガイド
Lumberyard ブログ、フォーラム、
およびフィードバック
当社で Lumberyard を改善し続けるにあたり、開発者コミュニティの皆様に感謝します。皆様の
フォーラムへの参加、メッセージ、およびバグレポートがなかったら、Lumberyard は現在のように強
力になっていないでしょう。
• 今後も <[email protected]> 宛にフィードバックを送信してください。
• forums にご意見を投稿いただけることをお待ちしています。
• Amazon GameDev Blog では、新しい変更に関する最新情報を入手でき、ご意見をお知らせいただ
くこともできます。
Version 1.6
812

アジア女性スポーツネットワーク（AWS） ガイドライン

仮想デスクトップサービスAmazon WorkSpacesの自社導入開始～既存

エンタープライズ向けAWSクラウド デザインパターンのご紹介 （BCP-DR編）

Ni系アモルファスろう材

Generic Version for Disease, Illness or Symptom Danielle Groleau

2003年8月号 - カーメル・バプテスト教会

2015-01-15 Newびいど No.49 掲載 PDFファイル

FY1409

ご利用開始までのながれ