DataStorage
The ZEPETO World Data Storage component is the ability to store data by client (player connected to the server).
It is commonly used to store data such as inventory items, skill points, and levels.
Data is stored on a ZEPETO account basis and must be added to the server logic (World.multiplay package → index.ts).
User data stored through DataStorage can be viewed and changed through World Data Management.
Please refer to the following guide. [World Data Management]
Defining Function
declare module 'ZEPETO.Multiplay.DataStorage' {
interface DataStorage {
set<T>(key: string, value: T): Promise<boolean>;
mset<T>(keyValueSet: { key: string; value: T; }[]): Promise<boolean>;
get<T>(key: string): Promise<T>;
mget<T>(keys: string[]): Promise<{ [key: string]: T }>;
remove(key: string): Promise<boolean>;
}
function loadDataStorage(userId: string): Promise<DataStorage>;
}
To use the ZEPETO.Multiplay.DataStorage module, you must complete the import statement as follows:
import { DataStorage } from 'ZEPETO.Multiplay.DataStorage';
DataStorage.set(key, value)
A set function is a function that stores data.
It is stored with key and value as parameters, and the key value can be freely defined and used.
Caution
- On the local server in the Unity Editor environment, data is not preserved when the server is shut down and run again.
- After World deployment, data is stored in ZEPETO DB and maintained.
- If the rules below are not satisfied, data will not be saved normally.
- If there is no value
- When entering a value that cannot be stored in Value
- Data Storage Constraints
- key maximum size: 50 char
- Maximum number of keys: 1000
- Data maximum size: 500k char
- Data Storage API Call Restrictions
- Get (per minute): 60 + users currently connected * 10
- Set (per minute): 60 + currently connected users * 10
await playerStorage.set("level", 1);
DataStorage.get(key)
The get function is a function that looks up data.
Enter key as a parameter to query the value. Returns null if a key that does not exist is queried.
let playerLevel = await playerStorage.get("level") as number;
▼ Example code using Save & Load to record user levels
import { DataStorage } from 'ZEPETO.Multiplay.DataStorage';
async onJoin(client: SandboxPlayer) {
// Load current player's data storage
const playerStorage: DataStorage = client.loadDataStorage();
let playerLevel = await playerStorage.get("level") as number;
if (playerLevel == null) {
playerLevel = 1;
}
await playerStorage.set("level", playerLevel);
}
DataStorage Multi-Get/Multi-Set
You can import or store multiple values at a time.
Caution
- Features available in ZEPETO World Package 1.12.2 and later.
DataStorage.mget(keys)
The mget function allows Data Storage to fetch multiple values at a time.
Caution
- In mget(keys), keys must be an array.
- Entering an empty value results in an error.
- Be sure to add an exception handling code for whether the key value is valid by referring to the example code.
DataStorage.mset({key, value})
The mset function allows DataStorage to store multiple values at a time.
Enter and save a keyValueSet array in the format {key,value} as a parameter.
Caution
- If you specify a generic type, only the same type of data can be stored.
- If you do not specify it as generic, you can store each other's type of data.
- If you enter an empty array value, false is returned.
▼ DataStorage Multi-Get/Multi-Set Use Example Code
- Please use the error handling syntax.
this.onMessage<SaveValue>('save', async (client: SandboxPlayer, message: SaveValue) => {
const storage = client.loadDataStorage();
try {
// mset (multi key-value) store
const success = await storage.mset<number>([
{
key: 'key1',
value: 1
},
{
key: 'key2',
value: 2
}
]);
// If successful
if (success) {
// Get the values of key1 and key2 at once
const keys = ['key1', 'key2'];
const keyValeus = await storage.mget(keys);
keys.forEach(key => {
const value = keyValeus[key];
if (key === 'key1' && value !== null && value !== undefined) {
console.log(value);
} else if (key === 'key2' && value !== null && value !== undefined) {
console.log(value);
}
});
}
} catch(error) {
let systemError = (error as SystemError);
if (systemError.code === DataStorageError.Unknown || systemError.code === DataStorageError.NetworkError) {
// System error or network error
console.log(systemError.message);
} else if (systemError.code === DataStorageError.KeyConstraintViolated) {
// Key constraint violated
console.log(systemError.message);
} else if (systemError.code === DataStorageError.ValueConstraintViolated) {
// Value constraint violated
console.log(systemError.message);
}
}
});
Manage DataStorage based on UserId
Read/Write/Delete Data Storage based on UserId.
Caution
- Features available in ZEPETO World Package 1.9.0 and later.
- Please fill out the server code index.ts Sandbox.
Previously, only the accessor's own Data Storage was accessible, and there was no way to get information such as other people's scores or abilities.
First, to get user information, we define Schema Types and Room State as follows:

