Usage Examples

UI Updates with Enhanced Change Handling

Example

local PlayerState = require(ReplicatedStorage.Libraries.PlayerState.PlayerStateClient)

-- UI Elements
local coinsLabel = gui.CoinsLabel
local levelLabel = gui.LevelLabel
local experienceBar = gui.ExperienceBar

-- Initial UI setup (data access automatically waits)
local function updateUI()
    coinsLabel.Text = tostring(PlayerState.Get("Coins") or 0)
    levelLabel.Text = "Level " .. tostring(PlayerState.Get("Level") or 1)

    local exp = PlayerState.Get("Experience") or 0
    local maxExp = (PlayerState.Get("Level") or 1) * 100
    experienceBar.Size = UDim2.new(exp / maxExp, 0, 1, 0)
end

-- Listen for changes with enhanced info
local connections = {}

connections.coins = PlayerState.OnChanged("Coins", function(newValue, oldValue, info)
    coinsLabel.Text = tostring(newValue or 0)

    -- Show gain/loss animation
    if oldValue and newValue > oldValue then
        showGainAnimation(newValue - oldValue)
    end
end)

connections.level = PlayerState.OnChanged("Level", function(newValue, oldValue, info)
    levelLabel.Text = "Level " .. tostring(newValue or 1)
    updateUI() -- Recalculate experience bar

    if oldValue and newValue > oldValue then
        showLevelUpEffect()
    end
end)

-- NEW: Global change listener for debugging
connections.debug = PlayerState.OnChanged(".", function(newValue, oldValue, info)
    if info and info.action then
        print(`[DEBUG] {info.action} at {table.concat(info.path, ".")}`)
    end
end)

-- Initial update
updateUI()

-- Enhanced cleanup function
local function cleanup()
    for name, connection in pairs(connections) do
        if connection and typeof(connection) == "table" and connection.Disconnect then
            connection:Disconnect()
        end
    end
    connections = {}
end

Settings Management

Example

-- Settings UI manager with caching
local SettingsManager = {}

local PlayerState = require(ReplicatedStorage.Libraries.PlayerState.PlayerStateClient)
local SoundService = game:GetService("SoundService")

function SettingsManager.init()
    -- Apply initial settings (automatically waits for data)
    local musicEnabled = PlayerState.GetPath("Settings.MusicEnabled")
    local soundEnabled = PlayerState.GetPath("Settings.SoundEnabled")

    SoundService.AmbientReverb = musicEnabled and Enum.ReverbType.City or Enum.ReverbType.NoReverb
    SoundService.Volume = soundEnabled and 1 or 0

    -- Listen for changes
    PlayerState.OnChanged("Settings.MusicEnabled", function(enabled)
        SoundService.AmbientReverb = enabled and Enum.ReverbType.City or Enum.ReverbType.NoReverb
    end)

    PlayerState.OnChanged("Settings.SoundEnabled", function(enabled)
        SoundService.Volume = enabled and 1 or 0
    end)
end

return SettingsManager

Inventory Display with Array Change Handling

Example

-- Inventory UI manager with enhanced change detection
local InventoryUI = {}

local PlayerState = require(ReplicatedStorage.Libraries.PlayerState.PlayerStateClient)

-- UI elements
local inventoryFrame = gui.InventoryFrame
local itemTemplate = inventoryFrame.ItemTemplate

function InventoryUI.updateDisplay()
    -- Clear existing items
    for _, child in pairs(inventoryFrame:GetChildren()) do
        if child ~= itemTemplate and child:IsA("Frame") then
            child:Destroy()
        end
    end

    -- Get inventory data
    local inventory = PlayerState.GetPath("Inventory") or {}

    -- Create UI elements for each item
    for index, item in ipairs(inventory) do
        local itemFrame = itemTemplate:Clone()
        itemFrame.Name = "Item" .. index
        itemFrame.Visible = true
        itemFrame.Parent = inventoryFrame

        -- Update item display
        itemFrame.ItemName.Text = item.Name or "Unknown"
        itemFrame.Rarity.Text = item.Rarity or "Common"
        itemFrame.LayoutOrder = index
    end
end

function InventoryUI.init()
    -- Initial display (automatically waits for data)
    InventoryUI.updateDisplay()

    -- NEW: Enhanced inventory change listener
    PlayerState.OnChanged("Inventory", function(newValue, oldValue, info)
        InventoryUI.updateDisplay()

        -- Handle specific actions
        if info and info.action == "TableInsert" then
            showItemAddedEffect(info.index)
        elseif info and info.action == "TableRemove" then
            showItemRemovedEffect(info.index)
        end
    end)
end

return InventoryUI