Replicating Data

Creating a Replicator

To create a module, all you will need to do is pass the identifier of the replicator and the states and their default values that will be replicated to the client.

Important

Whatever states you specify when creating the replicator will be the only states you can change, otherwise an error will be thrown.

tip

When it comes to the identifier of the replicator, you aren't limited to a string! You can use a instance as well, such as a Model or a Folder!

Server:

local Replicator = require(path.to.module)

local ExampleReplicator = Replicator.new("ExampleReplicator", {
    ExampleState = "ExampleValue",
    ExampleNumber = 0,
    ExampleBoolean = false,
    ExampleTable = {
        Very = "Cool"
    }
})

Client:

local Replicator = require(path.to.module)

local ExampleReplicator = Replicator.new("ExampleReplicator")

Listening to Data Changes

To listen to data changes on the client, you can use the StateChanged signal on the replicator. This signal will fire whenever a state is changed, and will provide the state and new value as arguments.

ExampleReplicator.StateChanged:Connect(function(state, value)
    print(state, value)
end)

However, this can get a bit messy if you have multiple states in the same replicator you want to listen to (which you usually do), so here you can use the getStateChangedSignal method to get a signal for a specific state.

local ExampleStateSignal = ExampleReplicator:getStateChangedSignal("ExampleState")
ExampleStateSignal:Connect(function(value)
    print(value)
end)

This will only fire when the ExampleState state is changed, and will provide the new value as an argument.

Changing States

To change a state in the replicator, you can use the changeStates method. This method will take a table of states and their new values, and will replicate them to the client.

ExampleReplicator:changeStates({
    ExampleState = "NewValue",
    ExampleNumber = 5,
    ExampleBoolean = true,
    ExampleTable = {
        Very = "Cooler"
    }
})

Specific Player States

If you ever need to replicate different data to different players, you can do that very easily using the same replicator. In order to do this, you will need to use the changeStates method the same way you would normally, but instead, you will specify the players you want to replicate the data to.

-- Replicating to a specific player
ExampleReplicator:changeStates({
    ExampleState = "NewValue"
}, player)

-- Replicating to multiple players
ExampleReplicator:changeStates({
    ExampleState = "NewValue"
}, { player1, player2, player3 })

To the clients, this will act the exact same as if you were to change the states normally, but only the specified players will receive the new data, and they will still receive state updates that are not player specific as well. On top of this, the server will store a copy of what each player has, so you can access the data for a specific player at any time (See Accessing Data for more information).

tip

At some point you may want to resync a player back with the server's data, see Syncing Players to learn how to do this.

Accessing Data

On both the server and the client, you can access the data in the replicator at any time, and it will always be up to date. You can even get the data for a specific player on the server if you need to.

-- Accessing all the data
local data = ExampleReplicator:get()
print(data) -- prints all the data in the replicator

-- Accessing a specific state
local ExampleState = ExampleReplicator:get("ExampleState")
print(ExampleState) -- prints the value of ExampleState

-- Accessing a specific player's data
local playerData = ExampleReplicator:getForPlayer(player)
local playerExampleState = ExampleReplicator:getForPlayer(player, "ExampleState")
print(playerData) -- prints all the data for the player
print(playerExampleState) -- prints the value of ExampleState for the player

Accessing Player Specific Data

If you attempt to access player specific data on the client, it will throw an error. The client only has access to the data that is replicated to it, and it does not have access to the data for other players.

Syncing Players

If you have set player specific data for a player, you may want to at some point resync the player with the server's data. This can be done using the syncPlayer method.

ExampleReplicator:syncPlayer(player)

Doing this will tell the client to revert all specific changes and replace them with the server's data. This will also fire the StateChanged signal for the client as usual.