PlayerState

https://playerstate.netlify.app/
Admin
PlayerState is a robust, type-safe player data management system for ROBLOX games, utilizing...
Tokens:55,266
Snippets:516
Trust Score:7.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Quick Start: Server and Client Setup

Source: https://playerstate.netlify.app/installation

Use these require paths for the server and client scripts when PlayerState is placed in ReplicatedStorage.

```lua
-- Server script
local PlayerState = require(game.ReplicatedStorage.PlayerState.PlayerStateServer)

-- Client script  
local PlayerState = require(game.ReplicatedStorage.PlayerState.PlayerStateClient)
```

--------------------------------

### Enable Legacy Data Migration - Quick Start

Source: https://playerstate.netlify.app/migration

Use this configuration to enable and start migrating legacy data. Set `enabled` to true, specify your old DataStore name in `store`, and use `Auto` strategy with `{UserId}` as the key.

```lua
LegacyDataStore = {
    enabled = true,
    store = "OldStore",
    strategy = "Auto",
    keys = { "{UserId}" },  -- {UserId} auto-replaced with player's UserId
}
```

--------------------------------

### LeaderstatsConfig Example

Source: https://playerstate.netlify.app/api/types

An example demonstrating how to configure leaderstats, mapping display names like "💰 Coins" to their corresponding data paths such as "Coins".

```lua
local leaderstatsConfig: LeaderstatsConfig = {
    ["💰 Coins"] = "Coins",
    ["⭐ Level"] = "Level",
    ["👍 Likes"] = "Plot.Likes",
    ["🏆 High Score"] = "Stats.HighScore"
}
```

--------------------------------

### Initialize PlayerState on Server

Source: https://playerstate.netlify.app/installation

Verifies PlayerState setup by initializing it for each player when they join. Ensure the require path to PlayerStateServer is correct for your project.

```lua
-- In a server script - adjust path to your PlayerStateServer location
local PlayerState = require(game.ServerScriptService.PlayerStateServer) -- Adjust this path

game.Players.PlayerAdded:Connect(function(player)
    local success = PlayerState.Init(player)
    if success then
        print("PlayerState initialized for", player.Name)
    end
end)
```

--------------------------------

### Server: Set and Get Session Data

Source: https://playerstate.netlify.app/session-data

Initialize PlayerState for a player and use SetPath/GetPath to manage session data on the server. This example demonstrates setting and reading sprint and chop states.

```lua
-- ServerScriptService
local PlayerState = require(game.ReplicatedStorage.Libraries.PlayerState.PlayerStateServer)

Players.PlayerAdded:Connect(function(player)
    PlayerState.Init(player)

    -- Set session state
    PlayerState.SetPath(player, "session.isSprinting", true)
    PlayerState.SetPath(player, "session.isChopping", false)

    -- Read it back
    local sprinting = PlayerState.GetPath(player, "session.isSprinting")
end)

```

--------------------------------

### DictPath Examples

Source: https://playerstate.netlify.app/api/types

Illustrates DictPath usage for accessing various dictionary structures. Ensure paths accurately point to the desired tables.

```lua
"Settings"           -- Settings dictionary
"Plot.Buildings"     -- Building configuration
"Stats"              -- Player statistics
"Inventory.Equipped" -- Equipment slots
```

--------------------------------

### ChangeInfo Action Types and Example Usage

Source: https://playerstate.netlify.app/api/types

Explains the different `action` types within ChangeInfo ('Set', 'SetValues', 'TableInsert', 'TableRemove') and provides an example of how to use `PlayerState.OnChanged` to listen for table insert events.

```lua
PlayerState.OnChanged(".", function(newValue, oldValue, info)
    if info and info.action == "TableInsert" then
        print(`Item added at index {info.index} to {table.concat(info.path, ".")}`)
    end
end)
```

--------------------------------

### ArrayPath Examples

Source: https://playerstate.netlify.app/api/types

Provides examples of ArrayPath usage for accessing top-level, nested, and complex arrays. Correct pathing is crucial for array operations.

```lua
"Inventory"          -- Top-level array
"Plot.Buildings"     -- Nested array
"Achievements"       -- List of achievements
"Stats.RecentScores" -- Nested score array
```

--------------------------------

### Level System with Batch Operations

Source: https://playerstate.netlify.app/api/server

Examples demonstrating a level system using `PlayerState.Get`, `PlayerState.Set`, and `PlayerState.BatchSetValues` for efficient updates.

```APIDOC
## Level System with Batch Operations

### Description
Examples demonstrating a level system using `PlayerState.Get`, `PlayerState.Set`, and `PlayerState.BatchSetValues` for efficient updates.

### Method
Not applicable (Lua functions)

### Endpoint
Not applicable (Lua functions)

### Parameters
None

### Request Example
lua```lua
-- Level up player with batch operations
local function levelUp(player)
    local currentLevel = PlayerState.Get(player, "Level") or 1
    local currentCoins = PlayerState.Get(player, "Coins") or 0
    local bonusCoins = currentLevel * 100

    local success = PlayerState.BatchSetValues(player, {
        {path = "Level", value = currentLevel + 1},
        {path = "Experience", value = 0},
        {path = "Coins", value = currentCoins + bonusCoins}
    })

    if success then
        print(`{player.Name} leveled up to {currentLevel + 1}!`)
        return true
    end

    return false
end

-- Add experience with level up check
local function addExperience(player, amount)
    local currentExp = PlayerState.Get(player, "Experience") or 0
    local currentLevel = PlayerState.Get(player, "Level") or 1
    local expNeeded = currentLevel * 100

    local newExp = currentExp + amount

    if newExp >= expNeeded then
        -- Level up
        levelUp(player)
    else
        -- Just add experience
        PlayerState.Set(player, "Experience", newExp)
    end
