@usbx/data

Saving and leaderboards

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

profile_schemafunction profilefunction save_in_profilefunction documentsfunction storefunction orderedfunction profile_loadedevent profile_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

schema

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

collectionschema

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.