ソーシャル オーバーレイ統合

ゲーム内から EOS ソーシャル オーバーレイとフレンドのリストにアクセスする方法を説明します。

ソーシャル オーバーレイ (Social Overlay) は、ゲーム内からアクセス可能な Epic Online Services (EOS) の UI 要素です。デフォルトの統合では、shift-F3 を使用して [Social Overlay] にアクセスします。ソーシャル オーバーレイ で利用可能な主な機能は、ゲーム管理機能プレイヤー プレゼンス が提供されている フレンド リスト です。ゲーム管理によって使って、プレイヤーはフレンドをゲーム セッションに招待したり、フレンドが参加しているゲーム セッションに参加することができます。プレイヤー プレゼンスによって、プレイヤーのオンライン ステータス、有効なゲーム、ゲームで定義されているリッチ プレゼンス テキストの詳細が表示されます。

Exclusive Input モードを処理する

ソーシャルオーバーレイ (またはチェックアウトや認証などの EOS SDK によって管理されるオーバーレイ) が表示される間、すべてのキーボードとマウスの入力がオーバーレイによって無効になる可能性があります。オーバーレイは、ユーザーの意図がある場合にのみ表示されます。この意図に基づいてユーザーはゲームではなくオーバーレイを操作したいと考えているため、ゲームはキーボードまたはマウスの入力を受け取りません。

この間の動作を変更するシステム SDK ユーザー入力メソッド (Win32 API 関数 ShowCursor など) もあります。このメソッドのサポートおよび一般的なユーザー ステータスの情報提供をするために、ゲームは EOS_UI_AddNotifyDisplaySettingsUpdated を使用してコールバックを登録できます。コールバック データには、Visible フラグと Exclusive Input フラグの両方が含まれます。 コールバックは常に次の EOS_Platform_Tick 呼び出しで起動して、オーバーレイの現在のステータスをゲームに通知します。

購入中にソーシャル トーストを受信するなど、複数のブラウザ インスタンスが同時に Visible フラグに影響を与える可能性があります。さらに重要な使用例は、表示されているブラウザ インスタンスがユーザーの操作を必要とする場合です。この場合、Exclusive Input フラグは true になります。排他入力フラグに影響を与えるには、ブラウザ インスタンスも表示されている必要があります。

ローカリゼーション

ソーシャルオーバーレイのテキストのローカライズに使用するロケールコードは、Epic アカウントの作成時にプレーヤーが選択した言語、またはゲームが提供するオーバーライド値の 2 つのソースのいずれかになります。オーバーライド値を使用する場合は、ユーザーが Epic アカウントで選択したものに関係なく使用される値になります。これは、 `EOS_Platform_SetOverrideLocaleCode`を使用して行うことができます。

フレンド リストのプレイヤー プレゼンスを使用する

Presence Service (プレゼンス サービス) では、オンラインのユーザーのすべてのフレンドに共有され、変更時に更新される プレゼンス ステータス を維持管理します。オンライン ステータス の初期化と消去には、プレイヤーのログイン ステータスが使用されます。プレイヤーがプレイ中のゲームを特定するには、EOS_Initialize に提供する ProductName が使用されます。また、このサービスでは EOS_PresenceModification_SetRawRichText に提供されているすべての RichText が使用されます。

タイトルはプレゼンス情報を管理します。Epic は、最も機密性の高いゲームに対する追加的なセーフガードとして、開発中にプレゼンス情報をコードネームに設定することを推奨します。デフォルトのゲーム名は EOS_InitializeProductName フィールドにあります。

オンライン ステータス

プレイヤーが EOS_Auth_Login および EOS_Auth_Logout を使って EOS サービスに接続またはサービスを切断した際に、そのプレイヤーのオンライン ステータスはそれぞれ [Online (オンライン)] または [Offline (オフライン)] になります。EOS_PresenceModification_SetStatus API を使用することで、より詳細なステータスを表示することもできます。プレイヤーのフレンドのステータスは [ソーシャル オーバーレイ(Overlay/Social/Overview)] のフレンド ページに表示されます。

