Packaging Maps for Auto-Download

Note that if you don't own a server or web host, or just want to give the map to your friends without going to the bother of making it auto-download (Which is a bit of work, really)... or its just a single player or LAN map, you can simply give them the package HBC file. Clicking "package map for download" in the map editor will prompt you for a folder to place the result in. Use a fresh, clean folder, preferably far away from your hyperbol installation. For example, a new folder on your desktop would be perfect. Inside there, after clicking "package map for download", you will find the HBC file.

If you are running a server or want servers to be able to automatically upload your map to players... read on.

Allowing your maps to be automatically downloaded is a very important step in getting others to enjoy them with you – be it a deathmatch, botmatch, objective map, or even a custom campaign type map. You could simply give them the map manually, of course, but its much easier and better to use the packaging and automatic download systems built into the game to spread the map around. This HOWTO assumes you already have a map, and want to package it up so that it can be easily automatically distributed by servers which would like to run it. Before you start though, please make sure the following are already done – since once you pack a map up and are distributing it around, you’ll probably need to rename it if you wish to replace it with a newer version.

Note: You will need access to a public web host that people can download zip files from, in order to get this to work.

• Make sure you have named your map appropriately

  • the folder name should match the name of the map

  • the minimap name should match the folder name which should match the map name (with the _mm.dds at the end)

• Make sure you have created an appropriate minimap for your map

  • The minimap can be any size, but we recommend 1024x1024 or 512x512.
  • It must be a DDS file, (many tools such as GIMP and Photoshop, with the free nvidia plugins can output DDS files).
  • We recommend to use DXT5 compression.
  • The map editor can do this for you if your video card supports it.

• Make sure you have tested and compiled your map and run it in the game

  • This seems to go without saying, but still.
  • Run a couple botmatches, perhaps.

• Make sure your map has the proper name and description

  • This name and description shows up in various places. Make sure its set, or it will show up incorrectly in map selection screens and so on.

• Make sure your map is ‘optimized’

  • This means running the optimization tools built into the map editor. This can greatly improve the performance of your maps, as it bakes a lot of complicated info into structures that are easy for video cards to render.

• If it’s a beta you probably want to name it that way

  • For example, o_mymap_b1
  • This is because its very hard to ‘overwrite’ things, consistently, in an autodownload situation.
  • Next revision you release, give it the next name, like o_mymap_b2 So eventually, after all of this, you’ll have a map folder full of all sorts of files.
    • We’re now going to package that up specifically for downloading.

STEP 1: Making the package (Automated)

• In the map editor, you simply chose “file->package map for download”

• The map editor will check to make sure your map has been compiled, optimized, and has a minimap.

• NOTE: AT THIS POINT YOU SHOULD MAKE SURE THAT THE MINIMAP IS NEW. IF A PREVIOUS MINIMAP HAS BEEN GENERATED, THE MAP EDITOR WILL NOT OVERWRITE IT. If you're not sure, you should delete the minimap file (mapname_mm.dds) in the map's folder, before doing this.

• You’ll be asked where you want to save the resulting package(s).

  • I suggest making a fresh folder somewhere, and saving them in that folder, away from the rest of the files, since they are specifically designed to be distributed. A new folder on your desktop would be perfect!
  • It’s a bad idea to save these files anywhere in your hyperbol folder, since they’re for distribution.

• The packing process will automatically result in a “manifest” file for the map, as well as a ‘zip’ file, and a HBC file.

  • The ‘zip’ file will have an odd name – it contains the checksum for the map, and is very likely to be unique, so it can coexist in a folder with many other maps without conflicting. Don’t rename any of these files. Its NOT A REAL ZIPFILE, its actually the hbc file renamed to zip so that webhosts will find it - and to give it a definitely unique name.

  • The manifest file is a text file. Open it up and read it if you’re curious as to how the system works! Edit at your own peril. Note: After patch 1.06, the manifest file is no longer used and can be ignored

  • The 'hbc' is the actual modfile (its actually a copy of the zip). If you give this to your friends manually, and they double click on it, they will then have the map. But we're not doing it that way here - we're making it automatic!
  • Here's how it looks for a map called fun_stuff

  • 

After you have these files, there are two ways you can allow your server to automatically give maps to connecting players. You can offer it via remote HTTP download (players will download it of some other web server you control) or direct Auto Download from your server. If you can go the HTTP route, it might be better, since it will offload bandwidth from your server. However, if you have no access or want a simple setup, go the auto direct download route

