Storage

Deletes a player-specific value from storage. Equivalent to: DeleteValue(player.user.id .. "/" .. key, callback) For global values or custom key formats, use DeleteValue instead.

Storage.DeletePlayerValue(player, "TempData")

Storage.DeletePlayerValue(player, "Progress", function(error)
    if error == StorageError.None then
        print("Player progress reset")
    end
end)

Deletes a player-specific value from storage. Equivalent to: DeleteValue(player.user.id .. "/" .. key, callback) For global values or custom key formats, use DeleteValue instead.

Storage.DeletePlayerValue(player, "TempData")

Storage.DeletePlayerValue(player, "Progress", function(error)
    if error == StorageError.None then
        print("Player progress reset")
    end
end)

Deletes a value from storage with the given key.

-- Delete without callback
Storage.DeleteValue("TemporaryData")

-- Delete with callback
Storage.DeleteValue("OldLeaderboard", function(error)
    if error == StorageError.None then
        print("Value deleted")
    end
end)

Deletes a value from storage with the given key.

-- Delete without callback
Storage.DeleteValue("TemporaryData")

-- Delete with callback
Storage.DeleteValue("OldLeaderboard", function(error)
    if error == StorageError.None then
        print("Value deleted")
    end
end)

Retrieves a player-specific value from storage. Equivalent to: GetValue(player.user.id .. "/" .. key, callback) For global values or custom key formats, use GetValue instead.

Storage.GetPlayerValue(player, "HighScore", function(value, error)
    if error == StorageError.None then
        print(player.name .. " high score: " .. tostring(value))
    end
end)

Retrieves a value from storage with the given key. The callback receives the value and error code. If the key doesn't exist, value is nil and error is StorageError.None.

Storage.GetValue("GlobalHighScore", function(value, error)
    if error == StorageError.None then
        print("High score: " .. tostring(value))
    else
        print("Error: " .. tostring(error))
    end
end)

Increments a player-specific numeric value by the specified amount. Equivalent to: IncrementValue(player.user.id .. "/" .. key, amount, callback) For global values or custom key formats, use IncrementValue instead.

-- Add points to player
Storage.IncrementPlayerValue(player, "Points", 10)

-- Add currency with callback
Storage.IncrementPlayerValue(player, "Coins", 50, function(error)
    if error == StorageError.None then
        print("Coins added")
    end
end)

Increments a player-specific numeric value by the specified amount. Equivalent to: IncrementValue(player.user.id .. "/" .. key, amount, callback) For global values or custom key formats, use IncrementValue instead.

-- Add points to player
Storage.IncrementPlayerValue(player, "Points", 10)

-- Add currency with callback
Storage.IncrementPlayerValue(player, "Coins", 50, function(error)
    if error == StorageError.None then
        print("Coins added")
    end
end)

Increments a numeric value by the specified amount. If the value doesn't exist, it will be set to the amount. Safe for concurrent access - use this instead of UpdateValue for simple number increments.

-- Increment global player count
Storage.IncrementValue("TotalPlayers", 1)

-- Decrement with callback
Storage.IncrementValue("AvailableSlots", -1, function(error)
    if error == StorageError.None then
        print("Slot taken")
    end
end)

Increments a numeric value by the specified amount. If the value doesn't exist, it will be set to the amount. Safe for concurrent access - use this instead of UpdateValue for simple number increments.

-- Increment global player count
Storage.IncrementValue("TotalPlayers", 1)

-- Decrement with callback
Storage.IncrementValue("AvailableSlots", -1, function(error)
    if error == StorageError.None then
        print("Slot taken")
    end
end)

Searches for player-specific values that start with the given key prefix. Equivalent to: SearchValue(player.user.id .. "/" .. key, limit, cursorId, callback) For global values or custom key formats, use SearchValue instead.

