Skip to main content

Overwolf Development Kit

Overview​

The ODK is the Overwolf Development Kit for TypeScript. It is designed to simplify and enhance Overwolf app development by providing a modern, type-safe API.

Key features​

  • Easy creation and management of Desktop and OSR windows.
  • Create windows dynamically at runtime without pre-defining them in the manifest file.
  • Type-safe window options and positioning.
  • Utility methods for working with window IDs and the current window.
  • Monitor helper utilities for multi-monitor setups.
  • All window actions are asynchronous and return Promises for easy integration with async/await workflows.

Current status​

  • Window Management—the current version focuses on dynamic window management, including creation, control, and positioning of both desktop and OSR (Off-Screen Rendering) windows, as well as utilities for working with monitors and window states.
  • Future Plans—the ODK will expand to wrap more of the Overwolf API, providing a unified, type-safe toolkit for Overwolf app developers.

Installing the ODK​

This module requires Node 22.0.0 or later.

npm install @overwolf/odk-ts

How to build the package​

Production build​

Run:

npm run buildpackage
  • Outputs to the dist folder.
  • Creates an npm package archive: package.tgz.

Development build (with Source Maps)​

Run:

npm run builddevpackage

This is the same as the production build, but includes source map files for easier debugging.

Updating the ODK locally in another project​

  1. Copy the generated package.tgz from the dist folder to your target project's <3rd_party>/overwolf directory.

  2. In your target project, run:

    npm i file:<3rd_party>/overwolf/package.tgz

This will install the local odk-ts package for development or testing purposes.

Creating and using windows​

The ODK-TS provides you with an easy way to create, use, and manage windows in your app. For more detailed documentation, see ODK-TS Classes.

Creating windows​

You can create new windows using the provided classes. With the ODK, you do not need to define windows in your manifest file, windows can be created dynamically at runtime.

Create a desktop window​

import { DesktopWindow } from '@overwolf/odk-ts';

const win = new DesktopWindow({
  id: 'my_window',
  url: 'index.html',
  // ...other options
});

Create an OSR window​

import { OSRWindow } from '@overwolf/odk-ts';

const osrWin = new OSRWindow({
  id: 'osr_window',
  url: 'osr.html',
  // ...other options
});

Accessing windows​

Use the Windows utility to access existing windows:

Windows.self—get a wrapper for the current window.

import { Windows } from '@overwolf/odk-ts';

const currentWin = Windows.self();

Windows.fromId(id: string)—get a window instance by its Overwolf window ID.

import { Windows } from '@overwolf/odk-ts';

const win = Windows.fromId('my_window_id');

Window positioning options​

When creating or moving windows, you can use a variety of positioning options:

  • x, y—absolute coordinates for the window's top-left corner.
  • width, height—window size in pixels.
  • dockPosition—dock the window to a specific edge of the screen (see Edge enum).
  • minWidth, minHeight, maxWidth, maxHeight—set minimum and maximum window dimensions.
  • topMost—whether the window should stay on top of other Overwolf windows.
  • resizable—whether the window can be resized.
  • autoDpi, autoZoom—DPI and zoom handling.
  • keepWindowLocation—prevent window from moving when game focus changes.

See the Options interface in @overwolf/odk-ts/window/options/window_options for all available options and their descriptions.

All window actions are asynchronous and return Promises, making them easy to use with async/await.

You can easily control window position and state using methods on your window instance (from the WindowBase class):

  • window.center()—center the window on its monitor.
  • window.centerOnMonitor(monitor)—center on a specific monitor.
  • window.setPosition({x, y})—move to coordinates.
  • window.setSize({width, height})—resize the window.
  • window.setBounds({x, y, width, height})—set position and size.
  • window.dock(edge, {marginX, marginY}, monitor)—Docks to an edge (one-time). This positions the window at the specified edge, but if the window is moved or resized afterwards, it will not remain docked. Use this for a single placement action.
  • window.anchor(edge, {marginX, marginY})—Anchor to an edge (persistent). This attaches the window to the specified edge with the given margin, and the window will remain anchored even after move or resize events. The anchoring is automatically reapplied to keep the window at the edge.
  • window.move()—start dragging the window.
  • window.bringToFront(), window.minimize(), window.maximize(), window.restore(), window.show(), window.hide(), window.close() —control the window state.

The difference between Dock and Anchor:

  • Dock is a one-time operation. The window is placed at the edge, but will not stay docked if the user moves or resizes it.
  • Anchor is persistent. The window will remain attached to the edge and the anchoring will be reapplied automatically after move/resize events.

See the window_base.ts file for the full list of available methods.

Monitor Helper​

The MonitorHelper class provides a utility for getting the monitor associated with a window:

MonitorHelper.getWindowMonitor(window)—returns the monitor for a given window instance.

Example:

import { MonitorHelper } from '@overwolf/odk-ts';

const monitor = await MonitorHelper.getWindowMonitor(win);

Contributing​

Overwolf welcomes community contributions and extensions! If you’d like to improve, extend, or fix something in this project, follow the process below.

How to contribute​

  1. Fork the repository—create your own fork of the project on GitHub.
  2. Create a feature branch—work on your changes in a dedicated branch. Use git checkout -b my-feature.
  3. Make your changes:
    • Keep changes focused and scoped.
    • Follow the existing code style and conventions.
    • Add or update documentation where appropriate.
    • Include tests if applicable.
  4. Commit your work—use clear, descriptive commit messages. (e.g., git commit -m "Add support for XYZ")
  5. Push and open a Pull Request—push your branch to your fork and open a Pull Request (PR) against the main repository.

Pull Request guidelines​

To help us review PRs efficiently:

  • Describe what the change does and why it’s needed.
  • Link any related issues (if applicable).
  • Keep PRs focused (one feature or fix per PR when possible).
  • Be open to feedback and requested changes.

Extending the project​

If you’re planning a larger extension or architectural change, contact us and explain the intended use case and impact it will have. Overwolf recommends that you get early feedback before investing significant effort.

Code of conduct​

Please be respectful and constructive in discussions and reviews. Overwolf's aim is to keep this project welcoming and collaborative.