ObjectDeliverer ユースケース

このページでは、目的に合わせたProtocol・PacketRule・DeliveryBoxの選び方と、代表的なユースケースを説明します。ノードごとの入出力の詳細はBlueprint APIリファレンスを参照してください。

Protocolを選ぶ

共通のライフサイクルはすべてのProtocolで同じです。Create Object Deliverer Managerで作成したマネージャーを変数に保持し、StartでProtocol・PacketRule（・DeliveryBox）を渡して開始、Connected/Disconnected/ReceiveDataイベントで結果を受け取り、不要になったらCloseを呼び出します。

プロトコルを切り替える

プロトコルを変更するには、Startに渡すProtocolノードを差し替えるだけです。イベントのバインドや受信後の処理はそのまま使えます。

たとえば、TCP/IPサーバーで始めた通信をUDP送信者に切り替えるには、Create Protocol Tcp Ip ServerをCreate Protocol Udp Socket Senderに置き換えます。

C++では次のように書きます。

deliverer->Start(UProtocolFactory::CreateProtocolUdpSocketSender("192.168.0.100", 9099),
                 UPacketRuleFactory::CreatePacketRuleSizeBody());

独自のカスタムProtocolを作成することも可能です。

以下、各Protocolの特徴と設定項目を説明します。

TCP/IPサーバー、クライアント

TCP/IP通信用のProtocolです。TCP/IPは一対多通信に対応しているため、単一のサーバーに複数のクライアントが接続できます。

パケット再送機能を備えているため、送信されたメッセージは確実に受信者へ届けられます。ただし、複数パケットの送信時に、複数回分のパケットが結合して届いたり、1回分のメッセージの途中で分断されて届いたりすることがあります。そのため、パケット分割ルールにはNodivision以外の使用を推奨します。

Create Protocol Tcp Ip Server

Create Protocol Tcp Ip Client

TCP/IPの特徴

UDP送信者、受信者

UDP通信用のProtocolです。TCP/IPと異なり、UDPは接続ステップなしに受信者へメッセージを一方的に送信します。

パケット再送機能がないため、ネットワーク状況によってはパケットが届かない場合があります。その分、TCP/IPより高いパフォーマンスを提供します。毎Tick状態を送る機能など、まれにパケットが届かなくても問題ない用途に適しています。

Create Protocol Udp Socket Sender

Create Protocol Udp Socket Sender with Broadcast

Create Protocol Udp Socket Receiver

UDPの特徴

WebSocketクライアント

WebSocketのクライアントです。WebシステムのWebSocketサーバーと接続できます。v1.7.0以降で利用できます。

ws://に加えてwss://のURLを使用した暗号化通信にも対応しています。Set Auto Reconnectで切断後の自動再接続を、Set Reconnect Delayで再接続までの待ち時間（秒）を設定できます。

Create Protocol Web Socket Client

Create Protocol Web Socket Client with Protocols

Create Protocol Web Socket Client with Headers

WebSocketの特徴

共有メモリ

共有メモリは、複数のアプリケーションで共有できるメモリ空間を作成し、この空間へメッセージの書き込みと読み込みを行うProtocolです。

ネットワーク通信ではないため、同じPC上でのみ送受信が可能です。その代わり、他の方式と比べて優れた読み書き速度を提供するため、大きなメッセージのやり取りに適しています。

データが書き込まれたことを受信側が知る方法がないため、受信側は定期的にメモリを読み込んで新しい書き込みを確認する必要があります。ObjectDelivererはこの処理を自動的に行うため、通常ユーザーが意識する必要はありません。ただし、サードパティが作成したメモリを読み込む場合は、相手の読み込みルールを確認してください。

Create Protocol Shared Memory

共有メモリの特徴

ファイル書き込み、読み込み

特定のファイルへメッセージの書き込みと読み込みを行うProtocolです。

動作は共有メモリと似ていますが、実際のファイルに書き込むため、アプリケーション終了後もメッセージを確認できます。データを保存しておく用途に適しています。

Create Protocol Log Writer

Create Protocol Log Reader

ファイルの特徴

リフレクション

自分自身でメッセージの送受信を行うProtocolです。メッセージを送信すると、同じインスタンス上で受信イベントが発生します。他のインスタンスとメッセージを交換することはできません。

主に開発時のデバッグ目的での使用を想定しています。

リフレクションの特徴

TLS/mTLSで暗号化する

