Tutorial · Fundamentos de scripting

RemoteEvents no Roblox: do cliente para o servidor e de volta

Um LocalScript não consegue mudar o que os outros jogadores veem, e um Script de servidor não consegue mexer na tela de um jogador. Os RemoteEvents levam mensagens entre os dois. Este guia monta os três padrões que você mais vai usar, uma RemoteFunction que devolve uma resposta e as checagens no servidor que impedem um cliente modificado de abusar deles.

Atualizado em 12 de novembro de 202620 min de leituraEscrito por

Resumo

Um RemoteEvent é um objeto, normalmente guardado no ReplicatedStorage, que envia mensagens pela fronteira entre cliente e servidor. Um LocalScript chama FireServer e o servidor escuta no OnServerEvent, com o Player que enviou adicionado como primeiro argumento. O servidor chama FireClient(player, ...) ou FireAllClients(...), e os LocalScripts escutam no OnClientEvent.

  • Use uma RemoteFunction (InvokeServer e OnServerInvoke) só quando o cliente precisa de uma resposta. Evite o InvokeClient: um cliente que dá erro, sai ou nunca retorna quebra a chamada do servidor.
  • Nunca confie no que um cliente envia. No servidor, confira o tipo, o intervalo e a posse de cada argumento, a distância do jogador e a frequência com que ele dispara.
  • Funções, metatables e objetos que o outro lado não enxerga não sobrevivem à viagem. Um UnreliableRemoteEvent pode perder ou reordenar mensagens, e descarta qualquer carga acima de 1.000 bytes.
Nesta página
  1. Por que existem
  2. Prepare os remotes
  3. 1. Cliente para servidor
  4. 2. Servidor para um cliente
  5. 3. Servidor para todos
  6. RemoteFunctions
  7. Lista de validação
  8. O que não dá para enviar
  9. Retorna nil?
  10. UnreliableRemoteEvent
  11. Ordem e limites
  12. Qual usar
  13. Erros comuns
  14. Com o RoCode
  15. Perguntas frequentes
  16. Fontes e leitura extra

Por que os RemoteEvents existem

IlustraçãoCada clique pede ao servidor para pintar a part, então as telas dos dois jogadores mostram a cor nova.

Todo jogo do Roblox roda como um servidor mais um cliente por jogador. O servidor é a autoridade: um objeto novo ou uma mudança de propriedade só chega a todos os jogadores quando é o servidor que faz. Uma mudança feita em um LocalScript fica naquele único dispositivo, com poucas exceções, como o personagem do próprio jogador, cujo movimento o cliente dele controla. Então, quando um clique ou uma tecla deve mudar o mundo compartilhado, o cliente precisa pedir ao servidor, e quando o servidor quer que a tela de um jogador reaja, ele precisa avisar aquele cliente. Se a divisão entre Script e LocalScript é novidade para você, leia antes Script vs LocalScript vs ModuleScript (em inglês). Se programar em si é novidade, comece por como programar no Roblox Studio.

O Roblox dá a você três objetos para cruzar essa fronteira:

  • RemoteEvent: uma mensagem de mão única. Quem envia segue em frente na hora.
  • RemoteFunction: um pedido que espera uma resposta. Quem chama fica pausado até o outro lado retornar um valor.
  • UnreliableRemoteEvent: uma mensagem de mão única que pode se perder ou chegar fora de ordem, em troca de menos carga na rede. Serve para dados que mudam o tempo todo.
Qual chamada dispara qual evento
DireçãoQuem envia chamaQuem recebe conecta emQuem recebe ganha
Do cliente para o servidorremote:FireServer(...) em um LocalScriptremote.OnServerEvent em um ScriptO Player que disparou, depois os seus argumentos
Do servidor para um clienteremote:FireClient(player, ...) em um Scriptremote.OnClientEvent em um LocalScriptSó os seus argumentos
Do servidor para todos os clientesremote:FireAllClients(...) em um Scriptremote.OnClientEvent em um LocalScriptSó os seus argumentos
O cliente pergunta, o servidor responderemoteFunction:InvokeServer(...)remoteFunction.OnServerInvoke = function(player, ...)O Player, depois os seus argumentos. Quem chamou recebe de volta o que a função retornar

Os clientes não conseguem mandar mensagens direto uns para os outros. Para passar algo de um jogador para os demais, dispare para o servidor, confira lá e deixe o servidor repassar com FireClient ou FireAllClients. A orientação de segurança da Roblox é que o servidor funcione aqui como um porteiro, nunca como um simples repetidor.

Onde colocar os seus remotes

Um remote precisa ficar onde tanto o servidor quanto os clientes conseguem vê-lo. O lugar de costume é o ReplicatedStorage; a documentação da Roblox avisa que o Workspace ou uma Tool também podem ser o lugar certo em alguns casos. O ServerStorage e o ServerScriptService são só do servidor, então um LocalScript que espera um remote ali espera para sempre.

  1. No Explorer, passe o mouse sobre ReplicatedStorage, clique no botão + e insira uma Folder. Dê o nome Remotes.
  2. Passe o mouse sobre Remotes, clique em + e insira um RemoteEvent. Renomeie para descrever a função dele, por exemplo PaintRequest.
  3. Repita para cada remote. Este guia usa dois RemoteEvents (PaintRequest e Notify) e uma RemoteFunction (RedeemCode).
Explorer: tudo o que este guia adiciona, seção por seção
ReplicatedStorage
  Remotes  Folder  new
    PaintRequest  RemoteEvent  new
    Notify  RemoteEvent  new
    RedeemCode  RemoteFunction  new
