Skip to content
Untitled Sandbox - Developer Documentation
docs/api/data

@usbx/data

Saving and leaderboards

local data = require("@usbx/data")
profile_schemafunctionprofilefunctionsave_in_profilefunctiondocumentsfunctionstorefunctionorderedfunctionprofile_loadedeventprofile_failedevent

data.profile_schema

function

Declares the Profile every player gets. Declare it once; missing fields take their defaults, and players who joined before start loading then.

data.profile_schema(schema: Schema<any>, options: SchemaOptions?) -> ()
example
data.profile_schema(schema.struct({ coins = schema.number() }))

Use it forsetting up, once, what every player saves, like their tokens, level and items.

schemaWhat every Profile holds.
optionsoptionalIts version, and how to bring older Profiles up to it.
Build a profile_schema callversion · migrate
  • version

    The version number of the schema, which is a whole number starting from 1.

  • migrate

    A function that brings a value saved with an older version up to this one, which must not yield, so it cannot wait or pause.

data.profile

functionwaits

The player's Profile. Yields until it is loaded.

data.profile(player: Player) -> Document?
example
local profile = data.profile(player)

Use it forreading or changing a player's saved tokens when they buy something in your shop.

playerThe player.

data.save_in_profile

function

Keeps a per-player State in each player's Profile, so a value such as coins or a level lasts between visits. When a Profile loads, its saved value goes into the State, and every change of the State is written to the Profile, which saves as Profiles do.

data.save_in_profile<T>(state: PlayerState<T>, path: string?) -> ()
example
data.save_in_profile(coins, "coins")

Use it forkeeping a player's tokens or level between visits, without writing any save code yourself.

stateA per-player State, from state.create_per_player.
pathoptionalWhere it goes in the Profile, such as "coins" or "stats.wins". The State's key by default.

data.documents

function

Saved Documents of one schema, shared by every server of the game. Names have 1 to 100 characters, and names that start with __ are reserved.

data.documents(collection: string, schema: Schema<any>, options: SchemaOptions?) -> DocumentCollection
example
local guilds = data.documents("guilds", schema.struct({ name = schema.string() }))

Use it forsaving things that players share, like guilds, clans or the buildings of a town, across every server.

collectionName of the collection.
schemaWhat every document holds.
optionsoptionalIts version, and how to bring older documents up to it.
Build a documents callversion · migrate
  • version

    The version number of the schema, which is a whole number starting from 1.

  • migrate

    A function that brings a value saved with an older version up to this one, which must not yield, so it cannot wait or pause.

data.store

function

The Key-Value Store with the name.

data.store(name: string) -> KeyValueStore
example
local settings = data.store("settings")

Use it forkeeping game-wide settings, like a welcome message or a switch that turns an event on.

nameName of the store.

data.ordered

function

The Ordered Store of scores with the name. A leaderboard on the website shows one.

data.ordered(name: string) -> OrderedStore
example
local wins = data.ordered("wins")

Use it fortracking wins or best times so you can show an all-time leaderboard.

nameName of the store.

data.profile_loaded

event

Fires when a player's Profile has loaded, with the player and the Profile.

data.profile_loaded: Event<(Player, Document)>
example
data.profile_loaded:connect(function(player, profile) print(player.name, profile:get("coins")) end)

Use it forgiving a player their saved items the moment their data has loaded.

data.profile_failed

event

Fires when a player's Profile could not be loaded, with the reason.

data.profile_failed: Event<(Player, string)>
example
data.profile_failed:connect(function(player, reason) warn(player.name, reason) end)

Use it fortelling a player their progress did not load, or logging the reason.

↑ ↓ moveEnter openEsc close