▼ Example code for using UserId-based DataStorage
import { Sandbox, SandboxOptions, SandboxPlayer } from 'ZEPETO.Multiplay';
import { DataStorage, loadDataStorage } from 'ZEPETO.Multiplay.DataStorage';
import { UserInfo } from 'ZEPETO.Multiplay.Schema';
interface TargetData {
lastJoinRoom: string;
lastJoinTime: string;
}
export default class extends Sandbox {
onCreate(options: SandboxOptions) {
this.onMessage("TargetData", (client: SandboxPlayer, targetData: TargetData) => {
this.saveTargetData(client, targetData);
});
this.onMessage("GetTargetData", (client: SandboxPlayer, userId: string) => {
this.loadTargetData(client, userId);
});
}
onJoin(client: SandboxPlayer) {
const user = new UserInfo();
user.sessionId = client.sessionId;
user.userId = client.userId;
this.state.UserInfos.set(client.userId, user);
}
onLeave(client: SandboxPlayer, consented?: boolean) {
this.state.UserInfos.delete(client.userId);
}
async saveTargetData(client: SandboxPlayer, targetData: TargetData) {
console.log(`save target data (${client.userId})\n ${JSON.stringify(targetData)}`);
const playerStorage: DataStorage = client.loadDataStorage();
const result = await playerStorage.set("targetData", targetData);
client.send("Log", `Save Result : ${result}`);
}
async loadTargetData(client: SandboxPlayer, userId: string) {
console.log(`load target data (${userId})`);
const userStorage: DataStorage = await loadDataStorage(userId);
const targetData = await userStorage.get<TargetData>("targetData");
console.log(JSON.stringify(targetData));
if (targetData) {
client.send("TargetData", targetData);
} else {
const empty: TargetData = {
lastJoinRoom: "",
lastJoinTime: "",
}
client.send("TargetData", empty);
}
}
}
In the example above, the key points are as follows:
this.state.UserInfos.set(client.userId, user); | Stores data in DataStorage for a specific userID. |
const userStorage: DataStorage = await loadDataStorage(userId); const targetData = await userStorage.get("targetData"); | Reads data from a specific user in asynchronous form. It then imports data for a specific key value. |
this.state.UserInfos.delete(client.userId); | Deletes data to DataStorage for a specific userID. |
Caution
- If you use UserInfos.delete(), the target UserID's data will be deleted and it cannot be recovered, so please use it carefully.
- The World developer is responsible for deleting data using the UserInfos.delete() script.
PlayerPrefs - Saving data to the device
ClientStorage
Provides the ability to save players to the device they are connecting to.
It can be called from the client ZEPETO Script, and data will not be preserved if you delete the app or change the device.
It supports use in the same way as PlayerPrefs in Unity, and the storage capacity is limited to 10KB.
▼ Example code for checking the number of plays using the Save & Load function
import { ZepetoScriptBehaviour } from 'ZEPETO.Script';
import { PlayerPrefs } from 'UnityEngine';
export default class ClientSaveLoad extends ZepetoScriptBehaviour {
playCntKey: string = 'PlayCnt';
Start() {
if (PlayerPrefs.HasKey(this.playCntKey)) {
PlayerPrefs.SetInt(this.playCntKey, PlayerPrefs.GetInt(this.playCntKey) + 1);
console.log(`PlayCnt : ${ PlayerPrefs.GetInt(this.playCntKey) }`);
} else {
PlayerPrefs.SetInt(this.playCntKey, 1);
console.log('PlayCnt : 1');
}
}
}
View Unity PlayerPrefs information