Installation

Drop the RoExpress folder into ReplicatedStorage. RoExpress creates its own remotes automatically — you don't touch them.

copygame.ReplicatedStorage
  └── Modules
      └── Libraries
          └── RoExpress          ← root ModuleScript (init.luau)
              ├── App            ← ModuleScript
              ├── Network        ← ModuleScript
              ├── Broadcast      ← ModuleScript
              ├── Listener       ← ModuleScript
              ├── Router         ← ModuleScript
              ├── Codec          ← ModuleScript
              ├── Bridge         ← ModuleScript
              ├── TokenBucket    ← ModuleScript
              └── Base64         ← ModuleScript

Quick Start

Server

copylocal RoExpress = require(game.ReplicatedStorage.Modules.Libraries.RoExpress)
local app       = RoExpress("App")
local broadcast = RoExpress("Broadcast")
local bridge    = RoExpress("Bridge")

-- middleware — runs before every request
app:Use("logger", function(Player, Payload)
    print(Player.Name, Payload.method, Payload.route)
end)

-- typed param — req.params.userId is already a Lua number
app:Get("player/:userId=number", function(Player, Payload, req, res)
    res:Send({ userId = req.params.userId })
end)

-- server push — reliable, no client request needed
app:PushAll("roundEnd", { winner = "PlayerName" })

-- internal bus — fire to other server modules
bridge.Fire("playerJoined", { player = game.Players.LocalPlayer })

Client

copylocal RoExpress = require(game.ReplicatedStorage.Modules.Libraries.RoExpress)
local network  = RoExpress("Network")
local listener = RoExpress("Listener")
local bridge   = RoExpress("Bridge")

-- GET request
network:Get("player/123", nil, function(res)
    if res.type == "error" then return end
    print(res.data.userId)
end)

-- listen to reliable push AND unreliable broadcast — same API
listener:On("roundEnd", function(data)
    print("Winner:", data.winner)
end)

-- yield until an internal event fires (client-side bus)
local data = bridge.Wait("uiReady", 10)

Request Pipeline

Every incoming request flows through a fixed sequence. Each step can terminate the request early with a specific status code.

Status codes

App

Handles all incoming client requests. Owns its own Router and TokenBucket instance — no shared global state.

copylocal app = RoExpress("App")

Routing

Middleware

Return false to block with 403. Throw to send 500. Return nothing to continue.

copyapp:Use("auth", function(Player, Payload)
    if not isAuth(Player) then return false end
end)

Server Push

Reliable server-to-client events over the RemoteEvent. Received by listener:On(event). Guaranteed delivery.

req object

res object

Called when a typed route param fails coercion. If not registered, failures return 400 automatically.

Broadcast

Unreliable fire-and-forget events to clients over the UnreliableRemoteEvent. Subject to per-event and per-player rate limiting. Use for drop-tolerant, high-frequency events.

copylocal broadcast = RoExpress("Broadcast")

Rate limits

Network

Fires requests to the server and resolves responses via callbacks. Client-only.

copylocal network = RoExpress("Network")

NetworkResponse

Listener

Subscribes to events from the server. Handles both unreliable broadcasts and reliable server pushes through a single API — two connections, one interface.

copylocal listener = RoExpress("Listener")

Persistent subscription. Fires every time the event arrives from either channel.

Fires once then auto-unsubscribes. Safe against race conditions — handler is removed before being called.

Removes both On and Once handlers for the event.

Middleware runs before every handler regardless of source channel.

copy-- both events arrive through the same listener
listener:On("roundEnd", function(data)   -- reliable push
    UI:ShowWinner(data.winner)
end)
listener:On("killPing", function(data)   -- unreliable broadcast
    HUD:FlashKill()
end)

Router NEW

The advanced route matching engine powering app:Get and app:Post. Routes are sorted by specificity on registration — most specific always wins regardless of declaration order.

Segment syntax

Supported param types

copy-- all four coexist, priority order is automatic
app:Get("player/:id=number/coins", h1) -- wins for "player/123/coins"
app:Get("player/:id/coins",        h2)
app:Get("player/*/coins",           h3) -- req.captures[1] = segment
app:Get("player/**",                h4) -- req.captures[1] = table

Server Push NEW

Reliable one-way server-to-client communication. No request needed — the server initiates. The client receives via the existing Listener.

Push vs Broadcast

