Multiplayer for your game (net.* kits, gfnet-server) #

Pick how your game stays in sync across players, switch it on from the kits, tune it with a handful of settings, and run the server. Readable offline: gripforge docs net, or the MCP tool gripforge_docs (topic net).

What it is #

Every net.* kit runs the same Rust network core (gfnet-core): WebAssembly in the browser and in the Node server, a native library in Godot, Unity, Unreal and in the native server. One implementation everywhere, so a browser, a Godot build and a Unity build can play the same match. A game has one transport kit and one sync kit:

Choose the sync kit #

Install one sync kit per project (the other net.* kits come in as needed).

The model of a web game: what the room reads #

For a game that runs in the browser on the kits, the network model is not a Godot choice: it is the sync kit you install. The web room service reads it from the project itself and starts gfnet-server with that model, so nothing is copied and nothing can drift:

A project with no sync kit has no room (not_networked). A room created by hand for a game that is not a project (the net field of POST /api/v1/network/rooms, { model, sync, physics }) takes the same shape, validated by the core. For a car or kart game that mostly steers its own vehicle, claim is the cheap, responsive choice; authoritative when hits or an economy must be cheat-proof; rollback for a small deterministic duel. The MCP tool gripforge_net_kit only covers the Godot listen-server snippets (GfNet); for a web game use gripforge_gamekit_install of the sync kit and read gripforge docs web-multiplayer.

Turn it on #

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

You write only the keys that differ from the defaults. gripforge kit api net.transport (or net.claim…) lists every setting, with its type, bounds and default, and says which ones can change on a running session.

Settings that matter #

net.transport (all keys: gripforge kit api net.transport):

Per sync kit, the settings you reach for first:

net.state rules are data: argument schemas, conditions on the state, the seat, the turn and the phase, and effects (set, inc, push, remove, move, draw, deal, shuffle, random). The set is complete enough that most card and board games need no server code.

Server-side code: validation hooks #

Two places let your own code decide on the server:

• net.state actions declared with "hook": true are checked against their schema, turn, phase and conditions, then handed to the server host, which accepts them (with an optional state patch) or rejects them with a reason. No answer within hookTimeoutMs (5000) rejects the action. Engines expose it as GfNetState.validate (Godot), Validate / Validator (Unity) and OnValidate (Unreal).
• net.rooms hooks: the rooms actions your host validates before the rules run (challenge, accept, decline, cancel, pick, ready, leave_match, watch, unwatch, join_server), refused with your reason. Used with your own login (auth: true). See gripforge docs rooms-server.

Modding #

All net.* kits are services of game.engine: they declare no engine hook and no setting is open to mods. Transports, addresses, ports, capacities, limits and rates belong to the project and must be identical on every machine of a match. A mod that sets one is refused (config_not_moddable). With mods applied, the application id peers send is app followed by ~mods.<fingerprint>, so a client whose mods differ from the server's is refused with net.refused { code: "mods" }. Godot, Unity and Unreal have no mods: their handshake is unchanged.

Events and variables #

net.transport emits net.connected { id, resumed, transport }, net.disconnected { reason, final }, net.peer { id, on }, net.refused { code, msg } and net.overflow; variables net.status (idle, connecting, connected, reconnecting, closed), net.rtt and net.peers. The sync kits add their own (net.owner and net.denied for claim, lobby.changed for the lobby, rooms.changed, rooms.challenged, rooms.match_ready, rooms.match_ended for rooms…).

The server: gfnet-server #

gfnet-server is the dedicated server of the net.* kits, a native program. One process is one match or one waiting room. It runs the same core as the clients and only opens sockets, pumps the core and prints the lines a supervisor reads. Build it from the repository (cargo build --release -p gfnet-server in native/gfnet).

gfnet-server --model claim --app my-game@1 --port 27015
gfnet-server --model state --app my-game@1 --config match.json --exit-on-end

It prints GF_NET_READY {...} once it listens, closes cleanly on SIGINT / SIGTERM, and exits 70 if the core panics. One port serves WebSocket and native TCP+UDP clients.

Not served by the native server: WebRTC, TLS (terminate it at a proxy), and the rooms launcher. The Node server gf-net-server (package @gripforgeai/net, same flags) covers WebRTC signalling and the rooms service (startRoomsService); the rooms server starter (gripforge create rooms-server) is built on it. Godot, Unity and Unreal projects can also run headless as dedicated servers.

Engines #

libgfkits provides the net.core service (and net.http for kits that talk to a web service) to the games it runs, with sockets of the machine. What a page alone can open is refused by name, never silently replaced: WebRTC ("webrtc needs a host link") and wss:// addresses. For those, use the WebSocket bridge of a server or run the client in a page. The local player of a room you host joins its own server through the listening port, as a TCP+UDP client of 127.0.0.1.

From a web page without the kits #

@gripforgeai/net is the package for a plain page or a three.js / React Three Fiber scene: typed sessions with the same options and event names as the engine wrappers.

import { connect } from '@gripforgeai/net';
const net = await connect({ model: 'claim', url: 'wss://play.example.com/gfnet', app: 'my-game@1' });
net.on('peer', ({ id, on }) => console.log(id, on ? 'joined' : 'left'));

Options are validated before the core is created: an unknown key, a wrong type or a value out of bounds throws a NetConfigError whose path names it. Commands never throw when the core refuses one: create returns 0, claim, input and the others return false, and command() returns { ok: false, error }.

When it does not work #