Using the Game Kits from Unity (GfGameHost) #

Play a GripForge game inside a Unity project: one component, GfGameHost, runs the Game Kits and tells your scene what happened; a second one, GfGameView, draws what the kits ask. Readable offline: gripforge docs unity, or the MCP tool gripforge_docs (topic unity).

What it is for #

The Unity package ai.gripforge.kits runs the same Rust logic of the Game Kits as the web player — movement, combat, inventory, missions, saves — from the same game file, through two native libraries:

They are the same libraries the Godot addon and the desktop player load. No rule of a kit is written in C#: the package only calls the libraries and maps what they ask to Unity objects. gripforge game-export --target unity makes the whole Unity project from a game. You may change the rules from C# by tapping hooks or adding registry entries.

Getting started #

For a Unity user: no Rust, no compiler, no GripForge repository. The libraries are prebuilt for every platform; the CLI fetches them.

1. Install the CLI (Node.js 22.19 or later): curl -fsSL https://gripforge.ai/cli/install.sh | sh on Linux and macOS, npm install -g https://gripforge.ai/cli/gripforge-cli-<version>.tgz on Windows (the current version is in https://gripforge.ai/cli/latest.json). Then gripforge login. An older CLI: gripforge update.

2. Export your game as a Unity project:

   gripforge game-export gkp_... ./my-unity-game --target unity

   The CLI downloads the web export of the game, fetches the libraries of its own version for every platform (kept in a cache), checks each file against the sha256 it carries, and writes the project. --platforms linux-x86_64 (or windows-x86_64, macos-universal) fetches only what you need. A game you already exported for the web converts the same way: gripforge game-export ./my-unity-game --target unity --from-web ./my-web-export.

3. Open the folder with Unity 6 (6000.0 or later) from the Unity Hub (Add project from disk). The first opening resolves the packages and sets the project up once: the Universal Render Pipeline, linear colours, both input systems, and the scene Assets/Scenes/Main.unity (a GfGameHost and its GfGameView). The menu GripForge → Set up the project does it again; it never changes what you already set.

4. Run it: open Assets/Scenes/Main.unity and press Play. Or build a player from the command line:

   Unity -batchmode -quit -projectPath ./my-unity-game -buildTarget Linux64 \
     -executeMethod GripForge.Kits.Editor.GfBuild.Player -gfOut build/linux/game

   (Win64, OSXUniversal likewise, where your editor has their build support.)

5. Change a rule in Assets/GameMods.cs (yours: an update never rewrites it) by tapping a hook of a kit:

   host.TapHook("combat.damage", (payload, hook) =>
       payload.Get("targetTeam") as string == "enemy" ? J.Obj("set", J.Obj("multiply", 2.0)) : null,
       J.Obj("id", "double_hits"));

Prerequisites #

• Unity 6 (6000.0 or later), with the build support of the platforms you build for.
• The packages the project names (fetched by Unity at the first opening): Universal Render Pipeline, glTFast (the models are read at run time), the Input System.
• A 64-bit platform: Linux x86-64, Windows x86-64, macOS (one universal library for Apple silicon and Intel).

The project #

The export holds no .wasm: the presentation modules are native code of libgfpresent.

Exporting a game #

gripforge game-export <gkp_id> [folder] --target unity [--platforms linux-x86_64,windows-x86_64,macos-universal]
                      [--capi <libraries folder>] [--package <ai.gripforge.kits folder>] [--webui-host <folder>]
                      [--bundle-web-engine | --webui-engine-when first-load|install] [--webui-engine-url <base>]
                      [--check] [--force] [--json]
gripforge game-export [folder] --target unity --from-web <web export> [same options]

• --platforms limits the libraries to the platforms named.
• --capi <dir> takes libraries you already have, offline: <platform>/libgfkits.* and <platform>/libgfpresent.* (the capi/ folder of a release of the native libraries). GRIPFORGE_UNITY_CAPI does the same.
• --package <dir> takes a copy of the package ai.gripforge.kits you already have (GRIPFORGE_UNITY_PACKAGE).
• --check writes nothing and tells what would change; --json prints the report.
• Updating: run the export again on the folder. The files the export manages (the game data, the package) are replaced; one you edited stops the update and is named (exit code 2) — --force replaces it. Your files are written once and kept.
• --bundle-web-engine puts the browser engine of the interface in the project (webui-engine/): nothing is ever downloaded while the game plays.

Drawing the game: GfGameView #

GfGameView needs a GfGameHost (beside it or above it). Every drawn frame it steps the logic, asks the host for the frame of the presentation and applies it:

• The entities. One object per entity of the game at its transform, interpolated between the two last ticks. The model bound to its slot is read from its .glb at run time (glTFast, the node names of the file kept) and sized by the rules of the web player (a character stands 1.8 m, model.placement…). An entity with no model is drawn by its stand-in (a capsule, a car body, a marker ring…), as the web player draws it.
• The clips. The clip of the state the kit asks for (model.anim): the one the pack maps to the state, else one of the same name, else one alike, else idle. One-shot states play once; a change cross-fades in 0.12 s; clips advance with the time of the game.
• The camera the kits describe in the camera.* state vars: top-down (perspective or orthographic), chase, first person; and what a module imposes (a pose, a mode, a shake).
• The scene. The default look of the web player, then what the kits set over it: the sun, the fill (Unity's three-colour ambient light), the exposure, the background, the fog, the bloom and grading of world.lighting (a global volume, ACES tone curve).
• What the kits draw themselves. The presentation modules of the kits run inside libgfkits; GfGameView applies their commands with Unity objects: meshes, textures, materials (the shader GripForge/Standard), nodes, instances, models of slots, lights, entity looks, effects, skeletons, sound.

The game lives under one object, GfWorld, mirrored on Z: the kits and the glTF files are right handed, Unity is left handed, and under that object the positions and rotations of the game are written as the kits give them. Things you place yourself in world space relate to the game through GfSpace.ToUnity / GfSpace.FromUnity.

What is not drawn is not invented. A command GfGameView does not apply is answered Refused to its module (which may draw something simpler by itself) and counted in Report().refused. See Known limits.

Which kits run in Unity #

Every kit whose logic is in the native library runs in Unity with the rules of the web: the catalogue says it by itself (gripforge kit api <kit>, section Targets: unity: native (libgfkits)) and names what is still missing, never leaving it out — 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 release, or a part of the network core not available natively (WebRTC, the shared physics of net.physics). The export lists the same lacks as warnings. Before writing a mechanism of your own in C#, read the kit's Targets: if it says native (libgfkits), use the kit (its config, hooks and mods).

HUD and menus #

The interface of the kits is ui.webui on every engine: the fragments of the kits, the same page as the web, run in an embedded browser engine (never the browser of the machine) by the ui.webui module of libgfpresent. Its picture is shown over the game, and it gets every input event before the game: what the interface takes never reaches the game. A click on a button of a fragment becomes the command of its kit, as on the web.

• The browser engine is installed once in a cache shared by every game of the user, the first time a game starts (the game plays meanwhile, a band shows the download) — or put in the project with --bundle-web-engine, or installed beforehand with gripforge webui-engine prepare.
• No interface is never silent: without the module, the host page or the engine, the game runs and the named reason (webui-module-missing, webui-host-page-missing, webui-engine-no-archive…) is shown in a band at the top of the window.
• Where the interface did not start, or for a game without fragments, a provisional HUD is drawn, marked as such.

Command line of a player #

A built player (or the editor) reads these options; nothing happens without them:

API reference #

GfGameHost (namespace GripForge.Kits) is a MonoBehaviour. Everything runs on the main thread. Values are the JSON of the kits as C# values: objects are Dictionary<string, object>, arrays List<object>, numbers double; J.Obj(…), J.Arr(…), J.Str(…), J.Num(…) and dict.Get(key) read and build them.

Properties #

Loading and starting #

Time #

Inputs #

GfGameView forwards the keyboard, the mouse and the gamepad itself (forwardInput).

Entities #

State, config, registries #

Services, operations, events #

Hooks #

Saves #

Presentation #

PresentNative, PresentKit, PresentModule, PresentStart, PresentFrame, PresentSnapshot, PresentCommands, PresentResult, PresentCommand, PresentInfo, HostRequests, AudioTake and UiStart / UiFrame / UiInput / UiStop are what GfGameView calls each frame; a view of your own calls them in the same order (the order of a frame is the one of GfGameView.Update).

Status #

Errors #

A presentation module the library does not have is named in the log at start and its kit is not drawn by a module; the game still runs.

Known limits #

• Shaders written by the modules. Unity compiles no shader while a game runs. A material a module shades with its own WGSL (MaterialWgsl: skies, water, roads) is drawn with its standard base material, and the module is told (Shader { ok: false }); a fullscreen pass of a module (PostPass) is not drawn.
• The look is close to the web player's, not identical: Unity's tone curve, light falloff and shadows differ.
• The picture of the interface is copied through memory each time it changes.
• The chase camera does not cast the rays that keep it out of walls.
• Everything else a module asks and the view does not draw is listed by GfGameView.Report().refused.

Versions #

The package carries the version of the native libraries it was written for (package.json), and checks the interface of libgfkits at start. Export again after updating the CLI: the package, the libraries and the game data are replaced together.