HaloNet Map Download Protocol
Protocol description
A standard protocol for downloading maps from HaloNet.Net, which HAC2 will move to, and other applications are free to use as well. "Application" describes a client or server-side modification, such as HAC2, HSE®, SAPP+LUA, Chimera, etc.
As of November 12th, 2019, I have added the "invader" compressed map format as created by 002/Kavawuvi- his github for invader is here: https://github.com/Kavawuvi/Invader
NOTE as of April 20, 2024 - maps.halonet.net is now running on Cloudflare. There is no longer any need for clients to loop through maps1, maps2, or maps3. These names will continue to exist, but they all go through Cloudflare. As such, the following documentation has been amended to use "maps" in the examples.
HAC2 and various client or server applications should operate as follows. Note that the default HTTP port is used, port 80.
Example URL to download a Custom Edition map:
http://maps.halonet.net/halonet/locator.php?map=zmm_battle_grounds
Map name is supplied as the variable "map". This is NOT case sensitive. CE maps are downloaded by default. To specify a PC (Combat Evolved) or Trial map, use the "type" variable to specify "ce", "pc", "trial" (or "demo"). Alternatively, "halor" (PC), "halom" (CE), or "halod" (Trial/Demo) can be used, as these are in the "product type" string most applications search for on startup.
The default download format is .zip - if you wish to download .7z or .inv (invader-compress), the URL should contain a "format" variable set to either zip, 7z or inv. Example:
http://maps.halonet.net/halonet/locator.php?format=7z&map=zmm_battle_grounds
If the "format" variable is not supplied, "zip" is the default.
A "noredirect" variable with a value of "1" can be supplied indicating that redirects are not allowed. In this case, a 404 error will be returned if the map is not local to the map server.
Example: http://maps.halonet.net/halonet/locator.php?format=7z&noredirect=1&map=zmm_battle_grounds
Map names should be "urlencoded" - https://www.w3schools.com/tags/ref_urlencode.asp - An example for Windows is to use InternetCanonicalizeUrlA: https://docs.microsoft.com/en-us/windows/desktop/api/wininet/nf-wininet-internetcanonicalizeurla
An example of a PC map download in 7z format:
http://maps1.halonet.net/halonet/locator.php?format=7z&type=pc&map=zmpsierra_1
Supported variables:
- map = specify the map name, preferably urlencoded
- format = download format, zip, 7z and inv supported
- type = Game product type, ce or halom (Custom Edition), pc or halor (Combat Evolved), demo or trial or halod (Trial)
- noredirect = 1 - Return 404 instead of 302 for a redirect.
Fault Tolerance
As of April 2024, all traffic for halonet.net goes through Cloudflare. It is a load-balanced and fault-tolerant configuration, using 5 back-end servers, in geographically diverse locations.
The following can be ignored, but it is still supported. maps1, 2 and 3 names DNS names will continue to exist, but they all go through the same Cloudflare load-balancer.
Deprecated notes as of April 2024:
The application should set the WinHTTP timeouts down to 10 or even 5 seconds so users don't face long waits for downloads. This can be done using the WinHttpSetTimeouts function. HaloNet's map servers should respond to the initial open quickly. The application can decide if the download speed is too slow, and switch to the next map server in the list if desired.
If a connection fails to maps1.halonet.net, you should retry to maps2.halonet.net, maps3.halonet.net, etc, until the name no longer resolves. The name resolution is only done in WinHttpSendRequest, and the error returned is ERROR_WINHTTP_NAME_NOT_RESOLVED.
A WinHttp example downloader can be provided on request. I hope to make one available on github.com at some point.
Multiple servers can be queried at the same time, or downloaded from at the same time. The fastest responder or first to download can be used. This may actually slow down downloads if a player's Internet connection is slow to begin with, so the application should provide a way to enable or disable that option.
Return codes
If the return code is 302, this is a "redirect". The URL returned in the Location header will point to the location to download the map in question. If this fails, continue on to the next map server and retry. This may be used to pull a map server out of the rotation, so every effort should be made to support this functionality.
Any return code other than 200 (success) or 302 (redirect) indicates a failure of that particular map server, and every effort should be made to try the next map server.
If the file returned is zero bytes, the map is not available in that format, if at all.
It is up to the application to decide when to stop trying. A user can be told map downloads are failing, and to press a certain key to stop trying, while the application continues to try the list of map servers. Or, it can stop when the list of map servers is exhausted.
Again, the "list" of map servers is just this: maps1.halonet.net, maps2.halonet.net, maps3.halonet.net, etc, until the name no longer resolves. It is again up to the application to decide what to do at that point.
If a map server fails to respond, the application is free to ignore this map server until a certain timeout passes, or for the entire session. For example, if maps1.halonet.net does not respond, later map download attempts can ignore this map server until the player restarts the game, or after 10 minutes have passed.
