API Reference

PlayerState provides separate APIs for server and client environments with enhanced type-safe interfaces and advanced features.

Overview

• Server Functions - Data manipulation, batch operations, and management (server-only)
• Client Functions - Data access, change listeners, and caching (client-only)
• Types - Enhanced TypeScript-style type definitions

🆕 Latest Features

Server Enhancements

• 🚀 Batch Operations - BatchSetValues() and FlushBatch() for high-performance bulk updates
• 🏆 Automatic Leaderstats - Integrated leaderstats creation and real-time synchronization
• 📊 Enhanced Status Checking - IsPlayerDataReady() for reliable validation
• 🔧 Cache Management - ClearPathCache() with automatic size limits
• 📦 Array & Dictionary Operations - Full CRUD operations with validation

Client Enhancements

• ⚡ Advanced Caching - Automatic value and path caching with cleanup
• 📈 Enhanced Change Listeners - Detailed action information (Set, TableInsert, etc.)
• 🎯 Global Change Monitoring - Listen to all changes with "." path
• ✅ Readiness Checking - IsReady() for reliable data status
• 🧹 Manual Cache Control - ClearCache() for debugging and optimization

Architecture

PlayerState follows a server-authoritative model with enhanced real-time synchronization:

┌─────────────────┐    ┌──────────────────┐
│   Server Module │────│ ProfileStore     │ (Data Persistence)
│                 │    │ (Automatic Save) │
└─────────────────┘    └──────────────────┘
         │
         ├─────────────► Replica ────────────┐
         │              (Real-time Sync)     │
         │                                   ▼
         ├─────────────► Batch System    ┌─────────────────┐
         │              (Performance)    │  Client Module  │
         │                               │                 │
         └─────────────► Leaderstats ────│  ► UI Updates   │
                        (Player List)    │  ► Game Logic   │
                                         │  ► Caching      │
                                         └─────────────────┘

Enhanced Data Flow

1. Server: All data modifications with batch processing and validation
2. ProfileStore: Enhanced persistence with automatic cleanup
3. Replica: Real-time sync with detailed change information
4. Client: Cached read access with advanced change detection
5. Leaderstats: Automatic integration and real-time updates

No Built-in Client Requests

PlayerState does NOT include built-in RemoteEvents or RemoteFunctions. Clients cannot directly request data changes for security reasons. You must create your own RemoteEvents with proper server-side validation for any client-initiated modifications.

Module Locations

-- Server Module (Server-side only)
local PlayerStateServer = require(ServerScriptService.Libraries.PlayerState.PlayerStateServer)

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

-- Default Data Schema (with leaderstats configuration)
local DefaultData = require(ReplicatedStorage.Libraries.PlayerState.DefaultData)

-- Configuration Module (server and client settings)
local Config = require(ReplicatedStorage.Libraries.PlayerState.PlayerStateConfig)

Enhanced Usage Examples

Server Operations - NEW

-- Initialize player (enhanced with leaderstats)
local success = PlayerState.Init(player)

-- Check data readiness
if PlayerState.IsPlayerDataReady(player) then
    -- Basic operations with return values
    local success = PlayerState.Set(player, "Coins", 1000)
    local coins = PlayerState.Get(player, "Coins")
    
    -- Batch operations for performance
    PlayerState.BatchSetValues(player, {
        {path = "Coins", value = 2000},
        {path = "Level", value = 5},
        {path = "Plot.Likes", value = 100}
    })
    
    -- Array & Dictionary operations
    PlayerState.AddToArray(player, "Inventory", {Id = "sword", Name = "Iron Sword"})
    PlayerState.SetInDict(player, "Plot.Buildings", "House", {Level = 2})
end

Client Operations - ENHANCED

-- Check readiness before operations
if PlayerState.IsReady() then
    -- Read data (with caching)
    local coins = PlayerState.Get("Coins")
    local likes = PlayerState.GetPath("Plot.Likes")
    
    -- Enhanced change listeners with action info
    local connection = PlayerState.OnChanged("Inventory", function(newValue, oldValue, info)
        if info and info.action == "TableInsert" then
            print(`Item added at index {info.index}`)
        elseif info.action == "TableRemove" then
            print(`Item removed from index {info.index}`)
        end
    end)
    
    -- Global change monitoring
    PlayerState.OnChanged(".", function(newValue, oldValue, info)
        if info and info.action then
            local pathString = table.concat(info.path, ".")
            print(`{info.action}: {pathString}`)
        end
    end)
