HWPlaySchemeSyntax: (hopefully) more complete explanation of the HWPLAY URLs
Sat, 16 Jan 2016 20:39:38 +0000
changeset 730 917fd6b57b16
parent 729 66476d95dc3d
child 731 42ff4b1eef88
HWPlaySchemeSyntax: (hopefully) more complete explanation of the HWPLAY URLs
--- a/HWPlaySchemeSyntax.wiki	Sat Jan 16 14:34:07 2016 +0000
+++ b/HWPlaySchemeSyntax.wiki	Sat Jan 16 20:39:38 2016 +0000
@@ -1,5 +1,44 @@
 #summary The Hedgewars URL scheme handler
+== Overview ==
+`hwplay` is an unofficial URL scheme for specifying a server and optionally a room. Hedgewars is able to interpret these URLs to automatically join the specified server and room.
+`hwplay` URLs are useful if you want to play on a server other than the official one.
+== Usage ==
+You can share a `hwplay` URL with other players so they join your server more easily.
+Since `hwplay` is an unofficial URL scheme, your browser and other software needs to learn first how to interpret these URLs.
+Applications might ask you which program to use with a `hwplay` URL. You have to point these to the Hedgewars program (`hedgewars.exe` on Windows, `hedgewars` on GNU/Linux and Mac OS).
+`hwplay` URLs are completely optional, you can of course join any server without a `hwplay` URL as long you know its hostname / IP address and port number (46631 by default).
+== Creating `hwplay` URLs ==
+When you are about to start a server in Hedgewas (Main menu → Network game → Local network → Start server), Hedgewars will create a `hwplay` URL for you and copy it into the clipboard if you click on the “invite” button.
+Note the generated URL might only work in your LAN, 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).
\ No newline at end of file
+== Syntax ==
+The syntax of the “hwplay” URL scheme is:
+`hwplay://<HOST>[:<PORT NUMBER>[?room=<ROOM NAME>]]`
+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
+ * `<ROOM NAME>` is the name of a room in the server
+If the port number is omitted, Hedgewars assumes the default port 46631.
+If the room name is given, the user will automatically join this room. If it is not given, the user will start in the lobby of the server.
+== 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.org?room=MyRoom`: Points to “MyRoom” on the server “example.org”
+ * `hwplay://example.com:59000`: Points to the server “example.com”, port number 59000
\ No newline at end of file