IOverwolfOverlayApi

Electron APIs / overlay / IOverwolfOverlayApi

APIs for managing Overwolf overlay windows, hotkeys, input modes, and game integration.

Enables apps to:

Register and track game activity.
Inject overlays into supported games.
Manage hotkeys.
Control input interception behavior.

Extends the EventEmitter interface to allow for subscription to overlay-related events such as game launch, focus changes, and input mode transitions.

Example

private _overlayApi: IOverwolfOverlayApi;

this._overlayApi.on('game-launched', (event, gameInfo) => {
  if (gameInfo.supported === true) {
    event.inject();
  }
});

Extends

EventEmitter

Properties

Property	Modifier	Type	Description
`hotkeys`	`public`	`IOverlayHotkeys`	The hotkeys API used to register, update, and remove overlay hotkeys. See IOverlayHotkeys.
`version`	`readonly`	`string`	The current version of the overlay package. Since 1.7.0

Methods

createWindow()

createWindow(options: OverlayWindowOptions): Promise<OverlayBrowserWindow>;

Create new Overlay window.

Parameters

Parameter	Type	Description
`options`	`OverlayWindowOptions`	Window configuration including name, z-order, passthrough, etc.

Returns

Promise<OverlayBrowserWindow>

A promise that resolves to the created OverlayBrowserWindow.

See

enterExclusiveMode()

enterExclusiveMode(options?: ExclusiveInputOptions): void;

Enters Overlay "Exclusive Mode" to intercept user input in games where the mouse cursor is not visible.

The game-input-exclusive-mode-changed event fires if exclusive mode was entered.

NOTE: This is only supported when getActiveGameInfo().gameInputInfo.canInterceptInput is false. Calling this function when unsupported will be ignored and will not throw an exception.

Parameters

Parameter	Type
`options?`	`ExclusiveInputOptions`

Returns

void

exitExclusiveMode()

exitExclusiveMode(): void;

Exits Overlay "Exclusive Mode", allowing user input to be sent to the game.

This is only effective if getActiveGameInfo().gameInputInfo.canInterceptInput is true.

Returns

void

fromBrowserWindow()

fromBrowserWindow(browserWindow: BrowserWindow): OverlayBrowserWindow | null;

Returns the overlay window associated with a given BrowserWindow.

Parameters

Parameter	Type	Description
`browserWindow`	`BrowserWindow`	The Electron `BrowserWindow` to query.

Returns

OverlayBrowserWindow | null

The corresponding overlay window or null if not owned by the overlay system.

See

OverlayBrowserWindow.

fromWebContents()

fromWebContents(webContents: WebContents): OverlayBrowserWindow | null;

Returns the overlay window associated with a given WebContents instance.

Parameters

Parameter	Type	Description
`webContents`	`WebContents`	The Electron WebContents to query.

Returns

OverlayBrowserWindow | null

The corresponding overlay window or null if not found.

See

OverlayBrowserWindow.

getActiveGameInfo()

getActiveGameInfo(): ActiveGameInfo | undefined;

Retrieves information about the currently active game, if available.

Returns

ActiveGameInfo | undefined

See

ActiveGameInfo.

getAllWindows()

getAllWindows(): OverlayBrowserWindow[];

Get all open overlay windows.

Returns

OverlayBrowserWindow[]

An array of OverlayBrowserWindow instances.

See

OverlayBrowserWindow.

getGpuPreference()

getGpuPreference(): Promise<GpuPreference>;

Returns the GPU preference currently recorded for this application's executable.

Resolves to 'default' when no entry exists — "no entry" and "let Windows decide" are the same state, so this never resolves undefined.

Returns

Promise<GpuPreference>

A promise resolving to the recorded preference.

Throws

On a non-Windows platform.

See

IOverwolfOverlayApi.setGpuPreference.
GpuPreference.

Since

2.0.5

installHighElevationHelper()?

