Steamworks ドキュメンテーション
Steamクラウド
概略
Steamクラウドは、ゲームからファイルをSteamのサーバーに自動で保存し、プレイヤーはSteamにログインすればどのコンピューターからでもセーブゲームにアクセスできます。
統合のレベル
ファイルパス構成はSteamworksウェブサイト上にある必要があります。 アップロード、ダウンロード、列挙、削除には、ゲームコード内でSteamworksへのAPI呼び出しが適宜必要です。

Steamクラウドの概要

Steamクラウドは、ゲームに簡単で透過性のあるリモートファイルストレージシステムを提供します。 自動クラウド設定で指定されたファイルや、クラウドAPIを使用してディスクに書き込まれた (作成/変更/削除された) ファイルは、ゲーム終了後に自動的にSteamサーバーに複製されます。

ユーザーが違うコンピュータからゲームにアクセスする場合には、ゲームの起動前に新しいコンピュータにファイルが自動的にダウンロードされます。 ゲームは、クラウドAPIを通してファイルを読み込むか、通常通りディスクから直接読み込みます。 ビデオ設定等、マシン固有の構成は避けてください。

Steamクライアントは確実に、ゲームにアクセスしたすべてのコンピュータ上でのファイルの同期が維持されるようにします。

Steamクライアントの「設定」メニューの「クラウド」タブで「Steamクラウドを有効化して、サポートするアプリ情報を同期化する」のチェックを外すことで、ユーザーはクラウドとの同期をグローバルに解除できます。

ユーザーは、各ゲームのプロパティから、ゲームごとにクラウド同期を無効にすることもできます。

Spacewar_Cloud_Properties.png

ベストプラクティスと備考


Steamは、ゲームセッションの前後にユーザーのSteamクラウドファイルと同期することを覚えておくことは重要です。 セッション中に変更されたマッチメイキングファイルは、終了後すぐにクラウドストレージにアップロードされます。 ゲームが非常に大きなファイルまたは多くの小さなファイルをSteamクラウドに書き込む場合、ユーザーのインターネット帯域幅に顕著な影響を与え、Steamのシャットダウンやゲームの再起動に遅延を発生させる可能性があります。

一般的な規則として、小さいファイルの方が適切に機能します。 ユーザーの保存状態を異なるカテゴリ(頻繁に変更される場合と頻繁に変更されない場合)に分割できる場合は、カテゴリ毎に個別のファイルを使用することが推奨されます。 こうすれば、変更のない状態は、セッションごとに再アップロードされません。

ファイルサイズの制限


Steamクラウドのファイルサイズの絶対制限は、時間の経過とともに変化する可能性があります。 現在の制限としきい値は次のとおりです:

サイズ制限
100MBISteamRemoteStorage::FileWriteまたは
ISteamRemoteStorage::FileWriteStreamWriteChunkの呼び出しの最大サイズ
256MBユーザーの場所に最適ではないストレージエンドポイントが選択され、アップロード/ダウンロードのパフォーマンスに悪影響を及ぼす可能性があります

ファイルパスの保存

保存ファイルを書き込む場所を決定するときは、パスが現在のSteamユーザーに対して一意であることを確認してください。 必要に応じて、ISteamUser::GetSteamIDを介してユーザーの一意のSteamIDを取得できます。 そこから、GetAccountID()を使って、accountIDにアクセスすることで、保存パスを作成する際の一意の変数を取得できます。

クロスプラットフォームセーブ


ゲームが複数のプラットフォームをサポートしている、または将来的にサポートする予定がある場合は、ゲームにSteamクラウドを設定する際に以下を考慮してください。

ISteamRemoteStorageインターフェイスを介して直接ファイルを読み書きする場合は、ISteamRemoteStorage::SetSyncPlatformsを介してプラットフォームの同期を制御できます。 新しいファイルは、デフォルトですべてのプラットフォームに同期します。

Steam自動クラウドを使用する場合、いくつか重要な注意点があります。 まず、新しいファイルはデフォルトで、関連付けられた自動クラウドルートパスのOS設定のみに同期します。 これは、OSごとに個別のルートを設定すると、すべてのファイルがプラットフォームごとにパーティション化され、クロスプラットフォームでの保存が機能しないことを意味します。

クロスプラットフォームでの保存を有効にするには、単一のルートパス(主にWindows用)を定義してから、他のサポートされているプラットフォーム用にルートオーバーライドを作成する必要があります。 指定のルートパスと一致し、プラットフォームルートオーバーライドも設定されているファイルは、元のルートとすべてのオーバーライドで指定された全プラットフォームに同期します。 詳細は、Steam自動クラウドのドキュメントを参照してください。

