Installation

Drop the RoExpress folder into ReplicatedStorage, install via Wally, or clone from GitHub. RoExpress creates its own remotes automatically — you don't touch them.

Option A — Wally recommended

Add RoExpress to your wally.toml dependencies:

copy[dependencies]
RoExpress = "unofficialrobloxtutor/roexpress@2.0.0"

Then run:

copywally install

Wally drops it into your Packages/ folder. Require it from there:

copylocal RoExpress = require(game.ReplicatedStorage.Packages.RoExpress)

Option B — Creator Store

Get it directly from the Roblox Creator Store and drop the ModuleScript into ReplicatedStorage.

Option C — Manual / GitHub

Clone or download from GitHub and place the folder in ReplicatedStorage:

copygame.ReplicatedStorage
  └── Modules
      └── Libraries
          └── RoExpress          ← root ModuleScript (init.luau)
              ├── App            ← ModuleScript
              ├── Network        ← ModuleScript
              ├── Broadcast      ← ModuleScript
              ├── Listener       ← ModuleScript
              ├── Router         ← ModuleScript
              ├── Codec          ← ModuleScript
              ├── Bridge         ← ModuleScript
              ├── Tamper         ← ModuleScript
              ├── Port           ← ModuleScript  (v2.1)
              ├── Stream         ← ModuleScript  (v2.1)
              ├── 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 or blocking yields. Client-only.

copylocal network = RoExpress("Network")

copy-- with callback (non-blocking) — returns requestId
local id = network:Get("player/123", nil, function(res)
    print(res.data)
end)

-- no callback (blocking) — yields until response arrives
local id, res = network:Post("stats/save", data)
print(res.status, res.data)

-- blocking with timeout override + cancel from another thread
local id, res = network:Post("stats/save", data, nil, 5)
network:Cancel(id)  -- cancel if needed

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)

Benchmark

Fires real requests through your existing Network instance and measures round-trip latency. All timing is wall-clock — it covers serialisation, network transit, server handler execution, and deserialisation. Client-only.

copylocal network   = RoExpress("Network")
local Benchmark = require(game.ReplicatedStorage.RoExpress.Benchmark)

local bench = Benchmark.New(network)

Run

Fires iterations sequential requests and returns a statistics table. A warmup pass runs first and is discarded so JIT and connection overhead don't skew the numbers.

Results

Print

Writes a formatted summary to the Studio output window.

copy── player/123   GET × 20  (warmup: 3) ───────────────
   min          4.21 ms
   avg          6.83 ms
   median       6.10 ms
   p95         12.44 ms
   p99         18.07 ms
   max         18.71 ms
   ─────────────────────────────────────────────────────
   errors       0 / 20
   throughput   8.3 req/s
──────────────────────────────────────────────────────

RunAndPrint

Runs and prints in one call. Returns the Results table so you can store it for Compare.

copybench:RunAndPrint("player/123", { method = "GET", iterations = 30 })

Compare

Prints multiple Results side-by-side — useful for comparing routes, methods, or payload sizes.

copybench:Compare({
    bench:Run("player/123",   { label = "GET player" }),
    bench:Run("stats/save",   { method = "POST", label = "POST stats" }),
    bench:Run("leaderboard", { label = "GET board" }),
})

Drops the internal reference. Does not destroy the Network instance — the caller owns it.

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

Ports v2.1

Named isolated request pipelines. Each port owns its own RemoteEvent, Router, and TokenBucket. Global App middleware is inherited automatically. The direct answer to the MMO scaling problem — a combat flood cannot choke an inventory request when they run on separate ports.

Server

copylocal app = RoExpress("App")

-- global middleware — inherited by ALL ports automatically
app:Use("logger", function(Player, Payload)
    print(Player.Name, Payload.method, Payload.route)
end)

-- combat port — higher rate limit for fast-paced traffic
app:Listen("combat", function(port)
    port:Post("gun/fire/:damage=number", handler)
    port:Get("player/:id=number/health", handler)
end, { Max = 30, Refill = 10 })

-- inventory port — port-local auth middleware
app:Listen("inventory", function(port)
    port:Use("auth", function(Player, Payload)
        if not Sessions[Player.UserId] then return false end
    end)
    port:Get("player/:id=number/items", handler)
    port:Post("player/buy", handler)
end)

-- push to a port outside its callback
app:GetPort("combat"):PushAll("roundEnd", { winner = "PlayerA" })

Client

copy-- connect to named port remotes
local combat    = RoExpress("Network",  "combat")
local inventory = RoExpress("Network",  "inventory")
local combatPush = RoExpress("Listener", "combat")

