Garry's Mod Workshop addons and FastDL explained

Garry's Mod has two completely separate content systems and almost every "my players see ERROR signs" problem comes from confusing them. One is what the server loads and runs: addons in garrysmod/addons/, or a workshop collection mounted at startup. The other is what clients download before they can see any of it: workshop items Steam fetches for them, and loose files pulled over HTTP from a FastDL host. Mounting an addon on the server does not give it to players, and telling players to download something does not make the server run it. Once that is clear, the rest is mechanical.

What the server runs#

The server loads content from three places, in practice:

• Folders in `garrysmod/addons/`. A legacy addon is a folder containing the usual directories - lua/, models/, materials/, sound/, maps/, resource/ - and it is mounted as if those files were in garrysmod/ itself.
• `.gma` files in `garrysmod/addons/`. The packed format. Same result, one file instead of a tree. The gmad tool in the server's bin/ folder unpacks one if you need to look inside or serve its files another way.
• A workshop collection, mounted at startup with the +host_workshop_collection launch parameter. Items are downloaded into garrysmod/cache/workshop/ as .gma files and mounted from there.

Anything the server itself needs to run - admin mods, your gamemode, server-side scripts - belongs in addons/, installed by hand. Do not put those in the client collection: you will be pushing an admin mod's UI to every player who joins for no reason. The DarkRP server guide has the same split from the gamemode side.

Every file path must be lowercase. Garry's Mod on Linux is case sensitive, and an addon that ships Materials/Models/Thing.vmt works on a Windows test server and produces purple checkerboard on a real one. This is the single most common cause of content that "works for me".

Workshop collections#

A collection is the easiest way to run a server, and for most servers it is the right answer.

1. Create a collection on the Steam Workshop for Garry's Mod, add the addons every player needs, and set it Public.
2. Take the ID from the URL - the number after ?id=.
3. Add +host_workshop_collection 2519472571 to the launch parameters, or put it in the Startup tab field your panel provides.

At startup the server fetches the collection's item list, downloads anything it does not already have, and mounts it. Joining clients are told to download the same items, and Steam does that for them - out of your bandwidth, into their Steam workshop cache, where it stays for next time.

Reading the collection contents needs a Steam Web API key, passed on the command line with -authkey. You generate one from Steam's developer page against your own account. If the console reports that it could not retrieve the collection, that key is the first thing to check, and the Garry's Mod wiki is the place to confirm the current requirement, because this has changed over the years.

$ ./srcds_run -game garrysmod -console -port 27015 \    -authkey XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \    +host_workshop_collection 2519472571 \    +gamemode darkrp +map rp_downtown_v4c_v2 +maxplayers 40

What a collection is good at: updates. When an addon author publishes a fix, the server picks it up on next restart and every client's Steam updates to match. Hand-uploaded addons do not do that, and a server and client disagreeing about what version of an addon is installed is how you get errors nobody can reproduce.

What it is bad at: size. Everything in the collection is a download for every new player, and there is no partial join. A four-gigabyte collection is a ten-minute wait on a good connection before anybody sees your server, and most people will not wait.

The server's copy accumulates too. Remove an item from the collection and its .gma stays in garrysmod/cache/workshop/ forever. On a plan with 10 or 20 GB of disk that is worth clearing out occasionally; delete the cache folder and the server re-downloads only what the collection currently lists.

resource.AddWorkshop, for finer control#

host_workshop_collection is all-or-nothing. When you want a specific addon downloaded by clients without tying it to the server's mounted collection - or you want the list in version control rather than on a Steam page - use resource.AddWorkshop in a server autorun file:

resource.AddWorkshop("104815552")   -- map packresource.AddWorkshop("2151453461")  -- shared propsresource.AddWorkshop("180530595")   -- weapon base

The ID is a string, not a number. The file runs at server start, so changes need a restart.

This adds the addon to the client download list. It does not mount anything on the server, which is exactly what you want for content that only the client needs to render - and exactly the trap if you assumed it installed the addon. If the server needs the addon too, it still has to be in the collection or in addons/.

Both approaches can coexist. A common arrangement on a large server is a small collection for the things the server genuinely mounts, plus a resource.AddWorkshop list for client-side content, kept in a file alongside the rest of the configuration. The general mechanics of workshop content on dedicated servers, across games, are in Steam Workshop mods on dedicated servers.

Loose files and the slow way to send them#

Not everything is on the Workshop. Custom maps, a logo, a font, a sound pack you made - these are loose files in the server's own folders, and clients need them too. You tell the client with resource.AddFile:

resource.AddFile("maps/rp_yourmap_v2.bsp")resource.AddFile("materials/logo/banner.vmt")resource.AddFile("materials/logo/banner.vtf")resource.AddSingleFile("sound/ambient/radio_loop.wav")

Paths are relative to garrysmod/. resource.AddFile on a .mdl also queues the model's companion files; resource.AddSingleFile adds exactly one file and nothing else.

Here is the part people miss. With nothing else configured, those files are sent over the game's own network channel, which is slow by design - it was built for a server icon, not a content pack. net_maxfilesize caps the size of any single file, and the default is modest. A player joining a server with fifty megabytes of loose files on the game channel will sit at the download screen long enough to change their mind.

That is the problem FastDL solves.

Setting up FastDL#

FastDL is just a web server. You put a copy of the content in a directory that mirrors garrysmod/, and you tell the game server where it is:

sv_downloadurl "https://files.yourserver.net/gmod"sv_allowdownload 1sv_allowupload 0

The URL points at the directory that contains models/, materials/, sound/, maps/, resource/ and particles/ - the same names, the same nesting, all lowercase. A client that needs materials/logo/banner.vtf requests exactly that path underneath your URL. No directory listing is needed and none should be enabled.

HTTPS works and is what you should use. What does not work reliably is a URL that redirects, so point at the real location rather than a shortener or a redirecting front door.

sv_allowdownload 1 must stay on: it is what allows any client download at all, including over HTTP. Turning it off does not force players to have the content already, it just leaves them without it.

Compress everything. The client asks for banner.vtf.bz2 before it asks for banner.vtf, so upload the compressed copy and the download is a fraction of the size:

$ cd /var/www/gmod$ find . -type f ! -name '*.bz2' -exec bzip2 -k {} \;

-k keeps the original, which is worth doing while you are testing. Once you trust the setup, the .bz2 files alone are enough.

Where to put it: any static web hosting will do, and it wants disk and bandwidth rather than CPU. A small web hosting plan serves the directory perfectly well, takes the files over SFTP or the file manager, and includes a proxy slot - point an A record at the address shown and the certificate is issued and renewed for you, so https://files.yourserver.net works without you touching certbot. Your domain and its certificate covers the DNS side.

One honest note on bandwidth: a FastDL host serving a 2 GB pack to every new player on a busy night moves real traffic. Unmetered means you are not billed per gigabyte, not that saturating a shared uplink is fine - bandwidth and fair use is the version of this conversation nobody enjoys having later.

Which system for which content#

The honest default for a new server: put everything you can on the Workshop and use a collection, and keep FastDL for the handful of things that are not on it. Steam's delivery is faster than yours, it is cached on the player's machine between sessions, and it updates itself. Servers that put a mirror of their entire workshop content on FastDL are usually solving a problem they invented.

Keeping the download small#

This is the part that decides whether people join twice.

• Audit the collection by size, not by count. A single high-resolution vehicle pack can outweigh thirty scripts. The Workshop shows file size on each item's page.
• Delete the duplicate weapon bases. Most servers accumulate three overlapping packs because each new addon shipped one.
• Prop packs are for maps that use them. If no map or job references it, it is pure download.
• Decide what is required versus what is nice. A player does not need your staff team's custom player models to play.
• Test the real number. Join with a Steam account that has never been on the server, from a normal connection, and time it. Under two minutes is good. Over five and you are losing people.

Disk on the server matters too. A Garry's Mod install is a few gigabytes before addons, the workshop cache grows with the collection, and demos and logs accumulate. Fast storage shortens the mount time at startup, which is most of what you feel on a restart - what NVMe actually changes puts realistic numbers on that.

Troubleshooting missing content#

Purple and black checkerboard. A missing material. Either the client did not download it, or the path case is wrong on a Linux server, or the addon ships the .vmt without the .vtf.

ERROR signs floating in the world. A missing model. Same three causes, different file type.

Only some players see it. Their cl_downloadfilter is set to something other than all. none blocks every download and nosounds blocks audio; both are things people set once years ago and forgot. You cannot change it for them, but you can tell them.

Everyone downloads forever, then times out. FastDL path is wrong. Open the URL for one specific file in a browser - if https://files.yourserver.net/gmod/materials/logo/banner.vtf.bz2 does not download, neither will the game. A 404 here is the whole problem.

The workshop collection did not load. Check the console at startup for the collection fetch, confirm the collection is Public, and confirm the API key. A private or friends-only collection fails silently from the server's point of view.

Content works locally, breaks on the server. Case sensitivity, nine times out of ten. Rename everything to lowercase, including directory names, and restart.

An addon updated and now nothing works. Workshop addons update under you. If a server is stable and you need it to stay stable for an event, that is an argument for hand-installed .gma files for that week - and the base server setup guide covers where they go.

On RE:NODE, the file manager unpacks an uploaded archive in place, so a .gma or a content pack goes straight into addons/, and SFTP handles bulk uploads when a collection is too big to drag into a browser. The console is unfiltered, which is where the collection fetch and every missing-file complaint appear. Backup slots are on every plan, which is worth using before an addon audit rather than after it.

FAQ#

Do players download addons from my server or from Steam?

From Steam, for anything in the workshop collection or added with resource.AddWorkshop. Only loose files - custom maps, your own materials and sounds - come from your server or your FastDL host.

Is FastDL still needed if I use the Workshop?

Only for content that is not on the Workshop. Most servers need it for a custom map and a handful of files, and nothing else. If everything you run is a workshop addon, you can skip FastDL entirely.

Why does the server mount addons that clients do not get?

Because they are two lists. The server mounts what is in addons/ and in the collection; clients download what the collection and the resource.Add calls tell them to. An admin mod is deliberately in the first list and not the second.

How big should my collection be?

Small enough that a new player joins inside two minutes. In practice that means keeping the client-required content well under a gigabyte. Server-only addons do not count towards it, which is another reason to keep them out of the collection.

Do I need a Steam Web API key?

For host_workshop_collection, yes - the server needs it to read the collection's item list, and it is passed with -authkey. Addons installed by hand in addons/ need no key at all.

Can I host FastDL on the game server itself?

No. A game plan runs the game, not a web server. Use any static web hosting for the directory, point sv_downloadurl at it, and keep the files compressed with bzip2.