ServerScriptService
  PaintServer  Script  new
  WelcomeServer  Script  new
  FinishAnnouncer  Script  new
  RedeemServer  Script  new
  RemoteGuard  ModuleScript  new
StarterPlayer
  StarterPlayerScripts
    PaintClient  LocalScript  new
    NotifyClient  LocalScript  new
StarterGui
  CodeGui  ScreenGui  new
    CodeBox  TextBox  new
      RedeemClient  LocalScript  new
Workspace
  Paintable  Folder  new
  FinishLine  Part  new

Os scripts deste guia acham os remotes com WaitForChild. Ele retorna na hora quando o remote já está lá e espera quando não está, por exemplo quando um script de servidor cria remotes com o jogo rodando. Use um remote para cada tipo de pedido: cada handler do servidor confere então um único formato de argumentos, o que é muito mais fácil de acertar do que um remote só que faz de tudo.

Padrão 1: do cliente para o servidor, conferido pelo servidor

O trabalho mais comum: o jogador faz algo na tela dele, e o servidor decide o que acontece. Aqui o jogador aperta Q para escolher uma de quatro cores e clica ou toca em uma part para pintá-la. Todo mundo vê a cor nova, porque quem pinta é o servidor.

O cliente envia duas coisas: qual part, e um número de cor. Ele nunca envia a cor em si, e em outros jogos nunca deve enviar um preço, uma recompensa ou um valor de dano. Um cliente modificado pode enviar qualquer coisa, então o servidor guarda os dados de verdade (aqui, a paleta) e trata os argumentos como um pedido a conferir.

  1. No Workspace, insira uma Folder chamada Paintable e coloque nela algumas Parts ancoradas.
  2. Confira que ReplicatedStorage.Remotes tem um RemoteEvent chamado PaintRequest.
  3. Insira um Script no ServerScriptService chamado PaintServer, e um LocalScript em StarterPlayer, StarterPlayerScripts chamado PaintClient, com o código abaixo.
Script em ServerScriptService chamado PaintServer
local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local remotes = ReplicatedStorage:WaitForChild("Remotes")
local paintRequest = remotes:WaitForChild("PaintRequest") :: RemoteEvent
local paintable = workspace:WaitForChild("Paintable")

-- O servidor é o dono das cores. O cliente só envia um número que escolhe uma.
local PALETTE = {
	Color3.fromRGB(231, 76, 60),
	Color3.fromRGB(46, 204, 113),
	Color3.fromRGB(52, 152, 219),
	Color3.fromRGB(241, 196, 15),
}
local MAX_DISTANCE = 30 -- studs entre o personagem e a part
local COOLDOWN_SECONDS = 0.25

local lastPaint: { [Player]: number } = {}

-- O primeiro parâmetro é sempre o jogador que disparou. O Roblox preenche,
-- então dá para confiar nele. Tudo depois dele veio do cliente, e não dá.
paintRequest.OnServerEvent:Connect(function(player: Player, part: unknown, colourIndex: unknown)
	-- 1. Tipo: uma part de verdade, não uma tabela fingindo ser uma
	if typeof(part) ~= "Instance" or not part:IsA("BasePart") then
		return
	end

	-- 2. Intervalo: um número inteiro de 1 a 4. NaN e infinito também falham aqui.
	if type(colourIndex) ~= "number" or not math.isfinite(colourIndex) then
		return
	end
	if colourIndex % 1 ~= 0 or colourIndex < 1 or colourIndex > #PALETTE then
		return
	end

	-- 3. Alvo permitido: só parts na pasta Paintable, nada mais no jogo
	if not part:IsDescendantOf(paintable) then
		return
	end

	-- 4. Distância: o personagem do jogador precisa estar perto da part
	local character = player.Character
	local root = character and character:FindFirstChild("HumanoidRootPart")
	if not (root and root:IsA("BasePart")) then
		return
	end
	if (root.Position - part.Position).Magnitude > MAX_DISTANCE then
		return
	end

	-- 5. Limite de taxa: uma pintura por jogador a cada um quarto de segundo
	local now = os.clock()
	local last = lastPaint[player]
	if last and now - last < COOLDOWN_SECONDS then
		return
	end
	lastPaint[player] = now

	part.Color = PALETTE[colourIndex]
end)

Players.PlayerRemoving:Connect(function(player: Player)
	lastPaint[player] = nil
end)

Cada checagem que falha simplesmente retorna. Não há por que contar a um cliente trapaceiro o motivo da recusa.

LocalScript em StarterPlayerScripts chamado PaintClient
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local UserInputService = game:GetService("UserInputService")

local remotes = ReplicatedStorage:WaitForChild("Remotes")
local paintRequest = remotes:WaitForChild("PaintRequest") :: RemoteEvent
local paintable = workspace:WaitForChild("Paintable")

local COLOUR_COUNT = 4 -- o servidor guarda as cores de verdade
local selectedColour = 1

-- Só deixa o raio acertar parts dentro da pasta Paintable
local rayParams = RaycastParams.new()
rayParams.FilterType = Enum.RaycastFilterType.Include
rayParams.FilterDescendantsInstances = { paintable }