combat:Post("gun/fire/50", nil, callback)
inventory:Get("player/123/items", nil, callback)

combatPush:On("roundEnd", function(data)
    print(data.winner)
end)

app:Listen API

Creates a named port. Each port gets its own RemoteEvent in ReplicatedStorage/RoExpressPorts. The callback receives the port instance for route registration.

Returns a registered port by name. Useful for pushing outside the Listen callback.

Port API

Ports expose the same API as App — Get, Post, Use, Unuse, Push, PushAll, PushTo, OnParamError. Port-local middleware runs after inherited App middleware.

Infrastructure

Stream v2.1

60hz binary state streaming for FPS games, MMOs, and anything requiring high-frequency position synchronisation. Raw buffer packing — no JSON, no Base64. Up to 90% smaller packets than traditional approaches.

Wire format

Two dedicated remotes

Server

copylocal stream = RoExpress("Stream")

-- opt-in lag compensation
stream.EnableLagCompensation({ windowMs = 200, tickRate = 60 })

-- receive player state updates (up to 60x/second per player)
stream.OnState(function(player, state)
    worldStates[player.UserId] = state
end)

-- validate hits server-side
stream.OnHit(function(player, hit, valid)
    if not valid then
        tamper.Strike(player, "Invalid hit")
        return
    end
    applyDamage(hit.victimUserId, hit.damage, hit.hitPart)
    stream.ConfirmHit(victim, hit)
end)

-- broadcast world state at 60hz — one remote call for all players
RunService.Heartbeat:Connect(function()
    stream.Broadcast(worldStates)
end)

Client

copylocal stream = RoExpress("Stream")

-- send position at 60hz
RunService.Heartbeat:Connect(function()
    stream.SendState({
        userId   = LocalPlayer.UserId,
        position = HRP.Position,
        rotY     = math.deg(math.atan2(HRP.CFrame.LookVector.X, HRP.CFrame.LookVector.Z)),
        health   = Humanoid.Health,
        firing   = isFiring,
        ads      = isADS,
        jumping  = isJumping,
    })
end)

-- receive world state and interpolate other players
stream.OnWorld(function(states)
    for _, state in ipairs(states) do
        if state.userId ~= LocalPlayer.UserId then
            interpolateCharacter(state)
        end
    end
end)

-- report a hit
stream.SendHit({
    victimUserId = victim.UserId,
    damage       = 35,
    hitPart      = stream.HitPart.HEAD,
})

-- weapon state change
stream.SendWeapon({ weaponId = 1, state = stream.WeaponState.RELOADING })

Full API

Constants

copystream.HitPart.HEAD    -- 0
stream.HitPart.TORSO   -- 1
stream.HitPart.LIMB    -- 2

stream.WeaponState.IDLE      -- 0
stream.WeaponState.FIRING    -- 1
stream.WeaponState.RELOADING -- 2
stream.WeaponState.ADS       -- 3
stream.WeaponState.EMPTY     -- 4

stream.Flags.JUMPING   stream.Flags.CROUCHING  stream.Flags.ADS
stream.Flags.RELOADING stream.Flags.FIRING      stream.Flags.DEAD
stream.Flags.SPRINTING

Lag compensation

When enabled the server maintains a ring buffer of world snapshots. Hit packets carry a u16 timestamp (ms since stream start). On receipt the server finds the closest snapshot and validates the hit geometrically before passing valid = true to your OnHit handler.

copystream.EnableLagCompensation({
    windowMs = 200,  -- store 200ms of snapshots
    tickRate = 60,   -- 60 snapshots/second = 12 snapshots max
})

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  -- (Player, Payload) -> boolean?
type BroadcastHandler   = RoExpress.BroadcastHandler
type ListenerMiddleware = RoExpress.ListenerMiddleware  -- (event, data) -> ()
type NetworkCallback    = RoExpress.NetworkCallback

-- modules (server)
type App         = RoExpress.App
type Broadcast   = RoExpress.Broadcast
type Port        = RoExpress.Port
type Stream      = RoExpress.Stream
type Tamper      = RoExpress.Tamper
type TokenBucket = RoExpress.TokenBucket

-- modules (client)
type Network  = RoExpress.Network
type Listener = RoExpress.Listener
type Promise  = RoExpress.Promise

-- modules (shared)
type Bridge = RoExpress.Bridge
type Router = RoExpress.Router
type Codec  = RoExpress.Codec

-- 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)

MVC Pattern with RoExpress

