GMod Map Names and Versions: Prefix, File Name, Updates

A GMod map gets a file name made of lowercase letters, digits and underscores, with the gamemode prefix at the front and a version tag at the end, for example rp_harbourtown_v2. Every published change gets a new name. The reason: client and server identify a map by its file name, and anyone who already has a file under that name does not download a new one. If the two files differ, the connection attempt ends with an error message.

Prefixes: what GMod actually does with them

The prefix is a convention, not a switch. In the Lua code that ships with the game it is evaluated in one place: the main menu uses it to sort maps into categories, and it hides maps that start with sdk_, test_ or vst_. The mapping is in garrysmod/lua/menu/getmaps.lua. There, the prefix is everything up to and including the first underscore, and the name is converted to lowercase first. In addition, every gamemode can register its own patterns through the maps key in its text file. Sandbox registers ^gm_|^gmod_|^phys_, TTT registers ^ttt_.

Anything that matches no pattern ends up under "Other". As long as the Murder gamemode is not installed, that includes mu_: the prefix is not in the list that ships with the game. Murder registers ^md_|^mu_|^murder_ itself through its maps key. Which gamemode runs on a server is set by the +gamemode launch parameter, not by the map. Choose the prefix of the mode the map is built for.

Rules for the file name

• Lowercase only. Linux is case-sensitive, Windows is not. A RP_Town.bsp that loads on your machine is not found by a Linux server or a FastDL web server under rp_town.bsp. When building a Workshop addon, gmad.exe flags capital letters with [Filename contains captial letters].
• No spaces, umlauts or special characters. The map name is an argument of console commands such as changelevel and part of the FastDL address. In the console a space separates arguments, in a web address it has to be encoded. With a to z, 0 to 9 and _ you avoid both.
• Short and unique. This article gives no fixed length limit, because no reliable source for GMod could be found. If your map has the same name as a widespread map by someone else, you get the same conflict as with two versions under one name.
• Decide before building cubemaps. The cubemaps are stored in the pakfile under materials/maps/<mapname>/. See fixing cubemaps and reflections.

A version scheme that lasts

The engine does not prescribe a version tag. The following suffixes are community practice:

_final is a trap, because another bug often shows up after the final version. Then the next file is called _final2 or _final_fix, and nobody can tell from the name which one is newer. For most projects _b1, _b2 during testing and then _v1, _v2, _v3 is enough.

Count up for small fixes as well, because every change produces a different file.

What happens when two files share a name

When connecting, the client checks whether it already has maps/<mapname>.bsp. If the file is missing, it downloads it and stores it under garrysmod/download/maps. If it is there, the client downloads nothing, and the engine only compares the checksum with the server's. If the two differ, the connection attempt ends with a message of this form:

Your map [maps/rp_harbourtown_v2.bsp] differs from the server's.

The player then has to delete the old file by hand, and very few know that. The same mix-up happens in other ways:

• FastDL: The web space still holds the old .bsp.bz2, while the game server already has the new BSP. Every new player downloads the wrong file.
• Workshop: Steam updates subscribers automatically. According to the GMod wiki, a server checks its addons on every restart. If it is still running the old version, or host_workshop_autoupdate is set to 0, client and server have different files with the same name.
• Workshop and FastDL mixed: Some players have the map from the Workshop, others from download/maps. With one name, nobody can tell who has which version.
• Stored server data: DarkRP stores door settings, jail positions and job spawns per map name, and doors additionally by the ID of the map entity. If an update under the same name changes the entities, old entries can point to the wrong doors.

A new file name removes all of that: the old file stays on the player's disk but no longer gets in the way. Setting up server, FastDL and Workshop is covered in installing a GMod map on a server.

What carries the map name and has to be renamed with it

Renaming a BSP in the file explorer is not enough. According to the Valve Developer Community, models and props then lose their cubemap reflections, because the engine looks for the cubemaps in the pakfile under the file name of the BSP. The clean way: rename the VMF and compile again. After that, these files move along:

Then there is everything that contains the name as text: the start map in the server configuration, map vote lists and Lua code that compares game.GetMap() with a fixed name. Do not copy the .ain over, let the new BSP generate it from scratch, as described in navmesh and AI nodes. The order of compile, cubemaps, packing and testing is shown in the pre-release checklist.

Changelog: what buyers and server owners get out of it

A new file name means work for server owners: change the start map, update FastDL, set positions again. A changelog tells them whether it is worth it. Useful entries answer four questions:

• What was fixed, what is new?
• Have doors, spawns or other entities changed, so that stored server data has to be set again?
• Is new or different content required?
• Were navmesh and node graph regenerated?

For buyers, the version history is also a sign that the map is maintained. On bspmarket.de you submit a new version in the Creator area with a version number and an optional changelog. It is reviewed before publication and then appears on the product page under "Versions & changelog". Updates are free for buyers. What else belongs on a good product page is covered in selling GMod maps.

FAQ

Do I have to create a new Workshop item for every version?

No. The Workshop rules for GMod recommend publishing new versions as an update of the existing item. Give the BSP inside it the new version name all the same: then nobody can mix up two versions, and servers only have to adjust their start map. Either way, a server only picks up the update when it restarts. According to the GMod wiki, a server that still runs an older version of the map can stop players from joining. The process is described in uploading a GMod map to the Workshop.

Which prefix do I use if the map suits several gamemodes?

The one of the mode it is primarily built for. The prefix determines the category in the menu and what players expect. An rp_ map can still be started in Sandbox.

What do I do with old versions on the server and FastDL?

Delete them as soon as the server has switched to the new version, including the .bsp.bz2 and the old .nav and .ain files. Old copies on players' machines do no harm, because they have a different name.