UserInputService.InputBegan:Connect(function(input: InputObject, gameProcessed: boolean)
	if gameProcessed then
		return -- a tecla ou o clique foi para o chat ou para um botão
	end

	if input.KeyCode == Enum.KeyCode.Q then
		selectedColour = selectedColour % COLOUR_COUNT + 1
		return
	end

	local isClick = input.UserInputType == Enum.UserInputType.MouseButton1
	local isTap = input.UserInputType == Enum.UserInputType.Touch
	if isClick or isTap then
		local camera = workspace.CurrentCamera
		local ray = camera:ScreenPointToRay(input.Position.X, input.Position.Y)
		local result = workspace:Raycast(ray.Origin, ray.Direction * 500, rayParams)
		if result then
			-- Peça, não mande: o servidor decide se a pintura acontece
			paintRequest:FireServer(result.Instance, selectedColour)
		end
	end
end)

gameProcessed é true quando o motor já agiu sobre a entrada, normalmente na UI: um clique em um botão, ou teclas digitadas em uma caixa de texto como a barra do chat. Conferir isso faz com que digitar um Q em uma mensagem não mude a cor.

Padrão 2: do servidor para um cliente

O servidor envia uma mensagem a um jogador com FireClient. O primeiro argumento é o Player que vai receber, e o handler do cliente recebe só os argumentos depois dele. Use isso para tudo o que é pessoal: uma notificação, um popup de recompensa, um som que só aquele jogador deve ouvir. O guia de cutscene é um exemplo maior: o servidor decide quando um jogador vê uma cutscene e envia as tomadas dela àquele único jogador com FireClient, e o dispositivo dele move a câmera.

Esta dupla mostra uma mensagem de boas-vindas quando um jogador entra. O LocalScript monta a própria faixa pequena, então não há GUI para preparar.

Script em ServerScriptService chamado WelcomeServer
local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local notify = ReplicatedStorage:WaitForChild("Remotes"):WaitForChild("Notify") :: RemoteEvent

local function welcome(player: Player)
	-- O primeiro argumento escolhe qual cliente recebe. Ninguém mais vê isto.
	notify:FireClient(player, `Welcome, {player.DisplayName}! Press Q to change colour.`)
end

Players.PlayerAdded:Connect(welcome)

-- No Studio você pode entrar antes de este script conectar, então cumprimente quem já está aqui
for _, player in Players:GetPlayers() do
	welcome(player)
end
LocalScript em StarterPlayerScripts chamado NotifyClient
local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local notify = ReplicatedStorage:WaitForChild("Remotes"):WaitForChild("Notify") :: RemoteEvent
local player = Players.LocalPlayer

-- Uma faixa pequena no topo da tela, montada em código
local gui = Instance.new("ScreenGui")
gui.Name = "Notifications"
gui.ResetOnSpawn = false
gui.Parent = player:WaitForChild("PlayerGui")

local label = Instance.new("TextLabel")
label.AnchorPoint = Vector2.new(0.5, 0)
label.Position = UDim2.new(0.5, 0, 0, 16)
label.Size = UDim2.fromOffset(420, 44)
label.BackgroundColor3 = Color3.fromRGB(18, 11, 31)
label.TextColor3 = Color3.new(1, 1, 1)
label.TextScaled = true
label.Visible = false
label.Parent = gui

local messageCount = 0

-- Sem parâmetro de jogador aqui: o servidor já escolheu quem recebe
notify.OnClientEvent:Connect(function(message: string)
	messageCount += 1
	local thisMessage = messageCount
	label.Text = message
	label.Visible = true
	task.delay(4, function()
		if messageCount == thisMessage then -- esconde, a não ser que uma mensagem mais nova tenha substituído
			label.Visible = false
		end
	end)
end)

O servidor dispara no PlayerAdded, o que pode acontecer antes de este LocalScript ter conectado o handler. Tudo bem: o Roblox põe em fila as mensagens de RemoteEvent que chegam antes de existir um handler e as entrega, em ordem, assim que um conecta.

O cliente não precisa se proteger do servidor: só código de servidor consegue disparar o OnClientEvent. A anotação message: string é para o verificador de tipos; não é uma checagem em tempo de execução.

Padrão 3: do servidor para todos os clientes

O FireAllClients envia a mesma mensagem a todo jogador conectado. Ele não recebe o argumento Player, e cada cliente a recebe no mesmo OnClientEvent de antes, então o script NotifyClient do Padrão 2 já a mostra.

Este Script anuncia para todo mundo quando um jogador toca em uma linha de chegada pela primeira vez. Adicione ao Workspace uma Part ancorada chamada FinishLine, depois adicione o Script ao ServerScriptService.

Script em ServerScriptService chamado FinishAnnouncer
local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local notify = ReplicatedStorage:WaitForChild("Remotes"):WaitForChild("Notify") :: RemoteEvent
local finishLine = workspace:WaitForChild("FinishLine") :: BasePart

local finished: { [Player]: boolean } = {}

finishLine.Touched:Connect(function(hit: BasePart)
	local character = hit:FindFirstAncestorOfClass("Model")
	local player = character and Players:GetPlayerFromCharacter(character)
	if not player or finished[player] then
		return -- não é um jogador, ou já foi anunciado
	end
	finished[player] = true

	-- Todo cliente conectado roda o handler do OnClientEvent com este texto
	notify:FireAllClients(`{player.DisplayName} reached the finish!`)
end)

Players.PlayerRemoving:Connect(function(player: Player)
	finished[player] = nil
end)

Um exploiter consegue disparar o Touched para o próprio personagem de qualquer distância, o que não faz mal em um anúncio mostrado uma vez por jogador. Se depois você der uma recompensa por terminar, adicione checagens no servidor antes de pagar, como um tempo mínimo desde o começo da rodada.