optional installHighElevationHelper(): Promise<void>;

Install ow-electron helpers to %CommonProgramFiles%\<app-name> with UAC elevation. Allows injection into high elevation games. No-ops if files are already present.

Returns

Promise<void>

Resolves when installation completes.

Throws

HelperInstallError

exitCode 1223 — user cancelled the UAC prompt (ERROR_CANCELLED)
err.exitCode !== 1223 — the installer process failed. Log err.exitCode and investigate.
any other non-zero exitCode — installation failed.

Remarks

The helper binaries are installed to:

%CommonProgramFiles%\<app-name>\owe-helper-ui.exe (x64)
%CommonProgramFiles%\<app-name>\owe-helper-ui-x86.exe (x86)

Examples

// Check whether the helper is already installed
const installed: boolean = await api.isHighElevationHelperInstalled();

// Trigger UAC-elevated installation (shows a UAC prompt to the user)
try {
  await api.installHighElevationHelper();
  console.log("Helper installed successfully");
} catch (err: any) {
  if (err.exitCode === 1223) {
    // User cancelled the UAC prompt — not an error, just inform the user
    console.warn("User cancelled UAC prompt");
  } else {
    console.error("Installation failed, exitCode:", err.exitCode);
  }
}

async function ensureElevatedInjection(api: IOverwolfOverlayApi) {
  const installed = await api.isHighElevationHelperInstalled();
  if (!installed) {
    await api.installHighElevationHelper(); // may throw — handle UAC cancel
  }
  // Injection into elevated games now happens automatically on game launch
}

isHighElevationHelperInstalled()?

optional isHighElevationHelperInstalled(): Promise<boolean>;

Returns true if ow-electron helpers is already installed in %CommonProgramFiles%\<app-name>.

Returns

Promise<boolean>

true if the helper is installed and ready.

Example

const installed: boolean = await api.isHighElevationHelperInstalled();
if (!installed) {
  // Prompt the user to run the one-time setup before injecting into elevated games
}

on("error")

on(eventName: "error", listener: (...args: any[]) => void): this;

Fires when an internal error occurs within the overlay system.

Parameters

Parameter	Type
`eventName`	`"error"`
`listener`	(...`args`: `any`[]) => `void`

Returns

this

on("game-launched")

on(eventName: "game-launched", listener: (event: GameLaunchEvent, gameInfo: GameInfo) => void): this;

Fires when a registered game is launched. Call event.inject() to enable the overlay for the game.

Parameters

Parameter	Type	Description
`eventName`	`"game-launched"`	The event identifier for when a game is launched.
`listener`	(`event`: `GameLaunchEvent`, `gameInfo`: `GameInfo`) => `void`	Callback with game launch event and game metadata.

Returns

this

See

GameInfo.

on("game-exit")

on(eventName: "game-exit", listener: (gameInfo: GameInfo, wasInjected: boolean) => void): this;

Fires when a registered game process terminates.

Useful for performing cleanup, UI updates, or closing overlay windows.

Parameters

Parameter	Type	Description
`eventName`	`"game-exit"`	The event identifier for when the game exits.
`listener`	(`gameInfo`: `GameInfo`, `wasInjected`: `boolean`) => `void`	A callback function that receives the game info of the exited game.

Returns

this

Example

overlay.on("game-exit", (gameInfo, wasInjected) => {
  console.log(
    `Game exited: ${gameInfo.title} and ${wasInjected ? "was injected" : "was not injected"}`,
  );
  closeOverlayWindows();
});

See

GameInfo.

on("game-injected")

on(eventName: "game-injected", listener: (gameInfo: GameInfo) => void): this;

Fires when the overlay is ready and successfully injected into the game.

Parameters

Parameter	Type	Description
`eventName`	`"game-injected"`	`game-injected`
`listener`	(`gameInfo`: `GameInfo`) => `void`	Callback with game info.

Returns

