Writing a third-party kit — a kit logic module of your own, step by step #

A third-party kit is a kit of game logic that is not one of GripForge's: you write it in Rust, the build tool compiles it on the base GripForge fixes, and a game plays it together with GripForge's kits. Neither the core nor any other kit is recompiled. This page is the whole path — write, build, declare, verify, export, play — and can be followed without reading the code of the core. Readable offline: gripforge docs kit-third-party, or the MCP tool gripforge_docs (topic kit-third-party). The commands of this page — gripforge kit build|socle|add|verify|list| remove and the MCP tools gripforge_third_party_kit_* — are those of CLI 0.3.44 / MCP 0.1.61 or later (gripforge --version; gripforge update). The model behind it (the core, the interfaces, the costs): topic kit-modules; every structure shared in memory: topic kit-structures.

Use the existing kits first. A game is made by picking GripForge's kits and adapting them (config, mods, hooks of game.engine): MCP gripforge_gamekit_search, gripforge kit api <id>, and the topic third-party (mods, presentation modules). Write a kit of your own only for a rule no kit has and no mod of game.engine can express — and make it small, on top of the others (listen to their events, call their services), as the example does.

The worked example of this page is in the repository: examples/kit-third-party (acme.streak). It listens to an event of collect.tokens, reads and writes a component on the player, and calls a service of economy.money.

Two rules.

1. A third-party module is loaded only when the game declares it. The declaration names where the module comes from and its SHA-256; the lock of the game freezes the version, that fingerprint and the trust; the export and the page refuse a binary that is not the declared one.
2. A third-party kit is isolated unless the maker of the game says otherwise, kit by kit. Isolated, it keeps a memory of its own: it sees the shared zone and the interfaces of the core, nothing else, and cannot corrupt the game. Trusted (--trust common), it is placed in the memory of the core and of the other kits, as a kit of GripForge is — faster, and no longer isolated. §2 has the two side by side.

0. What you need #

• The GripForge CLI (gripforge, 0.3.44 or later). It ships the kit SDK — the Rust side of the contract a kit is compiled against — in its kit-sdk folder: no GripForge checkout is needed to build a kit. (The MCP client @gripforgeai/mcp 0.1.61 or later has the same tools; it uses the kit SDK of the CLI found on PATH, or the one you name: sdk, GRIPFORGE_KIT_SDK. A GripForge checkout is a kit SDK too: --sdk <checkout>.) None of these commands needs a login: they work on the files of the kit and of the game.

