Epic Online Services (EOS) の概要

Epic Online Services (EOS) は、高速で簡単、かつ信頼性の高い高品質のゲームの起動、操作、スケーリングを可能にするために作成された無料のクロスプラットフォーム サービスです。

単一の SDK で、デベロッパーとユーザーの両方にとってユーザー フレンドリーなエコシステムをビルドしやすくなります。どのような形でゲームをビルド・公開する場合でも、クリエイターとデベロッパーの両方にメリットがあります。これを利用することで、さまざまなプラットフォームを使用する友人とプレイする場合でも同じ品質のエクスペリエンスを実現できます。Epic の使命は、SDK を可能な限り移植しやすいように設計して、あらゆるエンジンやストアで動作したり、どんな主要なプラットフォームでも統合できるものを作ったりすることです。

これらのサービスには両方のゲーム サービスが含まれており、Epic アカウント サービス および Epic Games ストア と統合可能です。

SDK の基礎

EOS SDK には、C と C# ラッパーの 2 つの種類があります。

C を重点的に使用することで、コンパイラの選択、実装、呼び出し規約、データサイズ、またはアライメントに関係なく、統合機能を確保する安定したアプリケーション バイナリ インターフェース (ABI) を提供することが可能です。

これにより、SDK の独立したコードパッチを適用して開発の中断を少なくして、修正や更新を配布した後にアプリケーションを再コンパイルすることなく、SDK の寿命を維持できます。さらにこの場合、パブリック API のより慎重な公開が可能になります。

現在、EOS SDK は次のプラットフォームをサポートしています。

  • Nintendo Switch

  • PlayStation

  • Xbox

  • iOS

  • Android

  • Windows

  • Mac

  • Linux

バージョン管理

EOS SDK のバージョン管理を使用することで、API が変更されても、旧バージョンの SDK を使用するゲームとの後方互換性が保証されます。すべてのインターフェース、関数、およびデータ型には、それぞれに関連付けられたバージョンがあります。

新しい SDK バージョンがリリースされると、その SDK は旧バージョンを認識してサポートし、旧バージョンで作成されたデータや関数呼び出しに適切に対応できます。これには、元のバージョンの関数を内部で呼び出して、元の入力構造を新しい形式に移行し、可能な限り妥当なデフォルトを設定することなどが含まれます。

SDK を使用する古い製品は、更新なしで EOS との互換性を維持しています。

インターフェース ハンドル

EOS の機能は、モジュール式のサービス固有のインターフェースによってグループ化されています。たとえば、Lobbies) インターフェース は製品のロビーの作成とやり取りを処理し、Friends インターフェース はフレンドリストなどの機能を管理します。

EOS SDK ではPlatform インターフェース で提供される不透明型のハンドルを使用してインターフェースを公開します。インターフェース ハンドルの存続期間は Platform インターフェース自体が存続する限り継続し、そのインターフェースを使用するすべての API 関数の最初のパラメータとして必要です。

命名規則

使用方法と意図をわかりやすくするため、EOS SDK インターフェースでは次のような一貫した命名規則とプレフィックスを使用します。

命名規則

使用

Create

メモリを割り当てます。Release 関数とペアでの使用を想定しています。

Copy

Query 関数への以前の呼び出しからキャッシュされたデータを取得します。Release 関数とのペアでの使用を想定しています。

Release

この関数はメモリを解放します。これらは、Create 関数か Copy 関数と対応します。

Query

不特定期間にわたってバックエンド サービスと非同期的にやり取りします。このような呼び出しは、接続性に応じて、調整または再試行されることがあります。

Get

キャッシュ値が構造体を必要とせず、単なる値である場合に使用されます。バッファを必要とする文字列に Get を追加します。

関数シグネチャ

EOS SDK のすべての関数には、次のようなよく似た予測可能なシグネチャがあります。

  • インターフェースの最初のパラメータが常にハンドル。

    • C# の場合、ハンドル パラメータを渡す必要がない。

  • 「オプション」データ構造が、関数のすべてのパラメータをカプセル化し、API バージョン情報を含んでいる。

  • 非同期関数もアプリケーション固有のコールバック関数を備えているため、ユーザー定義のコンテキスト情報を受け入れ、コールバック関数を処理することができる。このコールバック関数は、非同期操作が最終的に成功または失敗したときに実行されます。また、接続の問題による遅延に対応するために実行されることもあります。

エラー ハンドリング

