単一の SDK で、デベロッパーとプレイヤーの両方にとってユーザー フレンドリーなエコシステムをビルドしやすくなります。どのような形でゲームをビルド・公開する場合でも、クリエイターとデベロッパーの両方にメリットがあります。 これを利用することで、さまざまなプラットフォームを使用する友人とプレイする場合でも同じ品質のエクスペリエンスを実現できます。Epic の使命は、SDK を可能な限り移植しやすいように設計して、あらゆるエンジンやストアで動作したり、 どんな主要なプラットフォームでも統合できるものを作ったりすることです。
SDK の基礎
EOS SDK には、C と C# ラッパーの 2 つの種類があります。
C を重点的に使用することで、コンパイラの選択、実装、呼び出し規約、データサイズ、またはアライメントに関係なく、統合機能を確保する安定したアプリケーション バイナリ インターフェース (ABI) を提供することが可能です。
これにより、SDK の独立したコードパッチを適用して開発の中断を少なくして、修正や更新を配布した後にアプリケーションを再コンパイルすることなく、SDK の寿命を維持できます。さらにこの場合、パブリック API のより慎重な公開が可能になります。
ゲーム クライアントを実行するプラットフォームに応じて、SDK のさまざまなタイプをダウンロードして使用することができます。
- Windows、macOS, Linux - C の EOS SDK と C# の EOS SDK。
- モバイル - iOS 用 EOS SDK、Android 用 EOS SDK。
- コンソール - C と C# ゲーム コンソール用 EOS SDK ダウンロード。
コンソール用 SDK ダウンロードは、プラットフォーム ホルダーと Epic Games に承認されているデベロッパーのみ利用可能です。 プラットフォーム ホルダーは以下になります。Microsoft (Xbox One, Xbox Series X), Sony (PlayStation 4, PlayStation 5), Nintendo (Switch).
コンソール用 SDK ダウンロードおよび関連ドキュメントの利用方法は以下のとおりです。- プラットフォーム ホルダーからコンソール デベロッパー アクセスを新生するためのガイダンスは「Developer Portal (dev.epicgames.com/dev-portal)」を参照してください。
- プラットフォーム ホルダーからの承認が取得できたら、eoshelp.epicgames.com の中の Console Developer Request for Epic Online Services フォームを使用して Epic Games に申請することができます。
リリース バージョン管理
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_EResult は EOS_EResult::EOS_Success として表示されます。
C# の場合、Result 型を使用して一般的なエラー値とインターフェース固有のエラーを含めることで、エラーコードがわずかに変化します。C SDK の例と比較すると、Success 値を持つ列挙型 Result は Result.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 インターフェース に固有の、ローカル認証セッションが期限切れになったか、無効になったため、ユーザーは再度ログインする必要があります。 |
エラー コードの詳細は、「SDK エラー コード」ページを参照してください。
文字列
入力および出力の両方の文字列は、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 エコシステム内のすべての製品に等しく適用されます。
アプリケーションがバックエンド サービスの使用量制限に達した場合、サービスの使用率が許容レベルに下がるまで、その後の新しいリソース割り当て要求は失敗します。
EOS SDK API リファレンス
「EOS API リファレンス」を参照してください。
注記: ** Epic Online Services (EOS) SDK を使用するには、ローカル ネットワーク、ルーター、ファイアウォールが指定されたホスト アドレスにアクセス可能でなければなりません。ホスト アドレスの一覧は、ドキュメント「ファイアウォール考慮事項」を参照してください。