Skip to main content

ServerRemoteProperty

This item only works when running on the server. Server

Server-side remote property class with per-player state management. Based on Sleitnick's Comm RemoteProperty implementation.

Values set can be anything that can pass through a RemoteEvent.

Here is a cheat-sheet for the below methods:

  • Setting data
    • Set: Set "top" value for all current and future players. Overrides any custom-set data per player.
    • SetTop: Set the "top" value for all players, but does not override any custom-set data per player.
    • SetFor: Set custom data for the given player. Overrides the "top" value. (Can be nil)
    • SetForList: Same as SetFor, but accepts a list of players.
    • SetFilter: Accepts a predicate function which checks for which players to set.
  • Clearing data
    • ClearFor: Clears the custom data set for a given player. Player will start using the "top" level value instead.
    • ClearForList: Same as ClearFor, but accepts a list of players.
    • ClearFilter: Accepts a predicate function which checks for which players to clear.
  • Getting data
    • Get: Retrieves the "top" value
    • GetFor: Gets the current value for the given player. If cleared, returns the top value.
Network Usage

Calling any of the data setter methods (e.g. Set()) will fire the underlying RemoteEvent to replicate data to the clients. Therefore, setting data should only occur when it is necessary to change the data that the clients receive.

Tables

Tables can be used with RemoteProperties. However, the RemoteProperty object will not watch for changes within the table. Therefore, anytime changes are made to the table, the data must be set again using one of the setter methods.

Functions​

Set​

</>
ServerRemoteProperty:Set(value: any) → ()

Sets the top-level value of all clients to the same value.

Override Per-Player Data

This will override any per-player data that was set using SetFor or SetFilter. To avoid overriding this data, SetTop can be used instead. 

-- Examples
remoteProperty:Set(10)
remoteProperty:Set({SomeData = 32})
remoteProperty:Set("HelloWorld")

SetTop​

</>
ServerRemoteProperty:SetTop(value: any) → ()

Set the top-level value of the property, but does not override any per-player data (e.g. set with SetFor or SetFilter). Any player without custom-set data will receive this new data.

This is useful if certain players have specific values that should not be changed, but all other players should receive the same new value. 

-- Using just 'Set' overrides per-player data:
remoteProperty:SetFor(somePlayer, "CustomData")
remoteProperty:Set("Data")
print(remoteProperty:GetFor(somePlayer)) --> "Data"

-- Using 'SetTop' does not override:
remoteProperty:SetFor(somePlayer, "CustomData")
remoteProperty:SetTop("Data")
print(remoteProperty:GetFor(somePlayer)) --> "CustomData"

SetFor​

</>
ServerRemoteProperty:SetFor(
player: Player,
value: any
) → ()

Set the value of the property for a specific player. This will override the value used by Set (and the initial value set for the property when created).

This value can be nil. In order to reset the value for a given player and let the player use the top-level value held by this property, either use Set to set all players' data, or use ClearFor. 

remoteProperty:SetFor(somePlayer, "CustomData")

SetForList​

</>
ServerRemoteProperty:SetForList(
players: {Player},
value: any
) → ()

Set the value of the property for specific players. This just loops through the players given and calls SetFor. 

local players = {player1, player2, player3}
remoteProperty:SetForList(players, "CustomData")

SetFilter​

</>
ServerRemoteProperty:SetFilter(
predicate: (
Player,
any
) → boolean,
value: any--

Value to set for the clients (and to the predicate)

) → ()

Sets the value for specific clients that pass the predicate function test. This can be used to finely set the values based on more control logic (e.g. setting certain values per team). 

-- Set the value of "NewValue" to players with a name longer than 10 characters:
remoteProperty:SetFilter(function(player)
	return #player.Name > 10
end, "NewValue")

ClearFor​

</>
ServerRemoteProperty:ClearFor(player: Player) → ()

Clears the custom property value for the given player. When this occurs, the player will reset to use the top-level value held by this property (either the value set when the property was created, or the last value set by Set). 

remoteProperty:Set("DATA")

remoteProperty:SetFor(somePlayer, "CUSTOM_DATA")
print(remoteProperty:GetFor(somePlayer)) --> "CUSTOM_DATA"

-- DOES NOT CLEAR, JUST SETS CUSTOM DATA TO NIL:
remoteProperty:SetFor(somePlayer, nil)
print(remoteProperty:GetFor(somePlayer)) --> nil

-- CLEAR:
remoteProperty:ClearFor(somePlayer)
print(remoteProperty:GetFor(somePlayer)) --> "DATA"

ClearForList​

</>
ServerRemoteProperty:ClearForList(players: {Player}) → ()

Clears the custom value for the given players. This just loops through the list of players and calls the ClearFor method for each player.

ClearFilter​

</>
ServerRemoteProperty:ClearFilter(predicate: (Player) → boolean) → ()

The same as SetFilter, except clears the custom value for any player that passes the predicate.

Get​

</>
ServerRemoteProperty:Get() → any

Returns the top-level value held by the property. This will either be the initial value set, or the last value set with Set(). 