this

See

GameInfo.

on("game-injection-error")

on(eventName: "game-injection-error", listener: (gameInfo: GameInfo, error: string, ...args: any[]) => void): this;

Fires when overlay injection into the game fails.

Parameters

Parameter	Type	Description
`eventName`	`"game-injection-error"`	`game-injection-error`
`listener`	(`gameInfo`: `GameInfo`, `error`: `string`, ...`args`: `any`[]) => `void`	Callback with game info, error message, and optional additional args.

Returns

this

See

GameInfo.

on("game-focus-changed")

on(eventName: "game-focus-changed", listener: (window: GameWindowInfo, gameInfo: GameInfo, focus: boolean) => void): this;

Fires when the game window focus state changes.

Parameters

Parameter	Type	Description
`eventName`	`"game-focus-changed"`	`game-focus-changed`
`listener`	(`window`: `GameWindowInfo`, `gameInfo`: `GameInfo`, `focus`: `boolean`) => `void`	Callback with window info, game info, and focus state.

Returns

this

See

GameWindowInfo.
GameInfo.

on("game-window-changed")

on(eventName: "game-window-changed", listener: (window: GameWindowInfo, gameInfo: GameInfo, reason?: GameWindowUpdateReason) => void): this;

Fires when the game window is resized or changes position.

Parameters

Parameter	Type	Description
`eventName`	`"game-window-changed"`	`game-window-changed`
`listener`	(`window`: `GameWindowInfo`, `gameInfo`: `GameInfo`, `reason?`: `GameWindowUpdateReason`) => `void`	Callback with window info, game info, and optional reason.

Returns

this

See

on("game-input-interception-changed")

on(eventName: "game-input-interception-changed", listener: (info: GameInputInterception) => void): this;

Fires when the game input interception capability changes.

Parameters

Parameter	Type	Description
`eventName`	`"game-input-interception-changed"`	`game-input-interception-changed`
`listener`	(`info`: `GameInputInterception`) => `void`	Callback with updated input state.

Returns

this

See

GameInputInterception.

on("game-input-exclusive-mode-changed")

on(eventName: "game-input-exclusive-mode-changed", listener: (info: GameInputInterception) => void): this;

Fires when exclusive input mode state changes.

Parameters

Parameter	Type	Description
`eventName`	`"game-input-exclusive-mode-changed"`	`game-input-exclusive-mode-changed`
`listener`	(`info`: `GameInputInterception`) => `void`	Callback with input mode details.

Returns

this

See

GameInputInterception.

on("shared-texture-unavailable")

on(eventName: "shared-texture-unavailable", listener: (reason: SharedTextureUnavailableReason) => void): this;

Fires when the shared-texture rendering path cannot be used with the current game, with the reason:

unsupportedGraphicsApi—the game's graphics API cannot composite GPU textures (D3D9 / OpenGL / Vulkan). Nothing to fix.
gpuAdapterMismatch—the game renders on a different GPU adapter than Chromium; a shared texture handle can only be opened on the adapter that created it. Fixable with IOverwolfOverlayApi.setGpuPreference and a restart; both adapters are named in the overlay log.
copyFailure—the game repeatedly failed to open the shared texture handles it received in-game. The overlay retried, then abandoned the path for this game. IOverwolfOverlayApi.setGpuPreference may help when the root cause is adapter-related; details are in the overlay log.
handleTransportBlocked—the GPU textures could not be handed to the game process at all. Nothing the application can do.

Fires at most once per injected game. The first two reasons are detected when the game's graphics are detected, before any frame is sent; copyFailure and handleTransportBlocked are reached only after frames were sent and repeatedly failed to arrive or draw. Either way, the affected overlay windows have already been switched to the CPU copy path by the time the event fires, so they stay visible and interactive, and GameWindowInfo.isSharedTextureAvailable reports false for the game.

Parameters

Parameter	Type	Description
`eventName`	`"shared-texture-unavailable"`	`shared-texture-unavailable`
`listener`	(`reason`: `SharedTextureUnavailableReason`) => `void`	Callback invoked once for the current game with the reason.

Returns

this

See

Overlay examples

Example

overlay.on("shared-texture-unavailable", async (reason) => {
  if (reason !== "gpuAdapterMismatch") return;
  if ((await overlay.getGpuPreference()) === "highPerformance") return;
  await overlay.setGpuPreference("highPerformance");
  promptUserToRestart();
});

Since

2.0.5

registerGames()

registerGames(filter: GamesFilter): any;

Parameters

Parameter	Type	Description
`filter`	`GamesFilter`	Configuration specifying which games to register and whether to include unsupported titles.

Returns

any

See

GamesFilter.

requestGameInjection()

requestGameInjection(classId: number): Promise<void>;

Requests game injection for the specified class ID (late injection).

If the game is running, the 'game-launched' event will be emitted, and you can call event.inject() to inject the overlay. If another game is already injected, the overlay will move to the newly injected game.

Throws an error if the game is not running.

Parameters

Parameter	Type	Description
`classId`	`number`	The class ID of the game to inject the overlay into.

Returns

Promise<void>

setGpuPreference()

setGpuPreference(preference: GpuPreference): Promise<void>;

Records a Windows per-executable GPU preference for this application, so Chromium's GPU process runs on the same adapter as games do.

The shared-texture path requires that: a shared GPU texture handle can only be opened on the adapter that created it, and Chromium takes the adapter driving the primary display while games run on the discrete GPU. When those differ the overlay falls back to the CPU copy path and emits shared-texture-unavailable.

An application restart is normally required. DXGI reads this preference when a process creates its D3D device, which Chromium's GPU process has already done by the time this API is reachable. Call IOverwolfOverlayApi.getGpuPreference to learn whether the application is already aligned and therefore needs no restart; this method is idempotent, so calling it unconditionally is safe.

Side effects — read before calling. It moves the entire application's rendering to that GPU, draining laptop battery and keeping the discrete GPU awake; it is persistent, user-visible Windows state under Settings → System → Display → Graphics; and it is keyed on the executable path, so moving or renaming the application leaves a stale entry behind. It is therefore never applied implicitly. Pass 'default' to remove the entry, the recommended revert on uninstall or when the user turns the overlay off.

Parameters

Parameter	Type	Description
`preference`	`GpuPreference`	`'highPerformance'` to pin this application to the high-performance adapter, or `'default'` to remove the entry and let Windows decide.

Returns

Promise<void>

A promise that resolves once the preference has been recorded.

Throws

If the registry cannot be written, or on a non-Windows platform.

See

Example

overlay.on("shared-texture-unavailable", async (reason) => {
  if (reason !== "gpuAdapterMismatch") return;
  if ((await overlay.getGpuPreference()) === "highPerformance") return;
  await overlay.setGpuPreference("highPerformance");
  promptUserToRestart(); // takes effect on the next launch
});

Since

2.0.5

takeScreenshot()

takeScreenshot(filePath: string, format?: "jpg" | "bmp"): Promise<void>;

Captures the current game frame and saves it to disk.

Only one screenshot can be in progress at a time. Calling this method while a previous capture is still pending will reject immediately — wait for the returned promise to settle before issuing the next call.

The output format is resolved by precedence: an explicit format argument wins; otherwise the extension already present in filePath (.jpg/.jpeg or .bmp) is used; otherwise it defaults to 'bmp'. The file extension is then normalized to match the resolved format, so an existing extension is rewritten rather than doubled (e.g. shot.jpg stays shot.jpg, and shot.png with format: 'jpg' becomes shot.jpg).

Internally all backends (D3D9, D3D11, D3D12, Vulkan) capture as BMP first and transcode to JPEG on demand, ensuring correct colors across all graphics APIs and formats.

