Remote Functions and Events

15 min

If you do not yet understand how Roblox clients and servers work together, read the /articles/Roblox Client Server Model|Roblox Client-Server Model article before proceeding.

Some actions can only be performed by a server and other actions only by a client. For example, a player (client) may activate a GUI button, upon which the server needs to enact a game-wide change. In these cases, a RemoteEvent or RemoteFunction lets server-side Script|Scripts and client-side LocalScript|LocalScripts communicate with each other.

Difference Between Remote Events and Functions

While remote events and remote functions both allow communication between servers and clients, there are some notable differences:

Remote Event
A `RemoteEvent` is designed for one-way communication. Using remote events, you can send information in the following ways:
Client → Server	Example — A player (client) presses the `P` key to drink an invisibility potion, then a `RemoteEvent` tells the server to make that player invisible to all other players.
Server → Client	Example — When a player's friend joins the game, that player (client) receives an on-screen notification.
Server → All Clients	Example — Before a race begins, a countdown timer is shown to all players.
Client → Client(s)	Example — A player chooses a new name for their in-game pet and shares it with friends.

Remote Function
A `RemoteFunction` is designed for two-way communication, such that it can send information across the server-client boundary and then wait for a response from the other side.
Client → Server → Client	Example — A player (client) fires a projectile, the server checks if a target was hit, and a response is sent back to the client with target-specific data (name of target, points to be awarded, etc.).
Server → Client → Server	(typically discouraged as noted below)

Using Remote Events

To implement remote events, you must create a RemoteEvent instance where both clients and the server can access it, for instance ReplicatedStorage.

In the Explorer window, click the button next to ReplicatedStorage and insert a RemoteEvent instance.

To use the new RemoteEvent instance with the following examples, rename it RemoteEventTest.

Client to Server

Game changes that happen within a LocalScript only affect the local player. If a client needs to make a change that affects the entire server, the client can send a remote request to the server. For example, the following uses a remote event to create a new part which everyone on the server can see:

Confirm that the RemoteEvent instance within ReplicatedStorage is named RemoteEventTest.
Create a LocalScript within StarterPlayerScripts. In its code, point to the RemoteEvent instance and fire an event with the RemoteEvent/FireServer|FireServer() method:

				
					Expected Output
				
					Expand
					
			local ReplicatedStorage = game:GetService("ReplicatedStorage")

local remoteEvent = ReplicatedStorage:WaitForChild("RemoteEventTest")

-- Fire the remote event
remoteEvent:FireServer()
		
				Copy Code
			
				Light Theme

If needed, additional data may be passed along with RemoteEvent/FireServer|FireServer(). This data will be available as additional parameters to the connected function:

				
					Expected Output
				
					Expand
					
			-- Include additional data when firing the event
remoteEvent:FireServer(BrickColor.Red(), Vector3.new(0, 25, 0))
		
				Copy Code
			
				Light Theme

Create a Script within ServerScriptService. In its code, point to the RemoteEvent instance and connect a function with an RemoteEvent/OnServerEvent|OnServerEvent connection:

				
					Expected Output
				
					Expand
					
			local ReplicatedStorage = game:GetService("ReplicatedStorage")

local remoteEvent = ReplicatedStorage:WaitForChild("RemoteEventTest")

-- Create a new part
local function onCreatePart(player, partColor, partPos)
	print(player.Name .. " fired the remote event")
	local newPart = Instance.new("Part")
	newPart.BrickColor = partColor
	newPart.Position = partPos
	newPart.Parent = workspace
end

-- Call "onCreatePart()" when the client fires the remote event
remoteEvent.OnServerEvent:Connect(onCreatePart)
		
				Copy Code
			
				Light Theme

Note that the connected function (lines 6-12) will receive the Player who fired the event as its first parameter (player), along with any additional parameters passed from the RemoteEvent/FireServer|FireServer() call.

Server to Client

When something happens on the server side, it may be useful to notify a specific player with a remote event. To accomplish this:

Confirm that the RemoteEvent instance within ReplicatedStorage is named RemoteEventTest.
Create a Script within ServerScriptService. In its code, point to the RemoteEvent instance and fire an event with the RemoteEvent/FireClient|FireClient() method:

				
					Expected Output
				
					Expand
					
			local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")

local remoteEvent = ReplicatedStorage:WaitForChild("RemoteEventTest")

local function onPlayerAdded(player)
	-- Fire the remote event
	remoteEvent:FireClient(player)
end
Players.PlayerAdded:Connect(onPlayerAdded)
		
				Copy Code
			
				Light Theme

Note that a Player object must be passed along with the RemoteEvent/FireClient|FireClient() call to indicate which specific player should be targeted.

Similar to client-to-server events, additional data may be passed along with RemoteEvent/FireClient|FireClient(). This data will be available as additional parameters to the connected function:

				
					Expected Output
				
					Expand
					
			local function onPlayerAdded(player)
	-- Include additional data when firing the event
	remoteEvent:FireClient(player, Players.MaxPlayers, Players.RespawnTime)
end
Players.PlayerAdded:Connect(onPlayerAdded)
		
				Copy Code
			
				Light Theme

Create a LocalScript within StarterPlayerScripts. In its code, point to the RemoteEvent instance and connect a function with an RemoteEvent/OnClientEvent|OnClientEvent connection:

				
					Expected Output
				
					Expand
					
			local ReplicatedStorage = game:GetService("ReplicatedStorage")

local remoteEvent = ReplicatedStorage:WaitForChild("RemoteEventTest")

-- Ignore the passed player; start with additional passed data
local function onNotifyPlayer(maxPlayers, respawnTime)
	print("Incoming server event...")
	print(maxPlayers, respawnTime)
end

-- Call "onNotifyPlayer()" when the server fires the remote event
remoteEvent.OnClientEvent:Connect(onNotifyPlayer)
		
				Copy Code
			
				Light Theme

As noted in step #2, the server must pass a Player object with RemoteEvent/FireClient|FireClient(). However, the receiving client-side function does not need to account for the player object in its list of parameters, so that function can begin with the second piece of data passed, in this case maxPlayers.

Server to All Clients

Sometimes the game server needs to manage a routine and dispatch an event to all clients, for instance showing a countdown timer for all players. To do this:

Confirm that the RemoteEvent instance within ReplicatedStorage is named RemoteEventTest.
Create a Script within ServerScriptService. In its code, point to the RemoteEvent instance and fire an event with the RemoteEvent/FireAllClients|FireAllClients() method:

				
					Expected Output
				
					Expand
					
			local ReplicatedStorage = game:GetService("ReplicatedStorage")

local remoteEvent = ReplicatedStorage:WaitForChild("RemoteEventTest")

local secondsRemaining = 5

-- Fire the remote event every second until time expires
for t = secondsRemaining, 1, -1 do
	remoteEvent:FireAllClients(t)
	wait(1)
end
		
				Copy Code
			
				Light Theme

Unlike RemoteEvent/FireClient|FireClient(), the RemoteEvent/FireAllClients|FireAllClients() method does not require a Player object, as it fires the remote event to all connected players.

Create a LocalScript within StarterPlayerScripts. In its code, point to the RemoteEvent instance and connect a function with an RemoteEvent/OnClientEvent|OnClientEvent connection:

				
					Expected Output
				
					Expand
					
			local ReplicatedStorage = game:GetService("ReplicatedStorage")

local remoteEvent = ReplicatedStorage:WaitForChild("RemoteEventTest")

local function onTimerUpdate(seconds)
	print(seconds)
end

-- Call "onTimerUpdate()" when the server fires the remote event
remoteEvent.OnClientEvent:Connect(onTimerUpdate)
		
				Copy Code
			
				Light Theme

Client to Client

