Quick start

Get PlayerState running in a few minutes. For DefaultData, environment config, and tuning, continue with Full setup after this page. API and feature updates are summarized in What's new (docs track PlayerState V1 and the Creator Store model).

Before you start

• The Roblox model includes ProfileStore and Replica — no separate dependency install if you use the model as shipped.
• The client API is read-only. All writes happen on the server (your own remotes + PlayerState server APIs).

1. Get the model

Download the PlayerState model from the Creator Store and insert it into your place (default layout uses ReplicatedStorage).

See Installation for manual install and optional folder layouts.

2. Require paths

Adjust paths if you moved modules out of the default tree:

-- Server
local PlayerState = require(ReplicatedStorage.Libraries.PlayerState.PlayerStateServer)

-- Client
local PlayerState = require(ReplicatedStorage.Libraries.PlayerState.PlayerStateClient)

3. Server — initialize each player

You must call PlayerState.Init(player) when a player joins.

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

Players.PlayerAdded:Connect(function(player)
    local ok = PlayerState.Init(player)
    if ok then
        PlayerState.Set(player, "Coins", 1000) -- example write
    end
end)

4. Client — read and listen

local PlayerState = require(ReplicatedStorage.Libraries.PlayerState.PlayerStateClient)

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

PlayerState.OnChanged("Coins", function(newValue)
    print("Coins updated:", newValue)
end)

Checklist

• Model is in the place and require paths resolve
• Server prints no errors and Init runs on join
• Client can read a value after join
• You have not put save logic only in PlayerRemoving without Init on the server

What's next

Step	Page
Schema and full init patterns	Full setup
PlayerStateConfig	Configuration
Saved vs replicated vs session data	Concepts · Data visibility
Copy-paste gameplay patterns	Examples
Every function	API reference
Something wrong?	Troubleshooting