Epicでは、GoogleがWebRTCのバージョンにおける脆弱性を公開 (詳細はこちら)したことを認識しており、EOS SDKに対する影響および次のステップを調査しています。
Pixel Streaming の Signaling and Web サーバーにはサンプル プレイヤー ページが用意されており、Unreal Engine アプリケーションからのメディアをストリーミングして、マウス、キーボード、タッチ イベントをアプリケーションに返すように設定されています。手順については、「Pixel Streaming 入門」を参照してください。ニーズに合うようであれば、このデフォルト プレイヤー ページをそのまま使用してください。
JavaScript や HTML など Web テクノロジーに関する十分な知識があり、独自の工夫を取り入れたい場合は、プレイヤー ページをカスタマイズして、Unreal Engine のコンテンツとリモートで対話する独自のカスタム UI を作成してください。ゲームプレイ イベントのトリガーやそれへの応答、Unreal Engine のビヘイビアを制御するコンソール コマンドの発行など、さまざまな操作を実行できます。
デフォルト プレイヤー ページをベースとして独自のカスタム プレイヤー ページを作成することをお勧めします。このページは Unreal Engine インストール フォルダの「Samples/PixelStreaming/WebServers/SignallingWebServer/public/player.html」にあります。このページに記載されている情報を参考にして、ページを拡張してプロジェクトのゲームプレイ ロジックと連携させる方法について学んでください。
デフォルトのプレイヤー ページ
HTML5 UI でカスタマイズしたプレイヤー ページ
HTML ページ要件
カスタム HTML プレイヤー ページでは、いくつかの要件に従う必要があります。
- 「
/scripts/webRtcPlayer.js」ファイルを含める必要があります。このファイルは、ブラウザと Unreal Engine アプリケーション間の通信を処理します。サーバーからのメディア ストリームを受信して表示します。必要な場合を除き、この JavaScript ファイルは変更しないでください。
<script type="text/javascript" src="scripts/webRtcPlayer.js"></script>
- 同様に「/scripts/app.js」ファイルを含めることも強く推奨します。このファイルでは、キーボード、マウス、タッチ イベントを処理するイベント リスナーが設定されます。また、プレイヤー ページで利用可能な複数の関数やフックも含まれます。これらについては、このページの後のセクションで説明されています。JavaScript に関して十分な知識がある場合は、ニーズに合わせてこのファイルのコードをカスタマイズし、デフォルトのビヘイビアを変更できます。例えば、キーボード入力を無効にして、マウスとタッチ イベントはそのまま動作するようにする場合は、このファイルをカスタマイズして、キーボード イベントを処理するコードを見つけてコメントアウトする必要があります。
<script type="text/javascript" src="scripts/app.js"></script>
- このページには ID が「
player」であるdiv要素が必要です。この要素は、UE4 アプリケーションからストリーミングされたビデオ フレームに置き換えられます。
<div id="player"></div>
- ページのロード時には、「
app.js」ファイルによって提供されるload関数を呼び出す必要があります。例えば、これを実行するにはonloadハンドラを<body>タグに追加します。
<body onload="load()">
プレイヤー ファイルの場所と URL
カスタム HTML プレイヤー ページを配置する場所と、クライアント ブラウザからそれにアクセスする方法については、オプションがいくつかあります。
- Signaling and Web サーバーのルート フォルダ内に「
custom_html」というフォルダを作成し、このフォルダ内にカスタム HTML プレイヤー ページを配置します。Signaling and Web サーバーを実行するコンピュータの IP アドレスまたはホスト名にこのファイル名を追加することで、アクセスできるようになります。 例えば、ファイル名が「custom_html/myplayerpage.html」であれば、「http://127.0.0.1/myplayerpage.html」とすることでアクセス可能になります。 - Signaling and Web サーバーの「
HomepageFile」パラメータをカスタマイズして、そのパスを、Signaling and Web サーバーのルート フォルダに相対的なカスタム HTML プレイヤー ページのファイル名に設定します。こうすることで、Signaling and Web サーバーを実行するコンピュータの IP アドレスまたはホスト名にアクセスした際に、これにアクセスできるようになります。 例えば、「myplayerpage.html」ファイルを「Engine/Source/Programs/PixelStreaming/WebServers/SignallingWebServer/myfolder」に保存する場合、「HomepageFile」パラメータを「myfolder/myplayerpage.html」に設定することで、「http://127.0.0.1/」などと、URL 内にファイル名を指定しなくてもこのページにアクセスすることができます。 - Signaling and Web サーバーの AdditionalRoutes パラメータを使用して、URL パスとコンピュータのローカル フォルダ間のマッピングをカスタマイズすることもできます。
これらのパラメータの詳細については、「Pixel Streaming リファレンス」も参照してください。
プレイヤー入力オプションをカスタマイズする
「app.js」ファイルにはいくつかの JavaScript コンフィギュレーション パラメータが用意されており、カスタム プレイヤー ページ内でこれらをオーバーライドすることで、ユーザー入力に対するプレイヤー ウィジェットの応答を制御できます。inputOptions オブジェクトでは次のプロパティが公開されています。
| プロパティ | デフォルト値 | 説明 |
|---|---|---|
| controlScheme | ControlSchemeType.LockedMouse |
プレイヤーがウィジェットとやり取りする際に、プレイヤー ウィジェットがマウスをキャプチャしてロックするかどうかを指定します。以下の値を受け入れます。
|
| suppressBrowserKeys | true | この設定が有効な場合、プレイヤー ウィジェットはファンクション キー (F1 ～ F12 キー) および Tab キーのキープレス イベントが発生した際に通常の処理を行うのではなく、これらを Unreal Engine アプリケーションに渡します。 つまり、この設定が有効な間は、例えば F5 キーを押してもプレイヤー ページはブラウザで更新されません。代わりに、このイベントが Unreal Engine アプリケーションに渡されて、シェーダの複雑さを可視化するためのビューに切り替わります (このアプリケーション内で定義されている機能)。 |
| fakeMouseWithTouches | false | このオプションが有効な場合、スマートフォンやタブレットなどタッチ スクリーン機能装備のデバイスでユーザーがストリームを表示した際に、Unreal Engine アプリケーションによってシングルフィンガー タッチ イベントがマウス クリック イベントおよびドラッグ イベントとして解釈されます。この設定を有効にすると、モバイル デバイスのユーザーは Unreal Engine アプリケーションを部分的に制御できます。アプリケーションの入力コントローラーが特にタッチ入力イベントを処理しない場合でもこのような制御が可能です。 |
次のようにコード ブロックを含めることで、これらの値をプレイヤー ページで設定できます。「app.js」ファイルをページにロードしたら、load 関数を呼び出す前に必ずこのコードを実行してください。
<script>
inputOptions.controlScheme = ControlSchemeType.HoveringMouse;
inputOptions.fakeMouseWithTouches = true;
</script>
ユーザー入力を無効にする
1 つ以上のタイプの入力デバイスに対してユーザー入力を完全に無効にするには、プレイヤー ページの JavaScript 環境内で以下の関数を空の実装でオーバーライドします。
- registerHoveringMouseEvents - inputOptions.controlScheme を ControlSchemeType.HoveringMouse に設定すると、すべての入力マウス イベントが無効になります。
- registerLockedMouseEvents - inputOptions.controlScheme を ControlSchemeType.LockedMouse に設定すると、すべての入力マウス イベントが無効になります。
- registerTouchEvents - モバイル デバイスとタブレットでタッチ イベントが無効になります。
- registerKeyboardEvents - すべてのキーボード イベントが無効になります。
例えば、JavaScript の次のブロックをプレイヤー HTML ページに含めると、すべての入力を無効にできます。前述のとおり、「app.js」ファイルをページにロードした後、load 関数を呼び出す前にこのコードを実行してください。
<script>
registerHoveringMouseEvents = function() {}
registerLockedMouseEvents = function() {}
registerTouchEvents = function() {}
registerKeyboardEvents = function() {}
</script>
1 つ以上のタイプの入力を有効のまま維持するには、目的の入力タイプに対応する行をコメントアウトまたは削除します。
プレイヤー ウィジェット スタイルをカスタマイズする
カスタム HTML プレイヤー ページで、Pixel Streaming プレイヤー ウィジェット、「id="player"」を含む <div> 要素を定義しておきます。このウィジェットには、標準 HTML と CSS メソッドを使用してスタイリングを追加できます。
ただし、ウィジェットのサイズを初期化し直す必要がある場合もあります。通常、このような状況が生じるのは、ブラウザ ウィンドウのサイズが変更された場合 (ウィジェットが自動的に利用可能なスペースを埋めるように設定されている場合)、または入力ビデオ ストリームの解像度が更新された場合です。このような状況ではプレイヤー要素の style 属性が新しい値で上書きされ、これによって独自の HTML や JavaScript で設定した値が上書きされる可能性が生じます。
これを回避するために、styleAdditional と呼ばれる特殊なグローバル変数にカスタム CSS 値を設定できます。app.js がプレイヤーのサイズを変更し、スタイルをクリアする必要がある場合は、styleAdditional 変数で設定した値が、プレイヤー要素に割り当てられる新しいスタイル属性の最後に常に追加されます。例えば、次の値を設定すると、ユーザーがマウスをプレイヤー ウィジェットの上に置いたときに、マウス カーソルが手の形に変更されます。
styleAdditional = 'cursor: grab; cursor: -moz-grab; cursor: -webkit-grab';
Pixel Streaming ブループリント API にアクセスする
Unreal Engine 内で動作する Pixel Streaming プラグインでは、ゲームプレイ ロジック内で使用可能なブループリント API が公開されています。これを使用して、プレイヤー HTML ページで送信されるカスタム UI イベントを処理して、Unreal Engine からプレイヤー ページにイベントを発信することができます。
このブループリント API にアクセスするには、PixelStreamingInputComponent をレベルのアクタに追加します。アプリケーションの PlayerController が安全な選択です。そのためには、ブループリント メニューの Add Component をクリックして、ドロップダウンから [Pixel Streaming Input] を選択します。
クリックしてフルサイズで表示
UE 4.27 以前は、Pixel Streaming プラグインをロードすると、PixelStreamingInput コンポーネントは自動的に追加されました。これに問題が多かったため、上記のようにユーザー自身がプロジェクトに追加することになりました。
プレイヤー ページから UE4 に通信する
「`app.js」ファイルには 2 つの JavaScript 関数が用意されています。これらを HTML プレイヤー ページで呼び出して、ユーザーにイベントとコマンドをブラウザから Unreal Engine アプリケーションに送信させることができます。
emitCommandを使用して、コンソールコマンドを Unreal Engine に送り返すことができます。たとえば、フレームレートを表示するにはstat fpsを使用します。下記の「emitCommand 関数を使用する」を参照してください。emitUIInteractionは任意の文字列や JavaScript オブジェクトをゲームに送信します。この関数を使用して、独自のカスタム コマンドをプレイヤー UI から送信します。これにゲームプレイ ロジック内で応答することで、アプリケーションで必要なエフェクトを生み出すことができます。下記の「emitUIInteraction 関数を使用する」を参照してください。
emitCommand 関数を使用する
emitCommand 関数を呼び出す際は、これに JavaScript オブジェクトを渡す必要があります。このオブジェクトには、次の文字列のいずれかに一致するキーが含まれている必要があります。
ConsoleCommand- このキーを使用して、コンソール コマンドをリモート Unreal Engine アプリケーションで実行します。このキーの値は、実行するコマンドと必要なパラメータを含む文字列です。次に例を示します。例：
let descriptor = {
ConsoleCommand: 'stat fps'
}
emitCommand(descriptor);
Unreal Engine コンソール コマンドには強力な権限があるため、emitCommand 関数によりセキュリティ リスクが生じることがあります。この関数を機能させるには、Unreal Engine アプリケーションを起動する際、または Unreal Editor から [Standalone Game (スタンドアローンゲーム)] オプションを使用して起動する際に、コマンドラインで -AllowPixelStreamingCommands パラメータを指定する必要もあります。
emitUIInteraction 関数を使用する
emitUIInteraction 関数を呼び出す際に、これに単一の文字列または JavaScript オブジェクトを渡すことができます。次に例を示します。
emitUIInteraction("MyCustomCommand");
or
let descriptor = {
LoadLevel: "/Game/Maps/Level_2"
PlayerCharacter: {
Name:"Shinbi"
Skin:"Dynasty"
}
}
emitUIInteraction(descriptor);
JavaScript オブジェクトを渡した場合、emitUIInteraction 関数はそれを内部で JSON 文字列に変換します。続いて、結果の文字列が Unreal Engine アプリケーションの Pixel Streaming プラグインに返されます。これにより、入力コントローラーでイベントが発生します。アプリケーションのゲームプレイ ロジックで、Bind Event to OnPixelStreamingInputEvent ノードを使用して、これらの入力を処理するように独自のカスタム イベントをバインドします。例：
クリックしてフルサイズで表示
このイベントは、通常はゲーム開始時に一度だけバインドする必要があります。Unreal Engine アプリケーションのインスタンスに接続されたプレイヤー HTML ページで emitUIInteraction 関数が呼び出されるたびに、emitUIInteraction に渡された入力にかかわらず、カスタム イベントが自動的に呼び出されます。
割り当てるカスタム イベント (例えば、前の画像にある UI Interaction ノード) には Descriptor と呼ばれる出力があり、emitUIInteraction 関数によって Unreal Engine アプリケーションに送信された文字列を取得する際に使用できます。その値を使用して、emitUIInteraction が呼び出された場合のゲームプレイ コードの応答を指定することができます。
例えば、次のブループリントでは、emitUIInteraction に与えられた入力に文字列「MyCustomCommand」が含まれるかどうかをテストして、イベントを処理するためのカスタム関数を呼び出します。
クリックしてフルサイズで表示
最初に JavaScript オブジェクトを emitUIInteraction に渡した場合は、Pixel Streaming > Get Json String Value (JSON 文字列値の取得) ノードを使用して、その JSON オブジェクトからあらゆるキーの値を取得できます。例えば、次のブループリントでは LoadLevel というキーについてテストを行います。このキーが存在する場合は、そのイベントを処理するためのカスタム関数が呼び出されます。
クリックしてフルサイズで表示
ネスト構造のキーを取得する必要がある場合は、キーに対して JavaScript で一般的なドット記法を使用します。例えば、PlayerCharacter.Name や PlayerCharacter.Skin です。
UE4 からプレイヤー ページに通信する
プレイヤーの JavaScript 環境内で応答可能なカスタム イベントを、接続されているすべてのプレイヤー HTML ページに発信するように Unreal Engine アプリケーションを設定することができます。こうすることで、ゲームプレイ イベントに応じて Web ページの UI を変更できるようになります。
これを設定するには、次の手順を実行します。
- Unreal Engine アプリケーションでは、イベントをプレイヤー ページに発信する際は常に Pixel Streaming > Send Pixel Streaming Response (Pixel Streaming 応答を送信) ノードを使用します。プレイヤー ページに発生したイベントの内容を示すには、ノードにカスタム文字列引数を指定します。
クリックしてフルサイズで表示
- プレイヤー ページの JavaScript に、Unreal Engine アプリケーションからの応答イベントをページが受信するたびに起動するカスタム イベント ハンドラ関数を記述する必要があります。これに、Send Pixel Streaming Response ノードにより送信された元の文字列引数が渡されます。次に例を示します。例：
function myHandleResponseFunction(data) {
console.warn("Response received!");
switch (data) {
case "MyCustomEvent":
... // handle one type of event
case "AnotherEvent":
... // handle another event
}
}
app.jsで提供されるaddResponseEventListener関数を呼び出すことで、リスナー関数を登録します。この関数にイベント リスナーの固有の名前と独自の関数を渡します。次に例を示します。
addResponseEventListener("handle_responses", myHandleResponseFunction);
- イベント リスナーを削除する必要がある場合は、
removeResponseEventListenerを呼び出して同じ名前を渡します。次に例を示します。
removeResponseEventListener("handle_responses");
より複雑なデータを渡す必要がある場合は、Send Pixel Streaming Response ノードに渡す文字列を JSON 形式に変換できます。次に例を示します。
次に、JavaScript イベント ハンドラ関数内で JSON.parse(data) を使用して文字列をデコードし、JavaScript オブジェクトに戻します。
非アクティブの接続をタイムアウトするよう設定する
Pixel Streaming のデプロイメントの際は、状況によっては一定期間非アクティブのユーザーの接続を自動的に切断したい場合があります。例えば、利用可能な Unreal Engine アプリケーションの数に制限があり、マッチメイキングを行うサーバーによってこれらのインスタンスへのアクセスが制御されている場合などは、新たな接続リクエストに対して利用可能なアプリケーション インスタンスを確保するために、非アクティブの古い接続を切断しなければならないことがあります。
Pixel Streaming プレイヤー ページの設定を変更して、ユーザーがプレイヤー ウィジェットと一定期間 (カスタマイズ可能) やり取りしていないこと、つまり「AFK」 (Away From Keyboard： キーボードから離れている) を検出させることができます。AFK システムによって次のような警告が表示されます。
ユーザーが引き続き応答しない場合は、AFK システムによって最終的にはセッションが切断されます。
ユーザーによりプレイヤー パネルと何らかのやり取りがあった場合、AFK タイマーはリセットされます。これには、マウスを動かしたりドラッグしたり、マウス ボタンを押したり、キーボード上のキーを押したり、モバイル デバイス上でイベントをタッチしたりといったアクションだけでなく、emitCommand および emitUIInteraction 関数で設定したカスタム インタラクションが含まれます。
AFK システムを利用するには、プレイヤー ページの JavaScript 内で次の 3 つのプロパティを設定します。この設定は、「app.js」ファイルをロードした後に、load 関数を呼び出す前に行ってください。
| プロパティ | 説明 |
|---|---|
afk.enabled |
AFK システムでユーザー インタラクションを確認するかどうかを指定します。デフォルト値は「false」です。非アクティブな接続をタイムアウトさせるには、これを「true」に設定します。 |
afk.warnTimeout |
ユーザーがキーボードから離れた状態を維持できる最大期間 (秒) を設定します。これを過ぎると、プレイヤー ウィジェットに警告のオーバーレイが表示されます。デフォルト値は「120」秒、つまり 2 分間です。 |
afk.closeTimeout |
「afk.warnTimeout」の期間が過ぎて、ユーザーに接続切断についての警告メッセージが発せられた後に、実際にユーザーの接続が自動的に切断されるまでの期間 (秒) を設定する変数です。途中でユーザーがプレイヤー ウィジェットとやり取りした場合は切断されません。デフォルト値は「10」秒です。 |
オーバーレイの内容をカスタマイズする場合は、プレイヤー ページで updateAfkOverlayText() 関数の定義を変更します。実装では、afk.overlay.innerHTML プロパティを、AFK タイムアウト値を超えた場合にプレイヤー ウィジェットに表示させる HTML に設定します。