初期セットアップ

Steamクラウドの設定には、Steamworksのアプリ管理パネルから Steamクラウド設定ページを開き、ユーザー毎のバイトクォータユーザーが持てるファイル数を決定する必要があります。

この割り当てはクラウド対応の各ゲームにおいて、ユーザー毎に適用されます。 ゲームタイトルに適した値を設定することを推奨しています。

注: ページの下部の「保存」をクリックし、更新された設定を忘れずに公開してください。 公開後に、ゲームを所有するユーザーのSteamクライアント上に、クラウドアイコンが表示されるようになります。

ゲームがすでにリリース済みの場合は、クラウドサポートをデベロッパーにのみ有効化というチェックボックスにマークを入れることができます。 ここにチェックが付いている場合、このタイトルの「Developer Comp」ライセンスを所有するSteamアカウントのみにクラウドのアイコンが表示され、Steamクラウドを使用することができます。 これは、ユーザーの体験を損なうことなくSteamクラウドの統合を安全にテストする際に便利です。 リリース前のゲームの場合はゲームの所有者がいないので、その特定のApp IDに対してクラウドストレージを見られたり、アクセスされることがないため、チェックを付けても何の影響もありません。

共有クラウドApp IDフィールドに入力することで、2つのApp ID間でクラウドストレージスペースを共有することができます。 これはゲームの体験版と製品版の間でのセーブデータを共有するために最もよく使われます。 値が0の場合、この機能は無効です。

SteamクラウドAPIとSteam自動クラウド

Steamは、Steamクラウドの利用に2つの異なる方法を提供しています。2つの方法の違いについて理解し、アプリケーションにとって最適な方法を決定してください。

1つ目の方法は、SteamクラウドAPI です。
クラウドAPIでは、ゲームにSteamクラウドを直接実装するための一連の関数が用意されています。 クラウドAPIは個々のSteamユーザーファイルを互いに分離し、Steamクラウド上での高度な制御を提供します。

SteamクラウドAPIは ISteamRemoteStorage APIインターフェイスで公開されており、Steamworks APIのサンプルアプリケーション(SpaceWar)で使用例を確認できます。

2つ目の方法は Steam自動クラウドです。
Steam自動クラウドは、SteamクラウドAPIを実装しないゲーム用です。 これは、迅速かつ簡単な方法でクラウドを提供しますが、SteamクラウドAPIの柔軟性には劣ります。

例えば、クラウド内に保存するセーブファイル選択させる等、Steamクラウドとのより深い統合を希望する場合は、クラウドAPIを使用してください。 それ以外の場合は、Steam自動クラウドを使用できます。

Steam自動クラウド

Steam自動クラウドは、SteamクラウドAPIの代替機能で、コードを書いたり、ゲームに手を加えることなく、アプリでSteamクラウドを使用できるようにします。 必要な作業は、クラウドに保存するファイルのグループを指定するだけです。 Steamは、アプリケーションの起動時と終了時に、これらのファイルグループを自動的に同期します。 ビデオ品質など、マシン固有の構成は避けてください。
注:steam_autocloud.vdfファイルはSteamworksクラウドパスによって指定された場所にそれぞれ作成されます。 このファイルはSteamが使用し、ゲームは無視することができます。

セットアップ

初期セットアップ完了後に、Steamクラウド設定ページ内のSteam自動クラウドの設定セクションが使えるようになります。

ルートパスはSteamクラウドに保存されるファイルのグループを表します。 各ルートパスには、単一のファイル、またサブフォルダー内のすべてのファイルといった、広範囲な指定も可能です。 同期するファイルのグループごとに、新しいパスを使用してください。

