このページでは、OmniGRPCをプロジェクトへ追加し、Blueprintで通信するためのアセットを用意する手順を説明します。.protoの取り込みは両エディションで共通です。Server Reflectionからの取り込みはFull Editionで使用できます。
プラグインを導入する
- Epic Games Launcherから、使用するUnreal Engineバージョンに対応したOmniGRPCを対象のEngineまたはプロジェクトへインストールします。
- Unreal Editorを起動し、Edit → Plugins → Networking → OmniGRPCを有効にします。
- Editorの再起動を求められた場合は再起動します。
プラグインには通信に必要なライブラリが含まれています。追加のソフトウェアやC++ライブラリのビルドは不要です。
Free EditionからFull Editionへ移行するときは、Editorを終了してプラグインを置き換えます。両者は同じプラグイン名を使用するため、同時には有効化しないでください。
Windows、Linux、macOS、Android、iOSのすべてで同じ.protoとBlueprintを利用できるのはFull Editionです。プラットフォームごとに通信処理を書き直す必要はありません。Free Editionの対応プラットフォームはWindows（Win64）のみです。
.protoからBlueprint用アセットを生成する
Content Browserへ.protoファイルをドラッグ＆ドロップします。取り込み後、既定の出力先/Game/OmniGrpcGenerated/に次のアセットが生成されたことを確認してください。ImporterのOutput Folderが生成先のルートです。
.proto内の定義 | 作られるアセット | Blueprintでの役割 |
|---|---|---|
message | User Defined Struct | サーバーへ送るデータ、サーバーから届くデータ |
enum | User Defined Enum | 複数の選択肢から値を選ぶ項目 |
service | OmniGrpc Service Asset | 呼び出せるサーバー機能の一覧 |
/Game/OmniGrpcGenerated/
├── Messages/
├── Enums/
└── Services/
生成されるStruct名は.protoのメッセージ名と同じです。たとえばLoginRequestからはMessages/LoginRequestが生成され、F接頭辞は付きません。
flowchart TD
Proto[.protoファイル] --> Import[Content Browserへインポート]
Import --> Message[message → MessagesのStruct]
Import --> Enum[enum → EnumsのEnum]
Import --> Service[service → ServicesのService Asset]
Message --> Request[MakeノードでRequestを作成]
Service --> Select[CallノードのServiceを設定]
Select --> Method[DetailsのMethod Nameを選択]
Method --> Typed[RequestとResponseの型が決まる]
Request --> Typed
別の.protoを参照している場合
取り込む.protoが別の.protoを参照している場合は、元のフォルダー構成を保ったまま用意してください。参照先のファイルが見つからないとImportに失敗します。失敗した場合はUnreal EditorのOutput Logに原因が出力されます。
Free EditionでStreamingメソッドを含む.protoを取り込んだ場合
Free Editionでも、Server StreamingなどのStreaming RPCを含む.protoの取り込みとアセット生成は成功します。ただし、取り込んだStreaming RPCを呼び出すノードはFull Editionでだけ使用できます。Service Assetの説明とUnreal Editorのログに、Full Editionが必要である旨が表示されます。
Server Reflectionからアセットを生成する
Full Edition のみサーバーがServer Reflectionという機能に対応している場合は、手元に.protoファイルがなくても通信に必要な情報をサーバーから取得できます。この機能はFull Editionでだけ使用できます。
- Content Browserの空白部分を右クリックします。
- Import from gRPC Reflectionを選びます。
- 接続先のHostとPort、Security、Service名、Output Folder、Timeoutを入力します。
- Importを押します。
Service名には、acme.user.UserServiceのようにpackage名を含む正式な名前を入力します。Service名が不明な場合は、サーバー管理者へ確認してください。サーバー側でReflectionが無効になっている場合や、接続設定が正しくない場合はImportできません。
画像準備中：Import from gRPC Reflectionダイアログ
画像差し替えマーカー
Content Browserの右クリックメニューと、Host／Port／Security／Service／Output Folder／Timeoutを入力したダイアログを見せる。
- 推奨ファイル名
images/OmniGRPC/setup-reflection-import.png- 代替テキスト
- gRPC Server ReflectionからService Assetを生成する設定画面
Service Assetを確認する
Service Assetには、そのサーバーで呼び出せる機能（Method）の一覧が保存されます。各Methodを開くと、送るStruct、受け取るStruct、通信方法を確認できます。通常のBlueprint作業では、その他の内部情報を変更する必要はありません。
画像準備中：UserServiceのService Asset
画像差し替えマーカー
最新mainで生成したUserService Assetを開き、Login、WatchUsers、UploadUsers、UserLookupのMethod種別とRequest／Response Struct参照を撮影する。LoginRequest／LoginResponseにF接頭辞が付かないことが読める画面。既存のsetup-service-asset.pngは旧命名のため差し替える。
- 推奨ファイル名
images/OmniGRPC/setup-service-asset-current.png- 代替テキスト
- OmniGRPCのService Assetに表示されたgRPCメソッド一覧
CallノードでServiceとMethodを選ぶ
- 通信方法に合うCallノードを追加し、
ServiceピンにService Assetを設定します。 - ノードを選択し、Detailsパネルの
gRPC → Method Nameを開きます。 - 呼び出すMethodを選び、Request／Responseの型を確認します。
| Callノード | UserServiceで選べるMethod |
|---|---|
Call gRPC Unary | Login、GetUser、ListUsers、RetryTest、EchoMetadata |
Call gRPC Server Streaming | WatchUsers（Full Edition） |
Call gRPC Client Streaming | UploadUsers（Full Edition） |
Call gRPC Bidi Streaming | UserLookup（Full Edition） |
Method名を文字列ピンへ入力する操作は不要です。候補はノードの通信方法で絞り込まれます。Serviceを変えたら、Methodも選び直してください。
Serviceを変数から渡す場合
同じBlueprintのメンバー変数にService Assetを初期値として設定し、CompileしてからGetノードを接続します。編集時にアセットを特定できるため、Methodの候補と送受信の型を解決できます。
実行時にだけ代入される変数やローカル変数では、編集時にServiceを特定できません。候補が空の場合は、まずServiceピンへアセットを直接設定して確認してください。
スキーマを更新する
元の.protoが変更されたら、生成済みService Assetを右クリックし、Regenerate from .protoを実行します。Struct、Enum、Service Assetが新しい内容に更新されます。
再生成後は、変更されたStructやService Assetを使っているBlueprintを開き、Compileを実行してください。データ項目やMethod名が削除・変更された場合は、ノードの接続が外れることがあります。エラーがないことと、入力値が意図せず初期値へ戻っていないことを確認します。
Reflectionから生成したアセットを更新する場合は、同じService名を指定してReflection Importを再実行します。
次のステップ
サンプルサーバーのパッケージに同梱されたuser_service.protoを使い、クイックスタートで基本的なUnary RPCを実行します。