World DataStorage

7min
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﻿
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.
TypeScript
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");
    }
}
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.
TypeScript
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);
            });
        }
    }
}
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.
TypeScript
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);
            }
        }
    }
}
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.
TypeScript
    const userStorage: DataStorage = await loadDataStorage(userId);
    const userStorage: DataStorage = await loadDataStorage(userId);
﻿
﻿
👍 Tip
If you want to store data between different worlds, implement it using httpService﻿ 
﻿
Updated 10 Oct 2024
Did this page help you?
HTTP request from the Multiplay server
PlayerPrefs - Saving data to the device