Array Operation Functions

AddToArray()

AddToArray(player, arrayPath, item) → boolean

Adds an item to the end of an array with validation.

Parameters: player: Player, arrayPath: ArrayPath, item: any
Returns: boolean - Success status

Example

-- Add item to inventory
local success = PlayerState.AddToArray(player, "Inventory", {
    Id = "sword_001",
    Name = "Iron Sword",
    Rarity = "Common"
})

if success then
    print("Item added to inventory")
end

-- Add achievement
PlayerState.AddToArray(player, "Achievements", "first_kill")

Note

Enhanced array operation with success return and validation

Array Indexing

Arrays are 1-indexed in Lua. Index 1 is the first item!

---

RemoveFromArray()

RemoveFromArray(player, arrayPath, index) → boolean

Removes an item from an array by index with bounds checking.

Parameters: player: Player, arrayPath: ArrayPath, index: number (1-based)
Returns: boolean - Success status

Example

-- Remove first item from inventory
local success = PlayerState.RemoveFromArray(player, "Inventory", 1)
if not success then
    warn("Failed to remove item")
end

-- Remove specific achievement
PlayerState.RemoveFromArray(player, "Achievements", 3)

Note

Safe index-based removal with bounds checking and validation

---

UpdateArrayItem()

UpdateArrayItem(player, arrayPath, index, newItem) → boolean

Updates an item in an array by index with validation.

Parameters: player: Player, arrayPath: ArrayPath, index: number (1-based), newItem: any
Returns: boolean - Success status

Example

-- Update inventory item
local success = PlayerState.UpdateArrayItem(player, "Inventory", 1, {
    Id = "sword_002",
    Name = "Steel Sword",
    Rarity = "Rare",
    Enchantments = {"Sharpness", "Durability"}
})

if success then
    print("Item upgraded successfully")
end

Note

Safe array item modification with index validation and bounds checking

Dictionary Operation Functions