PlayerState

A robust, type-safe player data management system for ROBLOX games using ProfileStore and Replica services.

Created by bellaouzo - A powerful solution for managing player data in ROBLOX games that utilizes Replica and ProfileStore.

Optional support — This documentation is free. You do not need to pay anything to use PlayerState or these docs. If you would like to leave a tip, it is genuinely appreciated, but completely optional and never expected.

In PayPal, use Send and enter joelbriskpro@gmail.com. Open PayPal

Features

Get: 2.2M/secSet: 478K/secGetPath: 2.1M/secSetPath: 488K/sec

Get: 3.5M/secGetPath: 2.77M/secCached: 3.2M/secGetAll: 4.5M/sec

• Type Safety: Full TypeScript-style type annotations
• Real-time Sync: Automatic client-server data synchronization
• Persistent Storage: ProfileStore integration for reliable data persistence
• Path-based Access: Easy nested data manipulation with dot notation
• Event System: Listen for data changes with callbacks
• Array & Dictionary Operations: Built-in helpers for collections
• Shared session: Server-wide temporary state replicated to every client in the current server (SharedSession)
• Server-only roots: Saved per-player fields stripped before the player Replica (ServerOnlyRoots)

More on features & visibility

Server-only persisted fields

Use a Server root (and ServerOnlyRoots) when data should save but never hit any client Replica—not just hidden UI, but actually absent from client-visible PlayerState. Server-only player data · visibility overview

:::

Quick Start

Server Setup

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

-- ⚠️ CRITICAL: You MUST have this PlayerAdded connection!
game.Players.PlayerAdded:Connect(function(player)
    PlayerState.Init(player) -- ← ESSENTIAL - PlayerState won't work without this!
end)

-- Set player coins (after Init)
PlayerState.Set(player, "Coins", 1000)

Client Usage

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

-- Get player coins
local coins = PlayerState.Get("Coins")

-- Listen for changes
PlayerState.OnChanged("Coins", function(newValue, oldValue)
    print("Coins updated:", newValue)
end)

Ready to Go!

The Roblox model includes all dependencies - just download and use!

Architecture overview

PlayerState uses a server-authoritative architecture:

Key components

• Server: Manages all data modifications using ProfileStore for persistence
• Client: Read-only access with real-time updates via Replica
• Synchronization: Automatic bi-directional sync between server and clients

Dependencies

• ProfileStore — Data persistence
• Replica — Real-time synchronization
• DefaultData module — Data schema definition
• PlayerStateConfig module — Centralized configuration settings

All dependencies are included in the Roblox model — no manual install needed.

Getting Started

1. Concepts — How persistence, replication, and scopes fit together
2. Installation - Add to your project
3. Setup - Configure the module and PlayerStateConfig settings
4. API Reference - Complete function documentation
5. Examples - Common usage patterns

Looking for a specific task? Use the “I want to…” shortcuts on the Guides hub.

See What's new for migrations, Shared Session, server-only roots, session data, and other highlights.

Migration & version

If you have existing player data, Legacy Data Migration can import from an old DataStore during profile load (opt-in).

PlayerState V1 is production-ready with active development — see What's new for recent capabilities.