Change Listener Functions

Read-only client subscriptions to replicated profile data. See the Change listeners guide for ChangeInfo vs path arrays.

OnChanged

OnChanged(pathOrKey, callback) → ReplicaClient.Connection?

Listens for changes to a specific data path or key.

Parameters: pathOrKey: string, callback: (newValue: any, oldValue: any, changeInfo: ChangeInfo | {string}?) -> ()
Returns: ReplicaClient.Connection? - Connection to disconnect the listener

Always returns a connection, even when called before data is ready; the listener starts firing once data arrives. Invalid arguments log a warning, like on the server.

When it fires

• On a direct change to the path, or to anything nested under it. After a nested change, a parent-path callback receives the parent's new value.
• When a parent path is replaced or set with SetValues on the server, e.g. SetValues(player, {Coins = 5}) reaches OnChanged("Coins").
• Array indices work in paths: OnChanged("Items.3").
• If the server enables SkipUnchangedWrites, writing a value equal to the current one doesn't fire.

changeInfo.path is a copy for each callback, so changing it doesn't affect other listeners. Connecting or disconnecting listeners from inside another listener is fine.

Basic Listening

local coinsConnection = PlayerState.OnChanged("Coins", function(newValue, oldValue)
    updateCoinsUI(newValue)
end)

Nested Paths

PlayerState.OnChanged("Plot.Likes", function(newValue, oldValue, pathInfo)
    updateLikesDisplay(newValue)
end)

Global listener - debug

PlayerState.OnChanged(".", function(newValue, oldValue, changeInfo)
    if changeInfo and changeInfo.action == "TableInsert" then
        print("Item added at index:", changeInfo.index)
    end
end)

Note

Prefer specific paths over "." in production. Disconnect listeners when UI is destroyed.

Managing connections

local connections = {}
connections.coins = PlayerState.OnChanged("Coins", updateCoinsUI)

for _, connection in connections do
    if connection then connection:Disconnect() end
end

---