Skip to content

ServerReplicate

The server-side representation of a Replicate. This is the object that you interact with when setting up Replicates on the server.

Summary

Methods
StartReplicating () : ServerReplicate
GetValue (path: ValuePath) : Variant
SetValue (path: ValuePath, value: Variant, temporary: boolean?) : Variant
Increment (path: ValuePath, value: number) : number
Ensure (path: ValuePath, defaultValue: Variant) : Variant
Delete (path: ValuePath)
ArrayInsert (path: ValuePath, value: Variant, temporary: boolean?)
ArrayRemove (path: ValuePath, index: number) : Variant
ArrayFind (path: ValuePath, value: Variant) : number?
Destroy ()

Methods

StartReplicating

ServerReplicate:StartReplicating ( ) : ServerReplicate

Tip

All GetReplicate calls will yield until ServerReplicate:StartReplicating() has been called. You should call this method as soon as the Replicate's initial data has been set.

GetValue

ServerReplicate:GetValue ( path: ValuePath ) : Variant

Parameters
path : ValuePath

Returns
Variant

SetValue

ServerReplicate:SetValue (
path: ValuePath, value: Variant, temporary: boolean?
) : Variant

Parameters
path : ValuePath
value : Variant
temporary : boolean?
Whether the inserted item should be temporary or not.

Returns
Variant
The previous value at the given path, or nil if there was no value.

Understanding Temporary Values

When using the "reference" SourceMode, you can set temporary values that wont save to the referenced source data table. For example, lets say you're loading player data from something like ProfileStore or DataStoreService and you want to give them a skin for this server only, you could do something like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
local exampleProfile = {
    skins = { }
}

local path = ValuePath("skins")
local replicates = { }
local playerData = { }

local function playerAdded(player: Player): nil
    local loadedDataSuccess: boolean, loadedData = pcall(DataStore:GetAsync(player.UserId))

    if loadedDataSuccess then
        if not loadedData then
            loadedData = table.clone(exampleProfile)
        end

        playerData[player] = loadedData

        local playerReplicate = Replicate.Server.new(player, playerData[player], {
            SourceMode = "reference",
        })

        playerReplicate:StartReplicating()
        replicates[player] = playerReplicate

        -- award them a premium skin, but dont save it since they might
        -- unsubscribe in the future
        if player.MembershipType == Enum.MembershipType.Premium then
            playerReplicate:ArrayInsert(path, "premium", true)
        end
    end

    -- temporary items will show up just like normal items
    local hasPremiumSkin: boolean = playerReplicate:ArrayFind(path, "premium") ~= nil

    print(hasPremiumSkin) --> true (assume player does have premium)

    return nil
end

local function playerRemoving(player: Player): nil
    local hasPremiumSkinInSavingData: boolean =
        table.find(playerData[player].skins, "premium") ~= nil

    print(hasPremiumSkinInSavingData) --> false

    local setSuccess: boolean, _ = pcall(DataStore:SetAsync(player.UserId))

    playerData[player] = nil
    replicates[player]:Destroy()

    return nil
end

Increment

ServerReplicate:Increment ( path: ValuePath, value: number ) : number

Parameters
path : ValuePath
value : number

Returns
number
The new value at the given path after the increment.

Ensure

ServerReplicate:Ensure ( path: ValuePath, defaultValue: Variant ) : Variant

Parameters
path : ValuePath
defaultValue : Variant

Returns
Variant
The current value, or defaultValue if nil.

Delete

ServerReplicate:Delete ( path: ValuePath ) : ()

Parameters
path : ValuePath

ArrayInsert

ServerReplicate:ArrayInsert (
path: ValuePath, value: Variant, temporary: boolean?
) : ()

Parameters
path : ValuePath
value : Variant
The value to append to the array.
temporary : boolean?
Whether the inserted item should be temporary or not. Read more.

ArrayRemove

ServerReplicate:ArrayRemove ( path: ValuePath, index: number ) : Variant

Parameters
path : ValuePath
index : number

Returns
Variant
The value that was removed from the array.

ArrayFind

ServerReplicate:ArrayFind ( path: ValuePath, value: Variant ) : number?

Parameters
path : ValuePath
value : Variant

Returns
number?
The index of the first occurrence of the value in the array, or nil.

Destroy

ServerReplicate:Destroy ( ) : ()

Danger

Only destroy Replicates when players are leaving! Once a player's Replicate is destroyed, they cannot receive more data unless they rejoin. This is a limitation of how Replicates are handled and may change in the future.