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

Features

🚀 1.04M ops/sec⚡ 6.6M UI updates/sec📊 Sub-μs response times

• 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!