Skip to content

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

  1. rtype-network: UDP socket on a thread, packet header, acks; test with two processes.
  2. Connection + manifest + full snapshot: the client sees the server world.
  3. Inputs up: the ship moves on the server and appears on the client.
  4. Deltas from the last ack + kSpawnOnly: scales to many bullets.
  5. Interpolation, quantization, rooms.

Connections

Pitfalls

  • Replicating renderer handles. TextureId and the other backend ids are local slots; replicated components use AssetId.
  • Client systems writing replicated state. Overwritten at the next snapshot; the side rule rejects it (see Systems).
  • Divergent kSpawnOnly simulation. The client's motion must match the server's (same system, both side, fixed timestep). Anything less predictable must be kEveryChange.
  • 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)