The TF2 Maps Workshop, for map authors and players

Discussion in 'Team Fortress 2 Talk' started by worMatty, Jun 8, 2015.

  1. worMatty

    aa worMatty Repacking Evangelist

    Messages:
    1,072
    Positive Ratings:
    834
    Information About the TF2 Maps Workshop for Map Authors and TF2 Players

    Hello, folks.

    This post is for map authors and game players. If you want help setting up a server to host Workshop maps, please see this thread.


    Table of Contents
    • What is the TF2 Maps Workshop?
    • How to Use the Workshop
    • Joining a Server Hosting Workshop Maps
    • Running Workshop Maps Locally
    • Submitting Maps to the Workshop
      • Updating a Map or Thumbnail
      • File Versioning
      • Alpha and Beta Maps
      • Valve Official Community Maps
    • Limitations
    • Problems
    • Known Issues
    • Technical Information
    • Need More Help or Have a Comment?


    What is the TF2 Maps Workshop?

    The TF2 Maps Workshop is a large online database of TF2 maps that is integrated with Steam. It lets players find interesting maps they want to play, and helps server operators find new maps to add to their mapcycle. Map authors can add their work to it, and Valve will use it to find maps for inclusion in the game.

    If a server hosts a Workshop map, it is downloaded from the Workshop and not from the game server. Workshop maps are compressed better than BZ2, and will stay compressed when they are stored on disk, so they have a huge space saving advantage over regular uncompressed BSPs.


    How to Use the Workshop

    To get started, open up Steam, click Community, then Workshop, or visit http://steamcommunity.com/workshop on the web. Find Team Fortress 2. On the game's Workshop page you can see some maps down below. You can sort the list a few ways, ordering by popularity in a set time period, or most recent, or most subscribed.

    If you find a map you like, you can do a bunch of things with it:
    • Rate a map up or down to tell the authors that you like or dislike the map. Ratings show that someone took the time to say how they feel about the map, in brief.
    • Favourite the map to add it to a list of favourites, allowing you to find it more easily later. You should use this when you want to keep an eye on the development of a map or plan to recommend it to a friend, or add it to a server.
    • Subscribe to a map to download it to your computer for offline play, or to get a head start on joining a server hosting it later. You can use the in-game server browser to find servers that are playing your subscribed maps later on.
    • You can add maps to a collection. You can have more than one collection, and you can use them for whatever purpose you like. If you run a server you could make a collection for your mapcycle so it's easier for you to keep track of it, and to help users download the maps before they join your server. If you are a content curator, you could make some collections for maps that you think your followers would like.
    You should play a map before you leave feedback.


    Joining a Server Hosting Workshop Maps

    To find servers playing Workshop maps there are a few methods available to you:
    • Visit the Workshop page of a map that you like and check the comments and discussions to find server IP addresses that people have posted.
    • Use the in-game server browser to list servers running Workshop maps, or only your subscribed maps.
    • Use the Steam server browser to search for servers that are running maps with filenames that begin with workshop/. All Workshop maps have this prefix when they are run on a server.
    • User a server tracking web site such as Game Tracker to find servers hosting maps beginning with workshop/.
    [​IMG]
    In-game server browser

    [​IMG]
    Game Tracker example

    When you join a server hosting a Workshop map that you do not have on your computer, there is a short delay during connection, while the game's progress bar will say Updating Steam resources... and Steam will download the Workshop map for you. The download progress appears on Steam's Downloads page, along with your regular game updates.

    [​IMG]
    The in-game progress indicator

    [​IMG]
    The progress of the Workshop map download is shown on Steam's Downloads page

    Workshop maps are stored on your computer in <Steam dir>/SteamApps/workshop/content/440. Each map lives inside its own directory, which is named using its unique nine-digit identification number, which I call a UGC ID (User-Generated Content).

    When a map author releases an update to their map, Steam will download the new version the next time you connect to a server that is hosting it, and replace the old version. Subscribed maps should be updated the next time you launch TF2.


    Running Workshop Maps Locally

    You can run a map in your game locally by opening up the developer console (you can enable the console in the game's options) and typing:
    Code:
    map workshop/123456789
    The map command tells your game to begin a listen server and run the map you specify. All Workshop maps must be prefixed with workshop/. The number is the map's UGC ID, which you can find in the URL of the map's page on the Workshop. You do not have to subscribe to a Workshop map in order to play it in this way, as the game will initiate the download if the map does not already exist on your computer.

    If you want to play with bots, you should use the console command tf_bot_quota #, where # is the number of players you want in the game, including humans, so if you typed 12 and you were the only human playing, eleven bots would be spawned. If the bots do not move, you will need to generate a nav mesh so they can understand the map. You can do that by enabling cheat mode using the console command sv_cheats 1 and then generate the nav mesh using the console command nav_generate. The game will build a nav mesh and restart the map when it is done. Nav meshes for workshop maps are stored in <Steam dir>SteamApps/common/Team Fortress 2/tf/maps

    Bear in mind that some maps aren't suitable for bots, so you might find that your bots become confused and begin to jump up and down in a corner somewhere. This is a sign the bots are stressed due to feelings of being caged, so it's kinder to despawn them.


    Submitting Maps to the Workshop

    :hint:
    Be sure that your map has been fully packed with any custom assets it uses, and it has its own cubemaps. It's good practice to temporarily remove or disable all of your custom assets or mods from TF2 after you compile and pack your map, and then launch the game and run the map, simulating the environment of another player so you can check for problems.

    You can add a map to the Workshop using the in-game Workshop interface. You will need at least one image of your map, which will be used as its key thumbnail on the Workshop map index. The image will be cropped and scaled to a square with dimensions of 512x512. Don't worry, you can add more images to your map's Workshop page later on. You can put text in your image and a border, to make it look more impressive. Pre-made TF2maps.net assets can be found here.

    [​IMG]
    The Workshop map submission interface

    Your map's title should be the name of the map without its gametype prefix or version number. So for example, if your map's filename was cp_candy_store_rc6, its title would be Candy Store. You may wish to include the game mode abbreviation (CP) in brackets after your map name. This is very useful if you have multiple game mode versions of your map in the Workshop, or if your game mode is a specialty type such as Deathrun or Versus Saxton Hale.

    Your description should be kept as brief as possible. It should explain the game mode of the map, any unusual features and a bit about the theme, your design choices and the build process. The Workshop search tool also searches each map's description, so you can use it for keywords.

    Workshop maps are compressed by the game before being uploaded to the Workshop. This process is known as repacking. It takes all of the file lumps in the map and compresses them using LZMA 2 compression (like 7-Zip) resulting in a replacement BSP that is typically less than half the file size. It's possible to repack your maps manually if you intend to distribute them through normal non-Workshop channels but you should not repack a map twice because it can cause problems. Always give an uncompressed map to the Workshop submission form.

    After you have uploaded your map, its Workshop page will appear automatically in the Steam overlay in TF2. You can view your map and edit its details at any time by visiting the Workshop and viewing your files:

    [​IMG]
    A shortcut to your Workshop files on the Workshop page in Steam

    [​IMG]
    Your Workshop items.

    When you click on your map, its control panel is seen on the right of the page:

    [​IMG]
    Settings for your Workshop map.

    You are free to add as many screenshots of the map as you like, free from the restrictions of the square format. You can also add a link to a YouTube video!
    The control panel here is where you add contributor credit to the map. Contributors will be asked to confirm their payment details before being added as a contributor. This is part of the way the Workshop works and is unavoidable.

    You can view the stats for your map by clicking on the Item Stats button in the top right of the page. Here you can view a record of how many users have rated, subscribed and favourited your map, contrasted with page visits. The stats page also gives you line graphs that show these stats over a time period.

    [​IMG]
    Item Stats page

    Whenever you upload a new version of a map, it has an entry logged in the Change Notes tab. You can edit the entry to add your changelog.

    [​IMG]
    The change log of a Workshop map

    Updating a Map or Thumbnail

    You can update your map or its thumbnail image using the same submission process as before, but this time, select your existing map and click Edit. Note that your description may be truncated. If that happens, copy and paste it from the Workshop page.

    File Versioning

    Using version numbers in filenames is no longer necessary with Workshop maps, as new versions of maps replace old versions. Still, it does no harm to keep using them and it makes it simpler if you want to keep distributing your map through regular channels as well as the Workshop, as you can create one map for both. Server operators do not need to ensure they use the correct filename, as the server software recognises maps by their UGC ID. If server operators use special configuration files for your maps, such as for Surf or MvM game modes, they will need to update those if you change your BSP filename, so you should consider having a way to notify them.

    Alpha and Beta Maps

    There is nothing stopping you from uploading a work-in-progress map to the Workshop. If you do, you should try to manage user expectations, as many people will not understand why your map has dev textures in it. You should put a roadmap in your description to give server operators an idea about the progression of the map's development.

    Valve Official Community Maps

    Valve will be using the Workshop to find maps to include in the game. It's now quite important to market your map. Here are some examples of what you can do:
    • Generate a reputation for producing interesting, unusual and popular work. If you have good standing in another gaming circle, introduce your work to them.
    • Associate with popular organisations involved with mapping, trading, competition or special events.
    • Ask accomplished mappers or content curators, such as YouTube personalities, to look at your work.

    Limitations

    There is no way to get people to download content packs for your map as a separate download. All assets your map uses must be packed in to the map. If you want to give credit to someone, you can add them as a Contributor in your map's Workshop page settings.

    Currently, custom soundscapes and soundscripts that are packed in a map don't work. The same goes for .pop and .res files for MvM maps. Those must be extracted by the server operator and installed on their server.


    Problems

    If you are having problems downloading or running Workshop maps, first check the game's console for error messages. Dead maps that have been removed from the Workshop will give an error message that they cannot be found. If you have subscribed to a map and there is something wrong with the file on your computer, try closing the game and unsubscribing from the map on its Workshop page. Restart Steam then run TF2. Exit TF2 and resubscribe to the map, then start TF2 and try running the map or joining the server again.

    If you would like to delete all of your Workshop maps and start afresh, you must quit TF2 and Steam, then delete everything inside SteamApps/workshop/content/440 and delete SteamApps/workshop/appworkshop)440.acf.
    • No system exists to notify server operators that a Workshop map has been updated, unless you count the server console output. Server ops may set up special map-specific config files for a map, so if its filename changes, those will not work any more. You might want to encourage people to sign up to a mailing list, or follow you on Twitter, or use some other means of notification like an RSS feed from a blog.
    • New problems with Workshop maps are being found all the time. You should keep an eye on the server operators using your map in case they complain of problems and remove it from their mapcycle.

    Known Issues
    • Soundscapes, soundscripts, nav meshes and MvM pop and res files that are packed in to Workshop maps do not currently work. These must be extracted by the server operator and hosted separately.

    Technical Information
    • How to repack your map manually for distribution via non-Workshop channels.
    • A repacked map can be browsed using GCFscape as normal, but individual packed assets cannot be extracted. You must extract the whole .zip file from the root of the map (which makes up lump 40, the pak file) and open it with an archive app that supports LZMA 2 compression, such as 7-Zip.
    • All Workshop maps are repacked when being uploaded to the Workshop. Their file size is typically less than half that of old, non-repacked maps. Unlike maps distributed in BZ2 packages, Workshop maps remain compressed after being downloaded.
    • All Workshop maps are downloaded from the Steam Workshop, and never from the game server.

    Need More Help or Have a Comment?

    Feel free to post in this thread or join the TF2Maps.net Steam chat room and ask in there.
    You can also contact me through the forum's private message facility, or on Steam.
     
    • Thanks Thanks x 8
    • Useful Useful x 1
    Last edited: Sep 14, 2015
  2. worMatty

    aa worMatty Repacking Evangelist

    Messages:
    1,072
    Positive Ratings:
    834
    Obsolete - // I will send an email to Valve about the two problems I listed above, that I haven't marked as being known issues.

    What features would you like to see in the TF2 map workshop, from the point of view of a client, mapper, or server operator?

    Obsolete - // I'm not sure if menu_photo images are displayed on the loading screen if they are packed in to the BSP [they are]. So I would want that to be addressed, if we can't include them separately.

    Obsolete - // From the point of view of a server operator, I'd like an easier way to synchronise workshop maps. Perhaps using a text file filled with IDs, like the CS:GO server does. That way I could just put in the text file, use the appropriate command and the server would take care of all the downloads for me. [That's how it works now]

    I'd also love a tool that checks the file names of existing server maps to see if they are available on the workshop. That would save us having to check each map separately, and having to check in the future.

    That's all I can think of at the moment.
     
    Last edited: Sep 14, 2015
  3. Fr0Z3nR

    aa Fr0Z3nR Creator of blackholes & memes. Destroyer of forums

    Messages:
    6,391
    Positive Ratings:
    4,906
    It's not possible, afaik, to pack in .nav meshes either, which make MvM maps and RD maps unable to work.

    Unless I'm incorrect (I skimmed this post)
     
  4. tyler

    aa tyler snail prince, master of a ruined tower

    Messages:
    5,034
    Positive Ratings:
    3,989
    I was hoping the name of the workshop map as published would be the in game display name, but it doesn't seem like it. Still, that means your map can be compiled as pl_badwater_basin (thereby displaying the full name) without worrying about people having to type that out all the time. That also means those pesky version numbers will be removed as well. That's good news for people that have wanted to have similar map names in the past, like with Furnace Creek.

    Hopefully they fix the problems with updating files.
     
  5. Freyja

    aa Freyja ¯\_(ツ)_/¯

    Messages:
    2,869
    Positive Ratings:
    4,896
    It is possible. You just need to say "no" when pakrat wants to update it, or it will crash servers.
     
    • Thanks Thanks x 1
  6. worMatty

    aa worMatty Repacking Evangelist

    Messages:
    1,072
    Positive Ratings:
    834
    Information about bsp_repack added, and some of the discussion from the server operator thread about whether or not to use file name versions. bsp_repack can be used in place of bz2 compression to save server and client disk space.
     
    • Thanks Thanks x 1
  7. Egan

    aa Egan

    Messages:
    1,318
    Positive Ratings:
    1,507
    When I tried doing bsp_repack on this surf map I was updating the refract materials seemed to break:

    regular bsp:
    [​IMG]

    bsp_repack:
    [​IMG]

    the refract material vmt (materials/oceanic/glass/oceanic_glass_01):
    "refract"
    {
    "$model" "1"
    "$bluramount" "1"
    "$surfaceprop" "glass"
    "$refractamount" "0.2"
    "$scale" "[1 1]"
    "%keywords" "tf, bulletcrops"
    "$normalmap" "oceanic/glass/oceanic_glass_01_normal"
    //"$dudvmap" "oceanic/glass/oceanic_glass_01_dudv"
    "$REFRACTTINTTEXTURE" "oceanic/glass/oceanic_glass_01"

    "Proxies"
    {
    "TextureScroll"
    {
    "texturescrollvar" "$bumptransform"
    "texturescrollrate" .1
    "texturescrollangle" 45
    }
    }


    "Refract_dx90"
    {
    "$refractamount" "0.100"
    }

    "Refract_DX80"
    {
    "$refractamount" ".025"
    "$REFRACTTINTTEXTURE" "oceanic/glass/oceanic_glass_01"

    "Proxies"
    {
    "TextureScroll"
    {
    "texturescrollvar" "$bumptransform"
    "texturescrollrate" 0.1
    "texturescrollangle" -90
    }
    }
    }

    "UnlitGeneric_dx8"
    {
    "$basetexture" "oceanic/glass/oceanic_glass_01"
    "Proxies"
    {
    "Sine"
    {
    "resultVar" "$alpha"
    "sineperiod" 15
    "sinemin" 0.1
    "sinemax" 0.1
    }
    }

    "UnlitGeneric_dx6"
    {
    "$basetexture" "oceanic/glass/oceanic_glass_01"
    "Proxies"
    {
    "Sine"
    {
    "resultVar" "$alpha"
    "sineperiod" 15
    "sinemin" 0.1
    "sinemax" 0.1
    }
    }
    }
    }
    }
    // BulletCrops Project
    // http://www.minerality.fr/bulletcropsproject/
     
  8. worMatty

    aa worMatty Repacking Evangelist

    Messages:
    1,072
    Positive Ratings:
    834
    How strange. I wonder if it happens on workshop maps? The submission process seems to use the same compression system, but maybe workshop map content is treated differently, and using bsp_repack on non-workshop maps might break something?
     
  9. Egan

    aa Egan

    Messages:
    1,318
    Positive Ratings:
    1,507
    I was planning to maybe submit the map to the workshop afterwards, I'll relay what happens when I do.
     
    • Thanks Thanks x 1
  10. worMatty

    aa worMatty Repacking Evangelist

    Messages:
    1,072
    Positive Ratings:
    834
    Changes!
    • Thread title changed.
    • Format of post changed to read like a comprehensive tutorial with sections.
    • Current information added, outdated information dropped.
    • Post now has images.
    I also changed the formatting a bit because the new forum software is a bit different. I love this WYSIWYG editor.
     
    • Thanks Thanks x 2