copy-- server
app:Push(player, "inventoryUpdate", { item = "sword" })
app:PushAll("roundEnd", { winner = "PlayerA" })
app:PushTo({ p1, p2 }, "zoneAlert", { zoneId = 3 })

-- client — same listener, zero API change
listener:On("inventoryUpdate", function(data) print(data.item) end)
listener:Once("roundEnd", function(data) UI:ShowWinner(data.winner) end)

Codec NEW

LZ77 sliding-window compression using Roblox's native buffer type. Opt-in per route. Completely transparent to both the handler and the client callback.

copy-- server — add { compress = true }
app:Get("feed/all", function(Player, Payload, req, res)
    res:Send(bigTable)  -- auto-compressed
end, { compress = true })

-- client — arrives already decompressed
network:Get("feed/all", nil, function(res)
    print(res.data)  -- plain Lua table
end)

How it works

The payload is JSON-encoded, compressed with LZ77 (4096-byte sliding window, minimum match 4 bytes), prefixed with a 2-byte magic header 0xC0 0xDE, then base64-encoded for transport. Network detects the magic header and decompresses before your callback fires.

Direct API

copylocal Codec = require(script.Parent.Codec)
Codec.Compress(data)       -- any → base64 string
Codec.Decompress(str)      -- base64 string → any
Codec.IsCompressed(str)    -- → boolean

Bridge NEW

A shared internal event bus — a structured replacement for raw BindableEvents. Available in both server and client contexts as a singleton. No remote involved: this is purely in-process communication between modules within the same context.

copylocal bridge = RoExpress("Bridge")  -- same instance everywhere in this context

Core API

Register a handler on a named channel. Multiple handlers per channel are supported — all fire in registration order.

Remove a specific handler by reference. Logs a warning if not found.

Clear all handlers on one channel, or every channel if no name is given.

Fire to all handlers on the channel. Handlers are snapshot'd before iteration so Unbind inside a handler is safe. Each handler is pcall'd — a crash in one doesn't stop the rest.

Returns true if the channel has at least one bound handler. Useful to guard Fire calls in hot paths.

copy-- ModuleA (DataService) — no reference to App needed
bridge.Bind("playerDataLoaded", function(data)
    LeaderboardService.Refresh(data.userId)
end)

-- ModuleB (PlayerService) — just fire, no coupling
bridge.Fire("playerDataLoaded", { userId = player.UserId, coins = 500 })

Yieldable variants

All three yield the current coroutine and resume it when the condition is met or the timeout expires. A temporary internal handler is registered and always cleaned up — no coroutine leaks.

Yields until the named channel fires once. Returns the data, or nil on timeout. Default timeout: 10 seconds.

Yields until the channel fires AND the predicate returns true. Non-matching fires are silently skipped — the coroutine stays yielded.

Yields until any one of the listed channels fires. Returns the winning channel name and its data. All internal handlers on losing channels are cleaned up after resolution.

copy-- Wait — yield until channel fires
local data = bridge.Wait("round.start", 30)
if data then print("started:", data.duration) end

-- WaitUntil — skip fires that don't match predicate
local data = bridge.WaitUntil("kill", function(d)
    return d.victim == LocalPlayer.Name
end, 60)

-- WaitFirst — whichever channel fires first wins
local event, data = bridge.WaitFirst({
    "round.start",
    "server.shutdown"
}, 60)
if event == "round.start" then
    print("Round started")
elseif event == "server.shutdown" then
    print("Server going down")
else
    print("Timed out")
end

TokenBucket

Per-instance rate limiter. App and Broadcast each own independent instances — they can never affect each other's state. Buckets are seeded for players already in the server on creation.

copy-- exposed on the App instance
local tb = app.TokenBucket

tb:GrantAll(5)                 -- reward burst after round
tb:GrantExact(winnerPlayer, 10) -- ignores Max cap
tb:Reset(player)               -- refill to Max immediately

Methods

Default: Max = 10, Refill = 2 tokens/second.

Base64

Lightweight encoder/decoder. Used internally for POST responses. Available directly if needed.

copylocal Base64 = RoExpress("Base64")

Base64.Encode("hello")               -- → base64 string
Base64.Decode("aGVsbG8=")            -- → "hello"
Base64.EncodeTable({ x = 1 })        -- JSONEncode then base64
Base64.DecodeTable("eyJ4IjoxfQ==")  -- base64 then JSONDecode

Exported Types

copylocal RoExpress = require(path.RoExpress)

