Getting Started

create-player-data saves and syncs player data in Roblox. type-safe, zero boilerplate, and you decide when to load it.

Install

[dependencies]
create_player_data = { pesde = "sap0bombado/[email protected]" }

pesde install

Create your data module

A shared module defines what every player's data looks like:

local createPlayerData = require '@pkg/create_player_data'

type ItemData = {
    health: number,
    dmg: number,
}

local template = {
    currency = 0,
    inventory = {
        apples = 5,
        oranges = 10,
    },
    settings = {
        music = true,
        sfx = true,
    },
    items = {} :: { [string]: ItemData },
    equippedItemId = nil :: string?,
    questProgress = {} :: { number },
}

export type template = typeof(template)

return createPlayerData<<template>>({
    template = template,
})

Values must be JSON-safe: numbers, strings, booleans, arrays, dictionaries, and nil for optional keys. No Instances, CFrame, Vector3, functions, or userdata.

Require it

-- Server
local Data = require(path.to.Data).server

-- Client
local Data = require(path.to.Data).client

Load data

create-player-data never loads players automatically. Call startSessionAsync in your own PlayerAdded handler:

local Players = game:GetService 'Players'

Players.PlayerAdded:Connect(function(player)
    local ok = Data:startSessionAsync(player)
    if not ok then
        player:Kick 'Could not load your data. Please rejoin.'
    end
end)

Once loaded, access the player's data with :get():

local playerData = Data:get(player)
playerData.currency(50)

Data saves automatically when the player leaves. New keys added to the template are reconciled into existing profiles on their next load.

Next steps

Server — loading, lifecycle, profiles, global messages
Options — configuration reference
Values — reading, writing, and listening to reactive data
Client — the read-only mirror