RPCs and events
Send one-off actions between client and host with directional MFUNCTION RPCs and session gameplay events, behind a default-deny authority gate.
Replication keeps state in sync. RPCs and events carry the other kind of traffic: "this happened". A client asks the host to fire, the host checks the request, and the host tells every peer. RPCs and gameplay events ride the same packet type, so they share one authority gate and one set of rate limits.
Declare an RPC
An RPC is a reflected MFUNCTION on a component, with a direction keyword Engine/Source/Runtime/Reflection/Public/Reflection/ReflectMacros.h:
| Annotation | Direction | Typical use |
|---|---|---|
MFUNCTION(Server) | Client to host | A request from the owning client |
MFUNCTION(Client) | Host to the owning client | A private reply |
MFUNCTION(Multicast) | Host to every peer | An effect everyone must see |
add Reliable | Uses the reliable channel | Anything that must arrive |
#pragma once
#include "Core/Platform.h"
#include "ECS/Component.h"
#include "Math/Vec3.h"
#include "Reflection/Reflect.h"
#include <cstdint>
namespace Mowo {
struct MOWO_REFLECTED_NAMED("NetShooter") MCATEGORY("Networking") NetShooterComponent {
MOWO_COMPONENT(NetShooterComponent)
MOWO_KEY("shots_fired") MOWO_DISPLAY("Shots Fired")
MREPLICATED uint32_t shotsFired = 0;
MFUNCTION(Server) void ServerFire(Vec3 origin, Vec3 direction) {
(void)origin;
(void)direction;
}
MFUNCTION(Multicast, Reliable) void MulticastFire(Vec3 origin, Vec3 direction) {
++shotsFired;
}
};
}This is the shape of the engine's own sandbox example. Arguments must be marshallable: bool, int32_t, uint32_t, int64_t, uint64_t, float, double, Vec2, Vec3, Vec4, Quat and std::string. RPC methods return void. Object and custom parameter types make a method unusable as an RPC FRpcDispatcher.
What the annotation does for you
- It installs the authority policy.
InstallAnnotatedRpcPolicieswalks every reflected component and allows eachServermethod for its owner only.ClientandMulticastmethods stay denied from clients ReplicationManager::InstallAnnotatedRpcPolicies. It runs when the manager initializes; call it again after a game module that adds RPC components has loaded. - It rejects the wrong direction. Sending a
Multicastmethod to the server, or aServermethod to clients, is refused on both the sending and receiving side.
Send an RPC
FRpcDispatcher serializes the arguments from reflection, and ReplicationManager sends them. The wire names a component and a method index, so a grant opens exactly one method.
#include "Core/Platform.h"
#include "Networking/Components/NetworkObjectComponent.h"
#include "ECS/World.h"
#include "Math/Vec3.h"
#include "Networking/Replication/ReplicationManager.h"
#include "Networking/Replication/RpcDispatcher.h"
#include "Reflection/ReflectionRegistry.h"
#include "Reflection/TypeDescriptor.h"
#include <cstdint>
#include <vector>
static bool RequestFire(Mowo::World& world, Mowo::EntityID entity, const Mowo::Vec3& origin, const Mowo::Vec3& direction) {
Mowo::ReplicationManager* replication = world.GetSystem<Mowo::ReplicationManager>();
Mowo::NetworkObjectComponent* netObject = world.GetComponent<Mowo::NetworkObjectComponent>(entity);
const Mowo::TypeDescriptor* desc = Mowo::ReflectionRegistry::Get().FindByDisplayName("NetShooter");
if (!replication || !netObject || !desc) {
return false;
}
const int index = Mowo::FRpcDispatcher::FindFunctionIndex(*desc, "ServerFire");
if (index < 0) {
return false;
}
Mowo::Vec3 o = origin;
Mowo::Vec3 d = direction;
void* args[] = { &o, &d };
std::vector<uint8_t> payload;
if (!Mowo::FRpcDispatcher::BuildArgsPayload(*desc, static_cast<uint16_t>(index), args, payload)) {
return false;
}
return replication->SendRpcToServer(netObject->networkId, static_cast<uint16_t>(desc->componentId), static_cast<uint16_t>(index), payload.data(), payload.size());
}The host uses SendRpcToAllClients or SendRpcToClient for the other directions. On the receiving side, FRpcDispatcher::DispatchComponentRpcByIndex resolves the component on the target entity and invokes the method.
While a session is running, FNetSession owns the RPC receiver. For component RPCs it looks up the entity and calls DispatchComponentRpcByIndex itself, then runs any fallback you installed with SetRpcFallback. You do not need to install a receiver of your own; the sandbox uses the fallback to turn a received ServerFire into a MulticastFire.
Script actor RPCs
A Wolang actor declares RPCs with @Server, @Client and @Multicast ((unreliable) for a droppable one) and the engine sends them over the script actor lane, a reserved method id that sits beside the named actor lane. The session grants a client that lane for an actor it owns only; the script layer then requires the named method to be declared @Server, the right number and kind of arguments, no more than wolang.RpcMaxBytes bytes and no more than wolang.RpcRate calls a second per method. A @Client or @Multicast method named by a client is refused. An inbound call runs under wolang.CallBudget. A script makes the call with CallRpc; see Wolang scripting.
The authority gate
Client-to-server RPCs are denied by default. Each one clears these checks in order before it reaches your code:
- Known peer
- Direction allowed
- Method allow-listed
- Within rate limit
- Owner check
- Invoke
- The sender is a registered peer.
- The method's direction allows client to server.
- The component and method index pair is allow-listed.
- The peer is within its token bucket (
net.rpc_rate_limit, 32 per second by default). - For
OwnerOnly, the target object exists and itsownerPeerIdmatches the sender.
Server-to-client RPCs are not policed; the host is the trust root.
To grant a method by hand, or widen one:
| Call | Effect |
|---|---|
AllowClientRpc(componentId, methodIndex, OwnerOnly) | The owner may call this one method. The default for Server methods. |
AllowClientRpc(componentId, methodIndex, AnyClient) | Any peer may call it. Use for global verbs like chat or ready-up, and validate the payload. |
AllowClientRpcComponent(componentId, authority) | Every method on the component. Logged, and overridden by per-method grants. |
DenyClientRpc(componentId, methodIndex) | Retract a grant. |
The enum is ReplicationManager::ENetRpcAuthority with Denied, OwnerOnly and AnyClient ReplicationManager::ENetRpcAuthority.
High-rate methods
The default bucket suits actions a player triggers by hand. A continuously swept sensor or a held trigger needs more. Register such a method with AllowClientRpcHighRate or SetRpcChannelClass(..., HighRate). It then uses a separate bucket (net.rpc_rate_limit_high, 200 per second) and defaults to the unreliable channel. A wider bucket is not a wider grant: owner checks still apply ReplicationManager::AllowClientRpcHighRate.
| Cvar | Default | Meaning |
|---|---|---|
net.rpc_rate_limit | 32 | Client RPCs accepted per peer per second |
net.rpc_rate_limit_high | 200 | The same, for HighRate methods |
net.input_rate_limit | 120 | Client input packets accepted per peer per second |
Large RPCs
An RPC whose arguments reach 64 KiB does not fit the normal RPC packet. It goes through the blob lane instead: the packet is compressed with zstd when that shrinks it, cut into chunks (1 KiB by default) and sent on the reliable unordered channel, the receiver acknowledges them, and the sender keeps at most a window of unacknowledged chunks in flight at a set byte rate per peer FNetBlobChannel. The receiver decompresses and follows whatever chunk size the sender used. A large payload therefore neither stalls the ordered reliable channel nor floods the link. When the last chunk arrives, the receiver handles the RPC exactly as if it had come in one packet, so a client RPC still passes the authority gate.
A blob is not ordered against the rest of the reliable stream. That is why smaller RPCs stay on their own channel by default; set net.RpcBlobThreshold to route every RPC packet above that many bytes through the lane as well. A client paces its blob lane to at most half the host's incoming byte budget, so the host's flood guard does not drop a large client RPC chunk by chunk.
| Cvar | Default | Meaning |
|---|---|---|
net.RpcBlobThreshold | 0 | RPC packets larger than this many bytes take the blob lane. 0 sends only arguments of 64 KiB or more there. |
net.BlobBytesPerSecond | 32768 | Bytes per second the lane sends to one peer. 0 is unlimited; the window still bounds what is in flight. |
net.BlobWindowChunks | 32 | Unacknowledged chunks a sender may have per peer, across all its queued blobs. |
net.BlobChunkBytes | 1024 | Payload bytes per chunk (256 to 16384). Keep chunk plus 40 bytes of headers under the transport MTU. |
net.BlobZstdLevel | 3 | zstd level for blobs queued from now on. 0 sends them as they are; a blob that does not shrink by 5% is sent as it is anyway. |
net.BlobBytesPerTick | 0 | Most blob bytes one replication tick sends across all peers. 0 is no cap. |
net.BlobMaxQueuedBytes | 16777216 | Payload bytes queued for one peer before further blobs are refused, so a stalled client costs the host a bounded amount of memory. |
net.MaxBlobBytes | 4194304 | Largest RPC the lane sends (4 MiB), and the largest a client accepts from the host. |
net.MaxClientBlobBytes | 262144 | Largest blob the host reassembles from one client (256 KiB). A larger announcement is refused before any memory is reserved. |
Gameplay events
Events are a lighter layer on the same packet for actions that are not tied to a component method. You pick a 16-bit id at or above 0x8000; ids from 0xFF00 up are reserved for the join protocol FNetSessionEventIds. Payloads use FNetEventWriter and FNetEventReader, which bounds-check every read and latch a failure flag.
#include "Networking/Session/FNetSession.h"
#include "Networking/Session/NetEventCodec.h"
#include <cstdint>
static constexpr uint16_t kDoorOpened = 0x8010;
static void OpenDoorLocally(uint32_t doorId) {
(void)doorId;
}
static void InstallDoorEvents(Mowo::FNetSession& session) {
session.RegisterEventHandler(kDoorOpened, [](uint32_t senderPlayerId, Mowo::FNetEventReader& reader) {
uint32_t doorId = 0;
reader.ReadU32(doorId);
if (reader.IsValid()) {
OpenDoorLocally(doorId);
}
});
session.AllowClientEvent(kDoorOpened, true);
}
static void ReportDoorOpened(Mowo::FNetSession& session, uint32_t doorId) {
Mowo::FNetEventWriter writer;
writer.WriteU32(doorId);
session.BroadcastEvent(kDoorOpened, writer);
}BroadcastEventworks from either role. On the host it runs the handler locally and sends the event to every client. On a client it asks the host, which checks and relays it, so every peer runs the event once FNetSession::BroadcastEvent.SendEventToServer,SendEventToAllClientsandSendEventToPlayerexist when you need a specific direction.- Client events are refused until
AllowClientEventis called. WithownerOnly(the default), the sender must own the pawn the event is stamped with. PassENetEventRate::HighRateas the third argument for an event a client sends continuously; it then draws on the high-rate bucket.DenyClientEventretracts the grant.
LeaveSession clears every handler and client event policy you installed, because they usually live in a hot-reloadable game module. Install them each time you start a session, not once per process FNetSession::ClearGameCallbacks.
RPCs from Visual Scripting graphs
Actor functions can carry the same annotations. When a Visual Scripting graph calls an MFUNCTION(Server, Reliable) or a Multicast function on an actor, the call is routed through the session to where it should run instead of executing locally AVisualScriptActor.
Related
- Replication for continuous state.
- How-to: a replicated actor for a Server RPC wired end to end.
- API:
FRpcDispatcher,ReplicationManager,FNetSession,FNetEventWriter,FNetEventReader.
Engine sources
This page describes behavior implemented in these files of the engine repository, checked against commit 5f421cb37.
- Engine/Source/Runtime/Reflection/Public/Reflection/ReflectMacros.h
- Engine/Source/Runtime/Networking/Public/Networking/Replication/ReplicationManager.h
- Engine/Source/Runtime/Networking/Public/Networking/Replication/RpcDispatcher.h
- Engine/Source/Runtime/Networking/Public/Networking/Replication/NetBlobChannel.h
- Engine/Source/Runtime/Networking/Public/Networking/Session/FNetSession.h
- Engine/Source/Runtime/Networking/Public/Networking/Session/NetSessionTypes.h
- Engine/Source/Runtime/Networking/Public/Networking/Session/NetEventCodec.h
- Engine/Source/Runtime/Game/Public/Game/AVisualScriptActor.h