Model-View-Controller is a way of organising your game's server code so networking, data, and logic stay cleanly separated. RoExpress maps naturally onto MVC — routes are your Controllers, DataStore modules are your Models, and what you send to clients is your View.

The pattern

Without MVC — the common mess

copy-- everything in one script, no separation
app:Post("shop/buy", function(Player, Payload, req, res)
    -- networking + data access + business logic all mixed together
    local ok, data = pcall(store.GetAsync, store, Player.UserId)
    if not ok then res:Status(500):Error("DB error"); return end
    if data.coins < 100 then res:Status(400):Error("Poor"); return end
    data.coins -= 100
    data.inventory[req.data.itemId] = true
    pcall(store.SetAsync, store, Player.UserId, data)
    app:Push(Player, "shop.purchased", data.inventory)
    res:Send({ ok = true })
end)

With MVC — clean separation

Model — PlayerModel.luau

copy-- pure data access, no networking knowledge
local PlayerModel = {}
local store = DataStoreService:GetDataStore("Players")

function PlayerModel.Get(userId: number)
    local ok, data = pcall(store.GetAsync, store, userId)
    return ok and data or { coins = 0, inventory = {} }
end

function PlayerModel.Save(userId: number, data: any)
    return pcall(store.SetAsync, store, userId, data)
end

function PlayerModel.DeductCoins(data: any, amount: number): boolean
    if data.coins < amount then return false end
    data.coins -= amount
    return true
end

return PlayerModel

Controller — ShopController.luau

copy-- handles routing only, delegates to model
local PlayerModel = require(script.Parent.PlayerModel)
local app         = RoExpress("App")

app:Post("shop/buy", function(Player, Payload, req, res)
    local data = PlayerModel.Get(Player.UserId)

    if not PlayerModel.DeductCoins(data, 100) then
        res:Status(400):Error("Insufficient funds")
        return
    end

    data.inventory[req.data.itemId] = true
    local ok = PlayerModel.Save(Player.UserId, data)

    if not ok then
        res:Status(500):Error("Save failed")
        return
    end

    -- View: push the updated inventory to the client
    app:Push(Player, "shop.purchased", {
        inventory  = data.inventory,
        newBalance = data.coins,
    })
    res:Send({ ok = true })
end)

Wiring it together with Bridge

Bridge lets models notify other modules without knowing about networking. Instead of models importing App or Broadcast, they fire a Bridge event and the Controller decides what to push.

copy-- Model fires a Bridge event — no networking knowledge needed
function PlayerModel.Save(userId, data)
    local ok = pcall(store.SetAsync, store, userId, data)
    if ok then
        bridge.Fire("player.saved", { userId = userId, data = data })
    end
    return ok
end

-- Controller listens and decides what to push
bridge.Bind("player.saved", function(payload)
    local player = Players:GetPlayerByUserId(payload.userId)
    if player then
        app:Push(player, "data.synced", payload.data)
    end
end)

Recommended folder structure

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.

Find me everywhere

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.

Find me everywhere

Promise Guide

RoExpress ships a built-in Promise implementation for Network requests. Use GetAsync and PostAsync instead of Get and Post when you prefer chainable async code over callbacks.

Basic usage

copylocal network = RoExpress("Network")

-- GetAsync returns requestId AND a chainable Promise
local id, promise = network:GetAsync("player/123")
promise
    :Then(function(res)
        print(res.data.coins)
    end)
    :Catch(function(err)
        warn(err.status, err.message)
    end)
    :Finally(function()
        UI:HideLoader()
    end)

Chaining Then handlers

Returning a value from a Then handler passes it to the next Then. This lets you transform data through the chain cleanly.

copylocal _, promise = network:GetAsync("leaderboard/top")
promise
    :Then(function(res)
        return res.data.entries  -- pass entries to next Then
    end)
    :Then(function(entries)
        for _, entry in ipairs(entries) do
            UI:AddRow(entry)
        end
    end)
    :Catch(function(err)
        UI:ShowError(err.message)
    end)

Error handling

If a Then handler throws, the chain falls through to Catch. You never need to wrap Then handlers in pcall.

copylocal _, promise = network:PostAsync("stats/save", data)
promise
    :Then(function(res)
        if res.data.saved then
            error("intentional error")  -- falls through to Catch
        end
    end)
    :Catch(function(err)
        warn("caught:", err.message or err)
    end)

Cancellation

copy-- GetAsync returns requestId so you can cancel by id or via the promise
local id, promise = network:GetAsync("feed/all")
promise:Then(function(res) UI:LoadFeed(res.data) end)