-- envelope
type Payload           = RoExpress.Payload
type Request           = RoExpress.Request
type Response          = RoExpress.Response
type NetworkResponse   = RoExpress.NetworkResponse
type BroadcastEnvelope = RoExpress.BroadcastEnvelope

-- handlers
type RouteHandler      = RoExpress.RouteHandler
type MiddlewareHandler = RoExpress.MiddlewareHandler  -- returns boolean?
type BroadcastHandler  = RoExpress.BroadcastHandler
type NetworkCallback   = RoExpress.NetworkCallback

-- modules
type App       = RoExpress.App
type Network   = RoExpress.Network
type Broadcast = RoExpress.Broadcast
type Listener  = RoExpress.Listener
type Router    = RoExpress.Router
type Codec     = RoExpress.Codec
type Bridge    = RoExpress.Bridge

-- bridge sub-types
type BridgeHandler   = Bridge.Handler
type BridgePredicate = Bridge.Predicate

-- router sub-types
type ParamType   = RoExpress.ParamType
type SegmentKind = RoExpress.SegmentKind
type MatchResult = RoExpress.MatchResult

Tamper NEW

Exploit detection and tamper reporting. Passively hooks into App's request pipeline and surfaces suspicious activity as structured reports. Server-only singleton.

copylocal tamper = RoExpress("Tamper")

-- subscribe to all detection events
tamper.On(function(report)
    print(report.player.Name, report.reason, report.severity, report.strikes)
end)

-- optional: auto-kick at 10 strikes
tamper.AutoKick(10, "Exploiting detected")

Detection tiers

Report object

Manual strikes

Use tamper.Strike() inside your own route handlers for business-logic violations Tamper can't detect generically — negative currency, impossible positions, out-of-range values.

copyapp:Post("shop/buy", function(Player, Payload, req, res)
    if req.data.amount < 0 then
        tamper.Strike(Player, "Negative purchase amount", "shop/buy", req.data)
        res:Status(400):Error("Invalid amount")
        return
    end
end)

Full API

Register the detection handler. One handler supported — calling again replaces the previous.

Enable auto-kick when a player reaches the strike threshold. Fires after the handler so you can log first.

Manually issue an immediate strike from your own validation logic.

Returns the full accumulated record for a player, or nil if no strikes on record.

Returns the current strike count. Returns 0 if no record exists.

Reset a player's record. Useful after a false positive or manual review.

Reset all player records. Useful on round transitions.

copytamper.SetThresholds({
    rateFloodWindow = 10,  -- seconds before rate flood window resets
    rateFloodCount  = 5,   -- 429s within window to trigger pattern strike
    routeScanCount  = 8,   -- distinct unknown routes to trigger scan strike
    paramFloodCount = 5,   -- repeated param fails on same route
})

Full example

copylocal tamper = RoExpress("Tamper")

tamper.AutoKick(10, "Cheating detected")

tamper.On(function(report)
    if report.severity == "immediate" then
        warn(string.format(
            "[Tamper] %s — %s on '%s' (strike %d)",
            report.player.Name, report.reason,
            report.route or "?", report.strikes
        ))
    elseif report.severity == "pattern" then
        warn(string.format(
            "[Tamper] PATTERN DETECTED — %s: %s (total strikes: %d)",
            report.player.Name, report.reason, report.strikes
        ))
        -- notify admins, log to external service, etc.
    end
end)

Kill Feed

Touches every layer — typed params, compression, server push, broadcast, wildcard routes, and middleware.

Server

copylocal app       = RoExpress("App")
local broadcast = RoExpress("Broadcast")
local bridge    = RoExpress("Bridge")
local killFeed  = {}

app:Use("logger", function(Player, Payload)
    print(Player.Name, Payload.method, Payload.route)
end)

app:Post("stats/save", function(Player, Payload, req, res)
    local entry = { killer=req.data.killerName, victim=req.data.victimName, weapon=req.data.weapon, timestamp=os.time() }
    table.insert(killFeed, 1, entry)
    app:PushAll("killFeed.entry", entry)          -- reliable
    broadcast:EmitAll("killFeed.ping", { killer=req.data.killerName, victim=req.data.victimName }) -- unreliable
    bridge.Fire("kill.registered", entry)           -- internal bus
    res:Send({ success = true })
end)

app:Get("stats/:userId=number", function(Player, Payload, req, res)
    res:Send(stats[req.params.userId])  -- userId already a number
end)

app:Get("feed/all",    handler, { compress = true })
app:Get("feed/recent", handler)  -- ?limit=20
app:Get("feed/*/kills", handler) -- req.captures[1] = period