Parameters

Parameter	Type	Description
`filePath`	`string`	Absolute path (UTF-8) where the image will be saved.
`format?`	`"jpg"` \| `"bmp"`	Output image format: `'jpg'` or `'bmp'`. When omitted, the extension in `filePath` is used, falling back to `'bmp'`.

Returns

Promise<void>

A promise that resolves with the absolute path the file was actually written to, including the normalized extension (which may differ from filePath).

Throws

'no active game' — the overlay is not currently injected into any game. Wait for the game-injected event before calling.

Throws

'screenshot already in progress' — a previous capture has not yet completed. Await the previous promise before calling again.

Throws

'no active graphics device' — the game has no active GPU device at this moment (e.g. the game window is minimized or in a device-lost state). Try again once the game is in the foreground.

Throws

'capture failed: <backend>' — the GPU-side readback failed (e.g. staging texture creation, memory map, or WIC encode error).

Example

overlay.on("game-injected", () => {
  overlay.hotkeys.register(
    { name: "screenshot", keyCode: "F9", passthrough: false },
    async (hotkey, state) => {
      if (state !== "pressed") return;
      const ts = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
      const filePath = path.join(app.getPath("pictures"), `screenshot_${ts}`);
      try {
        const savedPath = await overlay.takeScreenshot(filePath, "jpg");
        console.log("screenshot written to", savedPath); // ...filePath.jpg
      } catch (err) {
        console.error("Screenshot failed:", err.message);
      }
    },
  );
});

Example​

Extends​

Properties​

Methods​

createWindow()​

Parameters​

Returns​

See​

enterExclusiveMode()​

Parameters​

Returns​

exitExclusiveMode()​

Returns​

fromBrowserWindow()​

Parameters​

Returns​

See​

fromWebContents()​

Parameters​

Returns​

See​

getActiveGameInfo()​

Returns​

See​

getAllWindows()​

Returns​

See​

getGpuPreference()​

Returns​

Throws​

See​

Since​

installHighElevationHelper()?​

Returns​

Throws​

Remarks​

Examples​

isHighElevationHelperInstalled()?​

Returns​

Example​

on("error")​

Parameters​

Returns​

on("game-launched")​

Parameters​

Returns​

See​

on("game-exit")​

Parameters​

Returns​

Example​

See​

on("game-injected")​

Parameters​

Returns​

See​

on("game-injection-error")​

Parameters​

Returns​

See​

on("game-focus-changed")​

Parameters​

Returns​

See​

on("game-window-changed")​

Parameters​

Returns​

See​

on("game-input-interception-changed")​

Parameters​

Returns​

See​

on("game-input-exclusive-mode-changed")​

Parameters​

Returns​

See​

on("shared-texture-unavailable")​

Parameters​

Returns​

See​

Example

Extends

Properties

Methods

createWindow()

Parameters

Returns

See

enterExclusiveMode()

Parameters

Returns

exitExclusiveMode()

Returns

fromBrowserWindow()

Parameters

Returns

See

fromWebContents()

Parameters

Returns

See

getActiveGameInfo()

Returns

See

getAllWindows()

Returns

See

getGpuPreference()

Returns

Throws

See

Since

installHighElevationHelper()?

Returns

Throws

Remarks

Examples

isHighElevationHelperInstalled()?

Returns

Example

on("error")

Parameters

Returns

on("game-launched")

Parameters

Returns

See

on("game-exit")

Parameters

Returns

Example

See

on("game-injected")

Parameters

Returns

See

on("game-injection-error")

Parameters

Returns

See

on("game-focus-changed")

Parameters

Returns

See

on("game-window-changed")

Parameters

Returns

See

on("game-input-interception-changed")

Parameters

Returns

See

on("game-input-exclusive-mode-changed")

Parameters

Returns

See

on("shared-texture-unavailable")

Parameters

Returns

See