remoteProperty:Set("Data")
print(remoteProperty:Get()) --> "Data"

GetFor​

</>
ServerRemoteProperty:GetFor(player: Player) → any

Returns the current value for the given player. This value will depend on if SetFor or SetFilter has affected the custom value for the player. If so, that custom value will be returned. Otherwise, the top-level value will be used (e.g. value from Set). 

-- Set top level data:
remoteProperty:Set("Data")
print(remoteProperty:GetFor(somePlayer)) --> "Data"

-- Set custom data:
remoteProperty:SetFor(somePlayer, "CustomData")
print(remoteProperty:GetFor(somePlayer)) --> "CustomData"

-- Set top level again, overriding custom data:
remoteProperty:Set("NewData")
print(remoteProperty:GetFor(somePlayer)) --> "NewData"

-- Set custom data again, and set top level without overriding:
remoteProperty:SetFor(somePlayer, "CustomData")
remoteProperty:SetTop("Data")
print(remoteProperty:GetFor(somePlayer)) --> "CustomData"

-- Clear custom data to use top level data:
remoteProperty:ClearFor(somePlayer)
print(remoteProperty:GetFor(somePlayer)) --> "Data"
Show raw api
{
    "functions": [
        {
            "name": "Set",
            "desc": "Sets the top-level value of all clients to the same value.\n\n:::note Override Per-Player Data\nThis will override any per-player data that was set using\n`SetFor` or `SetFilter`. To avoid overriding this data,\n`SetTop` can be used instead.\n:::\n\n```lua\n-- Examples\nremoteProperty:Set(10)\nremoteProperty:Set({SomeData = 32})\nremoteProperty:Set(\"HelloWorld\")\n```",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 308,
                "path": "lib/netwire/src/NetWireTypes.luau"
            }
        },
        {
            "name": "SetTop",
            "desc": "Set the top-level value of the property, but does not override\nany per-player data (e.g. set with `SetFor` or `SetFilter`).\nAny player without custom-set data will receive this new data.\n\nThis is useful if certain players have specific values that\nshould not be changed, but all other players should receive\nthe same new value.\n\n```lua\n-- Using just 'Set' overrides per-player data:\nremoteProperty:SetFor(somePlayer, \"CustomData\")\nremoteProperty:Set(\"Data\")\nprint(remoteProperty:GetFor(somePlayer)) --> \"Data\"\n\n-- Using 'SetTop' does not override:\nremoteProperty:SetFor(somePlayer, \"CustomData\")\nremoteProperty:SetTop(\"Data\")\nprint(remoteProperty:GetFor(somePlayer)) --> \"CustomData\"\n```",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 334,
                "path": "lib/netwire/src/NetWireTypes.luau"
            }
        },
        {
            "name": "SetFor",
            "desc": "Set the value of the property for a specific player. This\nwill override the value used by `Set` (and the initial value\nset for the property when created).\n\nThis value _can_ be `nil`. In order to reset the value for a\ngiven player and let the player use the top-level value held\nby this property, either use `Set` to set all players' data,\nor use `ClearFor`.\n\n```lua\nremoteProperty:SetFor(somePlayer, \"CustomData\")\n```",
            "params": [
                {
                    "name": "player",
                    "desc": "",
                    "lua_type": "Player"
                },
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 354,
                "path": "lib/netwire/src/NetWireTypes.luau"
            }
        },
        {
            "name": "SetForList",
            "desc": "Set the value of the property for specific players. This just\nloops through the players given and calls `SetFor`.\n\n```lua\nlocal players = {player1, player2, player3}\nremoteProperty:SetForList(players, \"CustomData\")\n```",
            "params": [
                {
                    "name": "players",
                    "desc": "",
                    "lua_type": "{Player}"
                },
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 369,
                "path": "lib/netwire/src/NetWireTypes.luau"
            }
        },
        {
            "name": "SetFilter",
            "desc": "Sets the value for specific clients that pass the `predicate`\nfunction test. This can be used to finely set the values\nbased on more control logic (e.g. setting certain values\nper team).\n\n```lua\n-- Set the value of \"NewValue\" to players with a name longer than 10 characters:\nremoteProperty:SetFilter(function(player)\n\treturn #player.Name > 10\nend, \"NewValue\")\n```",
            "params": [
                {
                    "name": "predicate",
                    "desc": "",
                    "lua_type": "(Player, any) -> boolean"
                },
                {
                    "name": "value",
                    "desc": "Value to set for the clients (and to the predicate)",
                    "lua_type": "any"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 388,
                "path": "lib/netwire/src/NetWireTypes.luau"
            }
        },
        {
            "name": "ClearFor",
            "desc": "Clears the custom property value for the given player. When\nthis occurs, the player will reset to use the top-level\nvalue held by this property (either the value set when the\nproperty was created, or the last value set by `Set`).\n\n```lua\nremoteProperty:Set(\"DATA\")\n\nremoteProperty:SetFor(somePlayer, \"CUSTOM_DATA\")\nprint(remoteProperty:GetFor(somePlayer)) --> \"CUSTOM_DATA\"\n\n-- DOES NOT CLEAR, JUST SETS CUSTOM DATA TO NIL:\nremoteProperty:SetFor(somePlayer, nil)\nprint(remoteProperty:GetFor(somePlayer)) --> nil\n\n-- CLEAR:\nremoteProperty:ClearFor(somePlayer)\nprint(remoteProperty:GetFor(somePlayer)) --> \"DATA\"\n```",
            "params": [
                {
                    "name": "player",
                    "desc": "",
                    "lua_type": "Player"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 414,
                "path": "lib/netwire/src/NetWireTypes.luau"
            }
        },
        {
            "name": "ClearForList",
            "desc": "Clears the custom value for the given players. This\njust loops through the list of players and calls\nthe `ClearFor` method for each player.",
            "params": [
                {
                    "name": "players",
                    "desc": "",
                    "lua_type": "{Player}"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 424,
                "path": "lib/netwire/src/NetWireTypes.luau"
            }
        },
        {
            "name": "ClearFilter",
            "desc": "The same as `SetFilter`, except clears the custom value\nfor any player that passes the predicate.",
            "params": [
                {
                    "name": "predicate",
                    "desc": "",
                    "lua_type": "(Player) -> boolean"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 433,
                "path": "lib/netwire/src/NetWireTypes.luau"
            }
        },
        {
            "name": "Get",
            "desc": "Returns the top-level value held by the property. This will\neither be the initial value set, or the last value set\nwith `Set()`.\n\n```lua\nremoteProperty:Set(\"Data\")\nprint(remoteProperty:Get()) --> \"Data\"\n```",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 448,
                "path": "lib/netwire/src/NetWireTypes.luau"
            }
        },
        {
            "name": "GetFor",
            "desc": "Returns the current value for the given player. This value\nwill depend on if `SetFor` or `SetFilter` has affected the\ncustom value for the player. If so, that custom value will\nbe returned. Otherwise, the top-level value will be used\n(e.g. value from `Set`).\n\n```lua\n-- Set top level data:\nremoteProperty:Set(\"Data\")\nprint(remoteProperty:GetFor(somePlayer)) --> \"Data\"\n\n-- Set custom data:\nremoteProperty:SetFor(somePlayer, \"CustomData\")\nprint(remoteProperty:GetFor(somePlayer)) --> \"CustomData\"\n\n-- Set top level again, overriding custom data:\nremoteProperty:Set(\"NewData\")\nprint(remoteProperty:GetFor(somePlayer)) --> \"NewData\"\n\n-- Set custom data again, and set top level without overriding:\nremoteProperty:SetFor(somePlayer, \"CustomData\")\nremoteProperty:SetTop(\"Data\")\nprint(remoteProperty:GetFor(somePlayer)) --> \"CustomData\"\n\n-- Clear custom data to use top level data:\nremoteProperty:ClearFor(somePlayer)\nprint(remoteProperty:GetFor(somePlayer)) --> \"Data\"\n```",
            "params": [
                {
                    "name": "player",
                    "desc": "",
                    "lua_type": "Player"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 484,
                "path": "lib/netwire/src/NetWireTypes.luau"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "ServerRemoteProperty",
    "desc": "Server-side remote property class with per-player state management.\nBased on Sleitnick's Comm RemoteProperty implementation.\n\nValues set can be anything that can pass through a\n[RemoteEvent](https://developer.roblox.com/en-us/articles/Remote-Functions-and-Events#parameter-limitations).\n\nHere is a cheat-sheet for the below methods:\n- Setting data\n\t- `Set`: Set \"top\" value for all current and future players. Overrides any custom-set data per player.\n\t- `SetTop`: Set the \"top\" value for all players, but does _not_ override any custom-set data per player.\n\t- `SetFor`: Set custom data for the given player. Overrides the \"top\" value. (_Can be nil_)\n\t- `SetForList`: Same as `SetFor`, but accepts a list of players.\n\t- `SetFilter`: Accepts a predicate function which checks for which players to set.\n- Clearing data\n\t- `ClearFor`: Clears the custom data set for a given player. Player will start using the \"top\" level value instead.\n\t- `ClearForList`: Same as `ClearFor`, but accepts a list of players.\n\t- `ClearFilter`: Accepts a predicate function which checks for which players to clear.\n- Getting data\n\t- `Get`: Retrieves the \"top\" value\n\t- `GetFor`: Gets the current value for the given player. If cleared, returns the top value.\n\n:::caution Network Usage\nCalling any of the data setter methods (e.g. `Set()`) will\nfire the underlying RemoteEvent to replicate data to the\nclients. Therefore, setting data should only occur when it\nis necessary to change the data that the clients receive.\n:::\n\n:::caution Tables\nTables _can_ be used with RemoteProperties. However, the\nRemoteProperty object will _not_ watch for changes within\nthe table. Therefore, anytime changes are made to the table,\nthe data must be set again using one of the setter methods.\n:::",
    "realm": [
        "Server"
    ],
    "source": {
        "line": 287,
        "path": "lib/netwire/src/NetWireTypes.luau"
    }
}