roblox-remote-events

---
name: roblox-remote-events
description: Use when implementing client-server communication in Roblox, firing events between LocalScripts and Scripts, passing data across the network boundary, syncing game state, or defending against exploits that abuse RemoteEvents or RemoteFunctions.
---

# Roblox Remote Events & Functions

## RemoteEvent vs RemoteFunction

| Type | Direction | Returns value? | Use when |
|---|---|---|---|
| `RemoteEvent` | Any direction | No (fire-and-forget) | Notifying server of player action, broadcasting state |
| `RemoteFunction` | Client→Server | Yes (yields caller) | Client needs a result back (e.g. fetch inventory) |
| `UnreliableRemoteEvent` | Any direction | No | High-frequency updates where dropped packets are fine |

**Default to RemoteEvent.** Avoid server→client `RemoteFunction` — an exploiter's frozen callback stalls your server thread indefinitely.

---

## Where to Put Remotes

Always store Remotes in `ReplicatedStorage`. Create them from a server Script that runs before any LocalScript.

```
ReplicatedStorage/
  Remotes/
    DealDamage        (RemoteEvent)
    GetInventory      (RemoteFunction)
    SyncPosition      (UnreliableRemoteEvent)
```

```lua
-- Script in ServerScriptService
local folder = Instance.new("Folder")
folder.Name = "Remotes"
folder.Parent = game:GetService("ReplicatedStorage")

local function make(class, name)
    local r = Instance.new(class)
    r.Name = name
    r.Parent = folder
    return r
end

make("RemoteEvent",           "DealDamage")
make("RemoteFunction",        "GetInventory")
make("UnreliableRemoteEvent", "SyncPosition")
```

---

## Firing Patterns

### Client → Server (FireServer)

```lua
-- LocalScript
local DealDamage = game:GetService("ReplicatedStorage").Remotes:WaitForChild("DealDamage")
DealDamage:FireServer({ targetId = 12345, amount = 50 })
-- First arg on server is always the firing Player (injected automatically, cannot be spoofed)
```

```lua
-- Script (server) — VALIDATE everything in the payload
DealDamage.OnServerEvent:Connect(function(player, data)
    -- player identity is trustworthy; data contents are not
end)
```

### Server → One Client

```lua
local Notify = game:GetService("ReplicatedStorage").Remotes:WaitForChild("Notify")
Notify:FireClient(player, { message = "Welcome!" })
```

```lua
-- LocalScript
Notify.OnClientEvent:Connect(function(data)
    print(data.message)
end)
```

### Server → All Clients

```lua
AnnounceEvent:FireAllClients({ text = "Game starting in 10 seconds!" })
```

### RemoteFunction (Client Calls, Server Returns)

```lua
-- Script (server)
GetInventory.OnServerInvoke = function(player)
    return getPlayerInventory(player.UserId)
end
```

```lua
-- LocalScript
local inventory = GetInventory:InvokeServer()  -- yields until server returns
```

### UnreliableRemoteEvent (High-Frequency Sync)

```lua
-- LocalScript
RunService.Heartbeat:Connect(function()
    SyncPosition:FireServer(character.HumanoidRootPart.CFrame)
end)
```

```lua
-- Script (server) — still validate
SyncPosition.OnServerEvent:Connect(function(player, cframe)
    if typeof(cframe) ~= "CFrame" then return end
    -- apply with sanity bounds check
end)
```

---

## CRITICAL: Server-Side Security

**The client is hostile. Treat every argument as untrusted input.**

```lua
local MAX_DAMAGE = 100
local COOLDOWNS = {}
local COOLDOWN_SECONDS = 0.5

DealDamage.OnServerEvent:Connect(function(player, data)
    -- 1. Rate limit
    local now = tick()
    if COOLDOWNS[player.UserId] and now - COOLDOWNS[player.UserId] < COOLDOWN_SECONDS then
        return
    end
    COOLDOWNS[player.UserId] = now

    -- 2. Type checks
    if type(data) ~= "table" then return end
    if type(data.targetId) ~= "number" then return end
    if type(data.amount) ~= "number" then return end

    -- 3. Range clamp
    local amount = math.clamp(data.amount, 0, MAX_DAMAGE)

    -- 4. Server-side weapon lookup — never trust client-provided Instance
    local weapon = getEquippedWeapon(player)
    if not weapon then return end

    -- 5. Server-side target lookup
    local target = getPlayerByUserId(data.targetId)
    if not target then return end

    applyDamage(target, amount, player)
end)
```

---

## Exploit Patterns & Defenses

| Exploit | What the attacker does | Defense |
|---|---|---|
| Argument injection | Sends unexpected types to crash handler | Type-check all arguments |
| Damage amplification | Sends `amount = math.huge` | Clamp to sane maximum |
| Remote spam | Fires thousands of times per second | Per-player cooldown |
| Spoofed target | Sends another player's UserId | Server resolves from its own state |
| Infinite yield | Never returns from `OnClientEvent` callback | Avoid server→client RemoteFunction |
| Duplicate action | Replays a valid fire to buy twice | Check state / consume token before acting |

---

## Quick Reference

```
FireServer(args)            LocalScript → server
FireClient(player, args)    server → one client
FireAllClients(args)        server → every client
InvokeServer(args)          LocalScript → server, waits for return
OnServerEvent               server-side listener for FireServer
OnClientEvent               client-side listener for FireClient/FireAllClients
OnServerInvoke              server-side function assigned for InvokeServer
```

---

## Common Mistakes

| Mistake | Fix |
|---|---|
| `OnServerEvent` in a LocalScript | Use `OnClientEvent` on client; `OnServerEvent` is server-only |
| Remotes in ServerStorage | Move to ReplicatedStorage |
| Trusting payload beyond player identity | Validate every field in the payload |
| Server→client RemoteFunction | Use RemoteEvent; frozen client stalls server thread |
| No `WaitForChild` in LocalScript | Remotes may not exist yet; always use `WaitForChild` |
| Multiple `OnServerInvoke` assignments | Only the last assignment wins; keep it in one place |
| Firing inside tight loop without throttle | Use `UnreliableRemoteEvent` or accumulate delta time |