Clients send intents, never outcomes. A request says which action or configured item the player chose. The server resolves the price, eligibility, ownership, randomness, reward and resulting state. A typed client call still needs server checks: an exploiter can call the underlying remote directly.
Every remote lives in src/core/shared/Remotes.luau, in both the Remotes type and its matching builder. lint-boundaries rejects direct remote instances elsewhere and declarations that bypass the guarded constructors.
The four remote constructors
- intent(checks...)
Client to server, fire and forget. Type
Remo.ClientToServer; client:fire(...), server:connect(function(player, ...) ... end).- query({ checks }, { returns })
Client request with an answer. Type
Remo.ServerAsync; client:request(...)returns a Promise, server answers with:onRequest(...). The client checks the answer against the declared returns validators.- fact()
A server-to-client fact, typed
Remo.ServerToClient. Use it for one-off notifications; persistent display state belongs in Charm atoms and sync.- trap()
A honeypot, with tempting names such as
economy.giveCurrency. Normal client code never fires it, connects it or reuses its name. A call is reported to the anti-cheat.
Client actions use request<Action> names inside a domain namespace (shop.requestBuy). Server facts use past-tense names (notifications.pushed). Screens and controllers make requests; reusable UI components do not.
How a request becomes server state
Roblox/RemoteGuard runs first in each constructor's middleware. With the sender known, it counts the call and checks the argument count and every argument. On the server it also counts every send of a fact and every answer of a query, for the staff net command; the counting does not depend on the anti-cheat. Extra or invalid arguments are dropped and reported before the handler sees them. The handler then checks meaning against current server state and config, applies the change through its owner, and answers or syncs the result.
Shape checks and meaning checks
| Boundary | Checks | Example |
|---|---|---|
| Remote constructor | Argument count, types and bounded shape | RemoteGuard.text(64), t.strictInterface, constrained numbers, RemoteGuard.list(check, max) |
| Owning service | Current game rules and server facts | Item exists, player owns it, action is unlocked, current server price is affordable |
| Write owner | Its own invariants | CurrencyService owns balance changes; DataService owns save writes |
Checks for position-sensitive actions use server-observed geometry and distance. A client's selected grid cell or aim choice can be an input; a claimed hit, damage value, finish time, price or reward is never accepted as the decision.
Throttles, cooldowns and budgets
Spammable intents carry RemoteGuard.throttle(seconds) as middleware: the first call per player in a window goes through and the rest are dropped. It compares the clock, so a throttled remote costs nothing per frame (Remo's own throttleMiddleware connected a Heartbeat handler for every call it let through, and the Template no longer uses it). Where the newest call must win (a state report), RemoteGuard.throttle(seconds, true) delivers the last dropped call when the window ends. Queries are never throttled by middleware (RemoteGuard.throttle refuses one when it is built); their handlers use Util/RateLimiter. A handler also enforces its game-rule cooldown with Util/Cooldown and its per-player budget with Util/RateLimiter: the transport throttle is only a floor. Where every call matters (a settings toggle), limit it in the handler with a RateLimiter burst instead of a throttle.
A preference intent stays bounded the same way. settings.requestLayout carries a device class (one of five literals) and at most 32 HUD placements of { id, region, order }, never pixels; its guard refuses an unknown class, an id or zone over 32 bytes, an order out of bounds and any extra field. SettingsService.saveLayout shares the settings bucket and keeps only placements the game's layout allows that widget, so a modified client changes only its own HUD, and never moves a locked widget, places a strict one outside its zones or invents a zone (the HUD layout).
lint-boundaries (remotes-rate-limited) fails a server file that handles a query, or an intent with no throttle in Remotes.luau, unless it uses Util/RateLimiter, Util/Cooldown or AdminService.allowRead, or says why not with a rate-ok: comment.
The client never sends what a check rejects: a rejected call is an invalid_arguments detection against an honest player (anti-cheat). Cap text to the check's bytes before sending (Format.truncateBytes), send integers where the check wants integers, and keep the client under the anti-cheat's network.callsPerSecond across all its remotes: no remote per frame, per mouse move or per keystroke.
A change to two players' saves leaves its pending state first, checks both sides again, writes both with no yield between, and puts the first back if the second is refused. TradeService is the pattern: its six trade.* queries are each checked against the saves the server holds, never against an item, a quantity or a time the client sent.
Text a player typed that someone else will read (a name, a sign, a message) goes through TextFilterService before it is saved or shown: broadcast for everyone, forUser for one reader. It answers a refusal, never the raw text, when Roblox cannot filter it or the player is over the filter budget.
Clean up per-player limiter state when data unloads and when a player leaves before loading. Disabling anti-cheat keeps argument validation; it removes reporting and detections. Feature switches leave remote declarations present while skipping the disabled system's handlers.
Adding or changing a remote
Choose state or a request
Display-only state goes in SharedState or a private sync key. Use a remote for an intent, an answered request or a one-off fact.
Declare both halves
Add the type and builder entry in Remotes.luau using the correct constructor. Give every client argument a bounded validator.
Handle it on the server
Connect in the owning service's
init(). Validate meaning and rate, apply through existing owners, return an expected refusal as a Result-shaped answer.Call and display
Fire from a screen or controller. For a query, handle its Promise;
UI/Util/askprovides the shared transport-failure message. Show the answer or synced state.Record the contract change
Update the system note's Remotes section, say that the frontend/backend contract changes in the PR, and run the security-review, verify and playtest procedures.
The complete procedure and checklists live in the Template's add-remote skill, docs/systems/Networking.md and docs/engineering/Server Authority.md.
Place the handler and its pure rules.
Read server state through Charm and Fusion.
Updated