概要
インストール
EOS オーバーレイは、Epic Games Launcher によってインストールされます。ゲーム アプリケーションは、EOS サービス 再配布インストーラー を使用して前提条件の一部としてインストールすることも可能です。
SDK の初期化
Direct3D を初期化する前に、EOS SDK を初期化して、EOS_Platform_Create
を呼び出す必要があります。こうすることで、EOS オーバーレイが、ユーザーに表示する各ゲーム フレームでオーバーレイをレンダリングするのに必要なグラフィックス API フックをインストールすることができます。
Windows では、EOS オーバーレイは Direct3D9、Direct3D10、および OpenGL を実験的にサポートしています。実験的な機能を有効にするには、EOS_Platform_Create
を呼び出す前に、EOS_Platform_Options
の Flags
フィールドを適切な値で初期化します。
- 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 つです。
EOS_PF_LOADING_IN_EDITOR
- UE4 の Play-in-Editor (PIE)、Unity などのゲーム エディタで EOS SDK を使用している場合は必ず、このフラグを設定する必要があります。EOS_PF_DISABLE_OVERLAY
- オーバーレイ機能を明示的に無効にする場合は、このフラグを設定する必要があります。Ecom インターフェースの購入関連の機能が無効になります。EOS_PF_DISABLE_SOCIAL_OVERLAY
- オーバーレイ機能を明示的に無効にする場合は、このフラグを設定する必要があります。
互換性のあるレンダリング API とオペレーティング システム
Windows
利用の可能性 | API |
---|---|
利用可能 |
|
Experimental |
|
macOS
利用の可能性 | API |
---|---|
Coming Soon |
|
Linux
利用の可能性 | API |
---|---|
Coming Soon |
|
ソーシャル オーバーレイ
ソーシャル オーバーレイ (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 ボタン
プレイヤーは、[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 の招待機能の場合は、デプロイメントを アーティファクト にもマッピングしてください。
カスタム招待
Epic マッチメイキングを使用しないタイトルの場合、任意のペイロードで招待を送受信するための Custom Invites インターフェース があります。[Invite (招待)] ボタンをクリックすると、ソーシャル オーバーレイが EOS_CustomInvites_SendCustomInvite
を使ってカスタム招待を送信します。EOS_CustomInvites_AddNotifyCustomInviteReceived
と EOS_CustomInvites_RemoveNotifyCustomInviteReceived
は検知、カスタム UI 表示、カスタム招待の処理をすることが可能です。
ロビーを使用する
[Invite] ボタンをクリックすると、ソーシャル オーバーレイにより、ユーザーとゲームに代わって EOS_Lobby_SendInvite
を使用して、招待がロビー サービス経由で送信されます。ゲームはプレイヤーがいつオーバーレイで [Accept (承諾)] ボタンをクリックしたかを確認するために EOS_Sessions_AddNotifySessionInviteAccepted
を使用します。コールバック データには Invite ID が含まれており、これを使って Lobbies インターフェース内でゲームに関する情報を検索することができます。
セッション マッチメイキングを使用する
[Invite] ボタンをクリックすると、ソーシャル オーバーレイにより、ユーザーとゲームに代わって 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 呼び出しには、ゲームにエラー コードを含める必要があります。
セッション マッチメイキングの注意事項
現在のセッションが満員の場合、[Invite] ボタンは表示されません。また、招待されたプレイヤーが招待されたセッションに既に参加している場合、[Invite] ボタンは無効になります。セッションの「allow invites (招待を許可)」ステータスに影響を与える変更を通じて、招待のステータスをオーバーライドすることも可能です。セッション内のすべてのクライアントは、(Un)RegisterPlayer API の呼び出しを通じてセッションのステータスを維持する必要があります。
ネイティブ プラットフォームのフレンド
プレイヤーは、ソーシャル オーバーレイを使用して、Epic のフレンドとネイティブ プラットフォームのフレンドの両方とシームレスにやり取りできます。ソーシャル オーバーレイでネイティブ プラットフォームのフレンドを表示するには、ゲームは EOS SDK の初期化を IntegratedPlatform オプションとして提供する必要があります。インテグレーションの詳細については「Platform インターフェース」を参照してください。
アチーブメントを支援する
ソーシャル オーバーレイ はユーザーにアチーブメントのインターフェースを提供します。これを使用するには、Develper Portal でデータを適切に設定する必要があります。
アチーブメントのローカリゼーションはソーシャル オーバーレイの他の部分と同じルールに従います。本ページの冒頭および「ソーシャル オーバーレイの概要」で簡単に説明されています。
アチーブメントが非表示としてマークされているとロックされたアイコンが使用されますが、表示されるテキストは ソーシャル オーバーレイ ページ によって提供されます。アイコンが Dev Portal 内で提供されていない場合、デフォルトのアイコンがソーシャル オーバーレイ ページから提供されます。