Client writes via remotes

PlayerState keeps saved data server-authoritative. The client API is read-only for profile data. PlayerState does not include RemoteEvents or RemoteFunctions for gameplay writes—you expose your own and validate on the server.

Related: API overview · Troubleshooting — client can't write · Best practices

• Pattern
• Minimal example
• Checklist
• Built-in remotes

Pattern

1. Client fires your RemoteEvent with a small payload (for example action name + amount).
2. Server checks the player is in the game, types, ranges, cooldowns, and permissions.
3. Server calls PlayerState.Set, Increment, SetPath, or other server APIs.

Minimal example

Adjust paths if you moved modules — see Installation.

Server (ServerScriptService or equivalent):

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

local purchaseRemote = Instance.new("RemoteEvent")
purchaseRemote.Name = "PurchaseItem"
purchaseRemote.Parent = ReplicatedStorage

local ITEM_COST = 100

purchaseRemote.OnServerEvent:Connect(function(player, itemId)
    if not player or not player.Parent then
        return
    end
    if typeof(itemId) ~= "string" then
        return
    end

    local coins = PlayerState.Get(player, "Coins") or 0
    if coins < ITEM_COST then
        return
    end

    PlayerState.Increment(player, "Coins", -ITEM_COST)
    -- Grant item, update inventory paths, etc.
end)

Client:

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local purchaseRemote = ReplicatedStorage:WaitForChild("PurchaseItem")

purchaseRemote:FireServer("sword_01")

Checklist

• Validate every argument from the client (type, range, whitelist).
• Never call client-only APIs to mutate saved data.
• Rate-limit or debounce spam-prone remotes.
• For UI that must show live values, use OnChanged on the client — Change listeners.

Built-in remotes

PlayerState may expose a small number of read-only helpers (for example offline profile snapshots). Those are documented on the relevant API pages — do not confuse them with general write remotes. See GetOfflineData and Client errors.