author nemo
Thu, 27 Jan 2022 17:26:11 -0500
changeset 2219 12e5f8732e54
parent 2218 eb6eef27205c
permissions -rw-r--r--
latest on 1.0.0 branch is better

#summary The Hedgewars URL scheme handler

= Hedgewars server links =
== Overview ==
Hedgewars supports special links for Hedgewars servers. You can join a server by using a simple link. These links always start with “`hwplay://`” and look like this:


If your system is set-up to handle `hwplay` URLs, it will start Hedgewars and puts you immediately in the server.

The following link goes to the official Hedgewars server, you can try it out right now:


== Usage ==
Your browser and other software needs to learn first how to deal with `hwplay`.
We recommend to first click on “Assign file types” in the Settings menu, Advanced tab, this should set things up automatically for you.

If an application (like a browser) is confused about `hwplay`, point it to the Hedgewars program (`hedgewars.exe` on Windows, `hedgewars` on GNU/Linux and macOS).

Hedgewars itself also can use a `hwplay` URL as a command-line argument. See [CommandLineOptions#Frontend] for more information.

`hwplay` URLs are of course optional, you can join any server from the main menu by selecting the network game, then “local network”, then by selecting a server from the list or entering its address directly after clicking on the “Connect to” button.

== Creating `hwplay` URLs ==
When you are about to start a server in Hedgewars (Main menu → Network game → Local network → Start server), Hedgewars will create a `hwplay` URL for you. You can copy it into the clipboard if you click on the “invite” button.

Note the generated URL might only work in your LAN and not world wide, so please check the IP address. You can obtain your Internet IP address on http://myip.is/ (for example).

Of course, you can also try to create the URLs from hand (see below).

== Syntax ==
`hwplay` is an unofficial URL scheme supported by Hedgewars. The syntax of the “hwplay” URL scheme is:

`hwplay://<HOST>[:<PORT NUMBER>]`

Parts in square brackets are optional.
Parts enclosed in less-then and greater-than signs are parameters, where

 * `<HOST>` is the IP address or host name of the server
 * `<PORT NUMBER>` stands for the TCP port number of the server

If the port number is omitted, Hedgewars assumes the default port 46631.

== Examples ==
Here are some example `hwplay` URLs:

 * [hwplay://netserver.hedgewars.org]: Points to the lobby of the official server. This is the same as if you'd click on the “official server” button in the main menu
 * `hwplay://`: Points to the lobby on a LAN server with IP, port number 54321
 * `hwplay://example.com:59000`: Points to the server “example.com”, port number 59000