ルートパスは5つの部分で構成されています:
  1. ルート

    これはセーブゲームが通常保存される、所定のパスのリストです。
    ルートサポート対象のOS所定のパス
    アプリのインストールディレクトリすべて[Steam Install]\SteamApps\common\[Game Folder]\
    SteamCloudDocumentsすべてプラットフォーム特有のパス。例えばLinuxでは ~/.SteamCloud/[username]/[Game Folder]/
    WinMyDocumentsWindows%USERPROFILE%\My Documents\
    WinAppDataLocalWindows%USERPROFILE%\AppData\Local\
    WinAppDataLocalLowWindows%USERPROFILE%\AppData\LocalLow\
    WinAppDataRoamingWindows%USERPROFILE%\AppData\Roaming\
    WinSavedGamesWindows%USERPROFILE%\Saved Games\
    MacHomemacOS~/
    MacAppSupportmacOS~/Library/Application Support/
    MacDocumentsmacOS~/Documents/
    LinuxHomeLinux~/
    LinuxXdgDataHomeLinux$XDG\_DATA\_HOME/
  2. サブディレクトリ

    ルートに対するクラウド化されたファイルへのサブディレクトリパスです。 サブディレクトリがない場合は、「.」を入力してください。

    自動クラウド特別パス値
    自動クラウドでは、サブディレクトリのパスに、一意のSteamユーザーIDを使用できます。 これにより、コンピューター上のSteamユーザー毎に、別々にファイルが保存できるようになります。 ゲーム内でISteamUser::GetSteamIDを使うと、現在のユーザーのSteamIDまたはAccountIDを保存、読み込みできるようになります。
    • {64BitSteamID}-Steamパスにユーザーの64bit Steam IDを挿入する場合は、この変数を使用。 64 bit Steam IDの例 : 76561198027391269
    • {Steam3AccountID}-SteamパスにユーザーのSteam 3アカウントIDを挿入する場合は、この変数を使用。 アカウントIDの例:67125541
    例 : SavesDir/{64BitSteamID}
  3. パターン

    一致するファイルマスクのパターン。 * をワイルドカードとして使用できます。 ディレクトリ内の全ファイルが必要な場合には * を使用してください。

    例 : *.sav
  4. OS

    ファイルの同期元・先となるオペレーティングシステムを設定します。 これは、ファイルがOS固有である場合にのみ必要です。(そうでないことが望ましいですが!)
  5. 再帰検索

    一致するファイルの検索時にサブディレクトリを含めます。 これはSteamユーザーの名前やIDではない、非確定的なの名前のサブディレクトリに有用です。 Steam IDを使用している場合には、サブディレクトリフィールド内に後述の特別パス値を使用することを強く推奨します。

ルートオーバーライド

アプリがクロスプラットフォーム対応で、OSごとに異なるディレクトリを必要とする場合は、 上記で設定した、ルートオーバーライド機能を利用して代替パスを設定できます。

上記で指定したルートパスは、別のOS上でそれに相当する別のパスにオーバーライド可能です。 ルートオーバーライドを使用する場合、ルートOSドロップダウン内で「すべてのOS」を指定してください。

ルートオーバーライドは5つの部分で構成されています。
  1. オリジナルルート

    これは上記で設定したルートの1つに相当します。
  2. OS

    オーバーライドを適用するオペレーティングシステムです。
  3. 新しいルート

    指定したOS上で、オリジナルルートがマップする新しいロケーションです。
  4. パスの追加/置き換え

    これにより、オプションとして、新しいルートとオリジナルのサブディレクトリの間に挿入されるサブディレクトリパスを追加することができます。
  5. パスの置き換え

    「パスを置き換え」を有効にすると、「パスの追加/置き換え」で指定されたパスで、オリジナルのサブディレクトリをすべて置き換えます。

例:Unityアプリケーションに自動クラウドを設定する

以下は、OS毎にApplication.persistentDataPathプロパティ値が異なる場合にUnityで自動クラウドを設定するための例です。 Windows版はUnity内でDefaultCompanyに設定された企業とAutocloudSampleと呼ばれるプロジェクトのルートパスとして設定されます。 macOS、Linux/SteamOSでは、Application.persistentDataPathからの代替パスを「パスの追加/置き換え」フィールド内に設定して「パスの置き換え」を有効にします。

これらを設定すると、プレビュー内のサンプルのように、自動クラウドファイルが3つのフォルダー間で同期されます。

Cloud_Unity_Auto-Cloud_Example.png

リリース前のテスト

リリース済みのゲームにSteam自動クラウドを追加する場合で、初期セットアップ中に開発者専用モードを有効にした場合は、機能をテストするために追加の手順を完了する必要があります。
  1. テストするアプリを所有するアカウントでSteamにログインします。
  2. ブラウザーでsteam://open/console を開いて、Steamコンソールを開きます。
  3. コンソールにtestappcloudpaths <AppId>とテストするアプリのApp IDを入力します。 例:testappcloudpaths 480
  4. コンソールにset_spew_level 4 4と入力します。
  5. Steamからアプリを起動します。
  6. コンソールでアクティビティをチェックしてください。自動クラウドパスに既存のファイルがある場合には、アップロードされることを確認してください。 ファイルが無ければ、アプリ用のいくつかのファイルが保存され、アプリを閉じると同期を開始します。
  7. 別のPCから上記ステップを繰り返して、Steam自動クラウドからファイルがダウンロードされるかを確認します。
  8. ゲームがサポートする全てのオペレーティングシステムでテストしてください。
  9. テストを終了するにはtestappcloudpaths 0set_spew_level 0 0を設定してください。 コンソールタブを取り除くには Steamクライアントを再起動してください。

