RemoteFunction

Show Deprecated

A server should rarely invoke a client via InvokeClient() as it can be potentially game breaking. For client-only actions that don't require a callback, like updating a GUI, a server-to-client remote event should be used instead. If InvokeClient() is used, risks include:

  • If the client throws an error, the server will throw the error too.
  • If the client disconnects while it's being invoked, the InvokeClient() call will error.
  • If the client never returns a value, the server will hang forever.

A RemoteFunction is used to create in-game APIs that both the client and the server can use to communicate with each other. Like BindableFunction, a RemoteFunction can be invoked (called) to do a certain action and return the results.

If the result is not needed, we recommend that you use a RemoteEvent instead, since its call is asynchronous and doesn't need to wait for a response to continue execution. See Remote Functions and Events.

Code Samples

RemoteFunction1

1-- In a server script
2local ReplicatedStorage = game:GetService("ReplicatedStorage")
3
4local remoteFunction = ReplicatedStorage.RemoteFunction
5
6function remoteFunction.OnServerInvoke(player, name)
7 print("Hi, my name is", name, "and this invocation came from", player.Name)
8 return player.Name
9end
RemoteFunctions: Client to Server (LocalScript)

1local ReplicatedStorage = game:GetService("ReplicatedStorage")
2
3local createPartRequest = ReplicatedStorage:WaitForChild("CreatePartRequest")
4
5local newPart = createPartRequest:InvokeServer()
6print("The server created this part for me:", newPart)
RemoteFunctions: Client to Server (Script)

1local ReplicatedStorage = game:GetService("ReplicatedStorage")
2
3local createPartRequest = Instance.new("RemoteFunction")
4createPartRequest.Parent = ReplicatedStorage
5createPartRequest.Name = "CreatePartRequest"
6
7local function onCreatePartRequested(player)
8 print(player.Name, "wants to create a new part")
9 local newPart = Instance.new("Part")
10 newPart.Parent = workspace
11 return newPart
12end
13
14createPartRequest.OnServerInvoke = onCreatePartRequested
RemoteFunctions: Server to Client (LocalScript)

1local Players = game:GetService("Players")
2local ReplicatedStorage = game:GetService("ReplicatedStorage")
3
4local player = Players.LocalPlayer
5local playerGui = player:WaitForChild("PlayerGui")
6local createPopupRequest = ReplicatedStorage:WaitForChild("CreatePopupRequest")
7
8local function onCreatePopupRequested()
9 local screen = Instance.new("ScreenGui")
10 screen.Parent = playerGui
11
12 local closeButton = Instance.new("TextButton")
13 closeButton.Text = "Welcome to the game! Click me to play!"
14 closeButton.Size = UDim2.new(0, 300, 0, 50)
15 closeButton.Parent = screen
16
17 closeButton.MouseButton1Click:Wait()
18 closeButton.Visible = false
19end
20
21createPopupRequest.OnClientInvoke = onCreatePopupRequested
RemoteFunctions: Server to Client (Script)

1local Players = game:GetService("Players")
2local ReplicatedStorage = game:GetService("ReplicatedStorage")
3
4local createPopupRequest = Instance.new("RemoteFunction")
5createPopupRequest.Name = "CreatePopupRequest"
6createPopupRequest.Parent = ReplicatedStorage
7Players.CharacterAutoLoads = false
8
9local function onPlayerAdded(player)
10 createPopupRequest:InvokeClient(player)
11 player:LoadCharacter()
12end
13
14Players.PlayerAdded:Connect(onPlayerAdded)

Summary

Properties

Events

Methods

InvokeClient(player: Player, arguments: Tuple): Tuple  YIELDS

Calls the function bound to the RemoteFunction by RemoteFunction.OnClientInvoke for the given Player. Use only in a Script.

InvokeServer(arguments: Tuple): Tuple  YIELDS

Calls the function bound to the RemoteFunction by RemoteFunction.OnServerInvoke and returns what that function returns. Use only in a LocalScript.

Callbacks

OnClientInvoke(arguments: Tuple)  

OnServerInvoke(player: Player, arguments: Tuple)  

Properties

Events

Methods

InvokeClient

Yields

Calls the function bound to the RemoteFunction by RemoteFunction.OnClientInvoke for the given Player. Use only in a Script.

In practice, the server does not often invoke the client, as clients typically do not have information that the server doesn't have, and actions that only a client can take, such as displaying a GUI, typically do not require a callback. As such, RemoteEvent:FireClient() is recommended as an asynchronous method that doesn't need to wait for a response to continue execution.

See also RemoteFunction:InvokeServer() and RemoteFunction.OnServerInvoke for invoking the server from a client.

Warning

If a client throws an error or disconnects while it is being invoked from the server, RemoteFunction:InvokeClient() will error. It is therefore recommended to wrap this method in pcall() so it doesn't stop execution of other code.

For more information, see Remote Events and Functions.

Parameters

player: Player

The Player that the remote function is being fired to.

arguments: Tuple

The arguments passed to the RemoteEvent.OnClientInvoke method.


Returns

Code Samples

RemoteFunctions: Server to Client (LocalScript)

