プレイヤー Web ページをカスタマイズする

ストリーム ビデオとオーディオを再生する Web ぺージをカスタマイズする方法と、カスタマイズした Web ページと UE4 アプリケーション間でイベントを交換する方法を説明します。

Windows
MacOS
Linux

Pixel Streaming の Signaling and Web サーバーにはサンプル プレイヤー ページが用意されており、Unreal Engine アプリケーションからのメディアをストリーミングして、マウス、キーボード、タッチ イベントをアプリケーションに返すように設定されています。手順については、「Pixel Streaming 入門 」を参照してください。ニーズに合うようであれば、このデフォルト プレイヤー ページをそのまま使用してください。 

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

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

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

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>
  • <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

この設定が有効な場合、プレイヤー ウィジェットはファンクション キー (F1F12 キー) および 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 つ以上のタイプの入力を有効のまま維持するには、目的の入力タイプに対応する行をコメントアウトまたは削除します。

プレイヤー ウィジェット スタイルをカスタマイズする

ただし、ウィジェットのサイズを初期化し直す必要がある場合もあります。通常、このような状況が生じるのは、ブラウザ ウィンドウのサイズが変更された場合 (ウィジェットが自動的に利用可能なスペースを埋めるように設定されている場合)、または入力ビデオ ストリームの解像度が更新された場合です。このような状況ではプレイヤー要素の 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 にアクセスするには、次の手順に従います。

  1. Pixel Streaming プラグインは、常にスタートアップ時にコンポーネントを現在の Player Controller に追加します。これは、Actor (アクタ) > Get Component by Class (クラスごとにコンポーネントを取得) ノードを使用することで Player Controller から取得できます。[Component Class (コンポーネント クラス)] 入力をクリックして、リスト内で [PixelStreamingInputComponent] を見つけます。
    PixelStreamingInputComponent

    現在の Player Controller への参照が必要な場合は、前述のとおり、Game (ゲーム) > Get Player Controller (Player Controller の取得) ノードを使用します。

  2. Get Component by Class ノードの出力ポートからドラッグして、Pixel Streaming Input カテゴリを見つけます。

    クリックしてフルサイズで表示

プレイヤー ページから UE4 に通信する

「`app.js」ファイルには 2 つの JavaScript 関数が用意されています。これらを HTML プレイヤー ページで呼び出して、ユーザーにイベントとコマンドをブラウザから Unreal Engine アプリケーションに送信させることができます。

  • emitCommand では、コマンドのプリセット リストをゲームに送信したり、解像度を変更したり、コンソール コマンドを実行したり、エンコーダのビットレートを低減したりすることができます。下記の「emitCommand 関数を使用する 」を参照してください。

  • emitUIInteraction は任意の文字列や JavaScript オブジェクトをゲームに送信します。この関数を使用して、独自のカスタム コマンドをプレイヤー UI から送信します。これにゲームプレイ ロジック内で応答することで、アプリケーションで必要なエフェクトを生み出すことができます。下記の「emitUIInteraction 関数を使用する 」を参照してください。

emitCommand 関数を使用する

emitCommand 関数を呼び出す際は、これに JavaScript オブジェクトを渡す必要があります。このオブジェクトには、次の文字列のいずれかに一致するキーが含まれている必要があります。

  • ConsoleCommand - このキーを使用して、コンソール コマンドをリモート Unreal Engine アプリケーションで実行します。このキーの値は、実行するコマンドと必要なパラメータを含む文字列です。次に例を示します。例:

    let descriptor = {
        ConsoleCommand: 'stat fps'
    }
    emitCommand(descriptor);
  • Resolution - このキーを使用して、Unreal Engine アプリケーションのレンダリング解像度をリセットします。このキーの値は Width および Height プロパティを含むオブジェクトです。次に例を示します。例:

    let descriptor = {
        Resolution: {
            Width:1024,
            Height:768
        }
    }
    emitCommand(descriptor);
  • Encoder - このキーを使用して、メディア ストリームの品質を制御するコマンドをエンコーダに送信します。現時点では、BitrateReduction コマンドのみをサポートしています。この値は、利用可能な帯域幅の測定値の何 % をビデオ エンコーダ ビットレートに割り当てるかを指定しますこの値の設定が高すぎるとネットワークが輻輳してパケットが失われることがあり、その結果レイテンシーが増加して、クライアントでビデオにアーティファクトが発生します。デフォルトではこの値は 50% に設定されています。デプロイメント時にレイテンシーおよびビデオ アーティファクトの問題が生じる場合は、この値をさらに低く設定してみてください。例:

    let descriptor = {
        Encoder: {
            BitrateReduction:20
        }
    }
    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.NamePlayerCharacter.Skin です。

UE4 からプレイヤー ページに通信する

プレイヤーの JavaScript 環境内で応答可能なカスタム イベントを、接続されているすべてのプレイヤー HTML ページに発信するように Unreal Engine アプリケーションを設定することができます。こうすることで、ゲームプレイ イベントに応じて Web ページの UI を変更できるようになります。

これを設定するには、次の手順を実行します。

  1. Unreal Engine アプリケーションでは、イベントをプレイヤー ページに発信する際は常に Pixel Streaming > Send Pixel Streaming Response (Pixel Streaming 応答を送信) ノードを使用します。プレイヤー ページに発生したイベントの内容を示すには、ノードにカスタム文字列引数を指定します。

  2. プレイヤー ページの 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
        }
    }
  3. app.js で提供される addResponseEventListener 関数を呼び出すことで、リスナー関数を登録します。この関数にイベント リスナーの固有の名前と独自の関数を渡します。次に例を示します。

    addResponseEventListener("handle_responses", myHandleResponseFunction);
  4. イベント リスナーを削除する必要がある場合は、removeResponseEventListener を呼び出して同じ名前を渡します。次に例を示します。

    removeResponseEventListener("handle_responses");

より複雑なデータを渡す必要がある場合は、Send Pixel Streaming Response ノードに渡す文字列を JSON 形式に変換できます。次に例を示します。
Send Pixel Streaming response using JSON
次に、JavaScript イベント ハンドラ関数内で JSON.parse(data) を使用して文字列をデコードし、JavaScript オブジェクトに戻します。

非アクティブの接続をタイムアウトするよう設定する

Pixel Streaming のデプロイメントの際は、状況によっては一定期間非アクティブのユーザーの接続を自動的に切断したい場合があります。例えば、利用可能な Unreal Engine アプリケーションの数に制限があり、マッチメイキングを行うサーバーによってこれらのインスタンスへのアクセスが制御されている場合などは、新たな接続リクエストに対して利用可能なアプリケーション インスタンスを確保するために、非アクティブの古い接続を切断しなければならないことがあります。

Pixel Streaming プレイヤー ページの設定を変更して、ユーザーがプレイヤー ウィジェットと一定期間 (カスタマイズ可能) やり取りしていないこと、つまり「AFK」 (Away From Keyboard: キーボードから離れている) を検出させることができます。AFK システムによって次のような警告が表示されます。

AFK timeout warning

ユーザーが引き続き応答しない場合は、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 に設定します。

Select Skin
Light
Dark

新しい Unreal Engine 4 ドキュメントサイトへようこそ!

あなたの声を私たちに伝えるフィードバックシステムを含め、様々な新機能について開発をおこなっています。まだ広く使える状態にはなっていないので、準備ができるまでは、ドキュメントフィードバックフォーラムで、このページについて、もしくは遭遇した問題について教えていただけると助かります。

新しいシステムが稼働した際にお知らせします。

フィードバックを送信