Skip to main content

Persistence

note

Persistence is currently available as a closed beta. Only invited members of the community can access it at the moment.

What is Persistence?​

Worlds can use persistence to store high scores, inventories, the player's last position, currency, unlocks, preferences, and much more. When a player leaves a world and returns later, Udon can access their saved data.

This data is stored on VRChat's servers and is accessible on all platforms and in all instances of the same world. It is connected to the user's account, so if a player visits a world on a completely different device, Udon will still have access to that world's data.

One of the primary ways to use persistence is with Player Data. Player Data is a key-value storage system associated with each player. Any script can access the data, and it's capable of storing all integer types, floats, doubles, vectors, colors, strings, and byte arrays.

Persistence also includes Player Objects. Any game object with this component is automatically instantiated for each player. Udon scripts can be attached to player objects, and if a VRCEnablePersistence component is added to them then all synced data on those objects will persist. Player objects also have many uses outside of persistence, serving a similar use-case as per-player object pools. They can be used for anything that should be tied to each player in the instance, such as health bars, colliders for combat systems, and robust networked systems without ownership transfers.

Persistent User Data​

There are two types of User Data that Udon can save and load from VRChat's servers:

  • Player Data is a key-value database that allows Udon scripts to save and load User Data.
  • Player Object are GameObjects that automatically instantiate themselves for each player. All their synced Udon variables persist.

Installation​

note

Persistence will eventually become available in the public VRChat SDK, making the following section unnecessary.

SDK: -persistence.cb.x

Build: VRChat [p-test] (Not currently live compatible)

Bugs and feature requests: in the #persistence-feedback text channel of the VRChat General Testing Discord.

Reset User Data in all worlds​

Players can reset their own User Data for all worlds they visited by going to the VRChat website:

  1. Open the settings page on VRChat.com..
  2. Scroll down to the Persistent Data section.
  3. Click Reset All Player Progress.
  4. After reading the warning, click Yes to confirm.

Reset User Data in a specific world​

Players can reset their own User Data for specific worlds by going to the VRChat website:

  1. Open a specific world's page on VRChat.com.
  2. Scroll down to the Player Progress section (This section will not exist if you do not have User Data for that world)
  3. Click Reset Player Progress.
  4. After reading the warning, click Yes to confirm.

Data storage in different environments​

  • Client: Persistent data is stored in the VRChat servers connected to your account. You can visit on any device using the same account and the data will be shared. If you have multiple clients running on the same account in the same world at the exact same time, they may conflict and overwrite each other.
  • Local Test: Persistent data is stored within each client separately. Each local test client will act as if it is the first time in the world. Data will persist locally until the local test client is closed such as rejoining the test instance or reloading a new version of the world without closing the client.
  • ClientSim: Persistent data is stored in JSON files within your project. See ClientSim Persistence documentation for more details.

Limitations​

  • Each world may store 100 KB of Player Data and 100 KB of Player Object data per player on VRChat's servers.
    • VRChat stores User Data in a compressed format. If your world's data is easy to compress, you may be able to store more than 300 KB (compressed into 100 KB by VRChat).
    • You cannot save data that would cause you to exceed this limit. Instead, VRChat logs an error and your data won't be saved. Reduce the size of your data to avoid this.
  • The local player's User Data must be saved before they leave the world. Persistent data cannot be saved in the local player's OnPlayerLeft event.
  • Persistent data cannot be shared between different worlds.
  • Persistence does not have a feature for "save slots" built-in. However, world creators can use Udon to build a save slot system inside their worlds.

Making Persistent Prefabs​

When building prefabs that have persistent behavior, it's important to consider how they will interact with other prefabs in creators' projects.

First, consider using Player Objects rather than PlayerData, which are a better fit for most prefabs. Player Objects are nicely contained within a Prefab's hierarchy and are a better fit for persist large amounts of data and/or data that changes frequently. Remember that when you change any PlayerData for the local player, all of their PlayerData is sent, including data that hasn't changed. Every prefab in a world which uses PlayerData will add to this collection and require sending each time, which could quickly expand the networking usage in a world and could lead to bandwidth issues.

If PlayerData is still a better place for some of your prefab's data, consider adding a prefix to all the keys your prefab uses. For example, Momo's Persistent Post-Processing settings could pick the prefix "Momo-PPP-" and then use the keys:

  • Momo-PPP-BloomAmount
  • Momo-PPP-Vignette
  • Momo-PPP-Weight

This approach will greatly reduce the likelihood of the name colliding with another Prefab. The "Weight" key above, for example, could easily run into an issue if you had two different prefabs with a "Weight" parameter, but it's not very likely that another prefab will use "Momo-PPP" as their prefix.