-- cancel by request id (from any thread)
network:Cancel(id)

-- or cancel via the promise directly
promise:Cancel()

State checks

copypromise:IsPending()   -- true while waiting
promise:IsResolved()  -- true after successful response
promise:IsRejected()  -- true after error or timeout

Callback vs Promise — when to use which

TypeCoercer Guide

TypeCoercer is the shared serialisation utility that powers all route param coercion. Use it directly to convert RoExpress types to wire strings and back — useful when building route URLs dynamically or validating data outside of routes.

Getting it

copylocal tc = RoExpress("TypeCoercer")  -- available server and client

ToString — any type to wire string

copytc.ToString(Vector3.new(10, 5, -20))        -- "10,5,-20"
tc.ToString(Color3.fromRGB(255, 0, 128))    -- "255,0,128"
tc.ToString(CFrame.new(0,5,0))             -- "0,5,0,0,0,0,1" (quaternion)
tc.ToString(Enum.Material.Grass)           -- "Grass"
tc.ToString(workspace.Baseplate)           -- "Part:Baseplate"
tc.ToString(true)                          -- "true"
tc.ToString(42)                            -- "42"

FromString — wire string to Lua value

copylocal ok, val = tc.FromString("10,5,-20", "vector3")
-- ok = true, val = Vector3.new(10,5,-20)

local ok, val = tc.FromString("Running", "Enum.HumanoidStateType")
-- ok = true, val = Enum.HumanoidStateType.Running

local ok, val = tc.FromString("Part:Baseplate", "Instance")
-- ok = true, val = workspace.Baseplate (if registered root contains it)

Instance search roots

Register roots before using Instance coercion. Multiple roots are searched in registration order.

copy-- register once on startup
tc.RegisterInstanceRoot("Workspace", workspace)
tc.RegisterInstanceRoot("Players",   game:GetService("Players"))
tc.RegisterInstanceRoot("Teams",     game:GetService("Teams"))

-- now Instance params work in routes
app:Get("target/:t=Instance", function(Player, Payload, req, res)
    print(req.params.t.Name)  -- actual Instance
end)

Building route URLs dynamically

copylocal pos = HRP.Position
local url = "spawn/" .. tc.ToString(pos)
-- "spawn/10.5,5,-20.3"

network:Post(url, data)

All supported types

FPS Stream Guide

A complete walkthrough for wiring Stream into an FPS game — from setup through lag-compensated hit registration.

Why Stream?

Traditional Roblox networking sends JSON over RemoteEvents. A single player state update in JSON is ~200 bytes. With 20 players at 60hz that's 240,000 bytes per second just for position data. Stream packs the same data into 21 bytes — a world broadcast for 20 players is 420 bytes, sent once per tick.

Step 1 — Server setup

copy-- ServerScript
local stream = RoExpress("Stream")
local tamper = RoExpress("Tamper")
local worldStates = {}

-- opt-in lag compensation (200ms window, 60hz)
stream.EnableLagCompensation({ windowMs = 200, tickRate = 60 })

-- store incoming player states
stream.OnState(function(player, state)
    worldStates[player.UserId] = state
end)

-- validate hits
stream.OnHit(function(player, hit, valid)
    if not valid then
        tamper.Strike(player, "Invalid hit", "stream", hit)
        return
    end
    local victim = Players:GetPlayerByUserId(hit.victimUserId)
    if victim then
        applyDamage(victim, hit.damage, hit.hitPart)
        stream.ConfirmHit(victim, hit)
    end
end)

-- broadcast world at 60hz
RunService.Heartbeat:Connect(function()
    local states = {}
    for _, state in pairs(worldStates) do
        table.insert(states, state)
    end
    if #states > 0 then
        stream.Broadcast(states)
    end
end)

-- clean up on player leave
Players.PlayerRemoving:Connect(function(player)
    worldStates[player.UserId] = nil
end)

Step 2 — Client setup

copy-- LocalScript
local stream = RoExpress("Stream")
local HRP    = LocalPlayer.Character:WaitForChild("HumanoidRootPart")

-- send state at 60hz
RunService.Heartbeat:Connect(function()
    if not LocalPlayer.Character then return end
    stream.SendState({
        userId   = LocalPlayer.UserId,
        position = HRP.Position,
        rotY     = math.deg(math.atan2(
            HRP.CFrame.LookVector.X,
            HRP.CFrame.LookVector.Z
        )),
        health   = Humanoid.Health,
        firing   = isFiring,
        ads      = isADS,
        jumping  = Humanoid.FloorMaterial == Enum.Material.Air,
    })
end)

