Network sync: authoritative server (Source-style)

Provides server-authoritative multiplayer: a fixed server tick, user commands, client prediction and reconciliation, interpolation of remote entities, lag-compensated hits and delta snapshots.

Source: module-kits:kits/net_authoritative/usage/en.mdView Markdown source

Also read offline — CLI: grip-forge docs net-authoritativeMCP tool: gripforge_docs { "topic": "net-authoritative" }

Network sync: authoritative server (Source-style) (net.authoritative) #

What it is for #

Provides server-authoritative multiplayer: a fixed server tick, user commands, client prediction and reconciliation, interpolation of remote entities, lag-compensated hits and delta snapshots.

It needs net.transport, input.actions, game.engine; installing it brings them in.

Turn it on #

Install the kit in a project, then change a setting (the values shown are its defaults):

gripforge_gamekit_install   { project_id: "gkp_…", id: "net.authoritative" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "net.authoritative",
                              config: { "tickHz": 30, "snapshotHz": 20 } }

First example #

This is the body of the passing test the_session_is_an_authoritative_client_that_connects; the helper functions it calls are defined at the top of the same test file.

#[test]
fn the_session_is_an_authoritative_client_that_connects() {
    let mut s = online(json!({}));
    let sessions = call(&mut s, "probe.core", "sessions", json!([]));
    assert_eq!(sessions[0]["config"]["model"], "authoritative");
    assert_eq!(sessions[0]["config"]["role"], "client");
    assert_eq!(commands(&mut s)[0]["c"], "connect");
    assert_eq!(
        call(&mut s, "net.prediction", "session", json!([])),
        json!(1)
    );
    assert_eq!(
        call(&mut s, "net.lag_compensation", "client", json!([])),
        json!(1)
    );
    // The fire action is registered for the player to rebind.
    assert!(s.host.state.get("net.hp").is_some());
}

Settings and defaults #

Descriptions come from the kit manifest and stay in English.

