Game URL handler

Openplanet hooks into the game's native URL handler. Normally, the game's URL handler is installed by most games on first startup (eg. Trackmania and Maniaplanet). Turbo does not register a handler.

The native game's URL handler is fairly limited in functionality, so Openplanet hooks into it to allow plugins to add additional functionality.

URL handlers start with either trackmania:// or maniaplanet://.

The Play plugin

Openplanet ships with the Play plugin, which lets players play arbitrary maps through the URL handler. This is useful when you want to place a "Play map" button on a website, for example. Some possible URLs you can use:

• trackmania://openplanet/play/PRXOh_5msNrp2Kxz1lv7DPsLL4k
• trackmania://openplanet/play/56e30750-83af-449f-922e-7b1db9ffe728
• trackmania://openplanet/play/316306
• trackmania://openplanet/play/316536?secret=Jf2G0D2pjk2WwnypZCIySg
• trackmania://openplanet/play/nadeo/PRXOh_5msNrp2Kxz1lv7DPsLL4k
• trackmania://openplanet/play/nadeo/56e30750-83af-449f-922e-7b1db9ffe728
• trackmania://openplanet/play/mx/316306
• trackmania://openplanet/play/mx/316536?secret=Jf2G0D2pjk2WwnypZCIySg
• trackmania://openplanet/play/room/9/345809

The Play plugin is also a fully featured example of the URL protocol handler, and is excellently documented. It's a great example if you aim to create a plugin with a URL handler.

The fast handler

On Trackmania, you may notice that the URL handler is quite slow. This is because the handler has to be routed through Ubisoft Connect first, which then has to launch another instance of the game, and then talk to the existing open game window. Openplanet can fix this by enabling the fast URL handler in the settings. The fast URL handler is typically instant, and can be safely enabled in most cases as it is fully compatible with the game's built-in URL handlers as well.

Linux support

Linux support is currently not easy to do, and as such is not officially supported for the time being. Some workarounds exist though, and have been posted on the Discord. These may eventually become natively supported by Openplanet.

Implementing a custom handler

The OnProtocolUrl callback can be used to receive URL callbacks in your plugin code. Here's an example:

void OnProtocolUrl(const string &in path)
{
  print("Received a URL handler path: \"" + path + "\"");
}

If your plugin identifier (the folder name or .op name) is MyPlugin, then the following URL will route to your plugin, with the respective path value:

• trackmania://openplanet/myplugin path = empty string
• trackmania://openplanet/myplugin/ path = empty string
• trackmania://openplanet/myplugin/foo path = foo
• trackmania://openplanet/myplugin/foo/ path = foo/
• trackmania://openplanet/myplugin/foo/bar path = foo/bar
• trackmania://openplanet/myplugin/foo/bar?a=b&c=d path = foo/bar/?a=b&c=d (Query URLs can be parsed using Net::ParseUrlEncodedForm)

It's highly recommended to use the fast URL handler during development of plugins with custom URL handlers because it will save you a lot of time.