SetValues()

SetValues(player, values) → boolean

Sets multiple top-level values at once with leaderstats protection.

Parameters: player: Player, values: {[string]: any}
Returns: boolean - Success status

Example

local success = PlayerState.SetValues(player, {
    Coins = 1000,
    Level = 5,
    Experience = 750
})

if success then
    print("Batch update successful")
end

Note

Returns success status and prevents leaderstats modification in batch

Performance

Use SetValues() instead of multiple Set() calls for better performance!

---

BatchSetValues()

BatchSetValues(player, operations) → boolean

Queues multiple path-based operations for optimized batch processing.

Parameters: player: Player, operations: {BatchOperation}
Returns: boolean - Success status

Basic Batch

local success = PlayerState.BatchSetValues(player, {
    {path = "Coins", value = 1000},
    {path = "Level", value = 5},
    {path = "Plot.Likes", value = 50}
})

Complex Batch

local operations = {
    {path = "Coins", value = 2000},
    {path = "Experience", value = 500},
    {path = "Plot.Likes", value = 100},
    {path = "Settings.MusicEnabled", value = true},
    {path = "Stats.GamesPlayed", value = 25}
}

PlayerState.BatchSetValues(player, operations)

Notes:

• High-performance batch processing system with automatic optimization
• Configurable batch delay and size limits with auto-flush
• Prevents leaderstats modification

Batch Performance

• Operations are grouped by path structure for optimal performance
• Root-level operations are batched together
• Nested operations are intelligently grouped
• Auto-flush occurs at 20 operations or 0.03s delay

---

BatchUpdateValues

BatchUpdateValues(player, operations) → boolean

Applies multiple increment/decrement operations at path-based locations in a single batch. Validates that each target value is numeric, then commits all updates via BatchSetValues().

Parameters: player: Player, operations: {BatchUpdateOperation}
Returns: boolean - Success status (false if validation fails or any path is non-numeric)

Each BatchUpdateOperation has:

• path: string - Dot-notation path to a numeric value
• operation: "Increment" | "Decrement"
• amount: number? - Optional; defaults to 1

Example

local success = PlayerState.BatchUpdateValues(player, {
    {path = "Coins", operation = "Increment", amount = 100},
    {path = "Plot.Likes", operation = "Increment", amount = 5},
    {path = "Lives", operation = "Decrement"},  -- amount defaults to 1
    {path = "Stats.GamesPlayed", operation = "Increment"}
})

if success then
    print("Batch update applied")
else
    warn("BatchUpdateValues failed (invalid player, missing replica, or non-numeric path)")
end

Numeric paths only

If any path points to a non-numeric value, the function warns and returns false; no changes are applied.

---

FlushBatch()

FlushBatch(player) → boolean

Immediately processes all queued batch operations for a player.

Parameters: player: Player
Returns: boolean - Success status

Example

-- Queue operations
PlayerState.BatchSetValues(player, {
    {path = "Coins", value = 1000},
    {path = "Level", value = 5}
})

-- Force immediate processing
PlayerState.FlushBatch(player)

Note

Manual batch processing control for critical operations