Storage

Estella provides a Storage API for persisting data locally. It works across Web (localStorage) and WeChat MiniGame (wx storage) platforms with a unified interface.

Basic Usage

import { Storage } from 'esengine';

// String
Storage.setString('playerName', 'Alice');
const name = Storage.getString('playerName'); // 'Alice'

// Number
Storage.setNumber('highScore', 9999);
const score = Storage.getNumber('highScore', 0); // 9999

// Boolean
Storage.setBoolean('musicEnabled', true);
const music = Storage.getBoolean('musicEnabled', false); // true

// JSON (objects, arrays, etc.)
Storage.setJSON('settings', { volume: 0.8, language: 'en' });
const settings = Storage.getJSON<{ volume: number; language: string }>('settings');

Default Values

All getter methods accept an optional second parameter as the default value. It is returned when the key does not exist or when the stored value is corrupted:

const score = Storage.getNumber('score', 0);           // 0 if missing
const name = Storage.getString('name', 'Player');       // 'Player' if missing
const items = Storage.getJSON<string[]>('items', []);   // [] if missing or invalid JSON

Checking and Removing Keys

if (Storage.has('highScore')) {
    console.log('Save data found');
}

Storage.remove('highScore');

// Remove all Estella storage data
Storage.clear();

Game Save Example

import { defineSystem, addSystem, Res, Input, Storage } from 'esengine';

interface SaveData {
    level: number;
    hp: number;
    position: { x: number; y: number };
    inventory: string[];
}

function saveGame(data: SaveData): void {
    Storage.setJSON('save:slot1', data);
}

function loadGame(): SaveData {
    return Storage.getJSON<SaveData>('save:slot1', {
        level: 1,
        hp: 100,
        position: { x: 0, y: 0 },
        inventory: [],
    })!;
}

Tip

Use key naming conventions like save:slot1, save:slot2 to implement multiple save slots without needing a built-in slot system.

Player Settings Example

function loadSettings() {
    return {
        musicVolume: Storage.getNumber('settings:musicVolume', 1.0),
        sfxVolume: Storage.getNumber('settings:sfxVolume', 1.0),
        language: Storage.getString('settings:language', 'en'),
    };
}

function saveMusicVolume(volume: number) {
    Storage.setNumber('settings:musicVolume', volume);
}

API Reference

Method	Description
getString(key, default?)	Get a string value
setString(key, value)	Store a string value
getNumber(key, default?)	Get a number value
setNumber(key, value)	Store a number value
getBoolean(key, default?)	Get a boolean value
setBoolean(key, value)	Store a boolean value
getJSON<T>(key, default?)	Get a parsed JSON value
setJSON<T>(key, value)	Store a JSON-serializable value
has(key)	Check if a key exists
remove(key)	Remove a key
clear()	Remove all Estella storage data

Note

All keys are automatically prefixed with esengine: to avoid conflicts with other libraries. You don’t need to add this prefix yourself.

Platform Details

Platform	Backend	Limit
Web	localStorage	~5 MB
WeChat MiniGame	wx.getStorageSync	10 MB

Caution

Storage is synchronous on both platforms. Keep stored data small (settings, save states) to avoid frame drops. For large binary data, consider using platform-specific APIs directly.

Next Steps

• Scenes — scene loading and management
• Resources — runtime global state with the Resource system
• WeChat MiniGame — WeChat platform specifics