HTML interface over your game (ui.webui) #

Draw menus, HUD, inventories and dialogs as a web page over the game, written once, with one page API, on every output. Readable offline: gripforge docs ui-webui, or the MCP tool gripforge_docs (topic ui-webui).

What it is for #

ui.webui is the bridge between an HTML / JavaScript page and the game. The page can use any framework (or plain DOM) and is built by a web bundler. The kit pushes the game state to the page, announces the commands the page sends, and shares the pointer and the keyboard between the page and the game. It decides nothing of the game: a command of the page is announced (ui.command) and the kit or rule that answers it owns the decision.

Turn it on #

gripforge_gamekit_install   { project_id: "gkp_…", id: "ui.webui" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "ui.webui", config: { "stateHz": 15, "forwardEvents": ["score.changed"] } }

It requires game.engine. On Godot, Unity and Unreal the game chooses between the engine's native UI and ui.webui; by default one way per game (mixNativeUi: true keeps both, best avoided). The full reference is gripforge kit api ui.webui.

The page #

gf-webui.js (no framework, no dependency) is the same file on every output:

import { createBridge } from './gf-webui.js'

const bridge = createBridge({
  onState: (state) => render(state),           // full state, pushed by the game when it changes
  onEvent: (kind, data) => toast(kind, data),  // one-shot events
  onOpen: () => bridge.request(),              // (re)connected: ask for the full state again
})
bridge.start()
button.onclick = () => bridge.send('heal', { amount: 10 })

The page picks its transport by itself: web (the host defined window.__gfui_send), ipc (injected by the engine into the off-screen page), devws (a WebSocket to the game, the page open in a normal browser) or mock (?mock=1, no game).

Two layout rules make the input sharing exact:

1. a transparent background (paint one only under html.gfui-standalone);
2. a zero-sized root (#gfui-root { position: fixed; width: 0; height: 0 }): every piece of UI is positioned against the window and covers only what it paints; no pointer-events declarations.

Settings and defaults #

Only stateHz and theme are moddable: page, devUrl, browserPath, transport, mount... say which page, browser or port is used, and a mod must not point the bridge at another page.

Input sharing #

What the page does not claim belongs to the game.

• Keep the page background transparent (a still, fully opaque page is hidden after a few seconds).
• Off-screen, a press goes to the page only where the last frame is not transparent; a release goes to whoever received the press; moves are never consumed.
• The keyboard belongs to the page only while one of its elements has the focus; a clicked button gives it back, a text field keeps it until the player clicks the game.
• On the web, native DOM routing does it all.
• Unity cannot consume an input event: gate your game input with GfWebUI.GameOwnsPointer / GfWebUI.GameOwnsKeyboard.

Building the page #

ui/build.mjs builds the page with the bundler and copies it where each output serves it; it is incremental (a hash of the sources is stamped in the output). Node.js 18+ is needed on the development machine only; without it the engines keep the last page.

Fragments: the web UI of presentation modules #

A presentation module can bring its HUD and menus as a fragment: one file under modules/, ui.mjs exporting React components (the page's React, the module bundles none) and/or templates with data bindings, or a .html template. A module declares it in the web entry of present-modules.json ({ ui, views, vars, shared, emits, layer, origin, sha256 }); the game declares one with the fragments config (one per kit, the last wins).

• Data in: the fragment receives only the keys it lists (views, vars, shared, theme, themeVars, config, lang, assets, inputs, planned), as objects, with a delta of what changed. The theme also lands as --gf-* CSS variables (var(--gf-accent, <yours>)).
• Events back: dispatch(event, payload) of a component, or data-gf-on-click of a template, sends ui:emit. Accepted only for an event listed in emits; it becomes ui.command { cmd, payload, kit }, otherwise ui.fragment.refused. A fragment never feeds game input.
• Direct calls (secrets): call(method, args) reaches a method of the fragment's own kit listed in calls of its web/ui.json. It is never an event: what it carries (a password typed in a sign-in form) reaches no bus, mod, trace or log.
• Trust: a fragment runs with the trust of the mod scripts of game.engine. origin: "mod:<id>" obeys the mods policy (mods.enabled, mods.disabled, mods.deny.kits); sha256 is checked when given; scripts and on* attributes of a template are dropped.
• One way per kit: when a fragment draws a kit's interface, that kit's page views are not mounted beside it, so a HUD is never drawn twice. A refused fragment gives the page view back.
• ui.tree: a module that describes its UI as a tree is drawn as DOM by this kit too; both end in the same layer.

Events and service #

The kit declares no hook. The state and the outbox are not saved: the game pushes its state again after a load.

Engines and limits #

• The web player and the Godot web export need nothing more than the page.
• Desktop engines need a Chromium-based browser installed on the player's machine. The page is served from the project files (no HTTP server, no fixed port), frames are transported as images, so cost grows with a page that animates: renderScale and everyNthFrame trade quality for cost.
• Text is rendered at device scale 1 off-screen. Mobile and consoles are not covered by the off-screen path; Unity WebGL and Unreal HTML5 are not delivered.

When it does not do what you expect #