end
```
```

--------------------------------

### ValuePath Examples

Source: https://playerstate.netlify.app/api/types

Demonstrates various ways to use ValuePath for accessing data at different nesting levels. Ensure paths correctly reflect the data structure.

```lua
"Coins"              -- Top-level access
"Plot.Likes"         -- Nested access
"Settings.MusicEnabled"  -- Deep nesting
"Stats.HighScore"    -- Any depth
"Plot.Buildings.House.Level"  -- Complex nesting
```

--------------------------------

### Modular Service Structure Example

Source: https://playerstate.netlify.app/best-practices

Illustrates organizing code into modular services, where each service has a single, clear responsibility like handling currency or inventory.

```lua
-- ✅ Create focused service modules
-- CurrencyService.lua - Only handles currency
-- InventoryService.lua - Only handles inventory
-- LevelService.lua - Only handles leveling
-- SettingsService.lua - Only handles settings

-- Each service has a clear, single responsibility
```

--------------------------------

### Currency Management with Validation

Source: https://playerstate.netlify.app/api/server

Examples demonstrating how to manage player currency using `PlayerState.Get` and `PlayerState.Set`, including validation for awarding and spending coins.

```APIDOC
## Currency Management with Validation

### Description
Examples demonstrating how to manage player currency using `PlayerState.Get` and `PlayerState.Set`, including validation for awarding and spending coins.

### Method
Not applicable (Lua functions)

### Endpoint
Not applicable (Lua functions)

### Parameters
None

### Request Example
lua```lua
-- Award coins (validation handled internally)
local function awardCoins(player, amount, source)
    local currentCoins = PlayerState.Get(player, "Coins") or 0
    local success = PlayerState.Set(player, "Coins", currentCoins + amount)

    if success then
        print(`Awarded {amount} coins to {player.Name} from {source}`)
        return true
    else
        warn(`Failed to award coins to {player.Name}`)
        return false
    end
end

-- Spend coins with validation
local function spendCoins(player, amount, item)
    local currentCoins = PlayerState.Get(player, "Coins") or 0
    if currentCoins < amount then
        return false, "Insufficient coins"
    end

    local success = PlayerState.Set(player, "Coins", currentCoins - amount)
    if success then
        print(`{player.Name} spent {amount} coins on {item}`)
        return true, "Purchase successful"
    else
        return false, "Transaction failed"
    end
end
```
```

--------------------------------

### Settings Management Example

Source: https://playerstate.netlify.app/api/client

Demonstrates how to manage application settings using PlayerState, including applying initial settings and listening for changes to update game systems like sound and music.

```APIDOC
## Settings Management Example

### Description
Manages application settings by retrieving them from PlayerState and applying them to game systems. It also sets up listeners to react to changes in settings.

### Method
N/A (Module/Function implementation)

### Endpoint
N/A (Client-side module)

### Parameters
None (Internal to the module)

### Request Body
None

### Request Example
lua
-- Settings UI manager with caching
local SettingsManager = {}

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

function SettingsManager.init()
    -- Apply initial settings (automatically waits for data)
    local musicEnabled = PlayerState.GetPath("Settings.MusicEnabled")
    local soundEnabled = PlayerState.GetPath("Settings.SoundEnabled")

    SoundService.AmbientReverb = musicEnabled and Enum.ReverbType.City or Enum.ReverbType.NoReverb
    SoundService.Volume = soundEnabled and 1 or 0

    -- Listen for changes
    PlayerState.OnChanged("Settings.MusicEnabled", function(enabled)
        SoundService.AmbientReverb = enabled and Enum.ReverbType.City or Enum.ReverbType.NoReverb
    end)

    PlayerState.OnChanged("Settings.SoundEnabled", function(enabled)
        SoundService.Volume = enabled and 1 or 0
    end)
end

return SettingsManager

```

--------------------------------

### Path Example: ReplicatedStorage.Modules.PlayerState

Source: https://playerstate.netlify.app/installation

Adjust require paths for server and client modules if PlayerState is located at ReplicatedStorage.Modules.PlayerState.

```lua
-- Server module requires:
local DefaultData = require(game.ReplicatedStorage.Modules.PlayerState.DefaultData)

-- Client module requires:  
local DefaultData = require(script.Parent.DefaultData)
```

--------------------------------

### BatchOperation Example

Source: https://playerstate.netlify.app/api/types

Shows how to construct an array of BatchOperation objects for updating multiple player data values simultaneously. This is efficient for multiple changes.

```lua
local operations: {BatchOperation} = {
    {path = "Coins", value = 1000},
    {path = "Level", value = 5},
    {path = "Plot.Likes", value = 50},
    {path = "Settings.MusicEnabled", value = true}
}
```

--------------------------------

### Environment-Specific Setup

Source: https://playerstate.netlify.app/setup

Configure DataStore names and scopes based on the game's PlaceId for development or production environments. Adjust batching and caching delays for faster testing.

```lua
-- PlayerStateConfig.lua
local Config = {
    Server = {
        DataStore = {
            -- Use different DataStore names for different environments
            Name = game.PlaceId == 123456789 and "PlayerData_DEV" or "PlayerData_PROD",
            Scope = game.PlaceId == 123456789 and "Testing" or "Production",
        },

        -- Development: Faster batching for testing
        BatchDelay = game.PlaceId == 123456789 and 0.01 or 0.03,
        BatchSize = game.PlaceId == 123456789 and 5 or 20,
    },

    Client = {
        -- Development: Shorter cache for faster testing
        CacheDuration = game.PlaceId == 123456789 and 0.05 or 0.1,
    },
}
```

--------------------------------

### Configure Leaderboard Server Settings

Source: https://playerstate.netlify.app/api/server

Example configuration for enabling and setting up the leaderboard system on the server. This includes specifying data store names, tracked statistics, sync intervals, and update behavior.

```lua
Server = {
    Leaderboard = {
        Enabled = true,
        DataStoreName = "PlayerState_Leaderboards",
        TrackedStats = {"Coins", "Level", "HighScore"},
        SyncInterval = 60,
        UpdateOnPlayerLeave = true,
    },
}
```

--------------------------------

### Path Example: ReplicatedStorage.Shared

Source: https://playerstate.netlify.app/installation

Update require paths for both server and client modules when PlayerState is organized under ReplicatedStorage.Shared.

```lua
-- Server module requires:
local DefaultData = require(game.ReplicatedStorage.Shared.DefaultData)

-- Client module requires:
local DefaultData = require(game.ReplicatedStorage.Shared.DefaultData)
```

--------------------------------

### LeaderboardEntry and Array Examples

Source: https://playerstate.netlify.app/api/types

Shows the structure of a single LeaderboardEntry and how to represent an array of leaderboard entries. Useful for displaying leaderboard rankings.

```lua
local leaderboardEntry: LeaderboardEntry = {
    userId = 123456789,
    score = 1500,
    rank = 1
}

-- Leaderboard array
local leaderboard: {LeaderboardEntry} = {
    {userId = 123456789, score = 1500, rank = 1},
    {userId = 987654321, score = 1200, rank = 2},
    {userId = 555666777, score = 1000, rank = 3}
}
```

--------------------------------

### Initialize Player Data with PlayerState

Source: https://playerstate.netlify.app/setup

Essential server-side setup to initialize PlayerState data for each player upon joining. This is critical for the module to function correctly.

```lua
-- ServerScriptService.PlayerManager
local Players = game:GetService("Players")
local PlayerState = require(game.ReplicatedStorage.Libraries.PlayerState.PlayerStateServer)

-- ⚠️ CRITICAL: You MUST have this PlayerAdded connection!
Players.PlayerAdded:Connect(function(player)
    local success = PlayerState.Init(player) -- ← ESSENTIAL - Don't skip this!

    if success then
        print(`[PlayerState] Successfully initialized data for {player.Name}`)

        -- Optional: Set default values for new players
        local coins = PlayerState.Get(player, "Coins")
        if coins == 0 then -- New player
            PlayerState.Set(player, "Coins", 100) -- Starting coins
            PlayerState.SetPath(player, "Settings.MusicEnabled", true)
        end
    else
        warn(`[PlayerState] Failed to initialize data for {player.Name}`)
        -- Player will be automatically kicked
    end
end)

```

--------------------------------

### Comprehensive Leaderboard System Setup

Source: https://playerstate.netlify.app/api/server

Sets up a comprehensive leaderboard system, including fetching top players by score, retrieving a player's rank, and manually updating leaderboard entries. Ensure PlayerStateConfig.Server.Leaderboard is configured.

```lua
-- Server: Comprehensive leaderboard system with validation
local function setupLeaderboardSystem()
    -- Configuration reminder
    -- Make sure PlayerStateConfig.Server.Leaderboard is properly configured!

    -- ✅ Get top 10 players for coins (works if configured)
    local topCoins = PlayerState.GetLeaderboard("Coins", 10)
    if #topCoins > 0 then
        for rank, entry in ipairs(topCoins) do
            print(`#{rank}: User {entry.userId} - {entry.score} coins`)
        end
    else
        print("No coin leaderboard data available (check configuration)")
    end

    -- ✅ Get player's current rank (returns nil if not ranked)
    local playerRank = PlayerState.GetPlayerRank(player, "Coins")
    if playerRank then
        print(`You're currently ranked #{playerRank} for coins!`)
    else
        print("You're not yet ranked for coins")
    end

    -- ✅ Manual leaderboard update (for special cases)
    local success = PlayerState.UpdateLeaderboard(player, "HighScore", 2500)
    if success then
        print("High score leaderboard updated!")
    else
        print("Failed to update leaderboard (check configuration)")
    end
end
```

--------------------------------

### Get() and GetPath() - Retrieve Player Data

Source: https://playerstate.netlify.app/api/client

Fetches player data from the PlayerState. `Get()` retrieves a value by key, while `GetPath()` allows retrieval using a dot-separated path for nested data.

```APIDOC
## Get(key) / GetPath(path)

### Description
Retrieves player data from the PlayerState.

### Method
N/A (Function call)

### Endpoint
N/A (Client-side function)

### Parameters
#### Path Parameters
- **key** (string) - Required - The key of the data to retrieve (for `Get`).
- **path** (string) - Required - The dot-separated path to the data to retrieve (for `GetPath`).

### Request Body
None

### Request Example
lua
-- Using Get
local coins = PlayerState.Get("Coins")

-- Using GetPath
local musicEnabled = PlayerState.GetPath("Settings.MusicEnabled")

```

--------------------------------

### Example DefaultData Structure

Source: https://playerstate.netlify.app/api/types

Illustrates a typical structure for DefaultData, including player stats, inventory, settings, and leaderstats configuration. This serves as a blueprint for PlayerData.

```lua
{
    Coins = 0,
    Level = 1,
    Experience = 0,
    Inventory = {},
    Settings = {
        MusicEnabled = true,
        SoundEnabled = true,
    },
    Plot = {
        Likes = 0,
        Size = 1,
        Buildings = {},
    },
    Stats = {
        TotalPlayTime = 0,
        GamesPlayed = 0,
        HighScore = 0,
    },
    Achievements = {},

    -- NEW: Leaderstats configuration
    leaderstats = {
        ["💰 Coins"] = "Coins",
        ["⭐ Level"] = "Level",
        ["👍 Likes"] = "Plot.Likes"
    }
}
```

--------------------------------

### Development Setup Configuration

Source: https://playerstate.netlify.app/setup

Configure PlayerState for a development environment with specific DataStore settings for testing and faster iteration. Includes development-friendly batching, timeouts, and leaderboard sync intervals.

```lua
-- PlayerStateConfig.lua - Development environment
local Config = {
    Server = {
        Profile = {
            Key = "PlayerData_DEV",
        },
        DataStore = {
            Name = "PlayerData_DEV",
            Scope = "Testing",
        },

        -- Development-friendly settings
        BatchDelay = 0.01,
        BatchSize = 5,
        DataWaitTimeout = 5,

        Leaderboard = {
            Enabled = true,
            DataStoreName = "PlayerState_Leaderboards_DEV",
            TrackedStats = {"Coins", "Level", "HighScore"},
            SyncInterval = 30,
            UpdateOnPlayerLeave = true,
        },
    },

    Client = {
        -- Development settings for faster iteration
        CacheDuration = 0.05,
        CacheCleanupInterval = 10,
        MaxCacheSize = 500,
        MaxPathCacheSize = 500,
    },
}
```

--------------------------------

### Initialize PlayerState on Server

Source: https://playerstate.netlify.app/

Essential server-side setup for PlayerState. Ensure this connection is present for PlayerState to function correctly. Initializes the player's data management.

```lua
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)
```

--------------------------------

### Basic Coin Management Functions

Source: https://playerstate.netlify.app/examples

Provides basic functions for getting, adding, and spending coins. Assumes PlayerState library is available.

```lua
-- ServerStorage.CurrencyService
local CurrencyService = {}
local PlayerState = require(game.ReplicatedStorage.Libraries.PlayerState.PlayerStateServer)

function CurrencyService.GetCoins(player: Player): number
    return PlayerState.Get(player, "Coins") or 0
end

function CurrencyService.AddCoins(player: Player, amount: number): boolean
    if amount <= 0 then return false end
    
    local currentCoins = CurrencyService.GetCoins(player)
    PlayerState.Set(player, "Coins", currentCoins + amount)
    return true
end

function CurrencyService.SpendCoins(player: Player, amount: number): boolean
    local currentCoins = CurrencyService.GetCoins(player)
    if currentCoins < amount then
        return false
    end
    
    PlayerState.Set(player, "Coins", currentCoins - amount)
    return true
end

return CurrencyService
```

--------------------------------

### BatchUpdateOperation Example

Source: https://playerstate.netlify.app/api/types

Demonstrates creating an array of BatchUpdateOperation objects for incrementing or decrementing player data. The `amount` is optional and defaults to 1.

```lua
local operations: {BatchUpdateOperation} = {
    {path = "Coins", operation = "Increment", amount = 100},
    {path = "Lives", operation = "Decrement"},
    {path = "Plot.Likes", operation = "Increment", amount = 5}
}
```

--------------------------------

### Common Legacy Data Migration Key Setups

Source: https://playerstate.netlify.app/migration

Configure the `keys` array to specify how PlayerState should look up legacy data. Use `{UserId}` for the most common case, or include prefixed key formats like `PlayerData_{UserId}` if your old system used them.

```lua
-- Most common:
keys = { "{UserId}" }

-- If old system prefixed keys:
keys = { "{UserId}", "PlayerData_{UserId}" }
```

--------------------------------

### Initialize and Perform Basic PlayerState Operations

Source: https://playerstate.netlify.app/api

Initialize player state and perform basic set and get operations. Supports batch operations for efficiency.

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

-- 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})
```

--------------------------------

### Memory-Optimized Setup

Source: https://playerstate.netlify.app/setup

Configure settings for memory-conscious environments by reducing batching and batch sizes, limiting cache size, and enabling data cleanup. Client-side settings prioritize a minimal memory footprint with short cache durations and frequent cleanup.

```lua
-- PlayerStateConfig.lua
local Config = {
    Server = {
        -- Conservative memory usage
        BatchDelay = 0.05,
        BatchSize = 10,
        MaxCacheSize = 500,
        CleanExtraFields = true,
    },

    Client = {
        -- Minimal memory footprint
        CacheDuration = 0.05,
        CacheCleanupInterval = 15,
        MaxCacheSize = 250,
        MaxPathCacheSize = 250,
    },
}
```

--------------------------------

### Conditional Server Configuration in Lua

Source: https://playerstate.netlify.app/setup

This example demonstrates how to conditionally configure DataStore settings like BatchDelay, BatchSize, and MaxCacheSize based on the server's region or player count. Adjust these values to balance performance and resource usage.

```lua
local Config = {
    Server = {
        DataStore = {
            Name = "PlayerData_" .. (game.JobId:sub(1,8) or "default"),
            Scope = game.PrivateServerId and "Private" or "Production",
        },

        -- Adjust performance based on server load
        BatchDelay = game.Players.MaxPlayers > 20 and 0.05 or 0.03,
        BatchSize = game.Players.MaxPlayers > 20 and 30 or 20,
        MaxCacheSize = game.Players.MaxPlayers > 20 and 1500 or 1000,
    },
}
```

--------------------------------

### Example of Using OnChanged with ChangeInfo

Source: https://playerstate.netlify.app/api/types

Demonstrates how to use the OnChanged listener with enhanced change information to handle specific actions like TableInsert or TableRemove, or fall back to simple path information.

