Network sync: shared state (server-validated actions) (net.state) #

What it is for #

Syncs a shared, versioned state through server-validated actions, with no simulation tick: turn-based and board games, card games with hidden hands, party games, lobbies and persistent data.

It needs net.transport, 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.state" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "net.state",
                              config: { "preset": "none", "initial": null } }

First example #

<!-- test: kits/net_state/tests/net_state.rs::an_action_travels_as_a_command_and_answers_its_id_a_refusal_answers_null --> This is the body of the passing test an_action_travels_as_a_command_and_answers_its_id_a_refusal_answers_null; the helper functions it calls are defined at the top of the same test file.

#[test]
fn an_action_travels_as_a_command_and_answers_its_id_a_refusal_answers_null() {
    let mut s = online(json!({}));
    answer(&mut s, "c:act", json!(21));
    assert_eq!(
        call(&mut s, KIT, "act", json!(["draw", { "n": 2 }])),
        json!(21)
    );
    let sent = commands(&mut s);
    let act = sent.iter().find(|c| c["c"] == "act").unwrap();
    assert_eq!(act["type"], "draw");
    assert_eq!(act["args"], json!({ "n": 2 }));
    // No arguments: an empty object travels.
    call(&mut s, KIT, "act", json!(["pass"]));
    let sent = commands(&mut s);
    assert_eq!(sent.last().unwrap()["args"], json!({}));
    call(&mut s, "probe.core", "refuse", json!(["act"]));
    assert_eq!(call(&mut s, KIT, "act", json!(["draw", {}])), Json::Null);
    assert!(logged(&s, "net.state: act draw: act refused"));
}

Settings and defaults #

Descriptions come from the kit manifest and stay in English.

Services, events, variables #

• Service net.sync: The project replication model (one per project: the net.* sync kits conflict with each other).
• Service net.state: act(type, args) / state() / turn() / history() / undo() / crdt(); patch, accepted, rejected, turn, timer events; server hook, snapshots.
• Events emitted:
  • net.state.sync (v, seat) — The full view arrived (join, resume, resync).
  • net.state.patch (v, ops) — The view changed (compact JSON ops).
  • net.state.accepted (id, v) — An action of this client was applied.
  • net.state.rejected (id, why) — An action of this client was refused (rule reason, hook reason, rate, disconnected).
  • net.turn (seat, mine, n, round, remainingMs, active) — The turn changed.
  • net.timer (name, remainingMs, expired) — A timer started, was cancelled or expired (turn for the turn timer).
• Variables:
  • net.status (string) — Network status
  • net.rtt (number) — Ping (ms)
  • net.peers (number) — Players online
  • net.turn_seat (number) — Seat to play
  • net.my_turn (boolean) — My turn
  • net.turn_ms (number) — Turn time left
  • net.state_version (number) — State version

Hooks and modding #

This kit declares no hook and no collection to mod.

Engines #

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

Versions #

Kit version 1.3.0.