Saving data

A game can keep data between play sessions without a backend of its own: a player's progress and settings, state every player shares, and leaderboards. Scripts reach it through save; Rust code through the neo_save crate. Every call is asynchronous: it returns a promise that resolves on a later simulation tick, so scripts stay deterministic.

Saving and loading a player's data#

save is the current player's own data. save.get(key) resolves to the stored value (or null), save.set(key, value) stores any JSON-like value: numbers, strings, booleans, lists, objects.

import { World, on, save } from "neo";

export default class Progress extends World {
  state = { best: 0 };

  @on("round_start")
  async load() {
    this.state.best = (await save.get("best")) ?? 0;
  }

  @on("finished")
  async finished(player, time) {
    if (time > this.state.best) {
      this.state.best = time;
      await save.set("best", time);
    }
  }
}

from neo import World, on, save

class Progress(World):
    state = {"best": 0}

    @on("round_start")
    async def load(self):
        best = await save.get("best")
        self.state.best = best if best is not None else 0

    @on("finished")
    async def finished(self, player, time):
        if time > self.state.best:
            self.state.best = time
            await save.set("best", time)

default = Progress

this.save (self.save in Python) is the same object as the imported save.

Use setIf when two places might write the same key: read with getEntry, compute, write with the version you read, and retry if ok is false.

Shared data and other players#

• save.shared has the same calls for data every player of your game shares (a world record, a message of the day). Only the session's authority writes it: the host of a peer session, the player of a solo one.
• save.player(userId) reaches a specific player's data. Anyone in the session can read it; the player and the session's authority can write it (the authority only for players in its session).

Leaderboards#

save.leaderboard(name) is an ordered store of whole numbers by key:

const wins = save.leaderboard("wins");
await wins.increment(1);          // the current player's entry
const top = await wins.top(10);   // [{ key, value, rank }, …], highest first

wins = save.leaderboard("wins")
await wins.increment(1)
top = await wins.top(10)

increment(by, key) adds to an entry; without a key it's the current player's own (keyed by their user id). Players only write their own entry; the session's authority may write any key (a team's, say).

Where it's stored#

A game launched from the platform gets a session token with its launch; without one (playing in the editor, a downloaded build), saves stay on the device. Your script doesn't change.

Limits#

• Values: up to 4 MB each (as JSON). Keys: 1 to 128 characters. Store names (save.leaderboard(name)): letters, digits, _, . and -, up to 50.
• Each game has a request budget per minute that grows with the number of players in its sessions, and a total storage size. Over the budget, a call fails with resource_exhausted: save on meaningful moments (a level finished, a purchase), not every tick.
• Previous values are kept for 30 days.

A failed call rejects its promise (Python raises): catch it to show the player something or retry later.

Guests, deleting and exporting#

• A guest's data is kept when they make an account, whether they upgrade the guest account or sign up while playing as a guest.
• Deleting an account deletes everything games saved about that player, including their leaderboard entries.
• Players can download everything games saved about them from Settings > Your data.

From Rust#

Games built in Rust use the neo_save crate's Saves resource: each call returns a ticket, and the result arrives later as a SaveDone message.

use neo_save::{SaveDone, SaveScope, Saves};

fn load(mut saves: ResMut<Saves>, mut ticket: Local<Option<neo_save::SaveTicket>>) {
    if ticket.is_none() {
        *ticket = Some(saves.get(SaveScope::Me, "best"));
    }
}

fn loaded(mut done: MessageReader<SaveDone>) {
    for d in done.read() {
        info!("save {:?}: {:?}", d.ticket, d.result);
    }
}