```lua
local connection = PlayerState.OnChanged("Inventory", function(newValue, oldValue, info) 
    if info and typeof(info) == "table" and info.action then
        -- Enhanced change info
        if info.action == "TableInsert" then
            print(`Item added at index {info.index}`)
        elseif info.action == "TableRemove" then
            print(`Item removed from index {info.index}`)
        end
    else
        -- Simple path info
        print("Inventory changed")
    end
end)
```

--------------------------------

### Client: Read and Listen to Session Data Changes

Source: https://playerstate.netlify.app/session-data

Clients can read session data using GetPath and listen for changes using OnChanged. This example shows reading the sprint state and printing updates.

```lua
-- LocalScript
local PlayerState = require(game.ReplicatedStorage.Libraries.PlayerState.PlayerStateClient)

local sprinting = PlayerState.GetPath("session.isSprinting")
print("Is sprinting:", sprinting)

PlayerState.OnChanged("session.isSprinting", function(newValue, oldValue)
    print("Sprinting changed:", oldValue, "->", newValue)
end)

```

--------------------------------

### Setup Player State Event Handlers

Source: https://playerstate.netlify.app/api/server

Configures event listeners for player data lifecycle events. Use SetPath for nested updates and Set for direct value changes. Handles daily rewards and playtime calculations.

```lua
-- Setup event handlers for comprehensive data management
local function setupPlayerStateEvents()
    -- When player data loads
    PlayerState.ProfileLoaded:Connect(function(player, data)
        -- Welcome back message
        local loginCount = (data.Stats.Logins or 0) + 1
        PlayerState.SetPath(player, "Stats.Logins", loginCount)
        PlayerState.Set(player, "LastJoinTime", os.time())

        -- Check for daily rewards
        local lastReward = data.Stats.LastDailyReward or 0
        local currentDay = math.floor(os.time() / 86400) -- Days since epoch

        if currentDay > lastReward then
            PlayerState.SetPath(player, "Stats.LastDailyReward", currentDay)
            PlayerState.Increment(player, "Coins", 100)
            print(` {player.Name} received daily reward! `)
        end

        -- Initialize player systems
        setupPlayerUI(player)
        setupPlayerEffects(player)
    end)

    -- Before data saves
    PlayerState.BeforeSave:Connect(function(player, data)
        -- Final cleanup and validation
        data.LastSaveTime = os.time()

        -- Calculate session playtime
        local joinTime = data.LastJoinTime or os.time()
        local sessionTime = os.time() - joinTime
        local totalPlayTime = (data.Stats.TotalPlayTime or 0) + sessionTime

        PlayerState.SetPath(player, "Stats.TotalPlayTime", totalPlayTime)
        PlayerState.SetPath(player, "Stats.LastSessionTime", sessionTime)

        -- Validate data integrity
        if data.Coins and data.Coins < 0 then
            warn(` {player.Name} had negative coins, resetting to 0 `)
            PlayerState.Set(player, "Coins", 0)
        end

        print(`Saving {player.Name}'s data - Session: {sessionTime}s, Total: {totalPlayTime}s`)
    end)

    -- When profile unloads
    PlayerState.ProfileUnloaded:Connect(function(player, data)
        -- Analytics and external system updates
        local finalStats = {
            userId = player.UserId,
            coins = data.Coins or 0,
            level = data.Level or 1,
            totalPlayTime = data.Stats.TotalPlayTime or 0,
            logins = data.Stats.Logins or 0
        }

        -- Send to analytics (direct data access only)
        sendToAnalytics(finalStats)

        -- Cleanup player-specific systems
        cleanupPlayerUI(player)
        cleanupPlayerEffects(player)

        print(` {player.Name} profile unloaded - Final coins: {finalStats.coins} `)
    end)
end

-- Call this during server startup
setupPlayerStateEvents()
```

--------------------------------

### Client Type Safety: Setup Coin Display Listener

Source: https://playerstate.netlify.app/api/types

Sets up a type-safe listener for changes to the 'Coins' value. Updates a UI label and can trigger visual effects for coin gains. Requires PlayerStateClient module.

```lua
local function setupCoinDisplay(label: TextLabel): ReplicaConnection?
    return PlayerState.OnChanged("Coins", function(newValue: any, oldValue: any, info: ChangeInfo | {string}?)
        local coins: number = newValue or 0
        label.Text = tostring(coins)

        -- Handle enhanced change info
        if info and typeof(info) == "table" and info.action then
            if oldValue and coins > oldValue then
                showCoinGainEffect(coins - oldValue)
            end
        end
    end)