Automatic Direct Download Method

Either use the ThreadSpace: Hyperbol server configuration tool on Starport to generate the configuration for the server, or manually edit the config files if its not an official server. All you have to do is make sure the following fields are present and to your liking:

[MapConfig]
[Map]
MapFileName: "YOUR_MAP_NAME.hba"
...
[MultiplayerSettings]
...
AllowDirectMapDownloads: true
DirectDownloadPort: 12131
DirectDownloadMaxKBytesPerSecondPerSlot: 16
BaseMapDownloadURL: ""

Note that we have put YOUR_MAP_NAME.hba in the map section. So if your map is called funstuff, it would be funstuff.hba If you are behind a router, make sure that the Port you specify is routed to the particular server machine. Now place the hbc file inside a 'modfiles' folder, in the server's data folder. So for example, if your map is called funstuff, and the editor output funstuff.hbc, youd place it in your hyperbol server's folder so that it can be accessed in data/modfiles/funstuff.hba Once you have done this, you're done. Players connecting to your server will automatically download the map directly from your server.

Remote HTTP Server Method

If you don't want to use your server to send mod files to people, and would prefer to upload them to a remote server, do the following instead of the auto direct download: * For a server to run your map (and offer it to auto download to players) that server must have your map! The only way to get the server the map is to manually give the map to the server. Luckily, we already have the HBC mod package!

• Upload the ZIP file (not the MST) to a publicly visible web host that players connecting to the game can get it from. This means uploading it onto the web somewhere. It must be a direct download. In other words, you must be able to type the path into MSIE and be given the ZIP file back. Setting up a web host is beyond the scope of this HOWTO.

• Send the or copy the HBC file to the hyperbol server's modfiles folder. This simply means to place it in the modfiles folder. If there is no such folder, create it. It should be in hyperbolfolder\data\modfiles. So for example, steam\steamapps\common\tshb\data\modfiles\o_mapname.hbc

  • 

• Put the map into the map cycle.

  • You can edit the servers config file to do this, or use the in-game-gui.
  • If you have the HBC file in your folder, it should appear chooseable in your ingame GUI

  • otherwise, if you're hand editing, add mapname.hba to your cycle (HBA, NOT HBC).

  • Here's how the beginning of the hostoptions.cfg would look with the fun_stuff map (notice that we use a .hba)

    • 

• Make sure that the URL to the publicly visible website is in your server’s config file.

  • You will need to add the key "BaseMapDownloadURL" in to your hostoptions.cfg. The configuration key is "BaseMapDownloadURL". It can include folders, subfolders, etc., but should not contain a trailing slash: For example, put the following in your hostoptions.cfg:

    • BaseMapDownloadURL: "http://some.website.com/somefolder/maps"

    • This tag goes inside your hostoptions.cfg (or whatever custom config file you are using for your server), anywhere underneath the [MultiplayerSettings] section.

    • The above example indicates to clients that they can find the map zip files for download at that URL.

    • So in the above example, to download “map_1283120981.zip” it would search for it at http://some.website.com/somefolder/maps/map_1283120981.zip

    • Here's a picture of it inside my hostoptions.cfg:

    • 

  • Make sure that AllowDirectMapDownloads is set to false in the config file

  • You cannot use custom maps in official servers. Your server will not allow players to join it. Stats will not be counted. Don't waste your time trying to do this. Make sure your server is not listed as an official server in its config file (remove the starport username)

  • You do not need to have the word "/maps/" or "/somefolder/" in there. Its just an example. All thats going to happen is its going to take that URL you supply, put a slash at the end of it, and add the zip file name to it. So if you put "http://myurl.com" and your zip file is called "map_123.zip", it will become "http://myurl.com/map_123.zip". So your goal is to fill in the URL to the folder on the server that you're going to put your zip files, in such a way that you supply the entire path, minus the zip file part.

• If a custom map is excellent, it might eventually be 'made official' by Iocaine Studios - submit your maps using the Starport Map Submission page.
• At this point, your server is configured. Clients connecting should automatically get the map, and be able to immediately play.

  Notes * You can share a web host with other servers. If there is a common repository of maps and things, this makes it easy on everyone.

• This might seem like a lot of work at first, but once you have the web host, server and everything else set up, adding a new map is simply a matter of uploading the zip to the same webspace as you have uploaded all the others, and then putting the MST file and the ZIP (and renaming to hbc) on the server.

If correctly setup, when a player that doesn't have the map connects to your server, they will see the following: