Change listeners โ
How OnChanged callbacks work on the server and client, and what the third argument contains.
Signatures โ
| Side | API |
|---|---|
| SERVER API | OnChanged(player, pathOrKey, callback) |
| CLIENT API | OnChanged(pathOrKey, callback) |
Types: ChangeInfo ยท ChangeCallback.
Third argument: path array vs ChangeInfo โ
| Situation | Third argument (info / changeInfo) |
|---|---|
Direct Set / SetValues on the listened path | Often a path key array, e.g. { "Coins" } |
| Table insert/remove, or child path changed while listening on a parent | ChangeInfo table with action, path, optional index |
Listening on "." (every change) | Always a table with action and path |
ChangeInfo actions include "Set", "SetValues", "TableInsert", and "TableRemove".
info.path is a copy made for each callback, so changing it doesn't affect other listeners or later writes.
-- Client: table insert
PlayerState.OnChanged("Inventory", function(newValue, oldValue, info)
if type(info) == "table" and info.action == "TableInsert" then
print("Added at index", info.index)
end
end)When listeners fire โ
Same rules on server and client, for OnChanged and OnSharedChanged:
- Parent replaced: a listener on
"Coins"fires when a parent path is replaced or the key is set withSetValues, e.g..SetValues(player, {Coins = 5}) - Nested change: a listener on a parent path (e.g.
"Plot") fires when"Plot.Likes"changes, and receives the parent's new value. - Array indices: paths can include indices, e.g.
orOnChanged("Items.3").GetPath("Items.1") - Unchanged values: by default, setting a value to what it already is still fires. Turn on
SkipUnchangedWrites(server config) to skip replication andOnChangedin that case. - Inside a listener: client reads (
Get,GetPath, ...) always return the latest value, and you can connect or disconnect other listeners safely.
Client OnChanged always returns a connection, even if you call it before data is ready, and warns on invalid arguments. Listeners cost nothing when none are connected.
Server-only paths โ
OnChanged is tied to the player Replica. Writes under ServerOnlyRoots (e.g. Server.*) update profile.Data only and do not fire OnChanged. After server-only writes, use your own flow or read with GetPath / GetAll.
Client practices โ
- Prefer specific paths (
"Coins","Plot.Likes") over"."except when debugging. - Disconnect when UI is destroyed or the player leaves.
- Do not mutate tables returned from
Get/GetPathโ see Best practices.
Server practices โ
- Disconnect per-player connections in
PlayerRemoving. - Same narrow-path guidance as the client.
API reference โ
- Server OnChanged
- Client OnChanged
- OnSharedChanged (shared session, server and client)