Setting	Type	Default	Range or values	Meaning
`tickHz`	integer	`30`	5–128	Server simulation rate (Source: 64–128 for shooters).
`snapshotHz`	integer	`20`	1–128	Snapshots per second (≤ tickHz).
`cmdRedundancy`	integer	`3`	1–8	Each command packet repeats the last N commands (loss tolerance).
`interpolationMs`	integer	`100`	0–1000	Remote entities are drawn this far in the past (≥ 2 snapshot intervals).
`interpolationBuffer`	integer	`32`	2–256	Client: snapshots kept for interpolation.
`extrapolateMs`	integer	`250`	0–1000	Extrapolate at most this long when snapshots are late.
`maxUnlagMs`	integer	`1000`	0–2000	Lag compensation window (sv_maxunlag).
`unlagMarginTicks`	integer	`2`	0–64	Lag compensation: a shot may rewind this many ticks beyond the measured latency.
`lagSmoothing`	number	`0.2`	0.01–1	Weight of a new sample in the server-side latency estimate of a player (EWMA).
`maxCmdsPerTick`		`0`		Commands consumed per player per tick (catch-up after loss, caps speed hacks).
`repeatLastCmdMs`		`-1`		Server: when a player's command queue runs dry, its last movement input (axes, view, sprint — never fire, jump or other actions)…
`inputBufferTicks`		`-1`		Server command queue depth (ticks) the client aims at when timeDilation is on, so jitter does not starve the server (announced by…
`timeDilation`	number	`0`	0–0.25	Client clock dilation (fraction, both ways) that keeps the server queue at inputBufferTicks: faster when the server runs dry,…
`resimCatchup`	integer	`4`	1–16	Body prediction, engines without a synchronous physics step (Godot): net steps per physics frame while a resimulation catches up…
`starvedMs`	integer	`250`	0–10000	Client: no snapshot for this long while connected → event `starved` (then `fed` with the gap when they resume); counted in…
`maxQueuedCmds`	integer	`64`	4–256	Queued commands per player; the oldest are dropped beyond.
`maxPendingCmds`	integer	`256`	8–4096	Client: unacknowledged predicted commands kept (replayed on correction).
`maxPitch`	number	`1.5`	0.1–1.5707	Client: view pitch bound (rad) of the commands.
`errorSmoothingMs`	integer	`100`	0–1000	Prediction errors are blended out over this time.
`snapshotHistory`	integer	`64`	8–256	Snapshots kept per client as delta baselines (server and client; announced in the welcome).
`relevanceRadius`	number	`0`	0–100000	Only entities within this distance are sent (0 = everything).
`hitRadius`	number	`0.5`	0.05–10	Player hit sphere radius (m).
`hitHeight`	number	`1`	0–10	Hit sphere centre above the feet (m).
`eyeHeight`	number	`1.6`	0–10	Shot origin above the feet (m).
`fireRange`	number	`200`	1–10000	Hitscan range (m).
`fireRateHz`	number	`10`	0.1–60	Shots per second (enforced by the server).
`fireImpulse`	number	`0`	0–1000000	physics shared: impulse (N·s) a shot gives the dynamic body it hits (0 = shots ignore bodies).
`damage`	number	`25`	0–1000	Damage per hit.
`maxHp`	number	`100`	1–100000	Player health.
`respawnMs`	integer	`3000`	0–600000	Respawn delay after death.
`spawnRadius`	number	`5`	0–10000	Players spawn on a ring of this radius (m).
`physics`	string	`"none"`	`none`, `native`, `shared`	Bodies: none; native = the engine physics simulates (owner / dedicated server), the core replicates states, sleep and…
`playerRadius`	number	`0.4`	0.05–10	physics native / shared: radius of the player capsule (m, announced to the engines).
`playerHalfHeight`	number	`0.5`	0–10	physics native / shared: half height of the capsule cylinder (m; 0 = a sphere).
`predict`	string	`"auto"`	`auto`, `none`, `movement`, `bodies`	Client prediction: none (everything interpolated), movement (the local player, reconciled on each snapshot), bodies (also the…
`playerTolerance`	number	`0.01`	0–10	Prediction: player position error (m) below which the prediction is kept.
`playerVelTolerance`	number	`0.1`	0–100	Prediction: player velocity error (m/s) below which the prediction is kept.
`playerResim`	number	`0.5`	0–100	Prediction: position error (m) below which a soft correction (shift + blend) is enough; above, reset and replay (≥…
`playerVelResim`	number	`3`	0–1000	Prediction: the same for the velocity error (m/s, ≥ playerVelTolerance).
`bodyTolerance`	number	`0.02`	0–10	Body prediction: position error (m) below which a predicted body is kept.
`bodyRotTolerance`	number	`0.05`	0–3.2	Body prediction: rotation error (rad) below which it is kept.
`bodyVelTolerance`	number	`0.25`	0–100	Body prediction: velocity error (m/s) below which it is kept.
`bodyResim`	number	`0.3`	0–100	Body prediction: position error (m) above which the bodies are restored and resimulated (≥ bodyTolerance).
`bodyRotResim`	number	`0.35`	0–3.2	Body prediction: the same for rotation (rad, ≥ bodyRotTolerance).
`bodyVelResim`	number	`1.5`	0–1000	Body prediction: the same for velocity (m/s, ≥ bodyVelTolerance).
`predictRadius`	number	`6`	0–1000	Body prediction: bodies within this distance of the local player are predicted.
`predictHysteresis`	number	`1.25`	1–4	Body prediction: a predicted body stays predicted up to predictRadius × this.
`maxPredictedBodies`	integer	`8`	0–64	Body prediction: bodies predicted at once (nearest first).
`maxResimTicks`	integer	`30`	0–256	Body prediction: longer resimulations are skipped (restore only).
`bodyPlanTimeoutMs`	integer	`500`	50–10000	Body prediction: a step plan the host does not finish within this delay is dropped.
`blendThreshold`	number	`0.02`	0–100	Drawn discontinuities above this (m) are blended out.
`blendSpeed`	number	`3`	0.01–1000	A blend moves the drawn pose by at most this speed (m/s) on top of its motion.
`snapDistance`	number	`2`	0–10000	Drawn discontinuities and player corrections beyond this (m) snap instead of blending.
`resimAlways`	boolean	`false`		Benchmark: resimulate the bodies on every snapshot.
`remotePlayers`	string	`"predicted"`	`none`, `drawn`, `predicted`	Body prediction: the OTHER players' capsules in the predicted world (`others` of body_step).
`remoteExtrapolationMs`	integer	`350`	0–1000	Body prediction, remotePlayers predicted: a remote capsule is extrapolated at most this far ahead of its latest snapshot, by at…
`remoteConfidence`	number	`0.9`	0–1	Body prediction, remotePlayers predicted: share of the recent extrapolations of a remote player (checked against the snapshots)…
`remoteTolerance`	number	`0.25`	0.01–10	Body prediction, remotePlayers predicted: an extrapolation that lands within this distance (m) of the snapshot counts as right.
`remoteLatchRadius`	number	`2`	0–100	Body prediction, remotePlayers predicted: while a remote capsule is within this distance (m) of a predicted body, whether it is…
`predictHistoryTicks`	integer	`512`	64–8192	Client: predicted player states kept per command (reconciliation, body prediction).
`bodyHistoryTicks`	integer	`256`	16–8192	Body prediction: body states kept per tick (client) and command numbers per tick (server).
`tickEvents`	boolean	`false`		Server: emit a `tick` event every tick.
`bodyStepEvents`	boolean	`false`		Server, physics native: emit `body_step` every tick (always on with predict bodies).
`statsFullBytes`	boolean	`false`		Server: also weigh each snapshot as full states (stats fullBytes: the delta savings; costly).
`move`	object	`{"speed": 6, "sprint": 1.6, "accel": 60, "fri…`		Player movement, identical on the server and in the client prediction (announced in the welcome; a partial object keeps the other…

Services, events, variables #

Service net.sync: The project replication model (one per project: the net.* sync kits conflict with each other).
Service net.prediction: Predicted local player, reconciled on each snapshot; remote entities interpolated.
Service net.lag_compensation: Server-side rewind of the other players to the shooter's render time.
Events emitted:
- net.hit (by, target, damage, kill) — A lag-compensated hit confirmed by the server.
- net.correction (error, snapped) — The server corrected the local prediction.
- net.starved (ms) — No snapshot for starvedMs while connected (a stalled downlink: remote entities extrapolate, the prediction lead is frozen).
- net.fed (ms) — Snapshots resumed after a starved gap of ms.
- net.resim (ms, steps) — Web runtime, predict bodies: the predicted bodies were restored and resimulated (cost in ms, physics steps replayed).
Variables:
- net.status (string) — Network status
- net.rtt (number) — Ping (ms)
- net.peers (number) — Players online
- net.hp (number) — Health
Input actions: net_fire

Hooks and modding #

This kit declares no hook and no collection to mod.

Engines #

Declared targets: web, godot, unity, unreal. gripforge kit api net.authoritative lists the exact settings and services of your version.

Versions #

Kit version 1.2.0.