Studio GuideWorld SDK Guide
Log In

World DataStorage

ZEPETO's DataStorage is a remote database that stores and manages user gameplay data on a per-world basis.

It is suitable for storing user gameplay data that needs to be maintained or updated across multiple play sessions, as it is stored and managed by UserID.

Manage your users' play data using the API available on the ZEPETO Multiplay server.

You can view and modify user-specific play data stored in Data Storage from the World Data Management menu in ZEPETO Studio.

📘

Please refer to the following guide. [World Data Management]


Data Storage API

📘

Please refer to the following API reference. ZEPETO.Multiplay.DataStorage API

❗️

Caution

  • Please fill out the server code index.ts Sandbox.
  • 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.
  • Data won't be saved if the rules below aren't satisfied:
    • No value is provided
    • A value that cannot be stored is entered
  • Data Storage Constraints
    • Key length limit: 50 characters
      • Only alphabets, numbers, and underscore (_) are allowed in the key
    • Maximum number of keys: 1000 per User ID
    • Maximum Value data size: 500,000 characters
      • Note that value data is serialized along with an internal identifier when stored on the actual server. Use with a safety margin.
  • Data Storage API Call Restrictions
    • Get (per minute): 200 times
    • Set (per minute): 200 times

Read / Write / Delete data for a single key

You can read, write, and delete data for a single key in the DataStorage of the local player using DataStorage.get, DataStorage.set and DataStorage.remove.

import { DataStorage } from 'ZEPETO.Multiplay.DataStorage';

export default class extends Sandbox {

    //...

    async onJoin(client: SandboxPlayer) {
        // Load local player's data storage
        const playerStorage: DataStorage = client.loadDataStorage();

        // Get the value associated with the key 'level' 
	      let playerLevel = await playerStorage.get("level") as number;
        if (playerLevel == null) {
            playerLevel += 1; 
        }

        // Store incremented value
        await playerStorage.set("level", playerLevel);

        // Remove the data
        await playerStorage.remove("level");
    }
}

Read / Write data for multiple keys

You can read, write, and delete data for multiple keys in the local player's data storage using DataStorage.mget and DataStorage.mset.

import { DataStorage } from 'ZEPETO.Multiplay.DataStorage';

export default class extends Sandbox {

    //...

    async onJoin(client: SandboxPlayer) {
        const storage = client.loadDataStorage();
        // 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];
                console.log(value);
            });
        }
    }
}

Error Handling

You can implement appropriate handling for exceptions that occur when calling the DataStorage API by referring to the error types defined in DataStorageError.

import { DataStorage } from 'ZEPETO.Multiplay.DataStorage';

export default class extends Sandbox {

    //...

    async onJoin(client: SandboxPlayer) {
        // Load local player's data storage
        const playerStorage: DataStorage = client.loadDataStorage();

        try {
            let playerLevel = await playerStorage.get("level") as number;
        } 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);
            }
        }
    }
}

Access Data Storage by User ID

It is also possible to access a specific user's Data Storage by UserID using DataStorage.loadDataStorage, instead of the local player's Data Storage.

    const userStorage: DataStorage = await loadDataStorage(userId);

👍

Tip

  • If you want to store data between different worlds, implement it using httpService