# 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):

```text
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

<!-- test: kits/net_authoritative/tests/net_authoritative.rs::the_session_is_an_authoritative_client_that_connects -->
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.

```rust
#[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.