Client

copylistener:On("killFeed.entry", function(data) FeedUI:Add(data) end)
listener:On("killFeed.ping",  function(data) HUD:Flash(data) end)
network:Get("feed/all", nil, function(res) FeedUI:Load(res.data.entries) end)

Round Manager

Countdown via broadcast ticks, start/end via reliable push, Bridge for internal module coordination.

copylocal ROUND_TIME = 120
local roundActive = false

app:Post("round/start", function(Player, Payload, req, res)
    if roundActive then res:Status(400):Error("Already active"); return end
    roundActive = true
    app:PushAll("round.start", { duration = ROUND_TIME })
    bridge.Fire("round.began", { duration = ROUND_TIME }) -- notify server modules
    task.spawn(function()
        local t = ROUND_TIME
        while t > 0 and roundActive do
            broadcast:EmitAll("round.tick", { timeLeft = t })
            task.wait(1); t -= 1
        end
        if roundActive then
            roundActive = false
            app:PushAll("round.end", { reason = "timeout" })
        end
    end)
    res:Send({ started = true })
end)

app:Post("round/end", function(Player, Payload, req, res)
    roundActive = false
    app:PushAll("round.end", { winner = req.data.winner })
    app.TokenBucket:GrantAll(5)
    res:Send({ ok = true })
end)

-- another module waits for round start without coupling
bridge.Bind("round.began", function(data)
    SpawnService.SpawnAllPlayers()
end)

Shop / Purchase Flow

Server-authoritative — validates stock and currency, deducts, then pushes the inventory update reliably.

copyapp:Get("shop/catalogue", function(Player, Payload, req, res)
    res:Send(catalogue)
end)

app:Get("shop/balance/:userId=number", function(Player, Payload, req, res)
    res:Send({ balance = currency[req.params.userId] or 0 })
end)

app:Post("shop/buy", function(Player, Payload, req, res)
    local item = catalogue[req.data and req.data.itemId]
    if not item                               then res:Status(404):Error("Not found");      return end
    if item.stock <= 0                         then res:Status(400):Error("Out of stock");   return end
    if (currency[Player.UserId] or 0) < item.price then res:Status(400):Error("Insufficient funds"); return end
    currency[Player.UserId] -= item.price; item.stock -= 1
    app:Push(Player, "shop.purchased", { item = req.data.itemId, balance = currency[Player.UserId] })
    res:Send({ success = true })
end)

Admin Commands

Route-level auth via middleware, typed boolean and number params, push-based announcements.

copylocal ADMINS = { [123456789] = true }

app:Use("admin-guard", function(Player, Payload)
    if Payload.route:match("^admin/") and not ADMINS[Player.UserId] then
        return false  -- 403
    end
end)

app:Post("admin/kick/:userId=number", function(Player, Payload, req, res)
    local target = game.Players:GetPlayerByUserId(req.params.userId)
    if not target then res:Status(404):Error("Not in server"); return end
    target:Kick(req.data and req.data.reason or "Kicked")
    res:Send({ kicked = target.Name })
end)

app:Post("admin/god/:userId=number/:state=boolean", function(Player, Payload, req, res)
    -- req.params.state is already a boolean, req.params.userId already a number
    app:Push(game.Players:GetPlayerByUserId(req.params.userId), "admin.god", { enabled = req.params.state })
    res:Send({ ok = true })
end)

app:Post("admin/announce", function(Player, Payload, req, res)
    app:PushAll("admin.announce", { message = req.data.message, from = Player.Name })
    res:Send({ ok = true })
end)

Friend Zone / Proximity

Server zone detection loop pushes enter/exit events reliably. Client fetches nearby players on demand.

copylocal zones = { spawn = { center=Vector3.new(0,0,0), radius=30 } }
local playerZone = {}

app:Get("zone/:name/players", function(Player, Payload, req, res)
    if not zones[req.params.name] then res:Status(404):Error("Unknown zone"); return end
    local inside = {}
    for uid, z in pairs(playerZone) do
        if z == req.params.name then table.insert(inside, game.Players:GetPlayerByUserId(uid).Name) end
    end
    res:Send({ players = inside })
end)