-- Search player's saved levels
Storage.SearchPlayerValue(player, "level_", 5, nil, function(values, cursorId, error)
    if error == StorageError.None then
        print("Found " .. #values .. " saved levels")
        for i, entry in ipairs(values) do
            print("Level: " .. tostring(entry))
        end
    end
end)

Searches for values that start with the given key prefix. Returns up to 'limit' most recent matching values.

Pagination: Pass nil for cursorId to get first results. Use returned cursorId for next page. If returned cursorId is nil, no more results exist.

Callback receives: array of values (tables with key-value pairs), cursorId, error

-- Search for all player scores
Storage.SearchValue("player_scores/", 10, nil, function(values, cursorId, error)
    if error == StorageError.None then
        for i, entry in ipairs(values) do
            print("Found: " .. tostring(entry))
        end
        
        -- Get next page if available
        if cursorId ~= nil then
            -- Call SearchValue again with cursorId for next page
        end
    end
end)

Sets a player-specific value in storage. Equivalent to: SetValue(player.user.id .. "/" .. key, value, callback) For global values or custom key formats, use SetValue instead.

Storage.SetPlayerValue(player, "Level", 5)

Storage.SetPlayerValue(player, "Inventory", { coins = 100, gems = 5 }, function(error)
    if error == StorageError.None then
        print("Player data saved")
    end
end)

Sets a player-specific value in storage. Equivalent to: SetValue(player.user.id .. "/" .. key, value, callback) For global values or custom key formats, use SetValue instead.

Storage.SetPlayerValue(player, "Level", 5)

Storage.SetPlayerValue(player, "Inventory", { coins = 100, gems = 5 }, function(error)
    if error == StorageError.None then
        print("Player data saved")
    end
end)

Sets a value in storage with the given key. Supported types: string, number, boolean, table, Vector3

CAUTION: For values that depend on previous values (e.g., leaderboards), use UpdateValue to prevent data loss. For incrementing/decrementing numbers, use IncrementValue instead.

-- Without callback
Storage.SetValue("GameMode", "TeamDeathmatch")

-- With callback
Storage.SetValue("ServerConfig", { maxPlayers = 10, friendlyFire = false }, function(error)
    if error == StorageError.None then
        print("Config saved successfully")
    end
end)

Sets a value in storage with the given key. Supported types: string, number, boolean, table, Vector3

CAUTION: For values that depend on previous values (e.g., leaderboards), use UpdateValue to prevent data loss. For incrementing/decrementing numbers, use IncrementValue instead.

-- Without callback
Storage.SetValue("GameMode", "TeamDeathmatch")

-- With callback
Storage.SetValue("ServerConfig", { maxPlayers = 10, friendlyFire = false }, function(error)
    if error == StorageError.None then
        print("Config saved successfully")
    end
end)

Safely updates a player-specific value based on its current state. Equivalent to: UpdateValue(player.user.id .. "/" .. key, modifier, callback) For global values or custom key formats, use UpdateValue instead.

Storage.UpdatePlayerValue(player, "Stats", function(currentStats)
    if currentStats == nil then
        return { kills = 1, deaths = 0 }
    else
        currentStats.kills = currentStats.kills + 1
        return currentStats
    end
end)

Safely updates a player-specific value based on its current state. Equivalent to: UpdateValue(player.user.id .. "/" .. key, modifier, callback) For global values or custom key formats, use UpdateValue instead.

Storage.UpdatePlayerValue(player, "Stats", function(currentStats)
    if currentStats == nil then
        return { kills = 1, deaths = 0 }
    else
        currentStats.kills = currentStats.kills + 1
        return currentStats
    end
end)

Safely updates a value based on its current state - prevents data loss from simultaneous updates.

Why use this instead of Get then Set:

• PROBLEM: If two players trigger updates at the same time, one update can be lost Example: Player A and B both try to add their score to leaderboard Player A reads 100, adds 50 = 150 Player B reads 100 (before A saves), adds 30 = 130 Result: Only 130 saved, Player A's 50 points lost!
• SOLUTION: UpdateValue ensures both updates apply correctly (result = 180)

How it works:

1. Retrieves current value (nil if doesn't exist)
2. Calls your modifier function with current value
3. Saves the value your modifier returns
4. If another update happened simultaneously, retries automatically with new current value

The modifier may be called multiple times if concurrent updates detected. Return nil from modifier to cancel the update (no change saved).

When to use:

• Leaderboards (adding new high scores)
• Counters (tracking total events)
• Lists (adding items to shared arrays)
• Any value that depends on its previous value

When NOT to use:

• Simple overwrites (use SetValue - it's faster)
• Number increments (use IncrementValue - it's optimized for this)

-- Update leaderboard with new high score
Storage.UpdateValue("GlobalHighScore", function(currentScore)
    local newScore = 1000
    if currentScore == nil or newScore > currentScore then
        return newScore
    else
        return nil -- Don't update if score isn't higher
    end
end, function(error)
    if error == StorageError.None then
        print("High score updated")
    end
end)

Safely updates a value based on its current state - prevents data loss from simultaneous updates.

Why use this instead of Get then Set:

• PROBLEM: If two players trigger updates at the same time, one update can be lost Example: Player A and B both try to add their score to leaderboard Player A reads 100, adds 50 = 150 Player B reads 100 (before A saves), adds 30 = 130 Result: Only 130 saved, Player A's 50 points lost!
• SOLUTION: UpdateValue ensures both updates apply correctly (result = 180)

How it works:

1. Retrieves current value (nil if doesn't exist)
2. Calls your modifier function with current value
3. Saves the value your modifier returns
4. If another update happened simultaneously, retries automatically with new current value

The modifier may be called multiple times if concurrent updates detected. Return nil from modifier to cancel the update (no change saved).

When to use:

• Leaderboards (adding new high scores)
• Counters (tracking total events)
• Lists (adding items to shared arrays)
• Any value that depends on its previous value

When NOT to use:

• Simple overwrites (use SetValue - it's faster)
• Number increments (use IncrementValue - it's optimized for this)

-- Update leaderboard with new high score
Storage.UpdateValue("GlobalHighScore", function(currentScore)
    local newScore = 1000
    if currentScore == nil or newScore > currentScore then
        return newScore
    else
        return nil -- Don't update if score isn't higher
    end
end, function(error)
    if error == StorageError.None then
        print("High score updated")
    end
end)