Information About Hosting Workshop Maps on a TF2 Server
Hi, folks.
This thread is for discussion about server configuration for Workshop maps. It does not cover publication or editing for map authors, or client problems. For that, please see this thread. This post is updated when anything significant changes about hosting Workshop maps on a server, after it has been tested and confirmed as best it can be.
A Bit About Workshop Maps
Workshop maps can be hosted easily on both stock TF2 servers and on servers that use SourceMod. You do not have to download a Workshop map manually to upload it to your server. The whole system of obtaining maps, and updating them, is handled automatically by the server in conjunction with the Steam Workshop. Clients connecting to your server will download the maps from the Workshop, making your FastDL server redundant.
Each Workshop map has a unique nine-digit number, which I call a UGC ID. You can find this in the URL of each map's page in the Steam Workshop. You must use this number to load maps, and in your mapcycle file.
Each Workshop map that has been downloaded to your game server is stored in its own directory in steamapps/workshop/content/440/{ugcid}. You can specify the directory where Workshop maps are stored using the launch parameter -ugcpath. The file steamapps/workshop/appworkshop_440.acf is a list of all the maps you have downloaded. The server uses it to keep track of them. You can use the cvar tf_workshop_map_status to check the currently tracked maps and their status.
Workshop maps are already compressed (known as repacked), and are slightly smaller than if they were compressed using BZ2, so if you make the switch to them, you can reduce the amount of disk space used.
How to Run Workshop Maps on Your Server
To run a workshop map on your server, just add it to your mapcycle using either of these two formats:
The second format includes what I call a 'friendly name' for the map. This does not have to be exactly the same as the map's filename (sans .bsp extension). Rather, it can be used to help you when you edit your mapcycle. The friendly name is also what SourceMod displays in its menu system, so try to keep it brief and informative.
When your server starts, it will read your mapcycle file and resolve all of the UGC IDs. It will begin to track them, so that if an updated map is available, it will be downloaded. To see the maps your server is tracking, you can use the command tf_workshop_map_status. You can tell the server to check tracked maps for updates using tf_workshop_refresh.
There is a short delay for connecting clients whilst the server downloads a map for the first time, during which time they will not be told what is happening.
If there is a dead map in the mapcycle (that is, a map that is no longer present on the Workshop), then it will still appear in voting lists, and can be voted for. If the map wins a player vote, then when the server attempts to switch to it, it will instead revert back to the map that was last played. The server console will output an error about such maps on each map change:
If the server attempts to change to a dead map as part of its cycle, it will fail and try the next map in the cycle:
You can also run a Workshop map directly, using either of the two formats above in conjunction with the rcon command changelevel, or the SourceMod map changing commands /map and /setnextmap. When the server tries to switch to that map it will begin to track and download it. You can track a map manually in an attempt to download it prior to switching to it, using the command tf_workshop_map_sync <ugc id>.
Differences Between Stock and SourceMod
You can use either of the above formats in your map cycle on a vanilla server, it does not matter, because when the server loads, it will resolve all of the UGC IDs in your mapcycle to their true filenames. So when a player goes to call a map vote, this is what they see:
Note in the screenshot above that the first number is that of a map that is no longer present on the Workshop (a dead map). Also note that the maps have been ordered alphabetically by filename and include version numbers.
If you use the simplified format in your mapcycle, this is what players will see in a SourceMod map menu:
If you use the second, extended format with friendly name, this is what players will see:
SourceMod is programmed to stop the last few maps from being played again. Unfortunately this doesn't work in the current public versions of SourceMod unless you use the true map filename in place of the friendly name. You can find those by loading up your server and using the console command tf_workshop_map_status to see all of the currently tracked maps.
Known Issues
Most of the bugs with Workshop maps have been ironed out but you should keep an eye out for new ones. Reports of problems aren't uncommon each time Valve makes an update.
There seems to be a bug preventing SourceMod servers from changing Workshop maps, at the moment. I have experienced it locally and have received a report of it in this thread. I will update this when I know more. (5th September 2015)
FAQ
Why are my SourceMod map lists unpopulated?
There was a problem with SourceMod that was introduced after an update to TF2 where the map handling code stopped adding maps to map list menus. This was fixed in SourceMod snapshot 1.7.3-git5214 and did not occur in 1.8 beta.
How can I delete all of my workshop maps and reset the server's tracking record of them?
Whilst the server is shut down, delete steamapps/workshop/appworkshop_440.acf and everything inside steamapps/workshop/content/440.
See Also
Problems, Comments and Suggestions?
By all means, post in this thread or contact me using the private message system or on Steam. Or pop in to the TF2maps.net Steam chat room if you'd like to chat with mappers and some server operators and developers.
Hi, folks.
This thread is for discussion about server configuration for Workshop maps. It does not cover publication or editing for map authors, or client problems. For that, please see this thread. This post is updated when anything significant changes about hosting Workshop maps on a server, after it has been tested and confirmed as best it can be.
A Bit About Workshop Maps
Workshop maps can be hosted easily on both stock TF2 servers and on servers that use SourceMod. You do not have to download a Workshop map manually to upload it to your server. The whole system of obtaining maps, and updating them, is handled automatically by the server in conjunction with the Steam Workshop. Clients connecting to your server will download the maps from the Workshop, making your FastDL server redundant.
Each Workshop map has a unique nine-digit number, which I call a UGC ID. You can find this in the URL of each map's page in the Steam Workshop. You must use this number to load maps, and in your mapcycle file.
Each Workshop map that has been downloaded to your game server is stored in its own directory in steamapps/workshop/content/440/{ugcid}. You can specify the directory where Workshop maps are stored using the launch parameter -ugcpath. The file steamapps/workshop/appworkshop_440.acf is a list of all the maps you have downloaded. The server uses it to keep track of them. You can use the cvar tf_workshop_map_status to check the currently tracked maps and their status.
Workshop maps are already compressed (known as repacked), and are slightly smaller than if they were compressed using BZ2, so if you make the switch to them, you can reduce the amount of disk space used.
How to Run Workshop Maps on Your Server
To run a workshop map on your server, just add it to your mapcycle using either of these two formats:
- workshop/123456789
- workshop/cp_mapname.ugc123456789
The second format includes what I call a 'friendly name' for the map. This does not have to be exactly the same as the map's filename (sans .bsp extension). Rather, it can be used to help you when you edit your mapcycle. The friendly name is also what SourceMod displays in its menu system, so try to keep it brief and informative.
When your server starts, it will read your mapcycle file and resolve all of the UGC IDs. It will begin to track them, so that if an updated map is available, it will be downloaded. To see the maps your server is tracking, you can use the command tf_workshop_map_status. You can tell the server to check tracked maps for updates using tf_workshop_refresh.
There is a short delay for connecting clients whilst the server downloads a map for the first time, during which time they will not be told what is happening.
If there is a dead map in the mapcycle (that is, a map that is no longer present on the Workshop), then it will still appear in voting lists, and can be voted for. If the map wins a player vote, then when the server attempts to switch to it, it will instead revert back to the map that was last played. The server console will output an error about such maps on each map change:
Code:
[TF Workshop] Error fetching updated information for map id 454372402
[TF Workshop] Info lookup failed for workshop file 454372402 ( EResult 1 )
Code:
CHANGE LEVEL: workshop/454372402
[TF Workshop] Preparing map ID 454372402
[TF Workshop] Error fetching updated information for map id 454372402
[TF Workshop] Info lookup failed for workshop file 454372402 ( EResult 1 )
[TF Workshop] Map failed to sync, load will not go well :(
CModelLoader::Map_IsValid: No such map 'maps/workshop/454372402.bsp'
Unable to change level!
In gameover, but failed to load the next map. Trying next map in cycle.You can also run a Workshop map directly, using either of the two formats above in conjunction with the rcon command changelevel, or the SourceMod map changing commands /map and /setnextmap. When the server tries to switch to that map it will begin to track and download it. You can track a map manually in an attempt to download it prior to switching to it, using the command tf_workshop_map_sync <ugc id>.
Differences Between Stock and SourceMod
You can use either of the above formats in your map cycle on a vanilla server, it does not matter, because when the server loads, it will resolve all of the UGC IDs in your mapcycle to their true filenames. So when a player goes to call a map vote, this is what they see:
Note in the screenshot above that the first number is that of a map that is no longer present on the Workshop (a dead map). Also note that the maps have been ordered alphabetically by filename and include version numbers.
If you use the simplified format in your mapcycle, this is what players will see in a SourceMod map menu:
If you use the second, extended format with friendly name, this is what players will see:
SourceMod is programmed to stop the last few maps from being played again. Unfortunately this doesn't work in the current public versions of SourceMod unless you use the true map filename in place of the friendly name. You can find those by loading up your server and using the console command tf_workshop_map_status to see all of the currently tracked maps.
Known Issues
Most of the bugs with Workshop maps have been ironed out but you should keep an eye out for new ones. Reports of problems aren't uncommon each time Valve makes an update.
There seems to be a bug preventing SourceMod servers from changing Workshop maps, at the moment. I have experienced it locally and have received a report of it in this thread. I will update this when I know more. (5th September 2015)
FAQ
Why are my SourceMod map lists unpopulated?There was a problem with SourceMod that was introduced after an update to TF2 where the map handling code stopped adding maps to map list menus. This was fixed in SourceMod snapshot 1.7.3-git5214 and did not occur in 1.8 beta.
How can I delete all of my workshop maps and reset the server's tracking record of them?Whilst the server is shut down, delete steamapps/workshop/appworkshop_440.acf and everything inside steamapps/workshop/content/440.
See Also
Problems, Comments and Suggestions?
By all means, post in this thread or contact me using the private message system or on Steam. Or pop in to the TF2maps.net Steam chat room if you'd like to chat with mappers and some server operators and developers.
Last edited:
