Overwolf app development: how to start
What is Overwolf
Overwolf is a great platform for developing apps to inject into games. It allows you to easily create applications that enrich the gaming experience, such as overlays, auto capture of replays, highlights, statistics, integration with external systems (including home automation).
Its operation, from the outside, is quite simple: our HTML apps are injected through the CEF (Chromium Embedded Framework) and communicate with the games through the GEP (Game Events Provider).
Each game implements its Overwolf events via GEP, some defined by the game developers themselves, some served by Overwolf through various methodologies.
An Overwolf app can be developed with HTML, JS and CSS and can be enriched with C# Plugins.
The usable frameworks are various: React, Angular, Vue, plain JS.
In this tutorial we will explore how to create an app with React, in particular based on this great template: https://github.com/AlbericoD/overwolf-modern-react-boilerplate
Follow the guidelines provided on Github repo to start and configure the initial app environment.
Hey, cowboy, wait!
To start developing your app, you need before to get whitelisted from Overwolf: it means your Overwolf user is recognized as developer and you’ll can load unpacked apps (apps not yet published on the store) from Developer Tools.
Hint: Developer Tools are disable by default. To enable them, follow this: https://overwolf.github.io/docs/topics/enable-dev-tools
To get whitelisted you have to send an email to developers at overwolf.comexplaining what you’ve in mind, attaching a sample app or some mocked wireframes.
Once you get whitelisted, you can start working on your app loaded into Overwolf and receive realtime events.
The anatomy of an Overwolf app
Our app can contain different “windows”, HTML pages (or React components) called by Overwolf and injected in separate windows.
Each window must be declared inside the manifest.json(docs: https://overwolf.github.io/docs/api/manifest-json).
One window can be:
- Desktop only — https://overwolf.github.io/docs/api/manifest-json#windows-desktop_only
- In-Game only — https://overwolf.github.io/docs/api/manifest-json#windows-in_game_only
Hint: don’t define windows without a dedicated desktop\game only configuration, could behave strangely (like ALT+TABBING the game when opening them)
The manifest.json
Inside this file most of the behaviors and configurations of the application are described.
For example:
- Define which games you target
- Define which events you want to receive and for which games
- Windows and their configurations
- Uploaded plugins
- Developer configurations
- Hotkeys
Detailed documentation is here:
https://overwolf.github.io/docs/api/manifest-json
The background window
All apps should have at least one background window, which is essential to control other windows and share data among them.
A background window is a transparent window, without interface, which is explicitly declared as is_background_pagein manifest.json. Overwolf will always open that window, as the first window (a kind of start window).
“background”: { “file”: “Files/index.html”, “background_optimization”: false, “is_background_page”: true },
Reference to React template: src/features/background-window/BackgroundWindow.tsx
The background window usually listen to events coming from Overwolf (API docs: https://overwolf.github.io/docs/api/overwolf-games-events):
- overwolf.games.onGameInfoUpdated
- overwolf.games.onGameLaunched
- overwolf.games.events.onInfoUpdates2
- overwolf.games.events.onNewEvents
How to use game events: https://overwolf.github.io/docs/topics/using-events
From the background window you can then:
- Show the Desktop window as if it were a startup window to show when the game is closed
- If you are in the game, open the overlays or start the application logic needed to make the application work
Communication between windows
The windows of your app can communicate with each other. How? There are several techniques, it also depends on which framework you are using.
In React there is Redux (and its store\actions\reducers), a famous package that allows state management within a React app.
If you use Redux, the store is served by the background window and from there it is “loaded” when the window is opened. It’s a slightly different approach compared to a classic React app: in that context you are used to have one store per “page” shared among React components. In Overwolf, the store is shared between multiple windows.
Otherwise, a simpler and highly functional approach, also suggested by Overwolf itself, is the use of the Event Bus (this could be applied to all JS frameworks and plain JS too):
From background window controller:
window.eventBus = EventBus;Trigger an event with data:
window.eventBus.trigger(Events.FIRST_STEAMID_UPDATE, {});And then listening to the event:
let background = overwolf.windows.getMainWindow();
this.eventBus = background.eventBus;addListenerToEventBus(eventName, callback) {
this.eventBus.addListener(eventName, callback);
}this.addListenerToEventBus(Events.GAME_SESSION_STATS_UPDATE, this.updateGameStats.bind(this));
Hint: be aware of the
.bind(this)because without binding it, in the callback thethiswill bedocumentand not the current class.
Basically, the Event Bus is exposed from the background window, it is simple to assign it as a property to the window object and from each window opened afterwards you can listen to the events relaunched by the Event Bus and consequently you can launch events from the same windows.
App state, user settings, remote data
Your app runs in a browser, basically: so to save data, be it configurations, user settings, persistent data to be used at various times, you can use the techniques used by a web app:
- the localstorage
- the IndexedDb
- Your remote API
Using localstorage and IndexedDB is quite simple: they are local stores linked to the app, shared between all windows and persistent when you close the app.
In particular, they are cleaned when the app is unplugged.
As far as remote APIs are concerned, there are several ways to implement them and it all depends on your application, your backend systems, and the database where you store the data.
Probably the easiest thing to do at first is to build a NodeJS + Express + Mongo app and publish it on Heroku while waiting to scale further. Have a look at the dedicated documentation on Google, there is a lot of it.
To call your API, using NPM packages, there are many alternatives: node-fetch or axios for example.
Debugging
A developer knows that his most valuable weapon is the debugger.
To debug an Overwolf app during development, use the Developer Tools built into the CEF (the same as a Chrome Browser) or the logs written via console.log
To open the Developer Tools on current page, use the hotkey CTRL+SHIFT+I or, from the Packages window, click on the window name.
Logs are saved on your disk, a file for each window, or shown in Console from the Developer Tools.
Hint: log path is %localappdata%\Overwolf\Log\Apps\<YOUR APP>\
Hot reload
When you are in the middle of the development, hot reload is definitely a great ally.
You can define which files to control so that the app is reloaded with each change by pointing to their extension (.js, .jsx, ,.css etc etc).
Look here: https://overwolf.github.io/docs/api/manifest-json#developer-game-settings
Hint: with webpack build this could be tricky: the app could restart more than one time because webpack deletes all and rebuild the app completeley.
C# Plugins
In some cases you will need functionality and operations that can not be performed by javascript: operations on the operating system, changes to the registry, special operations on the physical files of the user’s computer, process management etc etc..
Overwolf gives you the possibility to load C# plugin — strictly in .NET 4.5 — and use the functions exposed in JS.
For detailed information, read here: https://overwolf.github.io/docs/topics/how-to-use-plugins-in-your-app
Basically, you have to build a .NET Class Library (.dll) with Visual Studio (2017 is enough, better 2019, Community Edition is perfect).
The Class Library will be divided into namespaces and classes, as the .NET “theory” wants, each class can be loaded by Overwolf as a separate Plugin.
The example above contains:
- A C# class called “MyPlugin” inside the namespace overwolf.plugins
- The statement of manifest.json
- The JS code to load the plugin and use the defined method
As you can see above, the “myPluginFunction” method provides some parameters (which are all mandatory, there can be no optional parameters) and a callback defined by an Action.
Overwolf will wait for the callback response.
If you do not expect a result, the method can be a void without callback, but it is always better to have it for logging and debugging purposes.
You can also listen on incoming events from the plugin. More information here: https://overwolf.github.io/docs/topics/writing-your-own-plugin
Wrap up!
This tutorial is definitely not exhaustive and you may encounter other problems during the development of your app but it can be a good starting point to help you set it up and have some reference points to the Overwolf documentation (which is very extensive and very detailed).
For a more interactive help you can connect to the official Developers Discord https://discord.gg/overwolf-developers
Have fun!