-- interpolate other players
stream.OnWorld(function(states)
    for _, state in ipairs(states) do
        if state.userId ~= LocalPlayer.UserId then
            interpolateRemoteCharacter(state)
        end
    end
end)

-- report a hit
local function onHit(victim, damage, hitPart)
    stream.SendHit({
        victimUserId = victim.UserId,
        damage       = damage,
        hitPart      = hitPart,
    })
end

-- confirmed hit feedback
stream.OnHitConfirmed(function(hit)
    UI:ShowHitMarker(hit.hitPart == stream.HitPart.HEAD)
end)

Ports Guide

When to use ports, how to structure them, and how to avoid common mistakes.

When to use ports

Ports solve one specific problem — traffic isolation. You need ports when two domains of traffic could realistically saturate a shared remote and affect each other.

Structure recommendation

copylocal app = RoExpress("App")

-- global middleware — always runs first on every port
app:Use("version-check", function(Player, Payload) end)
app:Use("logger",        function(Player, Payload) end)

-- default pipeline — low-frequency game logic
app:Get("player/:id=number", handler)

-- combat port — high rate limit, no extra middleware
app:Listen("combat", function(port)
    port:Post("gun/fire/:damage=number", handler)
end, { Max = 60, Refill = 20 })

-- inventory port — auth middleware, default rate limit
app:Listen("inventory", function(port)
    port:Use("session-auth", function(Player, Payload)
        if not Sessions[Player.UserId] then return false end
    end)
    port:Get("items", handler)
    port:Post("buy",   handler)
end)

Remote limit warning

Exploit Detection Guide

Tamper hooks into App's pipeline passively. You don't wrap anything — just require it, subscribe, and optionally enable auto-kick.

Minimal setup

copylocal tamper = RoExpress("Tamper")

tamper.AutoKick(10, "Exploiting detected")

tamper.On(function(report)
    warn(string.format("[Tamper] %s — %s (strikes: %d)",
        report.player.Name, report.reason, report.strikes))
end)

Manual strikes for business logic

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

Tuning thresholds

copytamper.SetThresholds({
    rateFloodWindow = 10,  -- tighter window for faster detection
    rateFloodCount  = 3,   -- lower threshold for stricter games
    routeScanCount  = 5,   -- fewer unknown routes before pattern strike
    paramFloodCount = 3,
})

Discord Server

The official RoExpress Discord — get help, share what you're building, report bugs, and follow development updates in real time.

GitHub

The RoExpress source code is fully open source on GitHub. Browse the code, open issues, submit pull requests, or star the repo to follow updates.

Twitter / X

Follow @tostadium on X for development updates, release announcements, and Roblox scripting content.

Website

The official developer portfolio and home base for all RoExpress-related content.

Library Comparison

A factual comparison of the main Roblox networking libraries. Feature claims are sourced from each library's official README or documentation.

At a glance

Where RoExpress wins

Application-layer structure. RoExpress is the only library in this space that brings Express.js-style routing to Roblox — typed path params (:id=number), wildcards, globs, middleware chains, and named ports. Server code is organised, auditable, and testable in a way that event-based libraries cannot match.

Security first. Built-in rate limiting, payload validation, version mismatch detection, and the Tamper module are part of the framework — not afterthoughts.

Complete client API. Callback, blocking yield, and Promise patterns. Cancellation by request ID. No other library in this group offers all three.

No build step. Pure Luau, zero external dependencies, one Wally line.

Where others win

Raw byte performance. ByteNet and Zap serialise into buffer objects which are faster and smaller than Luau table serialisation. If you are sending thousands of small fixed-schema packets per second, ByteNet or Zap will outperform RoExpress at the transport layer.

Code-generated types. Zap generates Luau bindings from a schema file, giving compile-time type guarantees. It requires a Rust CLI and a build step, but the type safety is stronger than anything you can express purely in Luau.

Simplest possible API. BridgeNet2's Fire / Connect surface is familiar to anyone who has used vanilla RemoteEvents and has almost no learning curve.

When to use which

Design Consensus

Every major decision in RoExpress was made for a reason. This page records the reasoning — not just what was built, but why, what was rejected, and what tradeoffs were accepted. It exists so future contributors understand intent, not just code.

Overview timeline

Per-module decisions

Click any module to expand its specific design rationale.

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.

Research Papers

The academic foundations behind RoExpress's core techniques — compression, lag compensation, rate limiting, and game networking.