Full setup

Completed Quick start? This page covers schema, saves, client listeners, and pointing PlayerStateConfig at the right datastore.

Server setup

Required

Call PlayerState.Init(player) on PlayerAdded. See Quick start for the minimal script.

Initialize players

-- ServerScriptService.PlayerManager
local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local PlayerState = require(ReplicatedStorage.Libraries.PlayerState.PlayerStateServer)

Players.PlayerAdded:Connect(function(player)
    local success = PlayerState.Init(player)

    if success then
        print(`[PlayerState] Successfully initialized data for {player.Name}`)

        local coins = PlayerState.Get(player, "Coins")
        if coins == 0 then
            PlayerState.Set(player, "Coins", 100)
            PlayerState.SetPath(player, "Settings.MusicEnabled", true)
        end
    else
        warn(`[PlayerState] Failed to initialize data for {player.Name}`)
    end
end)

Saving data

When	What happens
Player leaves or server shuts down	Profile session ends; data is saved through PlayerState
You call SaveData(player)	Manual save; fires BeforeSave
On leave (hooks)	BeforeRelease runs, then BeforeSave — see Events
ProfileStore periodic autosave	Does not fire BeforeRelease or BeforeSave unless you call SaveData()

local success = PlayerState.SaveData(player)

Client setup

Read data

The client waits for profile data internally:

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local PlayerState = require(ReplicatedStorage.Libraries.PlayerState.PlayerStateClient)

local coins = PlayerState.Get("Coins")
print("Player coins:", coins)

Listen for changes

local coinsConnection = PlayerState.OnChanged("Coins", function(newValue, oldValue)
    updateCoinsDisplay(newValue)
end)

-- Disconnect when UI or player context ends
coinsConnection:Disconnect()

See Change listeners guide for ChangeInfo vs path arrays.

DefaultData configuration

Define your data schema in the DefaultData module.

Example DefaultData schema

-- ReplicatedStorage.Libraries.PlayerState.DefaultData
return {
    Coins = 100,
    Level = 1,
    Experience = 0,

    Inventory = {},
    Achievements = {},

    Settings = {
        MusicEnabled = true,
        SoundEnabled = true,
        GraphicsQuality = "Medium",
    },

    Plot = {
        Likes = 0,
        Size = 1,
        Theme = "Default",
        Buildings = {},
    },

    Stats = {
        TotalPlayTime = 0,
        GamesPlayed = 0,
        HighScore = 0,
        LastLogin = 0,
    },

    Purchases = {
        GamePasses = {},
        DeveloperProducts = {},
    },

    session = {
        isChopping = false,
        isSprinting = false,
    },

    Server = {
        Version = 1,
        Cache = {},
        LastSeen = nil,
        LifeStats = {},
    },
}

For session, Server, and SharedSession rules, see Data visibility, Session data, Server-only data, and Shared session.

Environment configuration

local Config = {
    Server = {
        Profile = {
            Key = "PlayerData",
            Template = DefaultData,
        },
        DataStore = {
            Name = game.PlaceId == YOUR_DEV_PLACE_ID and "PlayerData_DEV" or "PlayerData_PROD",
            Scope = game.PlaceId == YOUR_DEV_PLACE_ID and "Testing" or "Production",
        },
    },
}

Testing-only datastore:

DataStore = {
    Name = "PlayerData_TEST",
    Scope = "Testing",
},

Full reference: Configuration (batching, caches, migration config). Leaderboards: Leaderboard configuration.

Next steps

• Configuration — PlayerStateConfig tuning
• Examples — Currency, inventory, settings patterns
• API reference — Function documentation
• Best practices — Conventions and pitfalls

See also

Quick startConfigurationTroubleshooting