```

--------------------------------

### Configure Custom Fetcher Source

Source: https://playerstate.netlify.app/migration

Configure a custom fetcher for the legacy data store when data needs to be retrieved from a specific or custom source. This example demonstrates fetching from a 'CustomLegacyStore' with a custom function.

```lua
LegacyDataStore = {
    enabled = true,
    store = "LegacyStore",
    strategy = "Overwrite",
    keys = { "{UserId}" },
    advanced = {
        fetch = {
            custom = function(keyCandidates, userId, player)
                local DataStoreService = game:GetService("DataStoreService")
                local store = DataStoreService:GetDataStore("CustomLegacyStore", "v1")
                for _, key in keyCandidates do
                    local ok, data = pcall(function() 
                        return store:GetAsync(key)
                    end)
                    if ok and data then
                        return data, key
                    end
                end
                return nil, nil
            end,
        },
    },
}
```

--------------------------------

### TrackedStats Configuration Examples

Source: https://playerstate.netlify.app/setup

Define which player data fields to track on leaderboards. Supports top-level and nested statistics using dot notation. Only numeric values can be tracked.

```lua
TrackedStats = {
    -- Top-level stats
    "Coins",           -- Tracks player.Coins
    "Level",           -- Tracks player.Level
    "HighScore",       -- Tracks player.HighScore

    -- Nested stats (using dot notation)
    "Plot.Likes",      -- Tracks player.Plot.Likes
    "Stats.TotalPlayTime",  -- Tracks player.Stats.TotalPlayTime
    "Inventory.Count", -- Tracks player.Inventory.Count

    -- Any numeric data path
    "Achievements.Total",    -- Custom achievement tracking
}
```

--------------------------------

### Consistent Naming Conventions for Lua Functions

Source: https://playerstate.netlify.app/best-practices

Demonstrates consistent naming patterns for functions, using prefixes like 'get', 'set', and 'add' followed by the noun being acted upon, and service-specific function calls.

```lua
-- ✅ Use consistent naming patterns
local function getPlayerCoins(player) end      -- get + noun
local function setPlayerCoins(player, amount) end  -- set + noun
local function addPlayerCoins(player, amount) end  -- add + noun

-- Service functions
CurrencyService.GetCoins()
CurrencyService.AddCoins()
CurrencyService.SpendCoins()
```

--------------------------------

### Client Type Safety: Setup Global Listener

Source: https://playerstate.netlify.app/api/types

Establishes a type-safe listener for any changes across all player data. Logs actions like table insertions or removals with detailed path information. Requires PlayerStateClient module.

```lua
local function setupGlobalListener(): ReplicaConnection?
    return PlayerState.OnChanged(".", function(newValue: any, oldValue: any, info: ChangeInfo | {string}?)
        if info and typeof(info) == "table" and info.action then
            local changeInfo = info :: ChangeInfo
            local pathString = table.concat(changeInfo.path, ".")

            if changeInfo.action == "TableInsert" then
                print(`Item added to {pathString} at index {changeInfo.index}`)
            elseif changeInfo.action == "TableRemove" then
                print(`Item removed from {pathString} at index {changeInfo.index}`)
            end
        end
    end)
```

--------------------------------

### High-Traffic Game Setup

Source: https://playerstate.netlify.app/setup

Optimize for games with many concurrent players by using faster batching, larger batch sizes, and increased caching. Configure leaderboards for high traffic with longer sync intervals to reduce DataStore load.

```lua
-- PlayerStateConfig.lua - For games with many concurrent players
local Config = {
    Server = {
        -- Optimize for high traffic
        BatchDelay = 0.02,
        BatchSize = 50,
        MaxCacheSize = 2000,
        DataWaitTimeout = 15,

        Leaderboard = {
            Enabled = true,
            DataStoreName = "PlayerState_Leaderboards",
            TrackedStats = {"Coins", "Level", "HighScore"},
            SyncInterval = 120,
            UpdateOnPlayerLeave = true,
        },
    },

    Client = {
        -- Balanced caching for high traffic
        CacheDuration = 0.2,
        CacheCleanupInterval = 60,
        MaxCacheSize = 2000,
        MaxPathCacheSize = 2000,
    },
}
```

--------------------------------

### Safe Client-side Data Access

Source: https://playerstate.netlify.app/setup

Ensure safe data access on the client by providing fallback values for potentially missing data. This example demonstrates safely getting player coins, returning 0 if the value is not found.

```lua
-- Safe data access
local function getPlayerCoins()
    local coins = PlayerState.Get("Coins")
    return coins or 0 -- Fallback value
end
```

--------------------------------

### Get PlayerState Replica Instance

Source: https://playerstate.netlify.app/api/server

Gets the raw Replica instance for advanced operations. Enhanced validation ensures the replica is active.

```lua
local replica = PlayerState.GetReplica(player)
if replica then
    -- Advanced Replica operations
    replica:OnChange(function(action, path, ...)
        print(`Data changed: {action} at {table.concat(path, ".")}`)
    end)

    -- Check replica status
    print("Replica is active:", replica:IsActive())
end
```

--------------------------------

### PlayerState Basic Data Functions API

Source: https://playerstate.netlify.app/api/server

API for setting and getting top-level data values for a player.

```APIDOC
## Set()

### Description
Sets a top-level data value with enhanced validation. Use `SetPath()` for nested paths.

### Method
`Set(player, key, value) → boolean`

### Parameters
#### Path Parameters
- **player** (Player) - Required - The player whose data to set.
- **key** (string) - Required - The key of the data to set.
- **value** (any) - Required - The value to set.

### Response
#### Success Response (boolean)
- **Success status** (boolean) - Returns true if the value was set successfully, false if a leaderstats modification was attempted.

### Request Example
lua
local success = PlayerState.Set(player, "Coins", 1000)
if success then
    print("Coins updated successfully")
else
    warn("Failed to update coins")
end
```

```APIDOC
## Get()

### Description
Gets a top-level data value with validation. Automatically clones tables if `AutoCloneTables` is enabled.

### Method
`Get(player, key) → any`

### Parameters
#### Path Parameters
- **player** (Player) - Required - The player whose data to retrieve.
- **key** (string) - Required - The key of the data to retrieve.

### Response
#### Success Response (any)
- **The value** (any) - The retrieved value, or `nil` if not found. Tables are cloned if `AutoCloneTables` is enabled.

### Request Example
lua
local coins = PlayerState.Get(player, "Coins")
local level = PlayerState.Get(player, "Level")
print(`Player {player.Name} has {coins or 0} coins and is level {level or 1}`)

