SetInDict()

SetInDict(player, dictPath, key, value) → boolean

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

Parameters: player: Player, dictPath: DictPath, key: string, value: any
Returns: boolean - Success status

Example

-- 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

---

GetFromDict()

GetFromDict(player, dictPath, key) → any

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

Parameters: player: Player, dictPath: DictPath, key: string | number
Returns: any - The value, or nil if not found. Tables are cloned if AutoCloneTables is enabled.

Example

-- 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

---

RemoveFromDict()

RemoveFromDict(player, dictPath, key) → boolean

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

Parameters: player: Player, dictPath: DictPath, key: string
Returns: boolean - Success status

Example

-- 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

Cache Management Functions