Using the Game Kits on the desktop (the native player) #

Make a game that starts with a double click on Linux or Windows — no browser, no Rust, no Node on the player's machine. Readable offline: grip-forge docs desktop, or the MCP tool gripforge_docs (topic desktop).

What it is for #

gripforge game-export --target desktop makes a folder from a game: the prebuilt native player and the game as data. The player is the Bevy player of the web, built for the desktop; it loads libgfkits, the Rust logic of the Game Kits, and libgfpresent, the library of the kits' presentation modules — the files the Godot addon uses. One source per kit and per module: compiled to WebAssembly for the web page, to native code here — the same rules, the same drawing commands, no interpreter in between. Exporting a game compiles nothing: the same player opens any game.

Prerequisites #

• The GripForge CLI.
• A game (gkp_…), or its web export (gripforge game-export <gkp_id> <folder>).
• On the player's machine: Linux x86-64 or Windows x86-64 (10 and later) with a Vulkan driver. See Platforms.

Install #

Nothing to install beside the CLI, 0.3.53 or later (gripforge update gives the current one). The player is fetched by the export: about 30 MB per platform the first time, then from the cache.

First run: export a game #

gripforge game-export gkp_1234 my-game --target desktop
my-game/play.sh          # Linux; on Windows: my-game\play.cmd

The command downloads the web export of the game under my-game/.gripforge/web, takes the prebuilt player, and writes:

Options:

Run the export again on the same folder to update it. A file you edited stops the update unless --force is given.

Where the player comes from #

The CLI carries the catalogue of one player package: its version and, per platform, the sha256 of the archive and of every file in it. The archive is downloaded from https://gripforge.ai/cli/gripforge-player/<version>/<archive> (the assets of the release gripforge-player-v<version>; GRIPFORGE_DESKTOP_PLAYER_URL names another base that holds <version>/<archive>), checked against that catalogue before anything is unpacked, and kept in ~/.grip-forge/cache/gripforge-player-native/<version>. Nothing is trusted from the server.

Errors #

The export stops with a named code when it cannot have the player:

A folder given to --runtime holds either the files of a release (the archives) or the unpacked platforms with their manifest.json. When the CLI has no catalogue, the manifest of the folder is used and the report says the player was not checked against a published release.

Platforms #

What the native window shows #

