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

• OverlayWindowOptions.
• OverlayBrowserWindow.

---

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): null | OverlayBrowserWindow;

Returns the overlay window associated with a given BrowserWindow.

Parameters

Parameter	Type	Description
browserWindow	BrowserWindow	The Electron BrowserWindow to query.

Returns

null | OverlayBrowserWindow

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

See

OverlayBrowserWindow.

---

fromWebContents()

fromWebContents(webContents: WebContents): null | OverlayBrowserWindow;

Returns the overlay window associated with a given WebContents instance.

Parameters

Parameter	Type	Description
webContents	WebContents	The Electron WebContents to query.

Returns

null | OverlayBrowserWindow

The corresponding overlay window or null if not found.

See

OverlayBrowserWindow.

---

getActiveGameInfo()

getActiveGameInfo(): undefined | ActiveGameInfo;

Retrieves information about the currently active game, if available.

Returns

undefined | ActiveGameInfo

See

ActiveGameInfo.

---

getAllWindows()

getAllWindows(): OverlayBrowserWindow[];

Get all open overlay windows.

Returns

OverlayBrowserWindow[]

An array of OverlayBrowserWindow instances.

See

OverlayBrowserWindow.

---

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

• GameWindowInfo.
• GameInfo.
• GameWindowUpdateReason.

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.

---

registerGames()

registerGames(filter: GamesFilter): any;

Register games to track for overlay injection.

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>

---

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);
      }
    },
  );
});