Persisted Data

Saving game data and player progress that persists as game server start, stop or restart, and as players leave and rejoin a game is often necessary to create engaging experiences that offer a sense of progression or evolving gameplay.

HYTOPIA provides out of the box systems to persist data between game and player play sessions.

Supported Data Types

The HYTOPIA data persistence system allows you to persist any JSON compatible data using a generic key-value store service managed by the HYTOPIA systems specific to your game.

All JSON compatible data structures will work with HYTOPIA's data persistence systems.

Persisting Global Game Data

Global game data is game data that is modifiable, readable and shared between all running instances of your game when live on the HYTOPIA platform.

This type of data is great for things like global leaderboards, modifiable game configurations, retrieval and writing of unique state that may need to be accessed regardless of the game server instance, etc.

You can persist any JSON compatible data using the Persistence Manager in the HYTOPIA SDK. The persistence manager can be accessed like this:

import { PersistenceManager } from 'hytopia'

PersistenceManager.instance

All data persistence uses a key-value storage approach, we can use the Persistence Manager anywhere within our game code to retrieve or set persisted global game data.

import { PersistenceManager } from 'hytopia'

// ... previous code, etc.

// Set global persisted data
await PersistenceManager.instance.setGlobalData('my-key', { test: 1 });

// Get global persisted data
await PersistenceManager.instance.getGlobalData('my-key');

// ... other code, etc.

Persisted Player Data

Player data persistence is built on top of generic game data persistence with key/value storage of data automatically handled for you based on player id's for convenience. Learn more about Persisted Player Data

Local Testings vs. Production

Data persistence works within a testing context for local development and persists between server restarts. There are however a few caveats that you should be aware of:

• In a local environment, all persisted data is written to an automatically created dev/ directory within your project, with filenames being equivalent to the key used for storing the data.

• In a local environment, player's are assigned a player id sequentially as they join starting with 1 from the time a server starts or restarts. If you are testing persistence, the order in which a player joins matters. Typically persists is best tested using a single browser tab so that on server starts and restarts, your player is always assigned id 1 for consistent testing.

• If you use NODE_ENV=production while running your game server for things such as Multiplayer Testing, the persistence system will switch to trying to utilize HYTOPIA's services and will log a non-fatal error to your console if the following environment variables are not set: HYTOPIA_API_KEY , HYTOPIA_GAME_ID , HYTOPIA_LOBBY_ID - You will soon be able to get your game's values for these variables through the HYTOPIA creator portal, which will launch in April '25.

• When your deploy your game to HYTOPIA for release, HYTOPIA will automatically populate all correct environment variables and switch the persistence system to use HYTOPIA's persistence services.

Shallow Merging

Any time you modify existing global or player persisted data, if the root type of that JSON compatible data is an object, shallow merging will be performed.

For example, if your existing global data for your key my-config is as follows:

{
  "a": 1,
  "c": 3,
  "z": { "test": 1 }
}

And now let's say we update our my-config persisted data with:

{
  "b": 2,
  "z": { "different": true }
}

With shallow merging, the new value of my-config would be:

{
  "a": 1,
  "b": 2,
  "c": 3,
  "z": { "different": true }
}

Persistence Manager

Data persistence is built on top of HYTOPIA's persistence layer which is accessed primarily through the PersistenceManager and convenience methods on Player instances. You can learn more about both below.

• PersistenceManager API Reference
• Player API Reference