• rustup (https://rustup.rs). The build tool uses the Rust toolchain the base pins, with its components and its target; it does not use your default toolchain and never changes it. What is missing is named with the one command that installs it — or installed for you with --install:

  gripforge kit socle            # the build base, and whether this machine is ready for it
  gripforge kit socle --install  # installs the pinned toolchain beside yours (rustup toolchain install …)

• Node 22.19 or later (the CLI's own requirement).
• A game: a file game.json ({ "project": …, "lock": … }), or the folder that holds it. An exported web game (gripforge game-export <gkp_id> <folder>) is such a folder; examples/kit-third-party/game.json is such a file.
• A folder of kit modules to play the game: the core and the GripForge kits your game uses, each as a .wasm, with kit-modules.json. An exported web game has one when its player package has them (runtime-rust/kit-modules/), a player package too (kit-modules/). The core and GripForge's kits come compiled: adding your kit recompiles none of them.

1. Write the kit #

my-kit/
  kit.json          what the kit is: its id, its version, what it serves and what it needs
  src/lib.rs        the kit

No Cargo.toml, no export macro, no flags: the build tool writes the crate around your source, once per mode (§2), so the same source gives both builds.

kit.json

{
  "schema": "gripforge.kit-module/1",
  "id": "acme.streak",
  "version": "1.0.0",
  "description": "Rewards collecting streaks.",
  "services": ["[email protected]"],
  "requires": ["collect.tokens@^1.1"],
  "optional": ["economy.money@^1"]
}

• id: dotted, lowercase, under a prefix of your own (acme.…); never the id of a GripForge kit. It is the id fn id() returns and the one the game declares.
• version: major.minor.patch of the kit. It is the version the binary carries and the lock freezes.
• services: the capabilities of fn services(), with the version of their API. That version is the one of the service, not of the kit: it stays 1.0.0 while you only fix the kit, gets a new minor when you add a method.
• requires: the kits your kit cannot work without (it listens to them, calls them without a test). optional: the kits it uses only when the game has them (kx.host.has_service(…) first). The requirement is matched against the kit version of kit-modules.json (economy.money 1.3.0), not the version of the service API that kit api prints.
• Optional: "source" (the file of the kit, src/lib.rs by default), "module" (the function that gives the kit, module by default), "crates": { "smallvec": "1" } (crates of crates.io your kit needs; the crates of the base keep the versions of the base), "events" and "hooks" (what the kit declares for the game schema: §7b).
• Not written by you: provides, consumes, memory, structs, sha256. The build tool reads them from the binary it made and writes them in the manifest that goes with it.

src/lib.rs — a kit is a type that implements KitModule, given to the build tool by a public function. A module is stateless: what it keeps between hooks goes in kx.put(…) and is read back with kx.data::<T>().

use gripforge_kit_guest::bus::GameEvent;
use gripforge_kit_guest::host::{KitModule, Kx};
use gripforge_kit_guest::shared::current_player;
use serde_json::{json, Value as Json};
use std::rc::Rc;

struct Streak;
struct Settings { every: u64, bonus: f64 }

impl KitModule for Streak {
    fn id(&self) -> &'static str { "acme.streak" }                       // the id of kit.json
    fn services(&self) -> &'static [&'static str] { &["acme.streak"] }   // what it serves to the other kits

    fn setup(&self, kx: &mut Kx) {
        let cfg = kx.config().clone();                                   // its `config` in the project
        kx.put(Settings { every: cfg["every"].as_u64().unwrap_or(3), bonus: cfg["bonus"].as_f64().unwrap_or(25.0) });
        kx.define_var("streak.count", "number", "Streak", None, Some(json!(0)));
        kx.on("tokens.collected", "collected");                          // an event of collect.tokens
    }

    fn on_event(&self, kx: &mut Kx, tag: &str, ev: &GameEvent) {
        if tag != "collected" { return; }
        let Some(player) = current_player(kx.host) else { return };
        // Read a component, write it back.
        let count = kx.host.entities.component(&player, "streak").and_then(|c| c["count"].as_u64()).unwrap_or(0) + 1;
        kx.host.entities.set(&player, "streak", json!({ "count": count, "kind": ev.payload["kind"] }));
        kx.set_num("streak.count", count as f64);
        let (every, bonus) = { let s = kx.data::<Settings>(); (s.every, s.bonus) };
        if count % every == 0 && kx.host.has_service("economy.money") {
            // A service of another kit.
            let balance = kx.call("economy.money", "add", &[json!(bonus), json!("streak")]).ok();
            kx.emit("streak.bonus", json!({ "count": count, "bonus": bonus, "balance": balance }));
        }
    }

    fn call(&self, kx: &mut Kx, _capability: &str, method: &str, _args: &[Json]) -> Result<Json, String> {
        match method {
            "count" => Ok(json!(current_player(kx.host)
                .and_then(|p| kx.host.entities.component(&p, "streak").and_then(|c| c["count"].as_u64()))
                .unwrap_or(0))),
            _ => Err(format!("acme.streak has no method {method}")),
        }
    }
}

/// What the build tool takes.
pub fn module() -> Rc<dyn KitModule> { Rc::new(Streak) }

The complete file with comments: examples/kit-third-party/src/lib.rs. The two crates a kit always has are gripforge-kit-guest (the kit side of the interfaces) and serde_json (the value model of the core: 3 and 3.0 stay distinct, the keys keep their order).

The API of a kit (Kx) #

Everything goes through the kx: &mut Kx each hook receives. The ones you need most:

The other hooks (ready, teardown, spawn, scene_enter, component, mission steps…) and the cost of each call are in the topic kit-modules §3. Which events a kit emits, which services it serves, with which arguments: gripforge kit api <kit-id> --section events,services, or the MCP tool gripforge_gamekit_api.

Rules that save time:

• A read returns a copy (component, get, get_var): change it, then write it back with set / set_var.
• Do not hold a reference read from the world across a call that writes (emit, set, call): Rust refuses it; clone what you need first (let cfg = kx.config().clone();).
• An event emitted in a hook is delivered after the hook, in the next round of the same tick.
• An isolated kit that panics is left out (its hooks are logged as failed); the game goes on without it. A kit in the common memory that panics stops the game (§2).

2. Build it on the build base #

gripforge kit build my-kit                 # both builds, in my-kit/build/
gripforge kit build my-kit --out <dir> --mode isolated|common|both --install --jobs 4 --json

(MCP: gripforge_third_party_kit_build { kit, out?, mode?, install? }; gripforge_third_party_kit_socle for the base.)

Built [email protected] on the build base [email protected] (structures 1.0, rustc 1.99.0 (…))
  isolated my-kit/build/acme.streak-1.0.0.isolated.wasm
           sha256 0730139b…  (168099 bytes)
           manifest my-kit/build/acme.streak-1.0.0.isolated.kit.json
  common   my-kit/build/acme.streak-1.0.0.common.wasm
           sha256 6a5a9843…  (179749 bytes)
           manifest my-kit/build/acme.streak-1.0.0.common.kit.json

The build base is what makes a binary built by anyone fit the contract. It is fixed by GripForge, in the kit SDK (socle.json; gripforge kit socle prints it), and it is not a choice of the kit:

After the build the tool checks the binary, and stops with what was expected and what was found:

• it is the build of the mode asked (isolated, or relocatable for the common memory);
• its structures table (the custom section gripforge.structs, written by the compiler from the types of the contract) is the one of the base — the version of the contract, then each structure, field by field;
• its contracts section is the one of the mode; an isolated build links only the functions of the core that carry numbers; nothing asks the system (file, clock, random: a crate that does is named).

Then it writes, per build, the .wasm and its manifest .kit.json — your kit.json completed with what the binary says: provides, consumes, memory (the mode), structs, sha256, bytes, built (the base, the toolchain) — and build.json, which names the two.

The two builds, the two ways a game loads your kit:

Both speak the same contract: the functions of the interfaces (kithost.world@1 …) by their numbers, and in memory the structures of gripforge docs kit-structures — FixedValue, FixedPair, FixedBlock for any list or dictionary, the records of the shared zone, the event queue. Nothing of a compiler's own layout crosses, which is why a kit built by another Rust than the core's loads. These two builds are the only ways a kit module is loaded: a binary that is neither (not relocatable, no entry across memories — a kit module with a memory of its own reached by the calls bridge, as they were once built) is refused by every tool and by the page, by name (the binary is not a kit module a game can declare: it is neither relocatable … nor isolated … build the kit from its source with "gripforge kit build <kit folder>").

Build both and let each game choose: the source is the same.

3. Declare it in the game — and say how far you trust it #

gripforge kit add <game> --kit my-kit/build                       # isolated (the default)
gripforge kit add <game> --kit my-kit/build --trust common        # in the common memory: only a kit you trust
gripforge kit add <game> --wasm <file|url> --manifest <.kit.json|url> [--trust common] [--config '{"every":3}'] [--modules <dir>] [--check]

(MCP: gripforge_third_party_kit_add { game, kit | wasm + manifest, trust?, config?, modules?, check? }.)

<game> is a game.json or the folder that holds it. --kit takes the output folder of kit build and picks the build of the trust you give; --wasm + --manifest name one build yourself (files, or http(s) URLs: a module declared by URL is not copied, its SHA-256 is what holds it). The command reads the module and its manifest, checks them, and — unless --check — writes:

// project.thirdPartyKits[]
{ "id": "acme.streak", "version": "1.0.0", "source": "./third-party-kits/acme.streak-1.0.0.wasm",
  "sha256": "0730139b…", "bytes": 168099, "trust": "isolated", "manifest": { … } }
// project.installed[]      { "id": "acme.streak", "version": "1.0.0", "enabled": true, "config": { "every": 3 } }
// lock.order               […, "acme.streak"]            (a new kit mounts last: after the kits it calls)
// lock.kits["acme.streak"] { "version": "1.0.0", "enabled": true }
// lock.thirdParty["acme.streak"]   { "version": "1.0.0", "sha256": "0730139b…", "bytes": 168099, "trust": "isolated" }

and copies the module beside the game (third-party-kits/) and, when the game has kit modules, into them (kit-modules.json then says "memory": "isolated" or "common" for it: how the page loads it).

trust is the word of the maker of the game, for this kit:

• absent or "isolated": the kit keeps a memory of its own. Use it for any kit you did not write.
• "common": the kit enters the memory of the game. The command warns you each time (… is NOT isolated — a fault in it can corrupt the game). The lock freezes it like the version and the SHA-256: a trust edited by hand is refused by verify, the export and the page; it is changed by declaring the kit again.
• The build declared must be the one of the trust: an isolated binary is never placed in the common memory, a common binary never run isolated. There is no fallback from one to the other.

What is checked, each with a message that says what to change:

Its config is the config of its entry in project.installed (--config, kept when the kit is added again).

4. Verify, list, remove #

gripforge kit verify --kit my-kit/build [--trust common] --modules <kit modules>    # one build against a core, no game
gripforge kit verify <game> [kit-id] [--modules <dir>]                              # what a game declares
gripforge kit list <game>
gripforge kit remove <game> <kit-id>

(MCP: gripforge_third_party_kit_verify_build, …_verify, …_list, …_remove.)

One build against a core — before you hand a kit to someone, or when a core changes:

ok   [email protected]  isolated  sha256 0730139b43cd5fcc…  (168099 bytes)
     contract    expected [email protected], found [email protected]
     structures  expected 1.0, found 1.0

It compares the version of the contract and of every interface the kit consumes with what the core provides, then the structures of the contract one by one with the core's (kit-modules.json carries them). A refusal names the structure or the interface, what was expected and what was found; the exit code is 2.

What a game declares: each module is read again from its source and must have the SHA-256 the game declares and its lock froze; its manifest must still be what the binary says; the binary must be the build of the trust declared; the declaration, installed, the lock and the kit modules of the game must agree on the version, the fingerprint and the trust. Exit code 2 when a kit does not verify. list shows, per kit, isolated or COMMON MEMORY (trusted), its place in the mount order, its config, what it requires and serves. remove takes the declaration, the installed entry, the lock lines, the copy of the module and its kit module away.

5. Check what the game declares before it is played #

gripforge kit verify <game>
gripforge kit list <game>

verify reads every declared module again and compares it with the declaration and the lock (§4); list shows the mount order, the trust of each kit, what it requires and serves. The game is then played in a page (§6): the page loads the kit modules of the game exactly as declared and, when something does not fit, names the kit and the cause instead of starting. The services of a kit are called by the names of its API (gripforge kit api <kit>), its events are the topics that API lists.

| What you see | Cause | | the kit modules did not link: … was compiled against kithost.world@^1.3; the game provides [email protected] | the binary and the core are of different majors: build the kit again with the CLI of that core | | the kit modules did not link: … (memory "isolated"): structures contract 2.0, the owner (kithost.core) provides 1.0 … | the kit and the core are not of the same structures contract: build the kit again (§2), check with gripforge kit verify --kit … --modules … | | … (memory "common"): declared memory "common" but the binary is not relocatable / … the binary is relocatable … but it is declared memory "isolated" | the folder holds the build of the other mode: gripforge kit add again with the trust you mean (§3) | | … is in project.installed but not in lock.order | add the id to lock.order | | game.engine is in lock.order but not in project.installed | add its entry to installed: every id of lock.order has one, game.engine included | | your kit is mounted but nothing happens | the event has another topic or payload than you think (gripforge kit api <kit>; the line events lists every topic that was emitted), or the service is not served (has_service) because that kit is missing or mounted later | | <kit>.<method> is not served by <kit> / acme.streak has no method … | the method name (they are the names of the TypeScript API: canAfford, not can_afford) |

Both builds of the example (isolated and common) give the same game: same results, events, vars and components.

6. Export the game and play it in a page #

A game folder that already has its kit modules (an exported web game with runtime-rust/kit-modules/): after gripforge kit add <folder> … it is ready — npm run dev in the folder, open the address it prints.

A game of the site: gripforge game-export <gkp_id> <folder> downloads the game with its player and its kit modules; gripforge kit add <folder> --kit <build folder> then declares your kit in that folder (§3: the module and its manifest are read and checked, the declaration and the lock are written, the module goes with the kit modules of the game) and gripforge kit verify <folder> checks the result. A third-party kit has no TypeScript runtime and no view: nothing else is built for it. Both modes take the same path.

The page plays it like any kit. The kit modules are the Rust logic of every game (?logic=wasm and ?logic=kits mean the same): the page loads the core and the kits of the game's lock — yours with them — and nothing else. The console says it:

[gripforge] kit logic modules: the core and 5 kits (third-party: acme.streak)

Before a module is compiled the page compares it with the declaration: the version of kit-modules.json with the declared and locked one, the SHA-256 of the bytes with the declared one, the way the package loads it with the trust declared and locked. When it links the modules, the loader compares the structures table of your kit with the core's. There is no other wasm behind the kit modules: when something does not fit, the game does not start and the page shows the error, naming the kit, its version, its mode and the cause (topic kit-modules §1). It never plays the game without your kit in silence, and never loads it another way than declared.

The export refuses, with the reason, a game it could only ship broken:

7. Versions: what stays compatible #

• The interfaces. Your binary names what it was built against: consumes kithost.world@^1.3. A core that provides [email protected] accepts it; a core at 2.0.0 refuses it at load with a message. Within a major an interface only grows at the end: a function keeps its number, its name and its types, new ones get new numbers. The schemas of the interfaces are compared with their 1.0 snapshot in GripForge's CI.
• The structures. What is shared in memory is versioned apart (structures 1.0). A structure added, or a field added in reserved bytes, is a minor: a kit built on 1.0 loads in a core at 1.1. A size, an offset or a meaning changed is a major: the two do not load together, and every tool says so before the page does (structures contract: expected 2.0 …, found 1.0). Nothing about the compiler is compared.
• The build base moves with the CLI. A new CLI may pin another Rust or other crate versions: a kit built on the older base still loads while the contract and the structures are the same majors. Build again to follow.
• Your own versions. Change version in kit.json, build, then gripforge kit add again: it moves the version and the SHA-256 in the declaration, installed and the lock. The lock is what a game is checked against: the export and the page refuse a module of another version or with other bytes than the lock froze. The services you serve to other kits follow the rule of the interfaces: add methods, never change one.
• A SHA-256 names a binary, not a source. Two builds of the same source by the same CLI installed at the same place are the same bytes; built from an SDK at another path they differ (the compiler's symbol names depend on it). Ship the binary you verified.

7b. Changing and stopping what another kit decides: interceptable hooks #

An event cannot be modified or cancelled. The bus notifies after the fact, every subscriber in a fixed order. What a kit lets others change or stop is an interceptable hook of game.engine (engine.hooks, topic mods-engine): a decision the kit asks before it acts, and waits for. If you want to change a decision of another kit, tap its hook; if you want your own decisions to be changeable, declare a hook and run it before you act (then emit your event). Worked example: examples/kit-third-party-hooks (acme.tax).

Tap the hook of another kit, in code. The hooks of a kit are in its API (gripforge kit api economy.money): name, payload, which fields are mutable, whether it is cancellable.

fn setup(&self, kx: &mut Kx) {
    // priority: higher runs first, among the taps in code and the taps in data of the game and its mods.
    let opts = json!({ "priority": 0, "owner": "acme.tax", "id": "acme.tax.earn" });
    let _ = kx.call("engine.hooks", "tap", &[json!("money.earn"), kx.callback("earn"), opts]);
}

/// Called synchronously each time economy.money is about to credit: args[0] is the payload as the taps before
/// left it. Answer nothing (Json::Null), `{ set }` on mutable fields, or `{ cancel }` on a cancellable hook.
fn callback(&self, kx: &mut Kx, name: &str, args: &[Json]) -> Result<Json, String> {
    let amount = args[0]["amount"].as_f64().unwrap_or(0.0);
    if amount > 500.0 {
        return Ok(json!({ "cancel": true, "reason": "over_cap" }));
    }
    Ok(json!({ "set": { "amount": amount * 0.8 }, "reason": "tax" }))
}

A field that is not mutable, a value its schema refuses or a cancel of a hook that is not cancellable is refused and announced (engine.hook.refused); the game can also refuse a hook to mods (mods.deny.hooks).

Declare a hook of your own, in kit.json — the game schema then carries it, and a game, a mod or another module taps it like any hook:

"hooks": { "tax.rate": { "mutable": ["rate"], "cancellable": false,
                         "fields": { "rate": { "type": "number", "minimum": 0, "maximum": 1 } } } }

let asked = kx.call("engine.hooks", "run", &[json!("tax.rate"), json!({ "amount": amount, "rate": rate })])?;
if asked["cancelled"] == json!(true) { return Ok(Json::Null); }      // only when the hook is cancellable
let rate = asked["payload"]["rate"].as_f64().unwrap_or(rate);        // what the taps left
// … act, THEN notify:
kx.emit("tax.taken", json!({ "amount": amount, "rate": rate }));

See who did what: logic.hooks.trace() in the page or in a test lists every run — the taps in order, the fields each one set, who cancelled and why.

Both builds tap and declare hooks the same way (the test plays acme.tax isolated and in the common memory and compares the decisions).

8. Limits today #

• Kit modules only. A third-party kit exists only as its own module, which is how every game is played in Rust logic; the TypeScript KitHost cannot play it. What it means for you: the game needs kit modules for every kit it installs, so every GripForge kit of the game must have a Rust module (gripforge game-logic <gkp_id> says when one has not).
• Isolation is of the memory. An isolated kit cannot read or write the memory of the game, cannot take a link that hands an address, and writes in the shared zone only the event queue and its own regions. It is still code the game runs: it can emit events, set components and vars, call services, spend time. Read the source of a kit before you install it, isolated or not; common is for a kit you would have written yourself.
• No shared-memory build. The build tool does not make the build for a memory shared between threads: a game with a trusted third-party kit runs on the plain build of the kit modules (the page picks it by itself).
• Hosted creation. Create game can generate and retain project-local isolated kits after compilation and integration checks. The global search/pickers still list stock kits; arbitrary third-party uploads use an exported game folder (§3). Native exports of generated kits are not yet supported.
• The binary carries neither its id nor its version as a field the tools compare. What is compared is the manifest written by the build, the declaration, the lock and kit-modules.json; the SHA-256 ties them to the bytes. Keep fn id() and kit.json in step yourself; play the game (§6) after each add — the line of the console (kit logic modules: … (third-party: …)) must name your kit.
• Updating an exported game from the site (gripforge game-export <gkp_id> <folder> again) knows GripForge's kits only: it reports game.json and the kit modules as edited locally. After it, gripforge kit verify <folder>, and gripforge kit add again if the kit no longer verifies (its module is still in third-party-kits/).
• Logic only. A kit module computes; what is drawn comes from the presentation modules of the player (gripforge docs porting). Your kit shows itself through vars (HUD), components and events that existing views already read.
• Rust only. The kit side of the contract is the Rust crate of the kit SDK. The contract itself is not Rust's — numbered functions and structures with a declared layout — but there is no binding for another language yet.
• Cost. A kit module pays for each call to the core; an isolated one also pays one copy of the message each way. Read once per hook, prefer one query to many get, keep per-tick hooks for what needs them (topic kit-modules §3 and §6).

Hosted Create game now supports project-local, isolated generated Rust kits with bounded compilation, integration tests and admin history. Local CLI/MCP commands remain available for exported games.