-- With AutoCloneTables enabled, tables are automatically cloned
local inventory = PlayerState.Get(player, "Inventory") -- Safe to modify
table.insert(inventory, newItem) -- Won't affect original if AutoCloneTables is true
```

--------------------------------

### Get All Player Data

Source: https://playerstate.netlify.app/api/server

Retrieves all player data with validation. Returns a reference to the actual data, so be careful with modifications.

```lua
local allData = PlayerState.GetAll(player)
if allData then
    print("Player has", allData.Coins, "coins")
    -- Safely iterate through data
    for key, value in pairs(allData) do
        print(`{key}: {value}`)
    end
end
```

--------------------------------

### PlayerState Path-based Functions API

Source: https://playerstate.netlify.app/api/server

API for setting and getting nested data values using dot notation.

```APIDOC
## SetPath()

### Description
Sets a nested data value using dot notation with enhanced validation.

### Method
`SetPath(player, path, value) → boolean`

### Parameters
#### Path Parameters
- **player** (Player) - Required - The player whose data to set.
- **path** (ValuePath) - Required - The dot-separated path to the nested value.
- **value** (any) - Required - The value to set.

### Response
#### Success Response (boolean)
- **Success status** (boolean) - Returns true if the value was set successfully.

### Request Example
lua
local success = PlayerState.SetPath(player, "Plot.Likes", 50)
if success then
    print("Plot likes updated")
end

PlayerState.SetPath(player, "Settings.MusicEnabled", false)
PlayerState.SetPath(player, "Stats.HighScore", 1200)
```

```APIDOC
## GetPath()

### Description
Gets a nested data value using dot notation with optimized performance. Automatically clones tables if `AutoCloneTables` is enabled.

### Method
`GetPath(player, path) → any`

### Parameters
#### Path Parameters
- **player** (Player) - Required - The player whose data to retrieve.
- **path** (ValuePath) - Required - The dot-separated path to the nested value.

### Response
#### Success Response (any)
- **The value** (any) - The retrieved value, or `nil` if not found. Tables are cloned if `AutoCloneTables` is enabled.

### Request Example
lua
local likes = PlayerState.GetPath(player, "Plot.Likes")
local musicEnabled = PlayerState.GetPath(player, "Settings.MusicEnabled")
local highScore = PlayerState.GetPath(player, "Stats.HighScore")

-- With AutoCloneTables enabled, tables are automatically cloned
local settings = PlayerState.GetPath(player, "Settings") -- Safe to modify
settings.NewOption = true -- Won't affect original if AutoCloneTables is true
```

--------------------------------

### GetPlayerRank()

Source: https://playerstate.netlify.app/api/server

Gets a player's current rank on a specific leaderboard. Returns nil if the player is not ranked or if there are configuration issues.

```APIDOC
## GetPlayerRank()

### Description
Gets a player's current rank on a specific leaderboard statistic.