Because of the articles/Roblox Client Server Model|client-server model, communication between two or more clients must pass through the server. This is typically done as follows:

The sending client calls RemoteEvent/FireServer|FireServer().
On the server, the function connected to RemoteEvent/OnServerEvent|OnServerEvent hears this firing and calls RemoteEvent/FireClient|FireClient() or RemoteEvent/FireAllClients|FireAllClients() for the intended receiving client(s).

Using Remote Functions

As stated earlier, remote functions are designed to send a request across the server-client boundary and then wait for a response from the other side.

Before you can implement a remote function, you must create a RemoteFunction instance where both clients and the server can access it, for instance ReplicatedStorage:

In the Explorer window, click the button next to ReplicatedStorage and insert a RemoteFunction instance.

To use the new RemoteFunction instance with the following examples, rename it RemoteFunctionTest.

Client to Server

A client-side RemoteFunction is “invoked” when that client wants the server to do something and be notified when the server is done. For example, the following approach sends a request from the client, creates a part on the server, and returns it back to the client.

Confirm that the RemoteFunction object within ReplicatedStorage is named RemoteFunctionTest.
Create a Script within ServerScriptService. In its code, point to the RemoteFunction instance and bind a function to its RemoteFunction/OnServerInvoke|OnServerInvoke callback using the = operator:

				
					Expected Output
				
					Expand
					
			local ReplicatedStorage = game:GetService("ReplicatedStorage")

local remoteFunction = ReplicatedStorage:WaitForChild("RemoteFunctionTest")

-- Create a new part and return it
local function createPart(player)
	print(player.Name .. " requested a new part")
	local newPart = Instance.new("Part")
	newPart.Parent = workspace
	return newPart
end

-- Bind the "createPart()" function to the remote function's "OnServerInvoke" callback
remoteFunction.OnServerInvoke = createPart
		
				Copy Code
			
				Light Theme

Note that the bound function (lines 6-11) will receive the Player who invoked it as the first parameter (player).

Only one function can be bound to RemoteFunction/OnServerInvoke|OnServerInvoke at a time. If you assign multiple functions, only the last one assigned will be used.

Create a LocalScript within StarterPlayerScripts. In its code, point to the RemoteFunction instance and invoke the server with the RemoteFunction/InvokeServer|InvokeServer() method:

				
					Expected Output
				
					Expand
					
			local ReplicatedStorage = game:GetService("ReplicatedStorage")

local remoteFunction = ReplicatedStorage:WaitForChild("RemoteFunctionTest")

-- Invoke the function
local newPart = remoteFunction:InvokeServer()
print("The server created the requested part:", newPart)
		
				Copy Code
			
				Light Theme

Invocations will yield until the corresponding callback is found. If the callback was never set, the LocalScript that invokes it will not resume execution.

Like remote events, additional data may be passed along with the RemoteFunction/InvokeServer|InvokeServer() call and it will be available as additional parameters to the connected function:

				
					Expected Output
				
					Expand
					
			-- Pass a brick color and position when invoking the function
local newPart = remoteFunction:InvokeServer(BrickColor.Red(), Vector3.new(0, 25, 0))
print("The server created the requested part:", newPart)
		
				Copy Code
			
				Light Theme

				
					Expected Output
				
					Expand
					
			-- Create a new part and return it
local function createPart(player, partColor, partPos)
	print(player.Name .. " requested a new part")
	local newPart = Instance.new("Part")
	-- Use the "partColor" and "partPos" parameters to set the brick color/position
	newPart.BrickColor = partColor
	newPart.Position = partPos
	newPart.Parent = workspace
	return newPart
end
		
				Copy Code
			
				Light Theme

Server to Client

A server should rarely invoke a client via RemoteFunction/InvokeClient|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 RemoteFunction/InvokeClient|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 RemoteFunction/InvokeClient|InvokeClient() call will error.
If the client never returns a value, the server will hang forever.

Parameter Limitations