有効なゲーム

[Status パネル] 内で、表示されるゲーム名は、から ProductName から EOS_Initialize へ直接共有されます。これは、ホストの [language settings (言語設定)] で定義された製品名です。

リッチ プレゼンス テキスト

リッチ プレゼンス テキスト は、他のプレイヤーにゲームの概要を説明する内容にします。EOS_PresenceModification_SetRawRichText に提供する文字列がそのまま共有され、フレンド ページ内でフレンド ステータスの一部として表示されます。

フレンド リストのゲーム管理機能を使用する

ゲーム管理のインターフェースには [Join (参加)] ボタンと [Invite (招待)] ボタンが含まれています。実際どのように統合されているかは、ゲームとその セッション サービス または ロビー サービス の利用方法によって異なります。また、プレイヤーのアカウントをセッション サービス (Interfaces/Sessions) に関連付けるために、ゲームは Connect API も使用する必要があります。

ソーシャルオーバーレイを使用する場合、2 つの実装オプションがあります。

  • bPResenceEnabled = true でロビーまたはセッションインターフェースを使用する

    • これらの機能を使用でき、EOS は参加と招待の精度を維持します

  • ロビーやセッションのインターフェースを使用せず、 SetJoinInfo を使用してください

    • ゲームへの参加可能性を反映するために、必要に応じてその値を設定 / 空に保つ責任があります

Join ボタン

プレイヤーは、[Join] ボタンをクリックすることでフレンドのゲームに参加できます。SDK との統合は、使用されているゲーム管理サービスによって異なります。リモートプレーヤーのプレゼンスに Lobby ID、Session ID、または Join Info String (参加情報文字列) のいずれかが含まれていると、ボタンが有効になります。このデータは、プレゼンス サービス を使用してすべての友達に転送されます。これら 3 つの識別子すべてに、ユーザーが [Join] ボタンを押したときのコールバックが関連付けられています。ゲームには、現在のステータスのクリーンアップ後にユーザーの意図を考慮することが求められています。

ロビーを使用する

ロビー サービスを使用すると、ロビー ID が自動的に送信されます。次に、ゲームは EOS_Lobby_AddNotifyJoinLobbyAccepted を使用して、プレーヤーが [Join] ボタンをクリックしたことを確認します。クリーンアップ後、ゲームは提供された UiEventId を使用して、EOS_Lobby_CopyLobbyDetailsHandleByUiEventId によって関連付けられたロビーを取得し、それに参加する必要があります。参加が失敗した場合、ゲームは EOS_UI_AcknowledgeEventId を呼び出してソーシャル オーバーレイがそのステータスを更新できるようにすることが求められます。

セッション マッチメイキングを使用する

セッション マッチメイキング サービス を使用すると、セッション ID が自動的に送信されます。次に、ゲームは EOS_Sessions_AddNotifyJoinSessionAccepted を使用して、プレーヤーが [Join] ボタンをクリックしたことを確認します。クリーンアップ後、ゲームは提供された UiEventId を使用して、EOS_Session_CopySessionHandleByUiEventId によって関連付けられたロビーを取得し、それに参加する必要があります。参加が失敗した場合、ゲームは EOS_UI_AcknowledgeEventId を呼び出してソーシャル オーバーレイがそのステータスを更新できるようにすることが求められます。

カスタム サービスを使用する

プレーヤーの Join Info String を手動で設定するには、 EOS_PresenceModification_SetJoinInfo を使用します。開発者は、必要に応じて Join Info String の意味を自由に定義できます。

次にゲームは EOS_Presence_AddNotifyJoinGameAccepted を使って、プレイヤーが [Join] ボタンをクリックしたことを確認します。コールバック データには Join Info String が含まれます。

Invite ボタン

