sidecar

A sidecar is a native program your plugin ships inside the games an author builds. It exists because a plugin's runtime entry is renderer code — no native modules, no dynamic libraries, no raw sockets — and some integrations (a platform SDK, a hardware bridge) simply cannot live there. The sidecar runs as a child process of the game's main process and talks to your plugin over stdio.

This is the heaviest thing a plugin can declare: it is code that reaches the player's machine. It is deliberately explicit — per-platform binaries, mandatory digests, and an install permission the author sees by name.

Declare it

There is no capability string for sidecars: declaring one in contributes.sidecars is the request, and app.game.sidecar exists exactly when that list is non-empty.

{
  "entries": { "studio": "main.js", "runtime": "runtime.js" },
  "contributes": {
    "sidecars": [
      {
        "id": "yourname.plugin.bridge",
        "kind": "executable",
        "transport": "stdio-jsonl",
        "autostart": "onRequest",
        "startupTimeoutMs": 5000,
        "shutdownTimeoutMs": 3000,
        "restart": { "maxRetries": 2, "backoffMs": 1000 },
        "targets": {
          "windows-x64": {
            "entry": "bin/windows-x64/bridge.exe",
            "include": [
              "bin/windows-x64/bridge.exe",
              "dep:yourname.plugin.sdk/bin/windows-x64/sdk.dll"
            ],
            "sha256": {
              "bin/windows-x64/bridge.exe": "a1b2…64 hex chars"
            }
          }
        }
      }
    ]
  }
}

Declaring a sidecar without entries.runtime is a manifest error — it would ask the author to approve something nothing can use.

Platform keys

Keys are <platform>-<arch>, and only desktop is addressable:

windows-x64 · windows-arm64 · macos-x64 · macos-arm64 · macos-universal · linux-x64 · linux-arm64

(universal is accepted for macOS only.) A platform you declare nothing for simply has no sidecar there — a supported shape, not an omission. The build reports it as a warning so the author knows the feature is gone from that target before they ship it.

include and sha256

include lists everything shipped for that platform. Entries are either package-relative paths, or dep:<buildDependencyId>/<path> to pull an artifact produced by a declared build dependency — that is how a redistributable you may not mirror yourself reaches the pack. The entry must also appear in include.

sha256 is mandatory for every package-relative entry in include, as lowercase hex. It is verified at install and again at pack time, so a tampered package fails to install rather than silently shipping a different binary. dep: entries are covered by the build dependency's own digest instead.

Use it from the runtime entry

start is idempotent — repeated calls return the same running handle.

export default defineRuntimePlugin({
    async setup(app) {
        const sidecar = app.game.sidecar;
        if (!sidecar?.available("yourname.plugin.bridge")) {
            return; // web, mobile, or a desktop target that ships no binary
        }

        const bridge = await sidecar.start("yourname.plugin.bridge");
        const version = await bridge.request<string>("version");
        app.game.log("info", `bridge ${version}`);

        bridge.onEvent((method, params) => { /* pushed from the sidecar */ });
        bridge.onExit(({ code, signal }) => { /* it died; degrade */ });
    },
});

The handle

Correlation ids are the host's business — you call request("method", params) and get the result.

The wire protocol

You write the other end of this. The transport is newline-delimited JSON over stdio: one JSON object per line on stdout, UTF-8, \n-terminated (a trailing \r is tolerated, so CRLF works). stdout is the protocol; stderr is a plain log channel and is never parsed — write your diagnostics there. In a Production build only stderr lines that look like warnings or errors are kept; in Preview everything is logged.

A single line may be at most 1 MiB. Longer lines are dropped with a warning rather than tearing down the connection. Non-JSON lines, non-object frames, and unknown frame types on stdout are likewise logged and skipped.

Every frame carries a t discriminator.

Host → sidecar (on your stdin)

