SDK Integration

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

17 分で読めます

概要

インストール

EOS オーバーレイは、Epic Games Launcher によってインストールされます。ゲーム アプリケーションは、EOS サービス 再配布インストーラー を使用して前提条件の一部としてインストールすることも可能です。

SDK の初期化

Direct3D を初期化する前に、EOS SDK を初期化して、EOS_Platform_Create を呼び出す必要があります。こうすることで、EOS オーバーレイが、ユーザーに表示する各ゲーム フレームでオーバーレイをレンダリングするのに必要なグラフィックス API フックをインストールすることができます。

Windows では、EOS オーバーレイは Direct3D9、Direct3D10、および OpenGL を実験的にサポートしています。実験的な機能を有効にするには、EOS_Platform_Create を呼び出す前に、EOS_Platform_OptionsFlags フィールドを適切な値で初期化します。

  • Direct3D9 - EOS_PF_WINDOWS_ENABLE_OVERLAY_D3D9
  • Direct3D10 - EOS_PF_WINDOWS_ENABLE_OVERLAY_D3D10
  • OpenGL - EOS_PF_WINDOWS_ENABLE_OVERLAY_OPENGL

状況によっては、オーバーレイ機能を完全に無効にする必要がある場合もあります。このような状況が発生する例としては、デベロッパーがエディタでゲームを実行しているときに、エディタのグラフィックス API を接続すると問題が発生する場合などが挙げられます。EOS_Platform_Create に渡される EOS_Platform_Options は、64 個のフラグ用のスペースを持つビットフィールドである Flags メンバーを取るように拡張されました。現在のところ、オーバーレイを無効にするフラグは次の 3 つです。

  1. EOS_PF_LOADING_IN_EDITOR - UE4 の Play-in-Editor (PIE)、Unity などのゲーム エディタで EOS SDK を使用している場合は必ず、このフラグを設定する必要があります。
  2. EOS_PF_DISABLE_OVERLAY - オーバーレイ機能を明示的に無効にする場合は、このフラグを設定する必要があります。Ecom インターフェースの購入関連の機能が無効になります。
  3. EOS_PF_DISABLE_SOCIAL_OVERLAY - オーバーレイ機能を明示的に無効にする場合は、このフラグを設定する必要があります。

互換性のあるレンダリング API とオペレーティング システム

Windows

利用の可能性API
利用可能
  • Direct3D 12
  • Direct3D 11
  • Vulkan
Experimental
  • Direct3D 10
  • Direct3D 9
  • OpenGL

macOS

利用の可能性API
Coming Soon
  • Metal
  • Vulkan
  • OpenGL

Linux

利用の可能性API
Coming Soon
  • Vulkan
  • OpenGL

ソーシャル オーバーレイ

ソーシャル オーバーレイ (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 が使用されます。

オンライン ステータス

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

有効なゲーム

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

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

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

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

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

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

  • bPResenceEnabled = true でロビーまたはセッションインターフェースを使用する
    • これらの機能を使用でき、EOS は参加と招待の精度を維持します
  • ロビーやセッションのインターフェースを使用せず、 SetJoinInfo を使用してください
    • ゲームへの参加可能性を反映するために、必要に応じてその値を設定 / 空に保つ責任があります

参加ボタン

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

ロビーを使用する

ロビー サービスを使用すると、ロビー ID が自動的に送信されます。次に、ゲームは EOS_Lobby_AddNotifyJoinLobbyAccepted を使用して、プレーヤーが [参加] ボタンをクリックしたことを確認します。クリーンアップ後、ゲームは提供された 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 Info String が含まれます。

招待ボタン

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

カスタム招待

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

ロビーを使用する

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

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

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

招待のライフサイクルと注意事項

招待のライフタイムは招待したしたユーザーではなくセッション関連付けられています。つまり、ユーザーがロビーやセッションを離れてある程度の時間が経過した後でも、そのユーザーのフレンドをそのセッションに参加させることが可能です。招待は、受信側のゲーム クライアントではなく、バックエンド サービスでのみ破棄されます。招待が使用されるか、招待のロビー/セッションが破棄されると、招待は破棄されます。

招待が長期間使用されていない場合、招待がもともと関連付けられていたロビーまたはセッションが破棄された可能性があります。 この場合、招待は古くなっています。 ゲーム クライアントが古い招待にアクセスしようとすると、呼び出しが失敗します。 招待が古くなっている場合、プレイヤーに表示されるエラーの種類は次のとおりです。

  • The invite is not found (招待が見つかりません)
  • The game is full (ゲームは満席です)
  • The session doesn't exist anymore (セッションはすでに存在しません)

SDK が認識したエラーは、すぐに ソーシャル オーバーレイ に反映されます。ただし、受信側のゲーム クライアントは、発生したエラーや競合状態を処理する必要があります。 これは、受信側のゲーム クライアントのプレイヤーが招待を受け入れた後に行う必要があります。例えばた、セッションが招待に使用できなくなったことをゲームがプレイヤーに通知します。 ゲームは、招待が成功したか失敗したかに関係なく、ソーシャル オーバーレイに招待が処理されたことを通知する必要があります。 これを行うには、ゲームは、EOS_UI_AcknowledgeEventId() を呼び出す必要があります。 この API 呼び出しには、ゲームにエラー コードを含める必要があります。

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

現在のセッションが満員の場合、[招待] ボタンは表示されません。また、招待されたプレイヤーが招待されたセッションに既に参加している場合、[招待] ボタンは無効になります。セッションの「allow invites (招待を許可)」ステータスに影響を与える変更を通じて、招待のステータスをオーバーライドすることも可能です。セッション内のすべてのクライアントは、(Un)RegisterPlayer API の呼び出しを通じてセッションのステータスを維持する必要があります。

ネイティブ プラットフォームのフレンド

プレイヤーは、ソーシャル オーバーレイを使用して、Epic のフレンドとネイティブ プラットフォームのフレンドの両方とシームレスにやり取りできます。ソーシャル オーバーレイでネイティブ プラットフォームのフレンドを表示するには、ゲームは EOS SDK の初期化を IntegratedPlatform オプションとして提供する必要があります。インテグレーションの詳細については「Platform インターフェース」を参照してください。

実績を支援する

ソーシャル オーバーレイ はユーザーに実績のインターフェースを提供します。これを使用するには、デベロッパー ポータル でデータを適切に設定する必要があります。

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

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