20 · Replication (v2)¶
What it is¶
Replication is how the server's world is mirrored on the clients. The model is inputs up, state down: clients send their inputs; the authoritative server simulates and sends back what changed. There is no client-side prediction or rollback.
This doc describes the network plugins for an R-Type-like game: one shared screen, a few players (typically up to 4), and many short-lived bullets and enemies.
Why we need it¶
- R3: multiplayer with an authoritative server is a core requirement.
- R2: script-defined components must replicate with no per-type network code.
- R4: the plugins are generic: any game marks components as replicated and reads
PlayerInput.
How others do it¶
| Engine / library | Model |
|---|---|
| Quake 3 | Snapshots delta-compressed against the last acknowledged snapshot, over UDP |
| Unreal | Replicated properties on actors, relevancy, RPCs; Iris (data-oriented, dirty tracking, quantization) |
| bevy_replicon | Server-authoritative component replication for Bevy, change ticks, client entity mapping |
| Overwatch | ECS-based netcode with prediction and rollback (beyond our scope) |
Our choice¶
Quake 3-style deltas from the last acknowledged tick, driven by the ECS's change detection and reflection, with a per-component replication mode suited to R-Type's bullets.
How it works¶
Three layers¶
flowchart TB
game["Game (Luau)<br/>replication modes on components,<br/>spawn a ship on ClientConnected, read PlayerInput"]
plugins["ECS plugins (C++)<br/>ServerPlugin / ClientPlugin<br/>+ shared ReplicationPlugin"]
net["rtype-network (no ECS)<br/>UDP sockets, packets, acks,<br/>reliable channel, connections"]
thread["Network thread"]
game --> plugins
plugins -- "two thread-safe queues" --> net
net --- thread
rtype-network knows nothing about the ECS. Socket I/O runs on a network thread and exchanges
messages with the ECS through two thread-safe queues; only the plugins' systems touch the queues, so the
ECS stays single-threaded.
What lives in the ECS¶
| Kind | Name | Role |
|---|---|---|
| Component | NetworkId |
Stable identity of a replicated entity (assigned by the server) |
| Component | Owner{clientId} |
Which client controls the entity |
| Component | PlayerInput |
Named action states for one tick |
| Component (client-only) | Interpolated |
Last two received states, for smooth display |
| Resource (server) | ServerState |
Clients: address, last acked tick, input buffer |
| Resource (client) | ClientState |
Connection, latest server tick, NetworkId → Entity map, snapshot buffer |
| Event | ClientConnected / ClientDisconnected |
For the game to spawn or remove ships |
ReplicationPlugin ("rtype.replication") registers the components and events above and inserts the InputLayout
resource; ServerPlugin and ClientPlugin both add it, and a standalone game can add it alone. It also registers the
engine calls of the inputs (input/InputCalls.hpp): rtype.replication.addInput
({name, kind}, kind "button", "axis" or "vector2"), which engine.input.action makes on both sides, and
rtype.replication.readInput ({entity, action}), which gives a server script {held, pressed, released, axis,
vector} from an entity's PlayerInput, and, in an App that runs the client side, rtype.replication.localClient
(client/ClientCalls.hpp), which gives a client script {connected, client}: its id once the server gave it one, to
tell its own entities (their Owner) from the others'. It is registered here rather than by ClientPlugin, which the
Engine adds after the scripts load. The network I/O
(binding the socket, connecting, building the manifest) happens in Startup systems, once every plugin was built. The
server reads replicated components by id through a SystemParam of replication
(Parameters from other libraries: ReplicatedRead, one
DynamicQuery per replicated component, reporting its reads like a typed Query), built when the plugin adds its
systems: add ServerPlugin after the plugins that register replicated components. The client writes them by id
through Commands, applied after the phase, so ClientPlugin has no such constraint.
One server tick, one client frame¶
Server (headless, FixedUpdate at 60 Hz):
| Phase | System | Does |
|---|---|---|
| PreUpdate | net.receive |
Drain the queue → input buffers, acks, connect / disconnect events |
| FixedUpdate | net.applyInputs |
Input buffer of this tick → PlayerInput on the owner's ship |
| FixedUpdate | gameplay | Luau and C++ systems |
| PostUpdate | net.assignIds |
NetworkId for new replicated entities |
| PostUpdate | net.snapshot |
Per client: delta since that client's last acknowledged tick |
| PostUpdate | net.send |
Push packets to the network thread |
Client (every frame):
| Phase | System | Does |
|---|---|---|
| PreUpdate | net.receive |
Apply snapshots: spawn / despawn / write, through NetworkId → Entity |
| Update | net.interpolate |
Display the state at (latest server tick − ~100 ms) |
| PostUpdate | rtype.engine.networkInput |
Input actions → PlayerInput. Not in ClientPlugin: replication never includes plugins, so the Engine adds it (engine/NetworkInput), reading each InputLayout action from the plugins::input::Input action of the same name; it calls ClientState::setInput. A game outside the Engine writes its own |
| PostUpdate | net.sendInput |
Send the last 3 inputs (redundancy against loss) |
| Render | drawing |
sequenceDiagram
participant C as Client
participant S as Server
Note over C: PostUpdate: collect input
C->>S: inputs (ticks N-2, N-1, N)
Note over S: PreUpdate: receive<br/>FixedUpdate: apply input N, run gameplay<br/>PostUpdate: snapshot per client
S->>C: delta since last acked tick
Note over C: PreUpdate: apply delta<br/>Update: interpolate
C->>S: ack
Deltas from the last acknowledged snapshot make UDP manageable: the server never resends lost packets, it always sends "what changed since the snapshot you confirmed". A lost packet only makes the next delta larger.
The network plugin does not know the game's component types (C++ or Luau): net.snapshot reads every
replicated component by id through a DynamicQueries parameter, configured with one query per replicated
component (QueryList), so its reads are declared to the scheduler. iterSince(query, ack) gives what
changed since a client's acknowledged tick (see Systems).
Replication modes¶
R-Type has hundreds of bullets whose motion is predictable. Each component chooses a mode:
| Mode | Sent | Example |
|---|---|---|
kEveryChange |
Whenever its change tick is newer than the client's ack | Player ships, health, score, boss state |
kSpawnOnly |
Once, at spawn; the client simulates the rest with a both-side system |
Bullets, enemies on fixed paths |
kNone |
Never | Server-only AI state |
A bullet costs about 20 bytes once (capsule id, NetworkId, position, velocity, spawn tick) instead of
8 bytes × 60 times per second. The server sends a despawn when it hits something.
Combined with quantized fields (positions as fixed-point i16, see
Reflection) and no interest management (the whole level is
on one screen, everyone sees everything), traffic stays small.
Inputs up¶
PlayerInput holds the game's named actions (declared by scripts with engine.input.action, see
Luau bridge), in manifest order: one bit per button action, a quantized vector per
axis action. Clients send the last three inputs in every packet, so one lost packet costs nothing. The
server keeps a small input buffer per client and applies the input of the current tick (repeating the
last one if it is missing).
Packet layout (binary)¶
| Part | Direction | Fields, in order |
|---|---|---|
| Header | both | protocol id u16, type u8, tick u32, ack u32, ack bits u32 |
| Input | client → server | last 3 × (tick u32, buttons u32, axes i16 × 2 × n) |
| Snapshot | server → client | base tick u32, spawns[], despawns[], updates[] |
| Spawn (in a snapshot) | server → client | network id u32, capsule id u16, count u8, then count × (component id u16, fields…) |
| Update (in a snapshot) | server → client | network id u32, component id u16, field mask, fields… |
Component and capsule ids are the short numbers from the manifest. Fields are written by the reflection serializer, so Luau components need no network code.
Connection¶
sequenceDiagram
participant C as Client
participant S as Server
C->>S: hello (protocol version, plugin hash)
S->>C: manifest: components (name + layoutHash), capsules, input actions, client id
C->>C: map names to local ids, refuse on mismatch
S->>C: full snapshot
Note over S: ClientConnected event → Luau spawns the ship with Owner
loop every tick
C->>S: inputs (last 3)
S->>C: delta since last ack
C->>S: ack
end
C->>S: bye, or 2 s timeout
Note over S: ClientDisconnected event → despawn the ship
The manifest and the handshake use a small reliable channel (resent until acknowledged); snapshots and inputs use the unreliable one.
Rooms¶
The server runs one world per game room, plus a lobby world for matchmaking. Each room has its own
State (Lobby → Playing → GameOver, see Scheduler) and its own client list. The
network thread routes packets to the right room by client id.
What the game writes¶
local OnJoin = ecs.system("game.OnJoin", { events = { "net.ClientConnected" } })
function OnJoin:run(ctx)
for event in ctx.events["net.ClientConnected"] do
local ship = ctx.call("rtype.capsule.spawn", { capsule = "actors/ship.actor" })
ctx.commands:add(ship, "net.Owner", { client = event.client })
end
end
return OnJoin
Plus replication = "everyChange" or replication = "spawnOnly" on its components. That is all the networking the
game code sees; the same systems run in standalone mode, where PlayerInput comes from local input.
Looking at the world from a tool¶
In a debug run the server can open the admin channel (docs/network/design.md, Admin channel). The world messages
of that channel are answered by replication/admin/WorldAdmin, the only code that knows both the ECS and the admin
protocol: it lists the entities that have a component, shows the components of one entity with their values as text
(read from the reflected FieldInfos, so script-defined components show up like C++ ones), sets one value, spawns and
despawns an entity, and pauses, resumes or steps the schedules. Changes are recorded in the Commands of the
receive system and applied at the end of its phase, so they land between systems, before the tick's FixedUpdate,
and replicate to the clients like any other change. Nothing from a client reaches this path.
Build order¶
rtype-network: UDP socket on a thread, packet header, acks; test with two processes.- Connection + manifest + full snapshot: the client sees the server world.
- Inputs up: the ship moves on the server and appears on the client.
- Deltas from the last ack +
kSpawnOnly: scales to many bullets. - Interpolation, quantization, rooms.
Connections¶
- Uses: Change detection, Reflection,
Capsules, Events, Resources,
App and plugins (
ServerPlugin,ClientPlugin,StandalonePlugin), Entity (NetworkIdvsEntity). - External: Ethan's
Input/InputAction(source ofPlayerInput).
Pitfalls¶
- Replicating renderer handles.
TextureIdand the other backend ids are local slots; replicated components useAssetId. - Client systems writing replicated state. Overwritten at the next snapshot; the side rule rejects it (see Systems).
- Divergent
kSpawnOnlysimulation. The client's motion must match the server's (same system,bothside, fixed timestep). Anything less predictable must bekEveryChange. - Trusting the client. The server only accepts inputs, never state.
Open questions¶
- Transport details: reliability layer design, packet size limit, encryption or not. (Team)
- Tick rate: 60 Hz or 30 Hz? (Team)
- Rooms as separate Apps or one App with several worlds? (ECS + network)
- Does the Epitech subject impose specifics (UDP for gameplay, binary protocol, a protocol RFC document)? Check the subject version. (Team)