O FireAllClients alcança só os jogadores conectados naquele momento. Quem entra um segundo depois nunca vê a mensagem. Isso está certo para momentos únicos, como um anúncio, um efeito de explosão ou um som, mas errado para estado, como o timer de uma rodada ou a fase atual do jogo. Para estado, defina um atributo no servidor, por exemplo ReplicatedStorage:SetAttribute("TimeLeft", 30), e leia no cliente com GetAttribute e GetAttributeChangedSignal("TimeLeft"). Atributos replicam para todo cliente, inclusive para jogadores que entram depois.

RemoteFunction: quando o cliente precisa de uma resposta

Um RemoteEvent é disparar e esquecer. Uma RemoteFunction faz quem chama esperar: o InvokeServer pausa o código que o chamou até a função OnServerInvoke do servidor retornar, depois devolve o que ela retornou. Use uma quando o cliente não consegue continuar sem a resposta, como "esse código era válido?". Quando você não precisa de resposta, a Roblox recomenda um RemoteEvent, porque ele não espera.

Exemplo: uma caixa em que os jogadores digitam um código de recompensa. O servidor guarda os códigos, confere o texto e retorna dois valores: se deu certo, e uma mensagem para mostrar.

  1. Em ReplicatedStorage.Remotes, insira uma RemoteFunction chamada RedeemCode.
  2. No StarterGui, insira um ScreenGui chamado CodeGui, e dentro dele uma TextBox chamada CodeBox. Dê o tamanho e a posição que quiser.
  3. Adicione o Script abaixo ao ServerScriptService, e o LocalScript dentro da CodeBox.
Script em ServerScriptService chamado RedeemServer
local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local redeemCode = ReplicatedStorage:WaitForChild("Remotes"):WaitForChild("RedeemCode") :: RemoteFunction

-- Os códigos ficam no servidor, onde nenhum jogador consegue ler
local CODES: { [string]: number } = {
	LAUNCH = 100,
	THANKYOU = 50,
}
local MAX_LENGTH = 20
local COOLDOWN_SECONDS = 2

local usedCodes: { [Player]: { [string]: boolean } } = {}
local lastTry: { [Player]: number } = {}

-- Atribua com =. O OnServerInvoke é um callback, não um evento em que você dá Connect.
redeemCode.OnServerInvoke = function(player: Player, code: unknown): (boolean, string)
	local now = os.clock()
	local last = lastTry[player]
	if last and now - last < COOLDOWN_SECONDS then
		return false, "Wait a moment before trying again"
	end
	lastTry[player] = now

	if type(code) ~= "string" or #code == 0 or #code > MAX_LENGTH then
		return false, "Type a code first"
	end

	local key = string.upper(code)
	local reward = CODES[key]
	if not reward then
		return false, "That code doesn't exist"
	end

	local used = usedCodes[player]
	if not used then
		used = {}
		usedCodes[player] = used
	end
	if used[key] then
		return false, "You already used that code"
	end

	local leaderstats = player:FindFirstChild("leaderstats")
	local coins = leaderstats and leaderstats:FindFirstChild("Coins")
	if not (coins and coins:IsA("IntValue")) then
		return false, "Coins aren't set up in this game yet"
	end

	used[key] = true
	coins.Value += reward
	return true, `Code accepted: +{reward} coins`
end

Players.PlayerRemoving:Connect(function(player: Player)
	usedCodes[player] = nil
	lastTry[player] = nil
end)

Ele soma ao stat Coins do guia de leaderboard. Os códigos usados são lembrados só até o jogador sair, então, do jeito que está, um jogador pode entrar de novo e resgatar o mesmo código outra vez. Se as moedas são salvas, isso dá moedas grátis a cada entrada: antes de um jogo publicado usar isto, guarde os códigos usados de cada jogador junto com os dados salvos dele em um data store.

LocalScript em a TextBox CodeBox chamado RedeemClient
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local redeemCode = ReplicatedStorage:WaitForChild("Remotes"):WaitForChild("RedeemCode") :: RemoteFunction
local box = script.Parent :: TextBox

local GREEN = Color3.fromRGB(46, 204, 113)
local RED = Color3.fromRGB(231, 76, 60)

box.FocusLost:Connect(function(enterPressed: boolean)
	local code = box.Text
	if not enterPressed or code == "" then
		return
	end
	box.Text = ""
	box.PlaceholderText = "Checking..."

	-- O InvokeServer pausa esta função até o callback do servidor retornar.
	-- O pcall mantém o LocalScript rodando se a chamada falhar.
	local ok, accepted, message = pcall(function()
		return redeemCode:InvokeServer(code)
	end)

	if ok and type(message) == "string" then
		box.PlaceholderText = message
		box.PlaceholderColor3 = if accepted == true then GREEN else RED
	else
		box.PlaceholderText = "Something went wrong, try again"
		box.PlaceholderColor3 = RED
	end
end)

Uma RemoteFunction tem exatamente um callback de servidor. Se dois scripts definem o OnServerInvoke na mesma RemoteFunction, só o último roda.

Por que o InvokeClient é arriscado

Uma RemoteFunction também funciona no outro sentido, com InvokeClient no servidor e OnClientInvoke no cliente. A documentação da Roblox lista três riscos sérios:

  • Se o callback do cliente lança um erro, o servidor lança o erro também.
  • Se o jogador sai enquanto está sendo invocado, o InvokeClient lança um erro.
  • Se o cliente nunca retorna um valor, o script do servidor espera para sempre.

