Player Data Storage インターフェース で、デベロッパーは Epic Online Services (EOS) を使用してユーザーとゲームに固有のデータを暗号化してクラウド サーバーに保存できます。このインターフェースでストアしたデータは、ユーザーがログインに使用する任意のデバイスから利用できます。Player Data Storage インターフェースはあらゆるファイル形式をサポートしていますが、一般的にはゲームやリプレイ データの保存に使用します。
Player Data Storage インターフェースを利用するには、Platform インターフェース 関数 EOS_Platform_GetPlayerDataStorageInterface で EOS_HPlayerDataStorage ハンドルを取得します。Player Data Storage インターフェースの関数はすべて、最初のパラメータとしてこのハンドルが必要です。リクエストの完了時にトリガーする、コールバックの EOS_HPlatform ハンドルが確実にティックするようにしてください。
このインターフェースを使用するには EOS プラットフォームの初期化が必要で、これには以下に示す追加のパラメータを使用します。
-
const char* EncryptionKey:この 64 文字の 16 進数文字列は 256 ビットのキーを構成し、EOS がこれをユーザー データの暗号化に使用します。Epic のバックエンド サーバーはこのキーを格納しません。キーを指定せずにPlayer Data Storage インターフェースからファイル管理関数を呼び出すと、失敗してEOS_PlayerDataStorage_EncryptionKeyNotSetエラー コードを返します。 -
const char* CacheDirectory:これはローカル ディレクトリへのフルパスで、インターフェースがデータ ファイルを転送する際に一時的なストレージとして使用します。これは任意の場所を指定できます。通常は、システムの一時ディレクトリやゲームのデータ ディレクトリを選択します。指定したディレクトリが存在しない場合、EOS は作成を試みます。そして、EOS はディレクトリの競合をしないようにするので、複数のユーザーや製品に対して同じディレクトリを使用できます。このディレクトリに問題がある状態でファイル管理関数を呼び出すと、失敗してEOS_CacheDirectoryMissingまたはEOS_CacheDirectoryInvalidのエラーコードを返します。使用可能なフォルダに関するプラットフォーム別の制限については「EOS プラットフォーム ドキュメント」を参照してください。
ファイルを管理する
ファイル名の形式
EOS のファイル名は以下の形式です。Directory0/Directory1/DirectoryN/Filename.Extension
「Directory」と「Extension」の部分はオプションです。「/」文字を各ディレクトリ名の後ろに追加する必要がありますが、これは最初や最後の文字を含め他の場所には使用できません。ファイル名に以下の文字を使用できます。
- すべての ASCII 英数字
!-_+.'()
ファイル名が EOS_PLAYERDATASTORAGE_FILENAME_MAX_LENGTH_BYTES (64) 文字を超えてはいけません。
ファイル名のクエリ
EOS をクエリするとクラウドにストアされたファイル (1 つまたはすべて) に関する情報を取得できます。どちらのクエリの種類も、ファイル名、データ サイズ (バイト単位、暗号化なし)、MD5 ハッシュなど、見つかったファイルに関するメタデータを返します。その後、この情報のコピーをキャッシュしてから、ファイルにアクセスや変更を行います。ファイルはバックエンドで暗号化形式で格納されているので、いくつかのメタデータは暗号化されたファイルで提供されることに留意してください (ファイルサイズとハッシュなど)。メタデータは API に渡すファイルに対応する値とぴったり一致するというわけではありません。
クエリのコールバック関数の実行中に必ず、必要な情報をキャッシュからコピーする ようにしてください。このデータのライフタイムは、コールバック関数の期間を超えて持続することが保証されていません。複数のクエリを実行する場合、クエリが成功するたびにキャッシュの内容が変更される可能性があるため、これは特に重要です。
すべてのファイルをクエリする
すべてのファイルについて情報を取得するには、以下のように初期化した EOS_PlayerDataStorage_QueryFileListOptions データ構造で EOS_PlayerDataStorage_QueryFileList を呼び出します。
| プロパティ | 値 |
|---|---|
ApiVersion | EOS_PLAYERDATASTORAGE_QUERYFILELISTOPTIONS_API_LATEST |
LocalUserId | ファイル データを要求するローカル ユーザーの EOS_ProductUserId |
完了後に EOS は EOS_PlayerDataStorage_QueryFileListCallbackInfo データ構造で (EOS_PlayerDataStorage_OnQueryFileListCompleteCallback 型の) コールバック関数を実行します。呼び出しが成功すると、このデータ構造に見つかったファイル数が保存され、ファイルに関する情報が EOS キャッシュで利用できるようになります。
1 つのファイルをクエリする
名前がわかっている 1 つのファイルに関する情報だけを取得するには、以下のように初期化した EOS_PlayerDataStorage_QueryFileOptions 構造体を渡して EOS_PlayerDataStorage_QueryFile 関数を呼び出します。
| プロパティ | 値 |
|---|---|
ApiVersion | EOS_PLAYERDATASTORAGE_QUERYFILEOPTIONS_API_LATEST |
LocalUserId | ファイル データを要求するローカル ユーザーの EOS_ProductUserId |
Filename | クエリするファイル名 |
操作の完了後に EOS は EOS_PlayerDataStorage_QueryFileCallbackInfo 構造体で (EOS_PlayerDataStorage_OnQueryFileCompleteCallback 型の) コールバックを実行します。この呼び出しが成功すると、EOS はキャッシュからファイルに関するデータを利用できます。
キャッシュしたファイル情報を確認する
1 つ以上のファイルに関する情報を EOS が取得してキャッシュすると、ファイル名で EOS_PlayerDataStorage_CopyFileMetadataByFilename を呼び出すか、キャッシュにあるファイルのゼロベースのインデックスで EOS_PlayerDataStorage_CopyFileMetadataAtIndex を呼び出すことで、特定のファイルの情報を取得できます。キャッシュにあるファイル数を取得するには EOS_PlayerDataStorage_GetFileMetadataCount を呼び出します。その後この情報のコピーが不要になったら EOS_PlayerDataStorage_FileMetadata_Release を呼び出して使用しているメモリを解放します。
1 つのファイルに関する情報を EOS にクエリすると、EOS_PlayerDataStorage_GetFileMetadataCount から複数のファイルがキャッシュに存在することが判明する場合があります。以前にクエリした結果がキャッシュに残っている場合、このような状態になる可能性があります。この場合のベスト プラクティスは、EOS_PlayerDataStorage_QueryFileCallbackInfo にある ResultCode が EOS_Success であることを確認してから、EOS_PlayerDataStorage_CopyFileMetadataByFilename を呼び出して情報にアクセスすることです。
ファイル メタデータ構造は以下になります。
| プロパティ | 値 |
|---|---|
ApiVersion | EOS_PLAYERDATASTORAGE_FILEMETADATA_API_LATEST |
FileSizeBytes | ファイルの合計サイズ (バイト) (暗号化形式の場合、期待値よりも若干大きくなります) |
MD5Hash | ファイル全体の MD5 ハッシュ (十六進の数字) (暗号化ファイルのハッシュ) |
Filename | ファイル名 |
LastModifiedTime | ファイルが最後に保存された日時。Timestamp は POSIX/Unix 形式 (エポック時間) です。 |
UnencryptedDataSizeBytes | データ (ペイロード) の合計サイズ (バイト) (暗号化されていない元のの形)。 |
ファイルにアクセスおよび変更する
EOS はクラウドにあるファイルの読み取り、書き込み、削除を非同期でサポートします。読み込みと書き込みはストリーミング操作です。EOS では、ゲームがストリームの進行状況を確認したり、ストリームを調整または中断するために使用できるハンドルを提供します。
ファイルを読み込む
名前がわかっているファイルをクラウド (またはローカル キャッシュ) から読み込むには、EOS_PlayerDataStorage_ReadFile を呼び出します。その際は以下のように初期化した EOS_PlayerDataStorage_ReadFileOptions を渡す必要があります。
| プロパティ | 値 |
|---|---|
ApiVersion | EOS_PLAYERDATASTORAGE_READFILEOPTIONS_API_LATEST |
LocalUserId | 要求したファイルを読み取るローカル ユーザーのアカウント ID |
Filename | 読み取るファイルの名前 |
ReadChunkLengthBytes | 1 回の EOS_PlayerDataStorage_OnReadFileDataCallback 呼び出しで読み取る最大データ サイズ |
ReadFileDataCallback | 取得したデータを処理して必要に応じて転送を途中停止するコールバック関数 |
FileTransferProgressCallback | 転送状況を通知するオプションのコールバック関数で、設定すると少なくとも 1 回呼び出されます |
この関数は EOS_HPlayerDataStorageFileTransferRequest ハンドルを返し、これを使用して転送状況の確認、ファイル名の取得、転送のキャンセルを行います。転送中はいつでも、EOS_PlayerDataStorageFileTransferRequest_GetFileRequestState を呼び出して現在の状態のポーリング、EOS_PlayerDataStorageFileTransferRequest_GetFilename を呼び出して転送しているファイルの名前の確認、EOS_PlayerDataStorageFileTransferRequest_CancelRequest を呼び出して (エラーを生成せずに) キャンセルができます。転送を直接ポーリングせずに EOS から更新を受け取る場合は、転送を開始するときに有効な EOS_PlayerDataStorage_OnFileTransferProgressCallback 関数を (FileTransferProgressCallback パラメータとして) 提供します。そして EOS は定期的にそれを (EOS_PlayerDataStorage_FileTransferProgressCallbackInfo パラメータで) 呼び出して、ファイルの転送状況を通知します。このやり方を選択すると、コールバック関数の呼び出しを少なくとも 1 回必ず受け取れます。コールバック関数を使用した場合もハンドルを使用できますが、両者はほぼ同様の目的を果たすので、両方が必要なユースケースはほとんどありません。
ファイルのチャンクを受け取ると、(EOS_PlayerDataStorage_OnReadFileDataCallback 型の) ReadFileDataCallback は EOS_PlayerDataStorage_ReadFileDataCallbackInfo 型のパラメータで実行します。この構造体は、ファイルから取得した実際のデータ チャンクと、最後のチャンクかどうかを示す変数を含みます。また、列挙型の戻り値 EOS_PlayerDataStorage_EReadResult も利用でき、転送の続行、エラーによる終了、エラーを報告しないキャンセルを、これで EOS に指示します。
ReadFileDataCallback はメインの SDK スレッド (SDK のティックに使用するスレッド) からティックにつき 1 回のみ呼び出されます。そのため、ReadChunkLengthBytes に正しい値を設定することが重要です。チャンク サイズに小さすぎる値を設定すると、ユーザーの読み取りパフォーマンスが低下します。4096 の乗数の使用を推奨します。通常この値はシステムのメモリ ページ サイズに対応します。ReadChunkLengthBytes に SDK ティック頻度を乗算することで、最大読み取り速度を推定することができます。例：4096 * 30 の場合、最大 120 KB/秒となります。逆に、チャンク サイズに大木すぎる値を設定すると、SDK は内部により多くのメモリをアロケートします。適切な使用量を維持するには、ニーズに最も合った値を選択してください。
ファイル転送が完了すると、EOS は EOS_PlayerDataStorage_ReadFileCallbackInfo パラメータで EOS_PlayerDataStorage_OnReadFileCompleteCallback コールバック関数を実行します。このパラメータは成功や失敗の結果を表し、さらにファイル名を含みます。
EOS にはファイルをローカルにキャッシュして、将来の読み取り操作を高速化する機能があります。これらのファイルは EOS プラットフォームの初期化中に指定したキーで暗号化します。一方、ReadFileDataCallback 機能に送信するデータ チャンクは暗号化しません。
次のタイムライン図は、読み取り操作の想定される動作を示しています。
ファイルを書き込む
名前がわかっているファイルに書き込むには EOS_PlayerDataStorage_WriteFile を呼び出します。その際は以下のように初期化した EOS_PlayerDataStorage_WriteFileOptions を渡す必要があります。
| プロパティ | 値 |
|---|---|
ApiVersion | EOS_PLAYERDATASTORAGE_WRITEFILEOPTIONS_API_LATEST |
LocalUserId | ファイルをクラウドに書き込むローカル ユーザーのアカウント ID |
Filename | 書き込むファイルの名前 |
ChunkLengthBytes | ティックごとにファイルに書き込む最大データ量 |
WriteFileDataCallback | EOS にデータ チャンクを提供するコールバック関数 |
FileTransferProgressCallback | 転送状況を通知するオプションのコールバック関数 (EOS_PlayerDataStorage_OnFileTransferProgressCallback 型)。つまり、設定すると少なくとも 1 回呼び出されます。 |
この関数は EOS_HPlayerDataStorageFileTransferRequest ハンドルを返し、これを使用して転送状況の確認、ファイル名の取得、転送のキャンセルを行います。転送中はいつでも、EOS_PlayerDataStorageFileTransferRequest_GetFileRequestState を呼び出して現在の状態のポーリング、EOS_PlayerDataStorageFileTransferRequest_GetFilename を呼び出して転送しているファイルの名前の確認、EOS_PlayerDataStorageFileTransferRequest_CancelRequest を呼び出して (エラーを生成せずに) キャンセルができます。転送を直接ポーリングせずに EOS から更新を受け取る場合は、転送を開始するときに有効な EOS_PlayerDataStorage_OnFileTransferProgressCallback 関数を (FileTransferProgressCallback パラメータとして) 提供します。そして EOS は定期的にそれを (EOS_PlayerDataStorage_FileTransferProgressCallbackInfo パラメータで) 呼び出して、ファイルの転送状況を通知します。このやり方を選択すると、コールバック関数の呼び出しを少なくとも 1 回必ず受け取れます。コールバック関数を使用した場合もハンドルを使用できますが、両者はほぼ同様の目的を果たすので、両方が必要なユースケースはほとんどありません。
EOS が次のファイル チャンクをクラウドに送信する場合、WriteFileDataCallback (EOS_PlayerDataStorage_OnWriteFileDataCallback 型) は、EOS_PlayerDataStorage_WriteFileDataCallbackInfo 型のパラメータ、送信データ バッファへの void ポインタ、データ サイズを示す uint32_t ポインタを使用して実行します 。EOS_PlayerDataStorage_WriteFileDataCallbackInfo は、バッファに入る最大バイト数を示す DataBufferLengthBytes と呼ばれる変数を含みます。このコールバック関数は列挙型の戻り値 EOS_PlayerDataStorage_EWriteResult を持ち、転送の続行、正常な完了による終了、エラーによる終了、エラーを報告しないキャンセルを、EOS に指示するために使用します。
WriteFileDataCallback はメインの SDK スレッド (SDK のティックに使用するスレッド) からティックにつき 1 回のみ呼び出されます。そのため、ChunkLengthBytes に正しい値を設定することが重要です。チャンク サイズに小さすぎる値を設定すると、ユーザーの書き込みパフォーマンスが低下します。4096 の乗数の使用を推奨します。通常この値はシステムのメモリ ページ サイズに対応します。ChunkLengthBytes に SDK ティック頻度を乗算することで、最大書き込み速度を推定することができます。例：4096 * 30 の場合、最大 120 KB/秒となります。逆に、チャンク サイズに大木すぎる値を設定すると、SDK は内部により多くのメモリをアロケートします。適切な使用量を維持するには、ニーズに最も合った値を選択してください。
ファイル転送が完了すると、EOS は EOS_PlayerDataStorage_WriteFileCallbackInfo パラメータで EOS_PlayerDataStorage_OnWriteFileCompleteCallback コールバック関数を実行します。このパラメータは成功や失敗の結果を表し、さらにファイル名を含みます。データ消失を回避するために、ユーザーがゲームを終了したりコンソールをシャットダウンする前に、必ずこのコールバックを実行するようにします。
ファイルのコピー
ファイルのデータ コンテンツを手動ですべて読み書きせずに、必要に応じてファイルのコピーを作成できます。以下の値を含む EOS_PlayerDataStorage_DuplicateFileOptions で EOS_PlayerDataStorage_DuplicateFile を呼び出します。
| プロパティ | 値 |
|---|---|
ApiVersion | EOS_PLAYERDATASTORAGE_DUPLICATEFILEOPTIONS_API_LATEST |
LocalUserId | 操作を許可するローカル ユーザーのアカウント ID で、必ず元のファイルの所有者を指定します |
SourceFilename | コピーする既存のファイルの名前 |
DestinationFilename | 複製したファイルにつける名前 |
完了後に EOS が EOS_PlayerDataStorage_DuplicateFileCallbackInfo パラメータで EOS_PlayerDataStorage_OnDuplicateFileCompleteCallback 関数を実行します。次の状況でファイルの複製は失敗します。
- 元のファイルが存在しない。
- ユーザーが元ファイルの所有者でない。
- ユーザーのストレージに空きがない。
DestinationFilename で既存のファイルを指定した場合、そのファイルを複製で置き換えます。
ファイルを削除する
ファイルを削除するには、以下のように初期化した EOS_PlayerDataStorage_DeleteFileOptions で EOS_PlayerDataStorage_DeleteFileOptions を呼び出します。
| プロパティ | 値 |
|---|---|
ApiVersion | EOS_PLAYERDATASTORAGE_DELETEFILEOPTIONS_API_LATEST |
LocalUserId | ファイルの削除を許可するローカル ユーザーのアカウント ID で、必ずファイルの所有者を指定します |
Filename | 削除するファイルの名前 |
完了後に EOS がコールバック (EOS_PlayerDataStorage_OnDeleteFileCompleteCallback 型) を実行し、EOS_PlayerDataStorage_DeleteFileCallbackInfo 型のパラメータを渡します。ユーザーがファイルの所有者でない場合、ファイルの削除操作が失敗する可能性があります。
データのキャッシュと暗号化を行う
Player Data Storage インターフェースは、ファイル データとメタデータをクライアント システムの CacheDirectory フォルダにキャッシュします。EOS は読み取りと書き込みの操作で、クラウドからストリーミングする代わりに可能な限りこのデータを使用します。また、MD5 チェックサム テストを行って、データの破損を防ぐとともに、ローカルにキャッシュしたファイルがクラウド上のバージョンと一致することを確認します。この一連の読み取りと書き込みの操作は 1 回のコールバック サイクルで完了します。読み取りや書き込みの操作が成功するたびにキャッシュを更新し、削除操作ではキャッシュ ファイルをクリアして対応するメタデータも削除します。EOS はシャットダウンでキャッシュをクリアせず、次回のセッションでキャッシュ ファイルを再利用します。
プレイヤー データ ストレージ ファイルは常に暗号化した状態で保存され、EOS プラットフォームの初期化で指定したキーを使用します。暗号化キー自体はクラウドに保存されないため、キーを使用してデータにアクセスすることはできません。
ファイル復号化ツール
ファイル復号化ツール(File Decryption Tool) を使うと、新規ファイルを作成したり、Title Storage または Player Data Storage にロードされたファイルを簡単かつ便利に復号化することができます。
使用上の制限事項
Player Data Storage インターフェース で、デベロッパーは EOS を使用してユーザーとゲームに固有のデータを暗号化してクラウド サーバーに保存できます。このインターフェースでストアしたデータは、ユーザーがログインに使用する任意のデバイスから利用できます。Player Data Storage インターフェースはあらゆるファイル形式をサポートしていますが、一般的にはゲームやリプレイ データの保存に使用します。
サービスはストレージ量と使用レートの両方を制限します。スロットリングは使用レートの制限を強制し、サービスはファイルを削除してストレージ容量の制限を強制します。たとえば、1 ファイルの最大サイズを超えるファイルをアップロードすると、サービスは自動的にそのファイルを削除します。スロットリング、使用クォータ、ベストプラクティスの一般情報については、「」を参照してください。
| 使用タイプ | 制限事項 |
|---|---|
| 読み取りまたは書き込み | 1000 リクエスト / 分 |
| 1 ファイルの最大サイズ (下記注意を参照) | 200 MB |
| 自動削除ファイルサイズ | 400 MB |
| 1 フォルダの最大サイズ | 400 MB |
| 1 ファイルの最大ユーザー数 | 1000 |
もしユーザーがいずれかのストレージ容量の制限を超えるファイルをアップロードしようとすると、EOS_PlayerDataStorage_WriteFile コールは失敗し、EOS_Result_PlayerDataStorageFileSizeTooLarge を返します。ユーザーのストレージが一杯になると、EOS_PlayerDataStorage_WriteFile の追加呼び出しに失敗し、EOS_Result_PlayerDataStorageUserThrottled を返します。ユーザーのストレージは、ストレージ使用量を制限値以下にするために十分な数のファイルが削除されるまで、スロットル状態になります。自動削除されるファイルサイズを超えるファイルは、アップロード後に削除されます。
PlayerDataStorage と EGS Cloud Saves
Epic では以下の 2 つのクラウド保存サービスを提供します。Launcher Cloud Saves と EOS Player Data Storage です。Launcher Cloud Saves が最も広く使用されており、Epic Games Store のゲーム コンフィギュレーションの一部として設定することができます。しかしながら、2 つのサービスは異なる点があり、どちらを使用するのか影響を与えます。
- Launcher Cloud Saves は Epic Games Launcher 内でゲームと結びつきます。従って、プレイヤーが Launcher 外でゲームを起動する場合、ゲームは保存データのローカル版にのみアクセスすることになります。
- Launcher Cloud Saves は、一度設定した後は Epic 側で完全に処理されます。
- EOS Player Data Storage ではプレイヤーがオンライン上にいることが求められ、EOS API を使ってゲーム側で完全に動作します。これにより、データをプラットフォーム間で共有することができるようになる点が Launcher Cloud Saves と異なります。