EOS C SDK 関数のエラーコードは、一般的なエラー値と単一のインターフェースに固有のエラーの両方を追加するため、EOS_EResult 型を使用します。たとえば、EOS_Success 値を持つ列挙型 EOS_EResultEOS_EResult::EOS_Success として表示されます。

C# の場合、Result 型を使用して一般的なエラー値とインターフェース固有のエラーを含めることで、エラーコードがわずかに変化します。C SDK の例と比較すると、Success 値を持つ列挙型 ResultResult.Success として表示されます。

一般的なエラーでは、EOS_<ErrorCode> 形式を取り、インターフェース固有のエラー コードは EOS_<Interface>_<ErrorCode> として表示されます。次に例を示します。

エラー コード

意味

EOS_InvalidParameters

関数に渡された未設定または無効な入力パラメータが 1 つ以上あります。

EOS_InvalidUser

操作にユーザーが必要ですが、指定されたユーザーが無効であるかユーザーが指定されていません。

EOS_MissingPermissions

アクセス制限により、バックエンド システムがリクエストを拒否しました。

EOS_UnrecognizedResponse

SDK がバックエンドの応答を解析できませんでした。

EOS_OperationWillRetry

バックエンドの接続性が損なわれているため、SDK が再試行します。

EOS_IncompatibleVersion

呼び出しコードが送信した API バージョン パラメータが、SDK の関数のバージョン番号と一致しません。

EOS_Auth_TokenInvalid

Auth インターフェース に固有の、ローカル認証セッションが期限切れになったか、無効になったため、ユーザーは再度ログインする必要があります。

文字列

入力および出力の両方の文字列は、UTF-8 形式である必要があります。

メモリの割り当て

SDK 関数がコールバックにデータ構造を提供する必要がある場合、SDK ではデータ用のメモリを割り当て、コールバック関数が完了するとすぐにメモリを解放します。そのデータのコピーをキャッシュする必要がある場合は、コールバック関数の存続期間中にコピーを作成する必要があります。また、システムにカスタム メモリ アロケータが必要な場合は、SDK 作成時に指定する必要があります。

動詞 Get が名前に含まれる SDK 関数は、その SDK 関数が使用するメモリも所有しています。コールバックと同様に、後でデータにアクセスする必要がある場合は、そのデータのコピーを作成する必要があります。

動詞 Copy が名前に含まれる SDK 関数は例外です。これらの関数では、キャッシュ データのコピーを返し、呼び出し元がそのコピーの所有権を取得することが予期されます。C SDK でコピーを解放することはないため、SDK をシャットダウンする前に、対応する Release 関数を呼び出す必要があります。ラッパーが自動的にリリースを行うため、C# SDK がコピーされた構造体を手動でリリースする必要はありません。

サービス使用上の制限事項

すべてのユーザーにとって安定・信頼できるエコシステムを維持するため、Epic Online Services (EOS) は、クライアントの要求レート制限とサービス使用クォータを実装しています。SDK API がコードと正しく統合されている場合は、リクエストはその制限と割り当て使用量まで達することはありません。

ただし、制限や SDK のログ出力には注意を払うようにしてください。内部プレイテスト中は、「誤ったログが出力されていないか」をチェックして、EOS 関数が結果 EOS_TooManyRequests を返したり、誤った使用パターンに関する警告を発していないことを確認する必要があります。

クライアント要求の調整とサービス使用量の割り当ては、個々の製品が EOS エコシステム全体に与える影響を制限するために並行して機能しています。

スロットルをリクエストする

EOS SDK が、バックエンドサービスへの呼び出しが速すぎることを検出すると、ローカル クライアントは EOS_TooManyRequests エラー コードで API 呼び出しを拒否することで自己スロットルを行います。

バックエンド サービスには、最大使用ガイドラインを超えた個々のクライアントまたはホストされたサーバーからの要求を拒否する同様の機能があります。EOS SDK はこれを EOS_TooManyRequests としてレポートし、HTTP データで指定された時間で再試行を行うロジックを内部的に処理します。

サービス使用量の割り当て

各サービスは、デプロイメントごとに使用クォータを適用して、バックエンド サービスが常に製品にすぐに利用できる必要な容量を備えていることを保証しています。

サービスの種類に応じて、割り当ては固定されるか、各デプロイメントごとにオンラインの同時ユーザーの数に基づいて調整されます。すべての割り当ては、EOS エコシステム内のすべての製品に等しく適用されます。

アプリケーションがバックエンド サービスの使用量制限に達した場合、サービスの使用率が許容レベルに下がるまで、その後の新しいリソース割り当て要求は失敗します。