### Method
N/A (This appears to be a function call within a script, not a direct HTTP API endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **player** (Player) - Required - The player object for whom to get the rank.
- **statName** (string) - Required - The name of the statistic to retrieve the rank for (e.g., "Coins", "Level").

### Returns
- **number?** - The player's rank (1-based). Returns `nil` if the player is not ranked, the player is invalid, or if there are configuration issues.

### Request Example
```lua
-- Get player's coin rank
local coinRank = PlayerState.GetPlayerRank(player, "Coins")
if coinRank then
    print(string.format("You're ranked #%d for coins!", coinRank))
else
    print("You're not yet ranked for coins")
end

-- Check multiple ranks
local levelRank = PlayerState.GetPlayerRank(player, "Level")
local scoreRank = PlayerState.GetPlayerRank(player, "HighScore")

if levelRank and scoreRank then
    print(string.format("Level Rank: #%d, Score Rank: #%d", levelRank, scoreRank))
end
```

### Response
#### Success Response (200)
N/A (Function returns a number or nil)

#### Response Example
```json
5
```
```

--------------------------------

### Basic Leaderboard Configuration

Source: https://playerstate.netlify.app/setup

Configure essential leaderboard settings such as enabling leaderboards, setting the DataStore name, defining tracked statistics, and specifying the sync interval.

```lua
-- PlayerStateConfig.lua
local Config = {
    Server = {
        Leaderboard = {
            Enabled = true,                    -- Required: Enable leaderboards
            DataStoreName = "PlayerState_Leaderboards", -- DataStore for leaderboard data
            TrackedStats = {                   -- Required: Stats to track
                "Coins",                       -- Track coin count
                "Level",                       -- Track player level
                "HighScore",                   -- Track high scores
                "Plot.Likes",                  -- Track plot likes (nested path)
                "Stats.TotalPlayTime",         -- Track total playtime
            },
            SyncInterval = 60,                -- How often to sync (seconds)
            UpdateOnPlayerLeave = true,       -- Update when player leaves
        },
    },
}
```

--------------------------------

### Initialize Inventory UI and Handle Changes

Source: https://playerstate.netlify.app/api/client

Initializes the inventory UI and sets up listeners for inventory changes, triggering UI updates and visual effects for added or removed items.

```lua
-- Inventory UI manager with enhanced change detection
local InventoryUI = {}

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

-- UI elements
local inventoryFrame = gui.InventoryFrame
local itemTemplate = inventoryFrame.ItemTemplate

function InventoryUI.updateDisplay()
    -- Clear existing items
    for _, child in pairs(inventoryFrame:GetChildren()) do
        if child ~= itemTemplate and child:IsA("Frame") then
            child:Destroy()
        end
    end

    -- Get inventory data
    local inventory = PlayerState.GetPath("Inventory") or {}

    -- Create UI elements for each item
    for index, item in ipairs(inventory) do
        local itemFrame = itemTemplate:Clone()
        itemFrame.Name = "Item" .. index
        itemFrame.Visible = true
        itemFrame.Parent = inventoryFrame

        -- Update item display
        itemFrame.ItemName.Text = item.Name or "Unknown"
        itemFrame.Rarity.Text = item.Rarity or "Common"
        itemFrame.LayoutOrder = index
    end
end

function InventoryUI.init()
    -- Initial display (automatically waits for data)
    InventoryUI.updateDisplay()

    -- NEW: Enhanced inventory change listener
    PlayerState.OnChanged("Inventory", function(newValue, oldValue, info)
        InventoryUI.updateDisplay()

        -- Handle specific actions
        if info and info.action == "TableInsert" then
            showItemAddedEffect(info.index)
        elseif info and info.action == "TableRemove" then
            showItemRemovedEffect(info.index)
        end
    end)
end

return InventoryUI

```

--------------------------------

### IsReady()

Source: https://playerstate.netlify.app/api/client

Checks if player data is ready and the replica is active.

```APIDOC
## GET /api/status/ready

### Description
Checks if player data is ready and replica is active.

### Method
GET

### Endpoint
/api/status/ready

### Parameters
None

### Response
#### Success Response (200)
- **ready** (boolean) - True if data is ready, false otherwise.

### Request Example
```lua
if PlayerState.IsReady() then
    local coins = PlayerState.Get("Coins")
    print("Player has", coins, "coins")
else
    print("Data not ready yet...")
end
```

### Response Example
```json
{ "ready": true }
```

### Notes
Optional check - data access functions already wait automatically.
```

--------------------------------

### Dictionary Operation Functions

Source: https://playerstate.netlify.app/api/server

Functions for manipulating dictionary (table) data within the player state, including setting, getting, and removing key-value pairs.

```APIDOC
## SetInDict()

### Description
Sets a value in a dictionary/table with efficient nested path updates and automatic dictionary creation.

### Method
N/A (Function Call)

### Parameters
- **player** (Player) - Required - The player object.
- **dictPath** (DictPath) - Required - The path to the dictionary.
- **key** (string) - Required - The key to set within the dictionary.
- **value** (any) - Required - The value to set for the key.

### Returns
- **boolean** - Success status

### Request Example
```lua
-- Set building data (creates dictionary if needed)
local success = PlayerState.SetInDict(player, "Plot.Buildings", "House", {
    Level = 2,
    Material = "Wood",
    Position = Vector3.new(10, 0, 10)
})

-- Set game setting
PlayerState.SetInDict(player, "Settings", "GraphicsQuality", "High")

-- Set player stat
PlayerState.SetInDict(player, "Stats", "BestTime", 120.5)
```

### Note
Efficient nested path updates with automatic dictionary creation and race condition prevention.
```

```APIDOC
## GetFromDict()

### Description
Gets a value from a dictionary using a key with automatic type conversion. Automatically clones tables when `AutoCloneTables` is enabled in configuration.

### Method
N/A (Function Call)

### Parameters
- **player** (Player) - Required - The player object.
- **dictPath** (DictPath) - Required - The path to the dictionary.
- **key** (string | number) - Required - The key to retrieve the value from.

### Returns
- **any** - The value, or `nil` if not found. Tables are cloned if `AutoCloneTables` is enabled.

### Request Example
```lua
-- Get building data
local houseData = PlayerState.GetFromDict(player, "Plot.Buildings", "House")
if houseData then
    print("House level:", houseData.Level)
    print("House material:", houseData.Material)
end

-- Get with numeric key (automatically converted to string)
local item = PlayerState.GetFromDict(player, "Inventory.Equipped", 1)

-- Get setting
local quality = PlayerState.GetFromDict(player, "Settings", "GraphicsQuality")
print("Graphics quality:", quality or "Default")
```

### Note
- Automatically converts number keys to strings for consistency
- When `AutoCloneTables` is enabled in config, table values are automatically deep cloned
- Prevents accidental modification of internal data structures
```

```APIDOC
## RemoveFromDict()

### Description
Removes a key from a dictionary using efficient nested path updates.

### Method
N/A (Function Call)

### Parameters
- **player** (Player) - Required - The player object.
- **dictPath** (DictPath) - Required - The path to the dictionary.
- **key** (string) - Required - The key to remove from the dictionary.

### Returns
- **boolean** - Success status

### Request Example
```lua
-- Remove building
local success = PlayerState.RemoveFromDict(player, "Plot.Buildings", "OldHouse")
if success then
    print("Building removed")
end

-- Remove obsolete setting
PlayerState.RemoveFromDict(player, "Settings", "ObsoleteOption")
```

### Note
Efficient nested path removal with race condition prevention and minimal network traffic.
```

--------------------------------

### Get Raw Replica Instance

Source: https://playerstate.netlify.app/api/client

Access the raw Replica instance for advanced operations. Provides access to the underlying Replica object with enhanced validation.

```lua
local replica = PlayerState.GetReplica()
if replica then
    -- Access raw Replica API
    print("Replica data:", replica.Data)
    print("Replica tags:", replica.Tags)

    -- Advanced change listener
    replica:OnChange(function(action, path, param1, param2)
        print("Raw change:", action, table.concat(path, "."))
    end)
end
```

--------------------------------

### Minimal Legacy Data Migration Configuration

Source: https://playerstate.netlify.app/migration

This is the recommended minimal configuration for enabling legacy data migration. Ensure `enabled` is true, `store` points to your old DataStore, and `keys` includes `{UserId}`.

```lua
LegacyDataStore = {
    enabled = true,
    store = "OldStore",
    strategy = "Auto",
    keys = { "{UserId}" },
}
```
Tokens:
Raw