end

-- Manual cache management
PlayerState.ClearCache() -- For debugging or memory optimization

Enhanced Performance

• Server batch operations process up to 20 changes in 30ms for optimal performance
• Client caching reduces repeated data access overhead
• Automatic cache cleanup prevents memory leaks

Leaderstats Integration

PlayerState now automatically creates and manages leaderstats:

-- In DefaultData.lua
local DefaultData = {
    Coins = 0,
    Level = 1,
    Plot = { Likes = 0 },
    
    -- Automatic leaderstats configuration
    leaderstats = {
        ["💰 Coins"] = "Coins",
        ["⭐ Level"] = "Level", 
        ["👍 Likes"] = "Plot.Likes"
    }
}

Features:

• 🏆 Automatic Creation - Leaderstats appear when player data loads
• 🔄 Real-time Sync - Updates instantly when data changes
• 🛡️ Protection - Prevents direct leaderstats modification
• 🎯 Path Support - Works with nested data paths

Enhanced Path Notation

PlayerState supports dot notation with improved performance:

Enhanced Path Examples

-- Basic paths (cached for performance)
PlayerState.SetPath(player, "Settings.MusicEnabled", false)
PlayerState.SetPath(player, "Plot.Buildings.House.Level", 3)

-- Complex batch operations
PlayerState.BatchSetValues(player, {
    {path = "Stats.Combat.Weapons.Sword.Damage", value = 25},
    {path = "Inventory.Tools.Pickaxe.Durability", value = 100},
    {path = "Settings.Graphics.Quality", value = "High"}
})

-- Array operations with enhanced feedback
PlayerState.AddToArray(player, "Achievements", "first_win") -- Returns success
PlayerState.UpdateArrayItem(player, "Inventory", 1, newItemData) -- Index-based update

-- Dictionary operations
PlayerState.SetInDict(player, "Plot.Buildings", "Windmill", buildingData)
PlayerState.RemoveFromDict(player, "Settings", "ObsoleteSetting")

::: note Automatic Path Creation Paths automatically create nested structures when setting values, with enhanced validation! :::

Enhanced Error Handling & Status

All functions now include comprehensive error handling:

-- Server functions return detailed success indicators
local success = PlayerState.Init(player) -- boolean
local ready = PlayerState.IsPlayerDataReady(player) -- boolean
local added = PlayerState.AddToArray(player, "Inventory", item) -- boolean

-- Batch operations with validation
local success = PlayerState.BatchSetValues(player, operations) -- boolean
PlayerState.FlushBatch(player) -- Force immediate processing

-- Client functions with readiness checking
if PlayerState.IsReady() then
    local coins = PlayerState.Get("Coins") -- Safe access
end

-- Enhanced connection management
local connection = PlayerState.OnChanged("Coins", callback)
-- Remember to disconnect: connection:Disconnect()

Performance Optimizations

🚀 Server Performance

• Batch Processing: Intelligent grouping of operations
• Path Caching: Reusable path parsing (max 1000 entries)
• Automatic Cleanup: Memory management for long-running servers
• Leaderstats Protection: Prevents accidental modification

⚡ Client Performance

• Value Caching: Frequently accessed data cached with timestamps
• Nested Path Caching: Complex path resolution optimization
• Connection Management: Automatic cleanup and validation
• Cache Control: Manual ClearCache() for memory management

Migration Guide

From Previous Versions

Server Changes:

• Functions now return boolean success status
• Use IsPlayerDataReady() instead of manual checks
• Batch operations recommended for multiple changes
• Leaderstats are automatic (remove manual creation)

Client Changes:

• Use IsReady() before data operations
• Enhanced OnChanged() callbacks with action info
• Global listeners with "." path for debugging
• Manual cache management available

Next Steps

• Server Functions - Complete enhanced server API reference
• Client Functions - Complete enhanced client API reference
• Types - Enhanced type definitions and interfaces