Numeric Operation Functions

Increment()

Increment(player, key, amount?) → boolean

Increments a numeric value with validation. Works with both top-level keys and nested paths.

Parameters: player: Player, key: string, amount: number? (defaults to 1)
Returns: boolean - Success status

Example

-- Increment top-level values
local success = PlayerState.Increment(player, "Coins", 100)
if success then
    print("Coins increased by 100")
end

-- Increment by 1 (default)
PlayerState.Increment(player, "Level")

-- Increment nested values using paths
PlayerState.Increment(player, "Plot.Likes", 5)
PlayerState.Increment(player, "Stats.HighScore", 250)
PlayerState.Increment(player, "Stats.GamesPlayed") -- defaults to +1

Note

Only works with numeric values - warns if value is not a number

Numeric Values Only

Increment() only works with numeric values. Attempting to increment a non-numeric value will return false and show a warning.

---

Decrement()

Decrement(player, key, amount?) → boolean

Decrements a numeric value with validation. Works with both top-level keys and nested paths.

Parameters: player: Player, key: string, amount: number? (defaults to 1)
Returns: boolean - Success status

Example

-- Spend coins (top-level)
local success = PlayerState.Decrement(player, "Coins", 50)
if success then
    print("Coins decreased by 50")
else
    warn("Failed to spend coins")
end

-- Decrement by 1 (default)
PlayerState.Decrement(player, "Lives")

-- Decrement nested values using paths
PlayerState.Decrement(player, "Plot.Health", 10)
PlayerState.Decrement(player, "Stats.Attempts", 1)

Note

Internally uses Increment() with negative amounts

Performance & Safety

Use Increment() and Decrement() for numeric operations instead of Get() + Set() patterns. They're safer and more efficient!

-- ❌ Less efficient and less safe
local coins = PlayerState.Get(player, "Coins")
PlayerState.Set(player, "Coins", coins + 100)

-- ✅ Better approach
PlayerState.Increment(player, "Coins", 100)

Dictionary Operations: SetInDict() and RemoveFromDict() now use efficient nested path updates to prevent race conditions and minimize network traffic.

Batch Operation Functions