Upload a GMod Map to the Steam Workshop: Step by Step

You publish a GMod map in three steps: you create a folder with an addon.json and the BSP under maps/, build a .gma file from it with gmad.exe, and upload that with gmpublish.exe together with an icon of 512 × 512 pixels. The new item is hidden at first and only becomes visible once you set it to public on its Workshop page. If the upload fails, the cause is usually a file that is not on the whitelist, the addon.json or the icon.

Decide first: Workshop or sale

A public Workshop item is free and available to everyone. That cannot be cleanly undone: under the Steam Subscriber Agreement, removing the item later does not affect the rights of users who have already obtained a copy. A map you want to sell therefore does not belong on the Workshop beforehand. Conversely, the Workshop is the most convenient route for anything meant to be freely available, because Steam handles distribution and updates. The trade-off from a server's point of view is covered in custom map or Workshop map, the route to selling in selling GMod maps.

Folder layout and addon.json

Technically, a Workshop addon is a single .gma file: an archive built from a folder laid out like garrysmod/. The name of the folder does not matter. For a map it looks like this:

rp_harbourtown/
  addon.json
  maps/rp_harbourtown_v2.bsp
  maps/rp_harbourtown_v2.nav
  maps/graphs/rp_harbourtown_v2.ain
  maps/thumb/rp_harbourtown_v2.png
  materials/...
  models/...
  sound/...

You only need materials/, models/ and sound/ for content that is not inside the BSP. It is usually simpler to pack everything, see packing custom content into the BSP. The image under maps/thumb/ appears in the game's map selection. The thumbnails that ship with GMod are PNG files of 128 × 128 pixels.

The addon.json describes the addon:

{
	"title": "rp_harbourtown",
	"type": "map",
	"tags": [ "roleplay", "scenic" ],
	"ignore": [ "*.vmf", "*.psd" ]
}

Building the .gma with gmad.exe

gmad.exe and gmpublish.exe are in the GarrysMod/bin folder of the game installation. The GMod wiki warns against moving gmad somewhere else.

gmad.exe create -folder "C:\maps\rp_harbourtown" -out "C:\maps\rp_harbourtown.gma"

gmad checks every file against a whitelist and aborts with File list verification failed if one fails. Under maps/, only .bsp, .nav, .ain, .lmp and PNG files under maps/thumb/ are allowed, plus the usual formats for materials, models, sounds and Lua. With the -warninvalid option, gmad skips invalid files instead of aborting.

The whitelist has an important consequence for mappers: soundscape scripts (scripts/soundscapes_<mapname>.txt) and a particle manifest (maps/<mapname>_particles.txt) cannot be shipped as loose files. The usual way out is to pack them into the BSP. For soundscapes this is documented in the Valve Developer Community. After packing, check in game that sounds and particles really load.

Publishing with gmpublish.exe

The command for creating a new item is:

gmpublish.exe create -icon "C:\maps\rp_harbourtown.jpg" -addon "C:\maps\rp_harbourtown.gma"

1. Prepare the icon. It has to be a JPEG of exactly 512 × 512 pixels, saved as a baseline JPEG (not progressive) and smaller than 1 MB. The wiki additionally names a chroma subsampling of 4:2:0. PNG does not work.
2. Start Steam and log in with the account that should own the item. gmpublish works through the running Steam client.
3. Run the command. If you have not yet accepted Steam's Workshop agreement, gmpublish aborts and prints the address for it. On success, the output contains Success! Your new item ID is followed by the ID. Write it down.
4. Fill in the page. gmpublish reports that the new item is marked as hidden. Open it on the Workshop and add a description and screenshots.
5. Set the visibility. Only then do you make the item public.

Steam has four visibility levels: public, friends only, hidden (only for you) and unlisted. "Unlisted" means that anyone with the link can see the item, but it does not show up in any search. How a server loads Workshop addons and passes them on to players is covered in FastDL or Workshop.

Updates and change notes

gmpublish.exe list
gmpublish.exe update -id 1234567890 -addon "C:\maps\rp_harbourtown.gma" -changes "v3: fixed spawn in town hall"
gmpublish.exe update -id 1234567890 -icon "C:\maps\rp_harbourtown.jpg"

list shows the items you have uploaded. The ID is also in the address of the Workshop page after ?id=. -changes is optional, and you can edit the note later on the Workshop page in the "Change Notes" tab. Write it with ASCII characters only, so no umlauts or accents. According to the wiki, the upload otherwise goes through but the note is missing. According to the wiki, title, description and images are changed on the Workshop page.

Publish new versions as an update of this item and not as a new item. The Workshop rules for GMod recommend that. Servers check their addons for updates on restart. Until then the old BSP runs there, and according to the GMod wiki that can stop players from joining. Why a new version should also get a new file name is covered in map names and versions.

Third-party content: what the rules say

This is not legal advice, but a summary of what the rules state.

• In the Steam Subscriber Agreement you represent that you created a Workshop contribution yourself or are allowed to submit it on behalf of everyone involved, and that you hold the necessary rights to the content.
• The GMod wiki puts it more bluntly: do not upload addons you did not make, not even fixed versions, unless the author agrees. Reuploads are removed, even if the original no longer exists.
• According to the Workshop rules, addons with content from paid games such as Counter-Strike: Source or Half-Life 2 are removed, even if your addon needs those props to work. So do not pack such files into the BSP.
• Also not allowed are empty items and test items, addons that require an external download, and addons that restrict their use to certain servers.

Under the Subscriber Agreement, Valve can restrict or remove contributions for any reason. Who holds the rights to which parts of a map is sorted out in the article on copyright basics for GMod maps.

FAQ

How do I ship a TTT script if .txt under maps/ is not allowed?

Through data_static/. TTT looks for the weapon and spawn script first under maps/<mapname>_ttt.txt and then under data_static/<mapname>_ttt.txt. The whitelist allows .txt, .json, .xml, .csv and .dat in that folder.

Can I delete a Workshop item again?

Yes, on the Workshop page, and it cannot be undone. It does not bring back copies that subscribers already have.

Is "unlisted" enough to give a map to my server only?

No. Anyone with the link can subscribe to the item, and every player who joins gets the file anyway. For maps that should not be public, FastDL is the usual route.

How large can an addon be?

The Workshop rules name a limit of around 4 GB and advise against splitting an addon into several parts. If the upload reports "Compression Failed", the addon is too large according to the wiki. Smaller textures are the first lever, see reducing BSP file size.