1local Players = game:GetService("Players")
2local ReplicatedStorage = game:GetService("ReplicatedStorage")
3
4local player = Players.LocalPlayer
5local playerGui = player:WaitForChild("PlayerGui")
6local createPopupRequest = ReplicatedStorage:WaitForChild("CreatePopupRequest")
7
8local function onCreatePopupRequested()
9 local screen = Instance.new("ScreenGui")
10 screen.Parent = playerGui
11
12 local closeButton = Instance.new("TextButton")
13 closeButton.Text = "Welcome to the game! Click me to play!"
14 closeButton.Size = UDim2.new(0, 300, 0, 50)
15 closeButton.Parent = screen
16
17 closeButton.MouseButton1Click:Wait()
18 closeButton.Visible = false
19end
20
21createPopupRequest.OnClientInvoke = onCreatePopupRequested
RemoteFunctions: Server to Client (Script)

1local Players = game:GetService("Players")
2local ReplicatedStorage = game:GetService("ReplicatedStorage")
3
4local createPopupRequest = Instance.new("RemoteFunction")
5createPopupRequest.Name = "CreatePopupRequest"
6createPopupRequest.Parent = ReplicatedStorage
7Players.CharacterAutoLoads = false
8
9local function onPlayerAdded(player)
10 createPopupRequest:InvokeClient(player)
11 player:LoadCharacter()
12end
13
14Players.PlayerAdded:Connect(onPlayerAdded)

InvokeServer

Yields

A client invoking the server is necessary when the server either has access to information the client does not, or the client requests an action that only the server can perform. Used in a LocalScript, RemoteFunction:InvokeServer() calls the function bound to the RemoteFunction by RemoteFunction.OnServerInvoke and returns what that function returns.

If a returned result is not needed, it's recommended to use RemoteEvent:FireServer() instead, as its call is asynchronous and doesn't need to wait for a response to continue execution.

See also RemoteFunction:InvokeClient() and RemoteFunction.OnClientInvoke for invoking a particular client from the server.

For more information, see Remote Events and Functions.

Parameters

arguments: Tuple

The arguments passed to the RemoteEvent.OnServerInvoke method.


Returns

Code Samples

RemoteFunctions: Client to Server (LocalScript)

1local ReplicatedStorage = game:GetService("ReplicatedStorage")
2
3local createPartRequest = ReplicatedStorage:WaitForChild("CreatePartRequest")
4
5local newPart = createPartRequest:InvokeServer()
6print("The server created this part for me:", newPart)
RemoteFunctions: Client to Server (Script)

1local ReplicatedStorage = game:GetService("ReplicatedStorage")
2
3local createPartRequest = Instance.new("RemoteFunction")
4createPartRequest.Parent = ReplicatedStorage
5createPartRequest.Name = "CreatePartRequest"
6
7local function onCreatePartRequested(player)
8 print(player.Name, "wants to create a new part")
9 local newPart = Instance.new("Part")
10 newPart.Parent = workspace
11 return newPart
12end
13
14createPartRequest.OnServerInvoke = onCreatePartRequested

Callbacks

OnClientInvoke

Parameters

arguments: Tuple

Returns

Code Samples

RemoteFunctions: Server to Client (LocalScript)

1local Players = game:GetService("Players")
2local ReplicatedStorage = game:GetService("ReplicatedStorage")
3
4local player = Players.LocalPlayer
5local playerGui = player:WaitForChild("PlayerGui")
6local createPopupRequest = ReplicatedStorage:WaitForChild("CreatePopupRequest")
7
8local function onCreatePopupRequested()
9 local screen = Instance.new("ScreenGui")
10 screen.Parent = playerGui
11
12 local closeButton = Instance.new("TextButton")
13 closeButton.Text = "Welcome to the game! Click me to play!"
14 closeButton.Size = UDim2.new(0, 300, 0, 50)
15 closeButton.Parent = screen
16
17 closeButton.MouseButton1Click:Wait()
18 closeButton.Visible = false
19end
20
21createPopupRequest.OnClientInvoke = onCreatePopupRequested
RemoteFunctions: Server to Client (Script)

1local Players = game:GetService("Players")
2local ReplicatedStorage = game:GetService("ReplicatedStorage")
3
4local createPopupRequest = Instance.new("RemoteFunction")
5createPopupRequest.Name = "CreatePopupRequest"
6createPopupRequest.Parent = ReplicatedStorage
7Players.CharacterAutoLoads = false
8
9local function onPlayerAdded(player)
10 createPopupRequest:InvokeClient(player)
11 player:LoadCharacter()
12end
13
14Players.PlayerAdded:Connect(onPlayerAdded)

OnServerInvoke

Parameters

player: Player
arguments: Tuple

Returns

Code Samples

RemoteFunctions: Client to Server (LocalScript)

1local ReplicatedStorage = game:GetService("ReplicatedStorage")
2
3local createPartRequest = ReplicatedStorage:WaitForChild("CreatePartRequest")
4
5local newPart = createPartRequest:InvokeServer()
6print("The server created this part for me:", newPart)
RemoteFunctions: Client to Server (Script)

1local ReplicatedStorage = game:GetService("ReplicatedStorage")
2
3local createPartRequest = Instance.new("RemoteFunction")
4createPartRequest.Parent = ReplicatedStorage
5createPartRequest.Name = "CreatePartRequest"
6
7local function onCreatePartRequested(player)
8 print(player.Name, "wants to create a new part")
9 local newPart = Instance.new("Part")
10 newPart.Parent = workspace
11 return newPart
12end
13
14createPartRequest.OnServerInvoke = onCreatePartRequested