Unreal Engine でのプレイヤー Web ページをカスタマイズする | Unreal Engine 5.0 ドキュメンテーション

Epicでは、GoogleがWebRTCのバージョンにおける脆弱性を公開 (詳細はこちら)したことを認識しており、EOS SDKに対する影響および次のステップを調査しています。

JavaScript や HTML など Web テクノロジーに関する十分な知識があり、独自の工夫を取り入れたい場合は、プレイヤーページをカスタマイズして、Unreal Engine のコンテンツとリモートで対話する独自のカスタム UI を作成してください。ゲームプレイイベントのトリガーやそれへの応答、Unreal Engine のビヘイビアを制御するコンソールコマンドの発行など、さまざまな操作を実行できます。

デフォルトプレイヤーページをベースとして独自のカスタムプレイヤーページを作成することをお勧めします。このページは Unreal Engine インストールフォルダの「Samples/PixelStreaming/WebServers/SignallingWebServer/www/player.html」にあります。このページに記載されている情報を参考にして、ページを拡張してプロジェクトのゲームプレイロジックと連携させる方法について学んでください。

デフォルトのプレイヤーページ

HTML5 UI でカスタマイズしたプレイヤーページ

HTML ページ要件

カスタム HTML プレイヤーページでは、いくつかの要件に従う必要があります。

「/scripts/webRtcPlayer.js」ファイルを含める必要があります。このファイルは、ブラウザと Unreal Engine アプリケーション間の通信を処理します。サーバーからのメディアストリームを受信して表示します。必要な場合を除き、この JavaScript ファイルは変更しないでください。
```
              <script type="text/javascript" src="scripts/webRtcPlayer.js"></script>
```
<script type="text/javascript" src="scripts/webRtcPlayer.js"></script>
同様に「/scripts/app.js」ファイルを含めることも強く推奨します。このファイルでは、キーボード、マウス、タッチイベントを処理するイベントリスナーが設定されます。また、プレイヤーページで利用可能な複数の関数やフックも含まれます。これらについては、このページの後のセクションで説明されています。JavaScript に関して十分な知識がある場合は、ニーズに合わせてこのファイルのコードをカスタマイズし、デフォルトのビヘイビアを変更できます。例えば、キーボード入力を無効にして、マウスとタッチイベントはそのまま動作するようにする場合は、このファイルをカスタマイズして、キーボードイベントを処理するコードを見つけてコメントアウトする必要があります。
```
              <script type="text/javascript" src="scripts/app.js"></script>
```
<script type="text/javascript" src="scripts/app.js"></script>
このページには ID が「player」である div 要素が必要です。この要素は、UE4 アプリケーションからストリーミングされたビデオフレームに置き換えられます。
```
              <div id="player"></div>
```
<div id="player"></div>
ページのロード時には、「app.js」ファイルによって提供される load 関数を呼び出す必要があります。例えば、これを実行するには onload ハンドラを body タグに追加します。
```
              <body onload="load()">
```
<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`	プレイヤーがウィジェットとやり取りする際に、プレイヤーウィジェットがマウスをキャプチャしてロックするかどうかを指定します。以下の値を受け入れます。 `ControlSchemeType.LockedMouse` - このコントロールスキームがアクティブであるとき、プレイヤーウィジェットをクリックすると、マウスカーソルをキャプチャしてロックします。その後のマウスの動きは、Unreal Engine アプリケーションの入力コントローラーに迅速に渡されます。これにより、通常、ユーザーはマウスをドラッグするだけで、カメラを移動して回転できるようになります。プレイヤーウィジェットの制御からカーソルを解放するには、Esc キーを押します。 `ControlSchemeType.HoveringMouse` - このコントロールスキームがアクティブな場合は、マウスカーソルをプレイヤーウィジェットの上に置いてもそれ以外の操作は行われません。マウスの動きを Unreal Engine アプリケーションの入力コントローラーに送信するには、ユーザーはマウスの左ボタンをクリックしたままにする必要があります。
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 のデプロイメントの際は、状況によっては一定期間非アクティブのユーザーの接続を自動的に切断したい場合があります。例えば、利用可能な 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 に設定します。