PlayerState Documentation

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.

• Features
• Quick Start
• Architecture
• Dependencies
• Getting Started
• Recent updates

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

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

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

NOTE

All dependencies are included in the Roblox model! No manual installation needed.

Getting Started

1. Installation - Add to your project
2. Setup - Configure the module and PlayerStateConfig settings
3. API Reference - Complete function documentation
4. Examples - Common usage patterns

PlayerState V1

This is PlayerState V1 - production-ready with active development. Updates include new features, optimizations, and community-requested improvements. Your feedback shapes future versions!

Recent updates

• New: Added a new client function GetLeaderboardInfo(statName) to easily get your current leaderboard rank and score for a stat.
• Fixed: A small cache cleanup issue on the client.
• Improved: Leaderboard updates so players get up-to-date info sooner (no “wait for the next interval” feeling).
• New: Synced each player’s current leaderboard info to the client, so UIs can show rank/score more reliably.
• Improved: Scores feel instant: when a tracked stat changes, the displayed leaderboard score updates right away; the rank updates on the normal refresh cycle.
• Note: Leaderboard display data is treated as temporary and won’t be saved into player data.