The network transport of your game (net.transport) #

The connection layer under every multiplayer kit: how a client reaches the server, how long a silent link is kept, how a dropped player comes back, how fast a peer may talk. For the choice of the sync kit and the server program, read the multiplayer guide. Readable offline: gripforge docs net-transport, or the MCP tool gripforge_docs (topic net-transport).

What it is for #

net.transport owns the configuration of the connection and the status shown to the player. The sync kits (net.state, net.claim, net.authoritative, net.rollback, net.async) ask it for a session and never open a socket themselves. It checks your settings against the table of the network core, fills in the defaults, and hands them to that core: the same Rust core in the browser, in Godot, Unity, Unreal and in the dedicated server. It draws nothing. A game has exactly one transport kit; installing any sync kit brings it in.

Turn it on #

gripforge_gamekit_install   { project_id: "gkp_…", id: "net.transport" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "net.transport",
                              config: { "app": "my-game@1", "url": "wss://play.example.com/gfnet" } }

Write only the keys that differ from the defaults. gripforge kit api net.transport lists every key with its type and bounds.

First example #

<!-- test: kits/game_engine/host/tests/net_kits.rs::a_bad_transport_option_is_named_and_leaves_networking_off --> A wrong setting is named by its path, and networking stays off instead of running half configured:

{ "heartbeatMs": 5, "nope": true, "rate": { "burst": 0.5 } }

The log gets config.transport.heartbeatMs: expected >= 100, config.transport.nope: unknown property and config.transport.rate.burst: expected integer. The service still answers its defaults, and open fails with the same message.

Settings and defaults #

Constraints: heartbeatMs must be below timeoutMs; reconnect.minMs at most reconnect.maxMs; sendSoftBufferBytes at most sendHardBufferBytes; relay.maxPayload at most maxMessageBytes. Keys marked hot in gripforge kit api net.transport can change on a running session; the others apply at the next connection. The remaining keys tune the sockets of a server (listenHost, listenWebSocket, listenTcp, sniffMs, the pending-connection caps, the send buffers) and the direct-IP client (udpHelloMs, udpHelloTries, udpKeepaliveMs).

Services, events, variables #

• net.transport (service): config() the settings with their defaults, app() the application id of the handshake, open(model, sync, extra?) a session for a sync kit, host(model, sync, physics?) and hosted() the in-page server (role: "host"), listen(callback) and unlisten(id) its events.
• net.session (service): the session the sync kits plug into.
• net.connected (event): { id, resumed, transport }, the welcome arrived.
• net.disconnected (event): { reason, final }; final when no reconnection follows.
• net.peer (event): { id, on }, another peer joined or left.
• net.refused (event): { code, msg }, the handshake was refused (version, app, full, mods…).
• net.overflow (event): { dropped, total, cap }, events were dropped past eventQueueMax.
• net.status, net.rtt, net.peers (variables): connection state (idle, connecting, connected, reconnecting, closed), smoothed ping in ms, players online. Bind them to a HUD label.

Hooks and modding #

The kit declares no hook and no setting is open to mods: two machines of a match must agree on addresses, limits and rates. With mods applied, the application id sent in the handshake is app followed by ~mods.<fingerprint>, so a peer running other mods is refused with net.refused { code: "mods" }.

Engines #

The web uses WebSocket and WebRTC; Godot, Unity and Unreal use direct IP (tcp_udp; enet is treated as tcp_udp) with the WebSocket bridge as a fallback. role: "host" is available on the web only.

When it does not do what you expect #

• Networking never starts and the log names config.transport.<key>: that setting is unknown or out of bounds; fix it.
• open or host fails with a message about net.core: the host does not provide the network core, so no session can open.
• net.refused with code app: client and server have different app values; with mods: their mods differ.
• role: "host" without signalUrl and room accepts only the local player (a warning is logged).
• host says the page already hosts another model: one in-page server per page.
• per-connection overrides require role client: open was given transport overrides while role is host.

Limits #

No game rules, no matchmaking and no authentication: rooms, lobbies and logins belong to other kits. Rate limits are per peer, not per account. Direct IP needs an open port; the WebSocket bridge works through web proxies.

Versions #

Kit 1.3.1, protocol gfnet/1. 1.3 added the mods fingerprint to the handshake; 1.3.1 lets the caller of host choose the WebRTC room.