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 (
InvokeServereOnServerInvoke) só quando o cliente precisa de uma resposta. Evite oInvokeClient: 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
Por que os RemoteEvents existem
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.
| Direção | Quem envia chama | Quem recebe conecta em | Quem recebe ganha |
|---|---|---|---|
| Do cliente para o servidor | remote:FireServer(...) em um LocalScript | remote.OnServerEvent em um Script | O Player que disparou, depois os seus argumentos |
| Do servidor para um cliente | remote:FireClient(player, ...) em um Script | remote.OnClientEvent em um LocalScript | Só os seus argumentos |
| Do servidor para todos os clientes | remote:FireAllClients(...) em um Script | remote.OnClientEvent em um LocalScript | Só os seus argumentos |
| O cliente pergunta, o servidor responde | remoteFunction: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.
- No Explorer, passe o mouse sobre ReplicatedStorage, clique no botão + e insira uma Folder. Dê o nome
Remotes. - Passe o mouse sobre
Remotes, clique em + e insira um RemoteEvent. Renomeie para descrever a função dele, por exemploPaintRequest. - Repita para cada remote. Este guia usa dois RemoteEvents (
PaintRequesteNotify) e uma RemoteFunction (RedeemCode).
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.
- No Workspace, insira uma Folder chamada
Paintablee coloque nela algumas Parts ancoradas. - Confira que
ReplicatedStorage.Remotestem um RemoteEvent chamadoPaintRequest. - Insira um Script no ServerScriptService chamado
PaintServer, e um LocalScript em StarterPlayer, StarterPlayerScripts chamadoPaintClient, com o código abaixo.
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.
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.
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
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.
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.
- Em
ReplicatedStorage.Remotes, insira uma RemoteFunction chamadaRedeemCode. - No StarterGui, insira um ScreenGui chamado
CodeGui, e dentro dele uma TextBox chamadaCodeBox. Dê o tamanho e a posição que quiser. - Adicione o Script abaixo ao ServerScriptService, e o LocalScript dentro da
CodeBox.
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.
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
InvokeClientlanç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.
| Checagem | A pergunta que o servidor faz | Exemplo |
|---|---|---|
| Tipo | É o tipo que eu espero? Uma Instance, e não uma tabela montada para parecer uma? | typeof(part) == "Instance" and part:IsA("BasePart") |
| Intervalo | O 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 |
| Posse | Este 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ância | O 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 |
| Taxa | Este 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.
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:
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:
| Você envia | O que acontece |
|---|---|
| Uma função | O outro lado recebe nil |
| Uma tabela com metatable | A metatable se perde, junto com tudo o que a tabela só tinha por meio dela |
| Uma tabela que mistura chaves numéricas e chaves string | A Roblox diz para não fazer: envie um array puro ou um dicionário puro |
Uma tabela com valores nil dentro | Evite: a Roblox desaconselha nil em qualquer índice |
| Uma tabela com chaves Instance, userdata ou função | Essas chaves são convertidas em strings |
| Uma Instance que quem recebe não enxerga, como uma no ServerStorage ou uma criada por um LocalScript | O outro lado recebe nil |
| Qualquer tabela | Quem 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:
- Um caminho sem valor de retorno. Toda saída do
OnServerInvokeprecisa retornar alguma coisa. Umreturnvazio em uma checagem inicial devolvenil. - Um return dentro de uma função aninhada. Um
returndentro depcall(function() ... end), de um handler de:Connectou detask.spawnsó sai daquela função interna. Capture o resultado, por exemplolocal ok, data = pcall(...), e depois retornedatado próprio callback. - 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. - Outro script definiu o callback. Só a última atribuição ao
OnServerInvokeroda. 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.waitouWaitForChild, 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?
| Use | Para | Exemplo | Cuidado com |
|---|---|---|---|
| RemoteEvent | Mensagens de mão única que precisam chegar, em ordem | Cliente: "pinte esta part". Servidor: "mostre este aviso" | Valide todo argumento no servidor |
RemoteFunction com InvokeServer | O cliente precisa de uma resposta antes de continuar | Resgatar um código, confirmar uma compra | Quem chama espera; todo caminho precisa retornar um valor |
RemoteFunction com InvokeClient | Quase nunca | Use FireClient no lugar | Um cliente que dá erro, sai ou nunca responde quebra ou congela a chamada do servidor |
| UnreliableRemoteEvent | Atualizações frequentes em que só a mais recente importa | Direção da mira, efeitos cosméticos | Mensagens perdidas ou reordenadas; limite de carga de 1.000 bytes |
| Atributo ou objeto de valor definido pelo servidor | Estado compartilhado que deve estar sempre visível, inclusive para jogadores que entram depois | Timer da rodada, fase do jogo, o estado aberto de uma porta | Só mudanças do servidor chegam a todos; os clientes escutam com GetAttributeChangedSignal ou Changed |
| BindableEvent | Scripts do mesmo lado conversando entre si | Um script de servidor avisando outro que uma rodada terminou | Nã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.
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.
- 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
- Roblox Creator Docs: Remote events and callbacks (em inglês). FireServer, FireClient, InvokeServer, riscos do InvokeClient, limitações de argumentos e garantias de entrega
- Roblox Creator Docs: Securing the client-server boundary (em inglês). Camadas de validação, NaN, limite de taxa, repasses de cliente para cliente
- Roblox Creator Docs: Security and cheat mitigation tactics (em inglês). O que um cliente modificado consegue fazer, e a autoridade do servidor
- Roblox Creator Docs: Network ownership, movement validation, and physics (em inglês). Por que um cliente controla o próprio personagem, e os limites das checagens de distância
- Roblox Engine API: RemoteEvent (em inglês). Limite de taxa e o erro invocation discarded
- Roblox Engine API: RemoteFunction (em inglês). OnServerInvoke, avisos sobre o InvokeClient e cuidados com streaming
- Roblox Engine API: UnreliableRemoteEvent (em inglês). O limite de carga de 1.000 bytes
- Roblox Creator Docs: Properties and attributes (em inglês). Ordem de replicação entre mudanças de propriedade e remote events
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.