{"t":"hello","protocol":1,"pluginId":"yourname.plugin","sidecarId":"yourname.plugin.bridge","cwd":"…","mode":"production","game":{"name":"My Game","version":"1.0.0"}}
{"t":"req","id":1,"method":"achievements.unlock","params":{"id":"FIRST_END"}}
{"t":"req","method":"stats.flush"}
{"t":"bye"}

• hello is written immediately after spawn, synchronously. Read stdin from your first instruction — do not attach a reader later and expect it to still be there. mode is "preview" or "production".
• A req with id wants a reply. A req without id is a notification and wants none. params is omitted entirely when there is nothing to send.
• bye is the shutdown request, followed by stdin EOF.

Sidecar → host (on your stdout)

{"t":"ready","protocol":1,"caps":["achievements","stats"]}
{"t":"res","id":1,"result":{"ok":true}}
{"t":"res","id":2,"error":{"message":"Steam is not running","code":"NO_STEAM"}}
{"t":"evt","method":"overlay.shown","params":{"achievement":"FIRST_END"}}

• ready completes the handshake and must arrive within startupTimeoutMs. protocol must be 1 if you send it. caps is logged for diagnostics; the host gates nothing on it.
• res answers a req by id. A response with an error object rejects the plugin's promise; otherwise result resolves it. The plugin sees an Error whose message names the sidecar, the method, and your message, with code appended when present.
• evt is a push with no acknowledgement. There is no way for a sidecar to make a request of the host — only res and evt are recognized.

Lifecycle

Process environment

• cwd is a per-sidecar writable directory in the game's user data (sidecars/<pluginId>/<sidecarId>/), created for you. It is not the install directory, which is read-only in a real install. Put runtime files you need to write there.
• Environment variables are the game main process's own, unchanged except for ELECTRON_RUN_AS_NODE, which is set for kind: "node" and removed for kind: "executable". Nothing else is injected — all context arrives in hello.
• Shared libraries load from beside the executable (Windows) or via rpath (POSIX), not from cwd. Ship them next to entry.

Degrade, always

available() returning false is the normal case on most targets, not an error path:

Write the plugin so the feature it provides has a local answer without the sidecar, and treat the native path as an enhancement. A plugin that throws when available() is false is broken on the majority of targets an author can build.

Known boundaries

These are current, real limits — not hypotheticals.

• A plugin zip does not carry the executable bit. Neither the registry's packaging nor Studio's extraction records file modes, so on macOS and Linux a sidecar lands non-executable and could never spawn. The host repairs this immediately before spawning: on POSIX it checks the owner-execute bit and adds execute only where read is already granted, never widening visibility. If the chmod fails, the sidecar is marked unavailable rather than silently not working. You do not need to do anything, but do not be surprised by the mode on disk.
• Building several desktop targets at once ships no sidecars at all. The packaging pipeline currently serves every desktop target from one staged application directory, while sidecars are per <platform>-<arch>. When more than one desktop target is selected, the build emits a warning and packages none of them — putting a Windows executable inside a .app would be worse. Build one desktop target at a time when a sidecar matters.
• macOS signing. A nested executable must be signed together with the host application or Gatekeeper rejects it harder than an unsigned app. Until a signing pass lands, macOS builds carrying a sidecar are for your own use.
• Sidecars are not packed into the archive. Executables and dynamic libraries cannot run from inside an asar, so they ship unpacked beside it. Under a sealed (encrypted) build they stay unpacked too — a sidecar is an executable, and pretending it is protected would only mislead.
• Plugins are not isolated from each other in the renderer. Every runtime plugin is same-origin ESM in one renderer process, and the channel that reaches the sidecar host cannot cryptographically prove which plugin called it. The declaration boundary still holds — the host only ever spawns a sidecar some manifest declared — but do not treat a sidecar as a private channel between it and one plugin.
• A failed sidecar copy fails the whole Preview compile rather than degrading to "no sidecar this run". A missing dep: artifact or a digest mismatch will stop Preview from starting. In a production build that is the right behaviour; in Preview it is sharper than it should be.