PlayerData

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

セットアップ

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

ベストプラクティス

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

ネットワーキング

PlayerData は、特定の UdonBehaviour に結びつけられているわけではないため、UdonBehaviour の synchronization 設定には依存しません。スクリプトの設定を "Manual" や "Continuous" ではなく "None" に設定しても、そのスクリプトが PlayerData にアクセスしたり変更したりすることは妨げられませんし、PlayerData 全体の動作に悪影響を与えることもありません。

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

PlayerData の bandwidth cost は、synchronization を "Manual" に設定した UdonBehaviour 1つ分と同等です。

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

ローカルプレイヤーのデータを何らか変更すると、変更されていないデータを含め、そのプレイヤーの PlayerData すべてが送信されます。少量のデータを非常に高頻度で更新する場合や、大量のデータをゆっくり更新する場合であれば、Udon's bandwidth limits に達することはまずありません。しかし、PlayerData を使用して大量のデータと高頻度なデータの両方を同期する場合、その一方を player object に移行することを検討してください。player object を使用して永続的な変数を同期することもできますが、各オブジェクトは個別に同期されます。これにより、高速なデータと大きなデータを分離でき、ワールドのネットワーク帯域幅を削減できます。

イベント

PlayerData Info

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

State 列挙型は、以下の可能な状態を示します。

ベストプラクティス

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

メソッド

ストレージ情報

Player Data Storage 情報のメソッドは、Player Object Storage 情報のメソッドと併せて VRC.SDKBase.Networking 名前空間に含まれています。

例

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

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)}";    
    }
}

最終更新: 2025年11月25日