TCP/IPにTLSを追加した暗号化通信Protocolです（v1.9.0以降）。TCP/IPと同様の一対多通信に対応し、通信内容の暗号化と証明書ベースの認証を行えます。

用途に応じて、自己署名証明書と公開鍵ピンニング、カスタムCA証明書、双方向TLS（mTLS）などの構成を選べます。サーバー側ではサーバー証明書と秘密鍵のファイルパスを指定します。

Create Protocol Tcp Ip Server Tls

Create Protocol Tcp Ip Client Tls

TCP/IP TLSの特徴

TLSオプションの選定（どのユースケースで何を有効化するか）はFAQ: ユースケース別TLSオプション構成に、証明書の検証と信頼ポリシーはデータ形式と運用にまとめています。

ObjectDelivererのTLSクライアントと通信できるTLSサーバーのサンプルをGitHubで公開しています。レポジトリはAyumaxSoft/TLSServerSampleです。

パケット分割ルールを切り替える

TCP/IPなどのプロトコルでは、1つのメッセージが複数のパケットに分割されたり、逆に複数のメッセージが1つのパケットにまとめられたりすることがあります。ObjectDelivererはパケット分割ルール（PacketRule）でこの問題に対応します。

プロトコルと同様に、Startに渡すノードを差し替えるだけで分割ルールを指定できます。

ObjectDelivererは次の分割ルールをサポートしています。独自のカスタムルールを作成することも可能です。

• FixedLength
• Terminate
• SizeBody
• Nodivision

送信者と受信者は同じ分割ルールを使用する必要があります。サードパティが作成したプログラムと通信する場合は、相手がどの分割ルールを使用しているかを事前に確認してください。

FixedLength

FixedLengthは、各メッセージに固定の長さを設定してメッセージを分割するルールです。すべての送信でパケットサイズが固定されるため、分割ロジックがシンプルになります。ただし、指定したサイズより大きなメッセージは送信できない制限があります。

Create Packet Rule Fixed Length

Terminate

Terminateは、特定の値を区切り文字としてメッセージを区切るルールです。改行文字でメッセージを区切る使い方がよく行われます。メッセージ長を動的に変更できますが、毎回終端値を検索するため、パフォーマンスがわずかに低下します。

Terminateを指定しない場合、改行コード\r(0x0d)\n(0x0a)が使用されます。

Create Packet Rule Terminate

SizeBody

SizeBodyは、メッセージの先頭にメッセージサイズを埋め込むルールです。メッセージサイズを動的にでき、分割ロジックも比較的シンプルなため、優れたパフォーマンスを提供します。

Create Packet Rule Size Body

Nodivision

Nodivisionは、受信した各パケットについて分割や結合を行わず、そのまま1つのメッセージとして扱うルールです。

Create Packet Rule Nodivision

DeliveryBoxを切り替える

既定では、ObjectDelivererはバイト配列で送受信します。DeliveryBoxを指定すると、指定した形式のデータへ自動変換できます。毎回手動でバイト配列へ変換する必要がなくなります。

C++では次のように書きます。

auto deliverybox = UDeliveryBoxFactory::CreateObjectDeliveryBoxUsingJson(SampleObject::StaticClass());
deliverybox->Received.AddDynamic(this, &UMyClass::OnReceiveObject);

deliverer->Start(UProtocolFactory::CreateProtocolTcpIpServer(9099),
                 UPacketRuleFactory::CreatePacketRuleSizeBody(), deliverybox);

送信もDeliveryBox経由で行います。

auto message = NewObject<SampleMessage>();
deliveryBox->Send(message);

ObjectDelivererは次のDeliveryBoxをサポートしています。独自のカスタムDeliveryBoxを作成することも可能です。

• ObjectDeliveryBoxUsingJson
• Utf8StringDeliveryBox

ObjectDeliveryBoxUsingJson

任意のユーザー定義UObjectクラスをJSON文字列へ変換して送受信するDeliveryBoxです。

Unreal Engineで使用できるすべてのクラスはUObjectを継承しているため、多くのクラスのインスタンスをそのまま送受信できます。JSON形式でのメッセージ交換は他のプログラミング言語でも一般的なため、他のアプリケーションとの通信にも使えます。

JSONへのシリアライズ形式（クラス名を含むかどうか）の選び方についてはFAQ: ObjectDeliveryBoxUsingJsonの利用方法を参照してください。

Utf8StringDeliveryBox

任意の文字列をそのまま送受信するためのDeliveryBoxです。エンコーディングはUTF-8で行われます。