PlayerData

PlayerDataは、プレイヤーに関する永続データ（ゲームのスコアやワールド内での好みなど）を保存するためのキー・バリュー型データベースです。

セットアップ

UdonBehaviourでPlayerDataを使用するには、以下に説明する各種PlayerData関数を使用するだけです。どのUdonBehaviourからでも、ほぼいつでもどこからでもこれらの関数にアクセスできます。

ベストプラクティス

• OnPlayerDataUpdated を使用する際は、そのスクリプトの処理をローカルプレイヤーの変更のみに限定できるか、あるいはすべてのリモートプレイヤーに対してもトリガーする必要があるかを検討してください。
  • 例：ビデオプレイヤーの音量といったユーザー設定はローカルプレイヤーの更新のみで済みますが、インスタンス全体の「撫でた犬の合計数」を集計する協力型ゲームの場合は、誰かプレイヤーのスコアが増加するたびに反応して、グローバルスコアを増やす必要があります。
• PlayerDataを使用する前に、OnPlayerRestoredイベントを待機してください。OnPlayerRestoredは、プレイヤーの保存データが読み込まれ、Udonで安全にアクセスできる状態であることを示します。このイベントは、保存データがない場合でも実行されます。
• すべてのPlayer Keyを反復処理すると、数が多い場合に低速になる可能性があります。一般的なガイドラインとして、確認したいキーが少数である場合、あるいは10個を超えるキーを確認する必要がある場合などに適している、TryGetメソッドを使用して特定のキーの値を直接チェックしてください。

ネットワーキング

PlayerDataは、特定のUdonBehaviourに紐付いているわけではないため、UdonBehaviourの同期設定には依存しません。スクリプトの設定を「Manual」や「Continuous」ではなく「None」にしたとしても、そのスクリプトがPlayerDataにアクセスして変更を加えることができなくなることはなく、PlayerData全体の動作に悪影響を与えることもありません。

UdonBehaviourがPlayerDataの値を設定すると、PlayerDataはその値を自動的に同期します。内部的には、PlayerDataは RequestSerialization イベントを使用した手動同期と似た方法で値を送信します。つまり、UdonBehaviourは複数のPlayerDataキーを同時に設定し、それらをまとめて送信できるということです。UdonBehaviour側で各キーを個別に送信する必要はありません。同様に、UdonBehaviourがあるキーをある値に設定した後ですぐに別の値へ変更した場合、リモートユーザーはその中間値を受け取りません。データが変更される間隔が短すぎる場合、リモートユーザーは最終的な状態のみを受け取ります。

PlayerDataの 帯域幅コスト は、同期 を「Manual」に設定した1つのUdonBehaviourと同程度です。

ワールド内のすべてのUdonBehaviourは、そのワールドのPlayerDataへのアクセスを共有します。PlayerDataのキーを設定すると、ワールド内のどのUdonBehaviourからでもアクセス可能になります。PlayerDataはUdonBehaviourごとに「分離」されることはありません。

ローカルプレイヤーのデータを一つでも変更すると、変更されていないデータを含め、そのプレイヤーのPlayerDataすべてが送信されます。頻繁に更新される少量のデータや、ゆっくりと更新される大量のデータであれば、Udonの帯域幅制限に達する可能性は低いでしょう。しかし、PlayerDataを使用して大量かつ高頻度なデータを同期している場合は、そのどちらかをプレイヤーオブジェクトへ移行することを検討してください。プレイヤーオブジェクトを使用すると永続的な変数を同期できますが、各オブジェクトは個別に同期されます。これにより、高速なデータと大容量のデータを分離できるため、ワールドのネットワーク帯域幅を削減できます。

イベント

PlayerData情報

OnPlayerDataUpdatedイベントは、PlayerData.Info配列を提供します。この配列には、そのプレイヤーに関連付けられた現在のすべてのPlayerDataキーが含まれています。各要素には以下の情報が含まれます。

State列挙型は、以下の状態を表します。

ベストプラクティス

• OnPlayerDataUpdated を使用する際は、そのスクリプトの処理をローカルプレイヤーの変更のみに限定できるか、あるいはすべてのリモートプレイヤーに対してもトリガーする必要があるかを検討してください。
  • 例として、ビデオプレイヤーの音量設定はローカルプレイヤーに対してのみ更新すれば十分ですが、インスタンス内で「なでた犬の総数」を集計する協力型ゲームの場合は、任意のプレイヤーのスコア増加に反応してグローバルスコアを増やす必要があります。
• OnPlayerDataRestored イベントが発生するまで、PlayerDataの使用は待機してください。OnPlayerDataRestored は、プレイヤーの保存データがロード済みであり、Udonから安全にアクセスできる状態であることを示します。
• プレイヤーのキーをすべて反復処理すると、数が多い場合に低速になる可能性があります。一般的なガイドラインとして、確認したいキーが少数である場合、あるいは10個を超えるキーを確認する必要がある場合などに適している TryGet メソッドを使用して、特定のキーの値を直接確認してください。

メソッド

ストレージ情報

Player Data Storage（プレイヤーデータストレージ）に関するメソッドは、Player Object Storageに関するメソッドと同様に、VRC.SDKBase.Networking 名前空間に含まれています。

ストレージ情報は時間の経過とともに古くなる可能性があるため、更新が必要な場合があることに注意してください。RequestStorageUsageUpdate を頻繁に呼び出すことは避けてください。

クエリ

これらのメソッドは、キーに関連付けられた値についての詳細情報を取得するために使用します。キーに対して何らかの操作を行う前に、そのキーに何が存在するかを確認するのに役立ちます。

ミューテーター

これらのメソッドは、ローカルプレイヤーの PlayerData を保存するために使用します。リモートプレイヤーのデータを設定することはできません。

値は以前と異なる型であっても上書き可能です。一度書き込まれたキーは削除できません。

アクセサ

これらのメソッドを使用して、インスタンス内の任意のプレイヤーのPlayerDataを取得します。

キーが存在しない場合、その型のデフォルト値が返されます。例えば、PlayerData.GetInt() を呼び出した場合、0 が返されます。

例えば、string が含まれているキーに対して GetInt を使用した場合など、誤ったアクセサー型を使用した際もデフォルト値が返されます。

デフォルト値が望ましくない場合は、TryGet またはクエリを使用して、デフォルト値と欠落しているキーを区別してください。

例

永続的なジャンプカウンター

using TMPro;
using UdonSharp;
using VRC.SDK3.Persistence;
using VRC.SDKBase;
using VRC.Udon.Common;

public class JumpCounter : UdonSharpBehaviour
{
    public TextMeshProUGUI jumpText;
    private const string JumpsKey = "jumps";
    public override void InputJump(bool value, UdonInputEventArgs args)
    {
        if (value)
        {
            AddJump();
        }
    }

    public override void OnPlayerDataUpdated(VRCPlayerApi player, PlayerData.Info[] infos)
    {
        if (player.isLocal)
        {
            UpdateTextComponent();
        }
    }

    private void AddJump()
    {
        var currentJumps = PlayerData.GetInt(Networking.LocalPlayer, JumpsKey);
        PlayerData.SetInt(JumpsKey, currentJumps + 1);
    }
    
    private void UpdateTextComponent()  
    {  
        jumpText.text = $"Jumps: {PlayerData.GetInt(Networking.LocalPlayer, JumpsKey)}";    
    }
}