• The models of the game, their clips, the camera, the lights, the scenery and the effects: everything the kits draw through their presentation modules, with the same module host as the web player.
• The export warns about a kit the web draws through a module the player does not link.
• HUD and menus: the fragments of the kits (ui.webui), the same page as the web, drawn over the game by the ui.webui module of the library (Linux). The export copies them into game/ (present-modules.json, modules/*.ui.mjs). See HUD and menus below and Known limits.
• Keyboard and mouse buttons go to the input actions of the kits; the kits ask for full screen and pointer lock through their display settings.
• Which kits run: every kit whose logic is in the native library runs here with the rules of the web. The catalogue says it (gripforge kit api <kit>, section Targets: rust: native (libgfkits)) and names what is still missing on the desktop: a view of a kit drawn on the web page only (to provide by a ui.webui fragment), a fragment not yet in the published player, or a part of the network core (below).

HUD and menus (the browser engine) #

The interface of a game is made of web fragments (ui.webui). Its native form needs a browser engine embedded in the game — never the browser of the machine: about 133 MB to download on Linux (308 MB once unpacked), 153 MB on Windows, 127 MB (Apple silicon) or 135 MB (Intel) on macOS. It is a dependency installed once into a cache shared by every game of the user, at one of three moments:

• the first time the game starts (default): the game loads and plays meanwhile, the band at the top of the window shows the download, and the HUD appears when the engine is ready. A download cut in the middle is tried again, then resumed where it stopped at the next start;
• when the game is installed: ./play.sh --prepare installs it with no window and exits (0 = ready); an installer or a machine without network at play time runs it once. gripforge webui-engine prepare does the same without any game. Export with --webui-engine-when install for a game that must never download while it plays;
• in the game: --bundle-web-engine puts it in the exported folder; nothing is downloaded, ever.

The file downloaded is checked against the sum the game carries before anything is unpacked: the address can be changed (--webui-engine-url <base> at export, --webui-engine-url=<base> or GRIPFORGE_WEBUI_ENGINE_URL when the game starts, a local folder as file:///…/), the engine cannot.

Where the engine is looked for, in order: webui-engine/<version>-<platform>/ beside the player, the folder named by GRIPFORGE_WEBUI_ENGINE_DIR (or --webui-engine-dir=<dir>) or else the cache of the user, then a download; --no-webui-engine-download forbids the download.

The cache of the user is ~/.cache/gripforge/webui-engine/ on Linux ($XDG_CACHE_HOME/gripforge/… when set), %LOCALAPPDATA%\GripForge\webui-engine\ on Windows and ~/Library/Caches/GripForge/webui-engine/ on macOS; the engine of a version lives in its own folder there, <version>-<platform>/ (for example 154.0.34-1-macos-aarch64/). An archive of the engine has no folder at its top: to install one by hand, unpack it INTO that folder (mkdir -p <cache>/<version>-<platform> && tar xzf <archive> -C <cache>/<version>-<platform>), or let gripforge webui-engine prepare do it.

No interface is never silent. When the module, the host page or the engine is missing, or the engine cannot be fetched, the game starts and goes on, and the named reason (webui-module-missing, webui-host-page-missing, webui-engine-no-archive, webui-engine-offline, webui-engine-checksum…) is written in the log and shown in a band at the top of the window, with where the engine was looked for. While the engine is fetched the band shows the progress.

The picture of the interface is a GPU texture the browser shares with the game: nothing is copied by the processor. On a machine where the browser cannot share one (a single NVIDIA card today), the module falls back to pictures copied through memory and says so in the log: [ui.webui] FALLBACK cef-copy: no-shared-picture.

Checking an export #

my-game/bin/linux-x86_64/gripforge-player --replay my-game/game/game.json --reference reference.json

No window is opened: the game is played through the operations of a parity document { fixture, trace } and its trace is compared with the reference trace — the one the web host and the Godot addon are held to. It prints replay ok: N frames identical to the reference, or the first difference and exits 1.

GRIPFORGE_STATS=2 my-game/play.sh prints the frame rate every two seconds. GRIPFORGE_CAPTURE=shot.png GRIPFORGE_CAPTURE_AFTER=8 my-game/play.sh saves what the window shows after eight seconds and exits. gripforge-player --about prints the version, the presentation ABI, the library it loads and the kits it has a module for. GRIPFORGE_PRESENT_LIBRARY=<file> loads another build of the library.

Versions #

Known limits #

• The HUD and the menu of ui.menu (title screen, pause, Options) are web fragments; a click on one of their buttons becomes the command of its kit, as on the web (an event no module declared is refused by name in the log). Kits without a fragment are drawn as UI trees of their modules. The HUD of the car football and of the kart race is made of fragments too: the scoreboard and its banners (sport.ball), the objective (input.actions), the key prompts (ui.prompts), the end of the match (ui.endscreen), the race panel, item, speed and results (race.kart) and the mini-map (hud.minimap). The start screen of the race (shown by the web page while it holds the game) is not shown here: the race starts when the title screen closes.
• The browser engine of the interface is built for Linux x86-64, Windows x86-64 (pictures copied through memory) and macOS (pictures copied through memory). It was run on screen on Linux; on Windows only under Wine; never on a Mac.
• The player itself: Linux and Windows x86-64 today; macOS is not available yet (see Platforms).
• Sound: the audio kit runs (its state is in the game), but the native window plays no sound yet.
• Gamepads are not read by the native window yet.
• Network kits (net.*): the network core is served natively (TCP+UDP, then the WebSocket bridge); WebRTC and the shared physics of net.physics are not, and are refused by name.
• Saves: the kit host keeps them in memory; they are not written to the disk yet.
• A game holds at most 128 model files and 256 MB of models.