Any type of Roblox object such as an Enumeration, Instance, or userdata can be passed as a parameter when a RemoteEvent is fired or a RemoteFunction invoked. Lua types such as numbers, strings, and booleans can also be passed, although there are some limitations on how data can be passed.

Mixed Tables

Avoid passing a mixed table (some values indexed by number and others by key), as only the data indexed by number will be passed. For example, when the server receives the colorData table illustrated below, it will only see indices 1 and 2 containing "Blue" and "Yellow" while the other data will be lost in the transfer. Note, however, that sub-tables do not need to be indexed in the same way as their parent — in other words, as long as each individual sub-table is indexed with the same type, all of the data will be preserved.

				
					Expected Output
				
					Expand
					
			local ReplicatedStorage = game:GetService("ReplicatedStorage")

local remoteEvent = ReplicatedStorage:WaitForChild("RemoteEventTest")

-- Mixed table
local colorData = {}
colorData[1] = "Blue"
colorData[2] = "Yellow"
colorData["Color1"] = "Green"
colorData["Color2"] = "Red"

-- Table with two key-indexed sub-tables
local playerData = {}
playerData["CharData"] = {
	-- All children indexed by key
	CharName = "Diva Dragonslayer",
	CharClass = "Knight"
}
playerData["Inventory"] = {
	-- All children numerically indexed
	"Sword",
	"Bow",
	"Rope"
}

remoteEvent:FireServer(colorData)
remoteEvent:FireServer(playerData)
		
				Copy Code
			
				Light Theme

Metatables

If a table has a articles/Metatables|metatable, all of the metatable information will be lost in the transfer. For example, when the server receives the following table, the truck table that was passed will have the Name property but not the NumWheels property that was part of the Car metatable.

				
					Expected Output
				
					Expand
					
			local ReplicatedStorage = game:GetService("ReplicatedStorage")

local remoteEvent = ReplicatedStorage:WaitForChild("RemoteEventTest")

local Car = {}
Car.NumWheels = 4
Car.__index = Car

local truck = {}
truck.Name = "MyTruck"
setmetatable(truck, Car)

remoteEvent:FireServer(truck)
		
				Copy Code
			
				Light Theme

Non-Replicated Instances

If the value being sent is only visible to the sender, nil will be passed instead of the value. For example, if a server tries to pass a descendant of ServerStorage, the client listening to the event will see a nil value because that object isn’t replicated to the client.

Similarly, if a client creates a part and tries to pass it to the server, the server will see a nil value because the part isn’t replicated to the server.

				
					Expected Output
				
					Expand
					
			local ReplicatedStorage = game:GetService("ReplicatedStorage")
local ServerStorage = game:GetService("ServerStorage")
local Players = game:GetService("Players")

local remoteEvent = ReplicatedStorage:WaitForChild("RemoteEventTest")

-- Will be received as "nil" because client can't access ServerStorage
local storedPart = Instance.new("Part")
storedPart.Parent = ServerStorage

local function onPlayerAdded(player)
	remoteEvent:FireClient(player, storedPart)
end
Players.PlayerAdded:Connect(onPlayerAdded)
		
				Copy Code
			
				Light Theme

				
					Expected Output
				
					Expand
					
			local ReplicatedStorage = game:GetService("ReplicatedStorage")

local remoteEvent = ReplicatedStorage:WaitForChild("RemoteEventTest")

-- Will be received as "nil" because server doesn't know about this part
local clientPart = Instance.new("Part")
clientPart.Parent = workspace

remoteEvent:FireServer(clientPart)
		
				Copy Code
			
				Light Theme

Tags:

client
server
remote
event

Remote Functions and Events

Remote Functions and Events

Difference Between Remote Events and Functions

Using Remote Events

Client to Server

Server to Client

Server to All Clients

Client to Client

Using Remote Functions

Client to Server

Server to Client

Parameter Limitations

Mixed Tables

Metatables

Non-Replicated Instances

Related Articles

Handling Events

Roblox Client-Server Model