Um cliente modificado controla o próprio callback, então um trapaceiro pode causar o terceiro de propósito e segurar aquela thread do servidor pelo tempo que quiser. Para atualizar a tela de um jogador, use FireClient. Se o servidor realmente precisa de uma informação de um cliente, dispare um RemoteEvent, faça o cliente responder em outro RemoteEvent, e trate a falta de resposta como um caso normal no servidor.

Valide todo argumento no servidor

Um exploiter pode disparar qualquer RemoteEvent ou invocar qualquer RemoteFunction, quantas vezes quiser, com quaisquer argumentos. A única coisa que ele não consegue falsificar é o primeiro parâmetro: o Roblox preenche o Player que enviou. Tudo depois disso precisa ser conferido antes de o servidor agir. Esconder o remote ou conferir no LocalScript não ajuda, porque o trapaceiro controla o próprio cliente.

A lista de checagens do servidor
ChecagemA pergunta que o servidor fazExemplo
TipoÉ o tipo que eu espero? Uma Instance, e não uma tabela montada para parecer uma?typeof(part) == "Instance" and part:IsA("BasePart")
IntervaloO número é finito e está dentro do intervalo permitido? O texto tem um tamanho razoável?math.isfinite(n), n >= 1 and n <= 4, #text <= 20
PosseEste jogador é dono do item, tem o dinheiro, ou tem o direito de agir sobre este objeto?O item está no inventário dele; a part está dentro de Paintable
DistânciaO personagem do jogador está perto o bastante na cópia do mundo que o servidor tem? Dê uma folga para o lag.A até 30 studs da part
TaxaEste jogador está enviando rápido demais?Um cooldown por jogador ou um limite de taxa com rajada

O NaN merece um aviso só para ele. Ele é um number, então type(x) == "number" passa, mas toda comparação com ele é falsa, então uma checagem como x < 0 or x > 100 o deixa passar direto. O math.isfinite(x) rejeita o NaN e os dois infinitos.

Conheça o limite de uma checagem de distância. Cada cliente controla a física do próprio personagem, então um exploiter pode levar o personagem para o lado do alvo antes de disparar. A checagem ainda impede o abuso fácil de agir no mapa inteiro a partir de um ponto só. Mantenha também as parts alvo ancoradas: a documentação de segurança da Roblox avisa que um exploiter pode tomar a posse de rede de parts não ancoradas perto dele e puxá-las para perto, o que dribla uma checagem de distância.

Aqui estão as mesmas checagens como um ModuleScript que você pode reaproveitar em todo handler de remote.

ModuleScript em ServerScriptService chamado RemoteGuard
local Players = game:GetService("Players")

local RemoteGuard = {}

-- Um número real entre min e max. Rejeita NaN e infinito, que passam em uma
-- checagem simples type(x) == "number".
function RemoteGuard.number(value: unknown, min: number, max: number): number?
	if type(value) ~= "number" or not math.isfinite(value) then
		return nil
	end
	if value < min or value > max then
		return nil
	end
	return value
end

-- Um número inteiro entre min e max, para contagens, índices e quantidades
function RemoteGuard.integer(value: unknown, min: number, max: number): number?
	local n = RemoteGuard.number(value, min, max)
	if n and n % 1 == 0 then
		return n
	end
	return nil
end

-- Texto com limite de tamanho. O utf8.len retorna nil para UTF-8 inválido, que os data
-- stores rejeitam.
function RemoteGuard.text(value: unknown, maxLength: number): string?
	if type(value) ~= "string" or #value > maxLength or utf8.len(value) == nil then
		return nil
	end
	return value
end

-- Uma Instance da classe esperada, dentro do contêiner que você permite.
-- Uma tabela montada para parecer uma Instance falha na checagem de typeof.
function RemoteGuard.instanceIn(value: unknown, className: string, container: Instance): Instance?
	if typeof(value) ~= "Instance" then
		return nil
	end
	if not value:IsA(className) or not value:IsDescendantOf(container) then
		return nil
	end
	return value
end

-- True quando o personagem do jogador está a até maxDistance studs de position
function RemoteGuard.isNear(player: Player, position: Vector3, maxDistance: number): boolean
	local character = player.Character
	local root = character and character:FindFirstChild("HumanoidRootPart")
	if not (root and root:IsA("BasePart")) then
		return false
	end
	return (root.Position - position).Magnitude <= maxDistance
end

-- Um limite de taxa por jogador. Cada jogador pode fazer `burst` chamadas de uma vez, e
-- ganha de volta `perSecond` chamadas a cada segundo. Retorna uma função para chamar
-- antes de fazer o trabalho: ela responde true (pode ir) ou false (rápido demais).
function RemoteGuard.limiter(burst: number, perSecond: number): (Player) -> boolean
	local buckets: { [Player]: { tokens: number, updated: number } } = {}

	Players.PlayerRemoving:Connect(function(player: Player)
		buckets[player] = nil
	end)

	return function(player: Player): boolean
		local now = os.clock()
		local bucket = buckets[player]
		if not bucket then
			bucket = { tokens = burst, updated = now }
			buckets[player] = bucket
		end
		bucket.tokens = math.min(burst, bucket.tokens + (now - bucket.updated) * perSecond)
		bucket.updated = now
		if bucket.tokens < 1 then
			return false
		end
		bucket.tokens -= 1
		return true
	end
end

return RemoteGuard