テスト完了後は、忘れずに開発者専用モードを無効にして、変更を公開してください。

動的なクラウド同期


Steamクラウドは動的同期をサポートしています。クラウド内での変更は、アプリケーションのセッション中にローカルマシンにダウンロードできます。
ここでの例はSteam Deck上で一時中断されたゲームセッションです。 動的クラウド同期をサポートしているというマーク付きのアプリでは、Steamは一時中断時にファイルをSteamクラウドに同期します。 その後、ユーザーはゲームを別のデバイスで実行できるようになり、起動時にSteam Deckでのセッションからのアップデートを受け取ります。 終了時、これらの変更はSteamクラウドにアップロードされます。 最終的に、Steam Deckデバイスが起動されると、Steamはデバイスに変更を同期し、ローカルファイルが変更されたという通知をアプリケーションにポストします。 アプリケーションはこれらの変更を反復処理し、適切なアクションをとります。 例えば、ゲームは単純にディスクから進行をアップデートでき、ユーザーが他のデバイスで終了したポイントからゲームに復帰可能となります。

この機能が存在する理由および使用法についての詳細は、お知らせを参照してください。

この機能は、ファイル管理にISteamRemoteStorageAPIか、自動クラウドを使用するかに関わらず、アプリケーションをサポートします。

詳細は、ISteamRemoteStorageドキュメントの特に、 ISteamRemoteStorage::RemoteStorageLocalFileChange_tISteamRemoteStorage::GetLocalFileChangeCount、および ISteamRemoteStorage::GetLocalFileChangeを参照してください。

また、ISteamRemoteStorage::BeginFileWriteBatchISteamRemoteStorage::EndFileWriteBatchも参照してください。これらのラッパーを使用することで、ユーザーがシステムの一時中断を開始した時に、Steamクラウドに安全に同期するための役立つヒントがSteamに提供されます。

リリース前のテスト


ローカルで動的クラウド同期を有効にして、アプリのビルドをテストすることができます。すべてのユーザーに対して動的クラウド同期を有効にすると、新しいAPIメソッドやコールバックを処理しないビルドを実行する際にデータが失われる可能性があるため、この機能はすでにリリース済みのゲームに推奨されます。

PCからローカルでテストを行う方法:

  1. テストするアプリを所有するアカウントでSteamにログインします。
  2. ブラウザーでsteam://open/consoleを開いて、Steamコンソールを開きます。 (コマンドラインのsteam -consoleを使用してSteamを実行し、コンソールセクションに直接移動することもできます)。
  3. コンソールに@cloud_testdynamicsyncapp <AppId>と、テストするアプリのApp IDを入力します。 例:@cloud_testdynamicsyncapp 480
  4. Steamからアプリを起動します。
  5. ゲームを目的のポイントまで進めます。
  6. Steamコンソールで、prepare_for_suspendと入力します。 Steamは、ゲームプロセスを一時停止し、変更されたファイルをSteamクラウドにアップロードします。
  7. オプション:別のデバイスでゲームをプレイして、さらに進んだ状況を作り出してから終了し、Steamクライアントに進行状況をSteamクラウドにアップロードさせます。
  8. 元のデバイスに戻り、Steamコンソールでresume_suspended_gamesと入力します。 これにより、Steamクラウドから必要なファイルが同期され、ゲームに関連するAPI呼び出しが送信され、その後ゲームプロセスの一時停止が解除されます。

Steam Deckからローカルでテストを行う方法:

  1. Steam DeckをDevkitに接続します。
  2. CEFコンソールを使用するには、こちらを参照してください。
  3. JSコンソールで、SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp <AppId>”)と入力し、テストを有効にします。 その後、SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp 0”)と入力すると、テストを無効にできます。

デバッグ

まず、SteamworksパートナーWebサイト上で確実に変更を公開し、その後最大10分間待つか、Steamクライアントを再起動して公開された変更を受け取ってください。

Steamクラウドで問題が発生した場合は、%Steam Install%\logs\cloud_log.txt内のログファイルを確認してください。

追加情報はSteamworks APIのデバッグを参照してください。