NetworkService

Getting it

local NetworkService = Engine:GetService("NetworkService")

Overview

NetworkService replaces hand-made RemoteEvents and RemoteFunctions with remotes defined in code. A remote has a name, a direction and optional rules, and the service creates and wires the underlying instances for you. Every message from a client is checked before your code sees it:

1. Middleware you registered with Use can drop or rewrite it.
2. The Schema (a Guard schema) must accept the arguments.
3. The rate limit for that player must allow it (on by default: 20 calls per second, bursts of 40).

Anything that fails fires NetworkService.Violation on the server instead of reaching your handler.

Define each remote on both sides with the same name and settings, typically in a shared ModuleScript. The server creates the remote; the client waits for it (up to DefaultConnectionTimeout seconds).

local Engine = require(game:GetService("ReplicatedStorage"):WaitForChild("Engine"))
-- On the server, require ServerScriptService.Engine instead; see "Server and Client".
local NetworkService = Engine:GetService("NetworkService")
local Guard = Engine:GetPackage("Guard")

return {
	Equip = NetworkService:DefineRemote("Equip", {
		Direction = "ClientToServer",
		Schema = Guard.tuple(Guard.string({ MaxLength = 32 })),
	}),
	GetInventory = NetworkService:DefineRemote("GetInventory", {
		Direction = "ClientToServer",
		Mode = "Request",
	}),
	Hit = NetworkService:DefineRemote("Hit", {
		Direction = "ServerToClient",
		Batch = { Rate = 30 },
	}),
}

Remotes.Equip.Received:Connect(function(player, args)
	equip(player, args[1])
end)

Remotes.GetInventory:SetHandler(function(player)
	return getInventory(player)
end)

Remotes.Hit:Fire(player, damage, position) -- to one player
Remotes.Hit:Fire(nil, damage, position)    -- to everyone

Remotes.Equip:Fire("Sword")

Remotes.GetInventory:RequestAsync():andThen(function(items)
	renderInventory(items)
end)

Remotes.Hit.Received:Connect(function(_, args)
	showDamageNumber(args[1], args[2])
end)

Remotes

DefineRemote

NetworkService:DefineRemote(name: string, def: RemoteDef): Remote

Defines a remote. Each name can be defined once per side. Remotes can also be defined in configuration (Remotes = { [name] = def }), which creates them when the service loads.

Remote

GetRemote

NetworkService:GetRemote(name: string): Remote?

Validation and safety

Use

NetworkService:Use(fn: (ctx: { Player: Player?, RemoteName: string, Args: { any } }) -> (boolean, { any }?))

Adds middleware that runs on every incoming remote message, in the order added. Return false to drop the message, or true plus a new argument list to rewrite it.

NetworkService:Use(function(ctx)
	if ctx.Player and isBanned(ctx.Player) then
		return false
	end
	return true
end)

Violation

NetworkService.Violation: Signal<(player: Player?, remoteName: string, reason: string)>

Fires when an incoming message fails validation or the rate limit. Pair it with ModerationSystem to flag exploiters.

RateLimited

NetworkService.RateLimited: Signal<(player: Player?, remoteName: string)>

Streams

A stream sends many small messages in packets at a fixed rate, with optional double sending (Ports = 2) so a lost packet does not lose data. Batched remotes use streams internally; you can also create one directly.

CreateStream

NetworkService:CreateStream(settings: StreamSettings): Stream -- server

GetStream

NetworkService:GetStream(id: string, settings: StreamSettings): Stream -- client

Connects to a stream the server created, by its Id (send the id to the client, for example in an attribute).

Raw messages

For quick prototypes NetworkService also has plain, unnamed messaging: FireServer, FireClient, FireAllClients, their FireUnreliable... variants, InvokeServer, InvokeClient, the OnServerInvoke / OnClientInvoke properties, and the RawReceived: Signal<(player, args)> event.

Addresses

Every connection gets an address Game.Channel.Category.Connection, used as its Id. Channel 0 belongs to Engine's own services; your connections use channels 1 to 255 (default from configuration). Channels and categories let you group connections, for example one channel per game mode. GameNumber is the first part: set it in configuration, or leave it at 0 to derive a fixed number from game.GameId.

Stats

GetStats

NetworkService:GetStats(): { InKbps: number, OutKbps: number, PerRemote: { { Name, Kbps, CallsPerSec } } }

Bandwidth over the last second, in total and per remote. Sizes are estimates.

Properties

Configuration

Types

export type Remote
export type RemoteDef
export type RemoteMode = "Fire" | "Request"
export type RemoteDirection = "ClientToServer" | "ServerToClient" | "Both"
export type Stream
export type StreamSettings
export type Address = { Game: number, Channel: number, Category: number, Connection: number }
export type Stats