プレイヤーは、[Invite (招待)] ボタンを使ってフレンドをゲームに招待することができます。SDK との統合は、使用されているゲーム管理サービスによって異なります。それぞれに関連づけられた通知コールバックがあります。[Join] ボタンと同様に、ゲームにはユーザーの意図を考慮するために最善を尽くすことが求められます。Epic Games Launcher の招待機能の場合は、デプロイメントを アーティファクト にもマッピングしてください。

Custom Invites

Epic マッチメイキングを使用しないタイトルの場合、任意のペイロードで招待を送受信するための Custom Invites インターフェース があります。[Invite] ボタンをクリックすると、ソーシャル オーバーレイが EOS_CustomInvites_SendCustomInvite を使ってカスタム招待を送信します。EOS_CustomInvites_AddNotifyCustomInviteReceivedEOS_CustomInvites_RemoveNotifyCustomInviteReceived は検知、カスタム UI 表示、カスタム招待の処理をすることが可能です。

ロビーを使用する

[Invite] ボタンをクリックすると、ソーシャル オーバーレイにより、ユーザーとゲームに代わって EOS_Lobby_SendInvite を使用して、招待がロビー サービス経由で送信されます。ゲームはプレイヤーがいつオーバーレイで [Accept (承諾)] ボタンをクリックしたかを確認するために EOS_Sessions_AddNotifySessionInviteAccepted を使用します。コールバック データには Invite ID が含まれており、これを使って Lobbies インターフェース内でゲームに関する情報を検索することができます。

セッション マッチメイキングを使用する

[Invite] ボタンをクリックすると、ソーシャル オーバーレイにより、ユーザーとゲームに代わって EOS_Sessions_SendInvite を使用して、招待が Sessions インターフェース 経由で送信されます。ゲームは EOS_Sessions_AddNotifySessionInviteAccepted を使って、プレイヤーが [Accept (承諾)] ボタンをクリックしたことを確認します。コールバック データにはセッション ID が含まれており、これを使ってセッション インターフェース内でゲームに関する情報を検索することができます。

セッション マッチメイキングの注意事項

現在のセッションが満員の場合、[Invite] ボタンは表示されません。また、2 人のユーザーが同じセッションにいる場合、[Invite] ボタンは無効になります。セッションのステータスを (Un)RegisterPlayer API の呼び出しを通じて維持するかどうかはゲームによって異なります。セッションの「allow invites (招待を許可)」ステータスに影響を与える変更を通じて、招待のステータスをオーバーライドすることも可能です。

オーバーレイは競合状態は処理しません。招待を承諾しても、そのユーザーが必ずしもそのセッションに参加できるとは限りません。単にその可能性が高いことを示すのみです。それでもゲームは、他のメカニズムを使用して、ホストに参加しようとしているクライアントの行動を強制実行または調整する役割を担っています。例えば、1 つの空きスロットに対して、2 つのクライアントが招待をまったく同じ時刻に承諾した場合などがあります。

招待の ライフタイム は、招待したユーザーではなくセッション関連付けられています。つまり、ユーザーがセッションを離れてある程度の時間が経過した後でも、そのユーザーのフレンドをそのセッションに参加させることが可能です。招待は、自身が関連付けられているセッションが終了した際に破棄されます。招待のステータスはソーシャル オーバーレイには反映されないため、呼び出しが失敗することがあります。オーバーレイでは、発生するエラーはすべてメッセージ ボックスとして表示されます。

アチーブメントを支援する

ソーシャル オーバーレイ はユーザーにアチーブメントのインターフェースを提供します。これを使用するには、Develper Portal でデータを適切に設定する必要があります。

アチーブメントのローカリゼーションはソーシャル オーバーレイの他の部分と同じルールに従います。本ページの冒頭および「ソーシャル オーバーレイの概要」で簡単に説明されています。

アチーブメントが非表示としてマークされているとロックされたアイコンが使用されますが、表示されるテキストは ソーシャル オーバーレイ ページ によって提供されます。アイコンが Dev Portal 内で提供されていない場合、デフォルトのアイコンがソーシャル オーバーレイ ページから提供されます。