Deixe no ServerScriptService. O código dali nunca chega aos clientes, então ninguém consegue ler as suas checagens.

E aqui está o handler do Padrão 1 reescrito com ele. Substitua o conteúdo do PaintServer:

Script em ServerScriptService chamado PaintServer
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local ServerScriptService = game:GetService("ServerScriptService")

-- ":: any" só importa para o verificador de tipos estrito do Luau; não muda nada em tempo de execução
local RemoteGuard = require(ServerScriptService:WaitForChild("RemoteGuard")) :: any

local paintRequest = ReplicatedStorage:WaitForChild("Remotes"):WaitForChild("PaintRequest") :: RemoteEvent
local paintable = workspace:WaitForChild("Paintable")

local PALETTE = {
	Color3.fromRGB(231, 76, 60),
	Color3.fromRGB(46, 204, 113),
	Color3.fromRGB(52, 152, 219),
	Color3.fromRGB(241, 196, 15),
}
local canPaint = RemoteGuard.limiter(4, 4) -- uma rajada de 4, depois 4 por segundo

paintRequest.OnServerEvent:Connect(function(player: Player, partArg: unknown, colourArg: unknown)
	local part = RemoteGuard.instanceIn(partArg, "BasePart", paintable) :: BasePart?
	local colourIndex = RemoteGuard.integer(colourArg, 1, #PALETTE) :: number?
	if not part or not colourIndex then
		return
	end
	if not RemoteGuard.isNear(player, part.Position, 30) or not canPaint(player) then
		return
	end
	part.Color = PALETTE[colourIndex]
end)

O limitador remove a entrada de cada jogador quando ele sai, então a tabela dele não cresce durante a vida inteira do servidor.

As armas são onde essas checagens mais importam: nunca deixe o cliente dizer quem foi atingido. O remote do guia de espada não leva argumento nenhum, e o servidor acha os alvos sozinho. O guia de arma de fogo (em inglês) envia só um ponto de mira, que o servidor confere quanto a tipo, NaN e distância antes de lançar o próprio raio.

Os menus seguem a mesma regra: envie uma escolha, nunca o resultado. No guia de diálogo de NPC o cliente envia só o número do botão apertado, e o servidor procura o que aquela resposta dá. O menu do guia de teleporte envia o nome de um ponto, não uma posição, e o servidor acha o ponto na própria pasta e confere as Wins que ele exige.

O que dá e o que não dá para enviar

Você pode passar numbers, strings, booleans, tipos do Roblox como Vector3, CFrame, Color3 e itens de Enum, Instances que os dois lados enxergam, e tabelas com esses valores. Alguns valores mudam ou somem no caminho:

Argumentos que não chegam como foram enviados
Você enviaO que acontece
Uma funçãoO outro lado recebe nil
Uma tabela com metatableA metatable se perde, junto com tudo o que a tabela só tinha por meio dela
Uma tabela que mistura chaves numéricas e chaves stringA Roblox diz para não fazer: envie um array puro ou um dicionário puro
Uma tabela com valores nil dentroEvite: a Roblox desaconselha nil em qualquer índice
Uma tabela com chaves Instance, userdata ou funçãoEssas chaves são convertidas em strings
Uma Instance que quem recebe não enxerga, como uma no ServerStorage ou uma criada por um LocalScriptO outro lado recebe nil
Qualquer tabelaQuem recebe ganha uma cópia, nunca a mesma tabela

Um bom hábito é enviar identificadores em vez de objetos ou valores: o nome de um item, o índice de uma escolha, uma part que o servidor consegue procurar e conferir. O servidor então trabalha a partir dos próprios dados.

Por que uma RemoteFunction retorna nil

Se o InvokeServer devolve nil, passe por estes pontos em ordem:

  1. Um caminho sem valor de retorno. Toda saída do OnServerInvoke precisa retornar alguma coisa. Um return vazio em uma checagem inicial devolve nil.
  2. Um return dentro de uma função aninhada. Um return dentro de pcall(function() ... end), de um handler de :Connect ou de task.spawn só sai daquela função interna. Capture o resultado, por exemplo local ok, data = pcall(...), e depois retorne data do próprio callback.
  3. Um valor que não consegue atravessar. Uma função, ou uma Instance que o cliente não enxerga (qualquer coisa no ServerStorage, por exemplo), chega como nil. Com o instance streaming ligado, uma part que o servidor acabou de criar pode ainda não ter chegado ao cliente quando a função retorna.
  4. Outro script definiu o callback. Só a última atribuição ao OnServerInvoke roda. Procure o nome do remote nos seus scripts.

Se a chamada nunca retorna, nenhum script definiu o OnServerInvoke ainda (o Roblox põe as chamadas em fila até um definir), ou o callback está travado, por exemplo em um WaitForChild de algo que nunca aparece.

UnreliableRemoteEvent: para atualizações constantes e descartáveis

Um UnreliableRemoteEvent tem os mesmos métodos e eventos de um RemoteEvent: FireServer, FireClient, FireAllClients, OnServerEvent e OnClientEvent. A diferença é que o Roblox não garante nem a entrega nem a ordem. Uma mensagem pode ser descartada, sem reenvio, quando:

  • ela se perde no caminho, ou espera demais em uma rede congestionada
  • a carga dela é maior que 1.000 bytes
  • um cliente dispara mais rápido que o limite de taxa (o excesso é descartado, não atrasado)
  • nenhum handler está conectado quando ela chega (ela é descartada, não vai para a fila)

As mensagens também podem chegar fora de ordem, e não têm nenhuma relação de ordem com os seus RemoteEvents ou RemoteFunctions. Use um quando só o valor mais novo importa e a próxima atualização vem em uma fração de segundo: para onde um jogador está mirando, a posição de um efeito cosmético, um valor que muda a cada frame. Se a ordem importa, ponha um número de sequência ou um timestamp em cada mensagem e ignore tudo o que for mais antigo que a última que você tratou.

Nunca use um para algo que precisa acontecer exatamente uma vez, como uma compra, um dano, uma recompensa ou o começo de uma rodada. E valide os argumentos dele no servidor exatamente como faria com um RemoteEvent.

Ordem de entrega e limites de taxa

As garantias de entrega do Roblox valem para uma conexão em uma direção: do servidor para um cliente, ou de um cliente para o servidor.

  • RemoteEvents são confiáveis e ordenados. Mensagens perdidas são reenviadas enquanto o destinatário continua conectado, e as mensagens chegam na ordem em que você as disparou, mesmo entre RemoteEvents diferentes. Se o servidor dispara A, depois B, depois A para um jogador, esse jogador recebe A, B, A.
  • A ordem é sobre quando os handlers começam. Se um handler pausa, por exemplo com task.wait ou WaitForChild, a mensagem seguinte pode começar a ser tratada antes de a primeira terminar.
  • RemoteFunctions e RemoteEvents não são ordenados entre si. Se o seu código depende de ordem estrita, envie as mensagens relacionadas pelo mesmo tipo de remote, ou adicione o seu próprio número de sequência.
  • Mudanças de propriedade e de atributo não são ordenadas em relação aos remotes. Se o servidor muda uma propriedade e depois dispara um remote, o cliente pode ver qualquer um dos dois primeiro. Escute a própria mudança, por exemplo com GetPropertyChangedSignal, em vez de supor que ela já chegou.
  • Ainda sem handler. As mensagens de RemoteEvent ficam na fila até um handler conectar. A fila tem limites: quando enche, as mensagens seguintes são descartadas e o Output mostra um erro Remote event invocation discarded.
  • Um jogador que sai perde as mensagens que ainda não tinham chegado a ele.

Limite de taxa. As mensagens de RemoteEvent e de UnreliableRemoteEvent de um cliente para o servidor são limitadas a cerca de 500 requisições por segundo por cliente, conforme documentado em 30 de setembro de 2026. O limite é compartilhado por todos os remotes do mesmo tipo, então dividir um remote movimentado em dez não o aumenta. Acima do limite, as mensagens de RemoteEvent são processadas mais tarde e mantêm a ordem, enquanto as de UnreliableRemoteEvent são descartadas. O limite do motor não faz nada para impedir um jogador de disparar o seu remote 50 vezes por segundo, então todo handler que muda alguma coisa ainda precisa do próprio limite por jogador.

RemoteEvent, RemoteFunction, UnreliableRemoteEvent ou atributo?

Como escolher o jeito de o cliente e o servidor conversarem
UseParaExemploCuidado com
RemoteEventMensagens de mão única que precisam chegar, em ordemCliente: "pinte esta part". Servidor: "mostre este aviso"Valide todo argumento no servidor
RemoteFunction com InvokeServerO cliente precisa de uma resposta antes de continuarResgatar um código, confirmar uma compraQuem chama espera; todo caminho precisa retornar um valor
RemoteFunction com InvokeClientQuase nuncaUse FireClient no lugarUm cliente que dá erro, sai ou nunca responde quebra ou congela a chamada do servidor
UnreliableRemoteEventAtualizações frequentes em que só a mais recente importaDireção da mira, efeitos cosméticosMensagens perdidas ou reordenadas; limite de carga de 1.000 bytes
Atributo ou objeto de valor definido pelo servidorEstado compartilhado que deve estar sempre visível, inclusive para jogadores que entram depoisTimer da rodada, fase do jogo, o estado aberto de uma portaSó mudanças do servidor chegam a todos; os clientes escutam com GetAttributeChangedSignal ou Changed
BindableEventScripts do mesmo lado conversando entre siUm script de servidor avisando outro que uma rodada terminouNão atravessa entre servidor e cliente

Para um exemplo completo de RemoteFunctions e validação trabalhando juntas em algo pelo qual os jogadores pagam, veja como fazer uma GUI de loja. Sobre a linha do atributo, o script de servidor do guia de porta define um atributo Open em cada porta toda vez que ela se move, então qualquer LocalScript pode reagir a ele.

Erros comuns e como resolver

A maioria dos problemas com remotes aparece na janela Output (abra pelo menu Window ou pela aba Script). Olhe ali primeiro, depois compare com o sintoma abaixo. O guia de erros de script explica as mensagens de erro gerais com mais detalhe.

Infinite yield possible em um WaitForChild de um remote

Um script está esperando um remote que nunca chega. Confira que o nome e as maiúsculas batem exatamente, e que o remote está no ReplicatedStorage, não no ServerStorage nem no ServerScriptService, que os clientes não enxergam.

O servidor recebe os valores errados, deslocados em um

O LocalScript passou o próprio jogador, como em remote:FireServer(player, 5). O Roblox já adiciona quem enviou como primeiro parâmetro, então o servidor vê (player, player, 5). Chame remote:FireServer(5).

Nada acontece quando eu disparo o remote

Confira que cada chamada roda do lado certo: FireServer e InvokeServer só funcionam em código de cliente, e FireClient, FireAllClients e InvokeClient só em um Script de servidor. Um LocalScript nunca roda no ServerScriptService, no ServerStorage nem direto no Workspace; coloque em StarterPlayerScripts, StarterGui, StarterCharacterScripts ou StarterPack. Depois procure no Output um erro dentro do handler.

Remote event invocation discarded

Chegaram mensagens para um RemoteEvent que não tinha handler conectado, e a fila encheu. Normalmente o script do handler dá erro antes da linha do :Connect, está desativado, ou está travado esperando algo que nunca carrega. Conecte os handlers perto do topo do script.

Funciona para mim, mas os outros jogadores não veem a mudança

A mudança foi feita no cliente, em um LocalScript ou em um handler de OnClientEvent. Faça a mudança no handler OnServerEvent do servidor.

O InvokeServer nunca retorna

Ou nenhum script definiu o OnServerInvoke (o Roblox põe as chamadas em fila até um definir), ou o callback está travado em algo que pausa, como um WaitForChild ou uma requisição a um data store. Adicione um print no começo e no fim do callback para ver onde ele para.

Crie com o RoCode

Você também pode pedir ao RoCode para montar isso no jogo que você tem aberto. O RoCode é um agente de IA que trabalha por meio de um plugin do Roblox Studio, então ele cria os remotes e os scripts no seu Explorer em vez de dar código para você colar.

Você digita

Deixe os jogadores clicarem em parts da pasta Paintable para pintá-las. Use um RemoteEvent, e mantenha as checagens no servidor: só parts dessa pasta, a até 30 studs, e não mais que algumas pinturas por segundo.

O RoCode faz
  • Normalmente olha o jogo primeiro, com Search Game e Search Scripts, atrás de uma pasta Remotes ou de um handler que já exista, e usa as suas pastas quando elas estão lá
  • Cria o RemoteEvent no ReplicatedStorage com Create Instance, e escreve o Script de servidor e o LocalScript com Create Script
  • Checa a compilação de cada script com Check Script dentro do Studio antes de terminar. Isso pega erros de compilação, não bugs de lógica: não verifica tipos, não faz lint e não roda o seu código
  • Envia as mudanças em lotes, e cada lote é um ponto de desfazer no histórico do Studio

Com o plugin 3.9 ou mais recente, o RoCode pode rodar um teste curto e ler os erros, e com o plugin 3.9.11 ou mais recente ele pode controlar um personagem de teste, mas ele não clica em parts na vista 3D. Aperte Play você mesmo e tente quebrar as checagens, por exemplo pintando do outro lado do mapa. Se algo der erro, o Check Output consegue ler as linhas de Server e Client do seu último teste. A maioria dos sistemas de jogo conversa por remotes como estes, então eles voltam a aparecer quando você monta um jogo sistema por sistema com o RoCode. Como o RoCode se conecta ao Studio.

Perguntas frequentes

O que significa proteger a fronteira cliente-servidor no Roblox?

É o nome da página da documentação da Roblox sobre segurança de remotes ("Securing the client-server boundary"), e a ideia é simples: tudo o que um cliente envia por um RemoteEvent ou uma RemoteFunction pode vir de um exploiter, então o servidor confere antes de agir. Confira o tipo de cada argumento, mantenha os números em um intervalo razoável, confira se o jogador tem permissão de fazer aquilo naquele momento, e limite a frequência com que cada jogador pode disparar. A lista de validação acima mostra cada um desses pontos em código.

É seguro usar RemoteFunctions?

O InvokeServer é tão seguro quanto o seu callback de servidor: valide os argumentos e limite a taxa como em qualquer RemoteEvent. O InvokeClient é a direção arriscada, porque um cliente que dá erro, sai ou nunca retorna quebra ou congela a chamada do servidor.

Os exploiters conseguem ver e disparar os meus remotes?

Sim. Tudo o que está no ReplicatedStorage chega a todo cliente, e um cliente modificado pode disparar qualquer remote com quaisquer argumentos. Renomear ou esconder os remotes não os deixa seguros; conferir todo argumento no servidor, sim.

Um cliente pode enviar um RemoteEvent para outro cliente?

Não diretamente. Dispare para o servidor, confira lá, depois use FireClient ou FireAllClients.

Com que frequência posso disparar um RemoteEvent?

A Roblox documenta um limite de cerca de 500 requisições por segundo por cliente para mensagens de RemoteEvent e UnreliableRemoteEvent enviadas ao servidor, compartilhado por todos os remotes do mesmo tipo. Fique bem abaixo disso, e dê a cada handler o próprio limite por jogador.

O FireAllClients alcança jogadores que entram depois?

Não. Ele alcança os jogadores conectados naquele momento. Para estado de que quem entra depois precisa, defina um atributo ou um objeto de valor no servidor.

Qual é a diferença entre um RemoteEvent e um BindableEvent?

Um RemoteEvent atravessa entre servidor e cliente. Um BindableEvent conecta scripts do mesmo lado, como dois scripts de servidor.

Fontes e leitura extra

Como o código foi verificado: todo script desta página passa no verificador de tipos estrito do Luau com as definições da API do Roblox (luau-lsp, 12 de novembro de 2026). A verificação de tipos pega APIs com nome errado e tipos incorretos, não a lógica do jogo, então teste no Studio antes de publicar.

Teste o RoCode no seu próprio jogo.

Créditos grátis todo dia, sem cartão. Instale o plugin, descreva o recurso e confira o que aparece no Studio.