@ignifx/electron

What this is / when to use#

The Electron half of ignifx. It turns a game that already runs in a browser into a desktop app, without a second copy of the game: one renderer bundle serves both builds.

Three entry points, one per Electron process:

Use it when you are packaging a game, or debugging one that behaves differently on the desktop.

Environment#

Engine >=0.0.0 <1.0.0 · Electron 44.x (peer, optional) · Babylon Lite 1.27.0 through @ignifx/core.

The fastest way in is the scaffolder — it writes everything below for you:

npx @ignifx/cli my-game --template 3d-third-person --desktopcd my-game && pnpm install && pnpm dev:desktop

Mental model#

main process                       renderer (sandboxed, context-isolated)
────────────                       ──────────────────────────────────────
applyWebGpuSwitches()   ─┐
registerIgnifxScheme()   │ before app.whenReady()
                        ─┘
await app.whenReady()
serveIgnifxProtocol(dir) ──────►   ignifx://app/index.html   (secure origin)
createGameWindow({…})    ──────►   window, strict CSP header
installHostHandlers({window})
        ▲                                  │
        └────── ipcMain.handle ◄─── preload: exposeIgnifxHost()
                                           │  window.ignifxHost
                                           ▼
                                    electron() extension
                                      → app.platform.kind = "electron"
                                      → app.storage on the file system
                                      → app.desktop

The renderer never imports electron. It has no Node, no require, and no module system — window.ignifxHost is the entire interface, and electron() is what turns it into app.desktop and a StorageBackend.

First app#

desktop/main.ts — the Electron entry. The order is Chromium's, not a preference: a switch appended after whenReady is inert, and the symptom is navigator.gpu === undefined with no error anywhere.

import { join } from "node:path";import {  applyWebGpuSwitches,  createGameWindow,  installHostHandlers,  registerIgnifxScheme,  serveIgnifxProtocol,} from "@ignifx/electron/main";import { app } from "electron";const DEV_SERVER_URL = process.env["ELECTRON_RENDERER_URL"];applyWebGpuSwitches();registerIgnifxScheme();await app.whenReady();if (DEV_SERVER_URL === undefined) {  serveIgnifxProtocol(join(import.meta.dirname, "../renderer"));}const window = createGameWindow({  entry: DEV_SERVER_URL ?? "index.html",  preload: join(import.meta.dirname, "../preload/index.cjs"),  width: 1600,  height: 900,  title: "My Game",});installHostHandlers({ window });

desktop/preload.ts — two lines, and it must be built to CommonJS (see Gotchas).

import { exposeIgnifxHost } from "@ignifx/electron/preload";exposeIgnifxHost();

src/main.ts — the game, unchanged apart from one extension:

import { createApp } from "@ignifx/core";import { electron } from "@ignifx/electron";const canvas = document.querySelector("canvas");if (!(canvas instanceof HTMLCanvasElement)) {  throw new Error("the game needs a <canvas> on the page");}const app = await createApp({  canvas,  // First in the list: it only needs core, and `app.storage` should be the file backend before  // anything else reads a setting from it. A real game adds physics(), input(), audio() and the  // rest of its extensions after it.  extensions: [electron()],});app.log.info("desktop:", app.desktop.isElectron);

Register electron() unconditionally. Without a preload bridge it logs one debug line and gives you an app.desktop that answers isElectron === false, so the browser build is unchanged.

Core APIs#

app.desktop#

Everything but isElectron and versions rejects with IGX-1462 in a browser build.

@ignifx/electron/main#

app.storage on the desktop#

Unchanged API, different backend: userData/<namespace>/<encoded key>.json (or .bin), written through a temporary file and a rename so a crash leaves the whole old value or the whole new one. The names are byte-identical to @ignifx/core's Node file backend, so the same save file reads back outside Electron.

Recipes#

Building and shipping#

Add --mac, --win, or --linux to electron-builder for a real installer, on a runner of that platform: cross-compilation is not available for most targets. Code signing, notarization, and auto-update are documented after 1.0.

Per-OS caveats. macOS arm64 is verified end to end. Windows is NSIS (Squirrel needs electron-winstaller, whose install script this repository does not allow) and is configuration only — written, never built. Linux is likewise configuration only; it needs enable-features=Vulkan, which applyWebGpuSwitches appends, and a display (xvfb-run) on CI.

File formats#

None of its own. It serves whatever @ignifx/vite-plugin built — the manifest and the content-hashed assets — over ignifx://, unchanged.

Gotchas#

Deprecated (current window)#

None (pre-1.0: no deprecation window; breaking changes are listed in the changelog).

Where to look next#

skills/ignifx/SKILL.md for the engine entry skill · docs/architecture/14-platform-electron.md for the design · docs/adr/0018-electron-tooling.md for what the S9.1 spike measured, and for what is still unverified.