task.spawn(function()
    while true do
        task.wait(2)
        for _, player in ipairs(game.Players:GetPlayers()) do
            local char = player.Character; if not char then continue end
            local pos  = char:GetPivot().Position
            local prev = playerZone[player.UserId]; local curr = nil
            for name, zone in pairs(zones) do
                if (pos - zone.center).Magnitude <= zone.radius then curr = name; break end
            end
            if curr ~= prev then
                playerZone[player.UserId] = curr
                if     curr then app:Push(player, "zone.enter", { zone=curr })
                elseif prev then app:Push(player, "zone.exit",  { zone=prev }) end
            end
        end
    end
end)

Leaderboard

Compressed paginated fetch on join, live push on score change so clients stay current without polling.

copyapp:Get("leaderboard/top", function(Player, Payload, req, res)
    local limit  = math.min(tonumber(req.query.limit) or 10, 100)
    local offset = tonumber(req.query.offset) or 0
    res:Send({ entries = slice(scores, offset, limit), total = #scores })
end, { compress = true })

app:Get("leaderboard/rank/:userId=number", function(Player, Payload, req, res)
    local entry = findByUserId(scores, req.params.userId)
    if not entry then res:Status(404):Error("Not ranked"); return end
    res:Send(entry)
end)

app:Post("leaderboard/submit", function(Player, Payload, req, res)
    upsertScore(Player, req.data.score)
    rebuildRankings()
    app:PushAll("leaderboard.update", { top10 = { table.unpack(scores,1,10) } })
    res:Send({ rank = getRank(Player) })
end)

Player Data Save & Load

Push data on join so no client request is needed. Bridge notifies other server modules when data is ready.

copygame.Players.PlayerAdded:Connect(function(player)
    local ok, data = pcall(store.GetAsync, store, tostring(player.UserId))
    data = (ok and data) or defaultData()
    app:Push(player, "data.loaded", data)          -- push to client
    bridge.Fire("playerDataReady", { player=player, data=data }) -- notify server modules
end)

app:Get("data/me", function(Player, Payload, req, res)
    local ok, data = pcall(store.GetAsync, store, tostring(Player.UserId))
    res:Send((ok and data) or defaultData())
end, { compress = true })

app:Post("data/save", function(Player, Payload, req, res)
    local ok, err = pcall(store.SetAsync, store, tostring(Player.UserId), req.data)
    if not ok then res:Status(500):Error(err); return end
    res:Send({ saved = true })
end)

Matchmaking Queue

Join/leave via POST, position updates via push, PushTo fires the match-found notification to exactly the right players. Bridge signals an internal match-ready event.

copylocal MATCH_SIZE = 4; local queue = {}

local function pushPositions()
    for i, p in ipairs(queue) do app:Push(p, "queue.position", { pos=i, total=#queue }) end
end

app:Post("queue/join", function(Player, Payload, req, res)
    table.insert(queue, Player); pushPositions()
    res:Send({ position = #queue })
    if #queue >= MATCH_SIZE then
        local match = {}
        for i = 1, MATCH_SIZE do table.insert(match, table.remove(queue, 1)) end
        local names = {}; for _, p in ipairs(match) do table.insert(names, p.Name) end
        app:PushTo(match, "queue.matched", { players = names })
        bridge.Fire("match.ready", { players = match }) -- notify server modules
        pushPositions()
    end
end)

app:Post("queue/leave", function(Player, Payload, req, res)
    for i, p in ipairs(queue) do
        if p == Player then table.remove(queue, i); pushPositions(); res:Send({ left=true }); return end
    end
    res:Status(404):Error("Not in queue")
end)

Middleware Guide

Middleware runs before every request in registration order. It's the right place for logging, auth, and cross-cutting concerns.

Blocking

copyapp:Use("auth", function(Player, Payload)
    if not Sessions[Player.UserId] then return false end  -- 403
end)

Route-scoped guard

copyapp:Use("admin-only", function(Player, Payload)
    if Payload.route:match("^admin/") and not Admins[Player.UserId] then
        return false
    end
end)

Analytics preset

copyapp:Use("analytics", function(Player, Payload)
    print(string.format("[%s] %s %s %s",
        os.date("%H:%M:%S"), Player.Name, Payload.method, Payload.route))
end)

YouTube Channel

Video tutorials, deep-dives, and build-alongs covering RoExpress and Roblox game development.

Support the Project

RoExpress is free, MIT licensed, and always will be. If it's saved you time, a donation goes a long way toward keeping development active.

The Story

RoExpress didn't arrive fully formed. It came out of years of frustration, failure, circumstance, and stubbornness — built in pieces across very different seasons of life.

Updates

Full history of every change to RoExpress across all versions.