Map Porting Guide

Got a question or a tutorial?
Post Reply
User avatar
Shadow Sheep
Posts: 568
Joined: Wed Jul 08, 2015 10:22 pm

Map Porting Guide

Post by Shadow Sheep » Sun Jul 16, 2017 5:20 pm

First words

Porting a map to Team Fortress 2 (TF2) is taking a map from an other game, and have it play and look the same in TF2. If you were to load aCounter-Strike: Source (CSS) or Counter-Strike: Global Offensive (CSGO) map file directly into TF2 and notice that there is no difference, then you would have succesfully ported the map to TF2! Sadly though, this is never the case. So you will have to modify it until the map plays as intended. Don't worry though, you don't have to remake the map from scratch. In fact, you will rarely ever spend more than 10% of the time it took the mapper to create the map in the first place. So don't ever rush it, take your time, and by all means respect what the mapper originally intended to put into his map. Don't take credit for it unless the mapper themselves invite you to. Your role is only to have their work be accessible to a wider population of players (including you!).

Before we start, I want you to get out of your mind that porting maps is hard. It is a lot less hard to learn than learning how to surf or how to bhop, or how to play an fps game in the first place. If you know how to do one of these things, then you have the correct mindset to be able to port maps. It will look new and huge to you at first, but once you will have past the learning part (which is usually the toughest part of any concept in life), you will soon find yourself more familiar withit. Don't ever give up, especialy if you are close to release a map port: if you are very excited about being able to play a map, then a lot of other players probably are as impatient as you are!

This guide consists of 5 chapters:
  • Chapter 1 teaches you how to transform a CSS map to a TF2 one. You can skip this if you already know how to decompile, compile, how the packing system works for TF2, what bsp_repack is and already have everythng setup to port maps.
  • Chapter 2 teaches you all you need to know about Hammer. You will learn how to use the software and tips that will save you hours of work. Even if you are familiar with Hammer, you should take a look to make sure you are not missing out.
  • Chapter 3 is about all the things you can have to edit in the map to make it the same in team fortress 2. Its not meant to be read all in a row, but more like informations you should know if you run into these specific cases.
  • Chapter 4 gives you tips on how to improve a map. It teaches you mapping trick as well as gameplay mechanics you should be sensible to, and which will help you to tell if changing editing something in a lever " to make it better " is a good idea or not.
  • Chapter 5 goes through all the maps I have ever worked on and points out all the mistakes I have spotted on them. This is to show that even I make mistakes, and that you should learn from the ones you do. I also put it here so you can learn from mine, and hopefully not figure them out after as long as it took me to learn from them (so basically, I am saving you 2 years of porting experience!)

For this guide, I am using windows 10 at 64bits.

Here is a list of software mentionned in this tutorial that you will probably need to download:
Important note: SPOILERS aren't things you shouldn't click on, in fact its quite the oposite. Its just the only way I know to make all the images not load all at once and have the text scroll randomly when opening the page as the images fill in the space.

Chapter 1: The process of transferring CSS/CSGO files to TF2.

The steps are: decompile the map, extract the custom content from it, edit it in hammer, compile the map, pack the necessary things into it and bsp_repack it.

Decompiling the map transforms the map file into a file format hammer can read. Compiling the map transforms the hammer file into a file format the game can read.
Extracting the custom content from the map allows you to see the textures, models, particles and sounds from the map when editing it in hammer, but also when you run test compiles.

Packing the custom content into the map is what allows the other players to see them in-game, without having to download it from an external source. This is the reason why you will probably end up with the map filesize becoming bigger in TF2: if the map uses Counter-Strike native textures, they are not packed into the map because the players can load them from their game files regardless, but not TF2 players.

bsp_repack is an console command that lets you compress the final TF2 map into a much smaller one that can still be readable by the game. It makes the file smaller to upload, download and to store on people's computers. The only problem I have with it, is that the game will hang for a moment when trying to load new sounds from the map, since they are not stored in their native format.

A bit of a setup first (skip this if you have already extracted Counter Strike files and made folders for them):

We are going to make a folder on the computer where we will store mapping related tools, as well as ressources and maps we want to port.

If you only ever plan to port maps exclusively from CSS, or exclusively from CSGO, then you can directly skip to the GCFScape part, and extract all the files directly to your /tf folder.

Okay so first if you have 20 GB free on your hard drive space and came up with a cool name for your folder, then go ahead and create it. Mine is called " Hammer Tools ", but then I stored maps and other mapping stuff so its not as relevant anymore. All that counts is that you have at most two places: the game folders and where we place the tools and porting ressources are stored. Later on this folder will be refered to as the porting folder.

The plan is to extract CSS and CSGO files to it. The reason why we don’t do it in the game folder directly is for a couple reasons (which don’t apply if you only ever plan to port maps from only one of these games).
  • The first reason is because these two games have matching file names and paths, which means that you constantly have to swtich them back and forth each time you will work on a map that is from the other game. Extracting them in folder will allow us to create batch files which should do all of that work for us very easily.
  • The second reason is for checking purpose. You will often wonder (or at least I do a lot) if a file present in a map is from a game or if it is a custom one. If you can’t find it in the folders you extracted at the correct path, then it is likely a custom file you will need to add. It is also nice to see that a file you have has been modified, and so that even if that same file already exists in the game you port, it is better to use the modified version instead.
Before doing the extraction in question, we are also going to download our first porting tool! Its happenning guys! The software is called GCFScape, and will be used to look at the content from game’s packed files, as well as map’s packed file (spoiler alert: it doesn’t work for CSGO maps, we will do something else for these). Just download GCFScape here: ... and place it in your Porting Folder you have made.

I just realised…this is a zip file. You know how to extract zip files, right? Good! I am going to explain it anyway (you thought you could speak to me? I am just pixels on a monitor, I can’t hear you). First download 7zip here: Take the one suited for your computer version then follow the install instructions. Once its done, you should have a " 7zip " option apearing when right-clicking on your zip file. Just press " extract here " and now you should have GCFScape.

Again our goal is to make our life easier. So we will create a shortcut to GCFScape directly into our porting folder so we don’t have to browse directly to it everytime we want to access it. To do this, right-click within the folder and go to new>shortcut. Click the browse button and look for GCFScape.exe in your GCFScape folder. If you cannot find it, then its not too late to consider picking a better place to put your porting folder. Once found, press okay and now you can access GCFScape without going into the folder!

I can feel your impatience: Now open GCFScape. Its empty. Just consider it as a 7zip that can only extract, but for the valve packed stuff.

If you own CSS, or CSGO, navigate to your steam\steamapps\common\gamename\gn folder (so Counter-Strike Source\cstrike or Counter-Strike Global Offensive\csgo folder).

If you do not own CSS or CSGO, you can download the pack files here: .Be thankful to TheDeathly for that one, or else you would have to pay something like $10 to get Counter-Strike: Source and $15 for Counter-Stike: Global Offensive. For CSS, you need to get the cstrike_pak_xxx.vpk files as well as the _dir one. For CSGO, you need the pak01_xxx.vpk files as well as the _dir one.

To extract them using GCFScape, you need to open the one that says _dir, which will basically tell it to also open all of the other ones with numbers. Once opened, it should look like this:
Woah, this is a lot of folders. Each one is used by the game for different purposes. But for what we do on maps, we won't need all of them. First create a folder with the name of the game you want to extract (you really want to identify to which game each of the files you extract correspond to, trust me) and go navigate into that folder. While holding CTRL, and Leftclick the folders "materials", "models", "particles", "scripts" and "sound". It should select them, and only them at the same time. Finally, and click and drag the selected files you still have in GCFScape into the folder you have just made. It will freeze, don't worry about that. Just let GCFScape realize that it has gigabytes of files to transfer (which is the reason why we do all of this by the way, we don't want to wait all the time or go through this procedure ever again!). Do this for both games and we should be ready to go. You can now close GCFScape.

Now, navigate to your Team Fortress 2\tf folder, and copy-paste the folders we have extract earlier to it. You should now have Team Fortress 2\tf\materials, Team Fortress 2\tf\models etc. If you don’t, then you have made something horrible and should find a way to undo your mess really quick before will use this a lot!).

This is where the benefits of doing this kick in. You may have noticed that windows asked us if we wanted to replace the some files when we copy-pasted the files from the second game you picked. This is because these games have matching files stored in the same place, but with not the same content in it (textures looking different, sounds being different, etc).

We are going to make scripts files which will copy-paste the matching filenames for us. That way, we don't have to look for all of them each time we want to work on a map from an other game. I use win-merge to find the matching files, and I won't teach you how to use it in this tutorial. But it allows me to check which files match, and here is the paths it has generated for me. Just use them instead:

We will create 2 .bat files. One for each case (CSS to CSGO and the other way around). Just open notepad and copy-paste the content of the link. Then replace PATH with the path to your game folder, and PBTH with the path to where you have your vpks extracted. In my case, I have my game installed at "D:\Steam\steamapps\common\Team Fortress 2\tf" and my CSS vpks at "D:\Documents\Jeux\Hammer Tools\Game vpks\Counter Strike Source". Once replaced, just save it as a .bat file. Do the same for the other game and it should be done. Then an easy way to check if they work is to go in your game folders and to play in sound\buttons the sound weapon_confirm.wav and see if it sounds the same or not. If it changes as you execute the .bat files, then it works!

While we are at it, lets create an other one which will automaticaly remove the Half-Life 2 extracted files present in our game folders. When any Source game loads, it will load the .vpks in the /hl2 folder (they all have one). Now because Team Fortress 2 also has those, if the map references a resource from HL2, the game will always find it, even if not present within the map. You might get them by extracting other maps that have included them in it. Later on, you will use automatic packing software, and they will pack these HL2 files into your maps if they find them, even if not needed. That's why this .bat file will help you remove them.

Just copy paste these, replace PATH with your path to your /tf folder and save this as a .bat file. When, later in this tutorial, I tell you to purge the hl2 files, you will now know how to do so easily!

I also use this porting folder to place and store maps I am working on. I also use them to store all the non-TF2 content I plan to pack into the maps I work on (because I feel like that's a safer way to do it than trusting the auto-pack abilites of the map packers, but we will see this later). If you want to do it like me, go ahead and create a folder called "Hammer Maps" or anything you find more appropriate. Then create a folder for each game to allow you to store maps that have the same names, but from different games. Then in each of the games, I thought it would be cleaner to create a specific " surf " and " bhop " folder, but you definitely don't have to. This is where we will create a new folder for each map we will work on.

Congratulations, I think you went through one of the most boring steps of the porting process, and it might have taken you a long time to do it. Just keep in mind that this will be worth it in the long run, and that you will not need to ever do this again (I hope)!

Decompiling (skip this step if you already own the hammer file)

Turns a .bsp file (map readable by the game) into a .vmf file (map readable and editable by hammer).

I use bspSource to decompile my maps, which you can find here: ... index.html

Edit: Rio has made an unofficial, but awesome bspsource edit, which makes the decompiler now take into account the displacements solidity, the toolsbloccklights and the ladders in maps. You probably don't know what any of these things are yet, but as far as I can tell there is no downside to it at the time of writing this, which is why I strongly recommend you use it instead for the time being before it gets integrated in the official release:

You will need to install that java thingy to make it work when double-clicking the .jar file. Once installed in your porting folder, launch it and it should look like this:
Just drag and drop your map file into the white box (ends with .bsp which stands for Binary Space Partitioning). It should show in the list. Press "Decompile" and save it somewhere. I usually leave the extra "_d" at the end as a reference for later, when/if I need to use the untouched decompiled version.The way I do this step is that in the porting folder we have, I have a Hammer maps folder with in it a folder for each game, and then one for each gamemode. In that one I create a new folder with the name of the Counter-Strike map, and store the map archive, .bsp and decompiled map there. That way, even if my steam folder dies somehow, I always have a backup of the maps and Hammer files I worked on somewhere else, ready for use.
Anyway, once you have your Hammer file (ends with .vmf which stands for Valve Map File), go to your Team Fotress 2/tf/download/maps folder, and copy paste it there. We will open it later using Hammer. But first, we need to extract the custom resources from the map.

Extracting custom content from the map.

As I mentioned earlier, maps usually have resources that TF2 doesn't have, but can read if it finds it (because the Source engine is nice like that). So you will need to extract them.

Extracting Ressources from a map using GCFScape (Counter-Strike: Source maps, skip if porting CSGO map)

If you remember what we did earlier with the game .vpk's, then you shouldn't have any trouble with this step. You open GCFScape again, then click and drag your map file into it. I'll use a very complicated map for the example, so you have a better idea of what to extract out of yours.
To make it easier for us to pack the content back into the map when we publish it later, we will extract these into a separate folder. Then all we have to do is add anything we wish to add to that folder, and we will be guaranteed to have them packed into the map! Missing textures will show as a pink and black checker pattern in-game, and no matter how good your actual work in Hammer may be, missing textures will make it look like you can't port maps, which is absolutely wrong! You are a champion!

Here are the folders you SHOULD NOT extract:
  • The lumps folder

    It contains the map data that the compiler automatically generated. Things like static lighting information, collisions, visibility areas and more, are stored in files called lumps. You don't have to know what is in there, but here is a very interesting link in case you are curious about how it works: ... ile_Format

    All you need to know is that they are the reason why your map can be understood as one by your game, and so you probably (definitely) shouldn't touch them.
  • The materials/maps folder

    These are texture infos also automatically generated by the compiler (VBSP in this case). You can't really see them in the editor because the decompiler puts them back to their original form (except when it doesn't! l'll talk about how to fix that issue in hammer when i'l write chapter 3), but it contains info about which texture uses which cubemaps (the X_Y_Z ones) and also some other displacement texture fixing (for textures not originally supposed to be turned into displacements I suppose?). Anyway, don't extract these. If you pack them into the recompiled map, cubemaps might not have matching coordinates or appear normal.
  • The mapname.ent file

    File generated on compile which is basically plain text which contains informations about the entities in your level, such as coordinates and properties. When you hear about "Stripper configs" that affect entities in a map, or software like entspy, this is basically what they can change in the map. Any further editing of things like brushes, requires level editing through Hammer. Don't extract it, unless you need to see the info contained in it.
  • The file

    This is the zip file that contains all the other elements you are also seeing in the interface, except the lumps folder and the mapname.ent file. The map file would be much bigger if it was not compressed inside that zip file.
  • The .ppl file

    surf_christmas2 was the first project I have ever seen such a file in (and only that one). I know it has something to do with props and lighting. Its generated on compile though, so don't extract this.
So you will need to extract the following folders: maps, materials (without materials/maps, and probably /tools too), models, particles, scripts and sound. Go to your porting maps folder, and in the maps section of your Team Fortress 2 director, create a folder with the name of the map you plan to publish, then within it create a folder called " extraction ". Go in it, then click and drag the folders you have selected. The result should look like this:
Extracting ressources from a map using VIDE (counter-strike: global offensive maps, or any other source game)

If your map is from Counter-Strike: Global Offensive, or another more recent BSP format, then GCFScape will not be able to detect the files. For that you will need to extract them using VIDE.

So first download and install VIDE in your porting folder from this link:

Open it, and click on the Packfile Lump editor tool.

Click Open and look for the original .bsp file you want to extract.

We will extract them to a folder we will use later, to pack the content back into the map. I recommend you have a folder dedicated to maps in your porting folder, and in it, create a folder for the map you want to port. Then in it, create a folder called "extraction", or something you will remember later.

Then in VIDE, press the "Extract" button and save the .zip file in that extraction folder. Then using 7zip, extract the zip here into the extraction folder so you have it ordered as /extraction/materials and so on. Before doing anything, go to the /materials folder and delete the /maps and any texture you think are available by default in TF2, for example textures in the /tools folder. This allows you to avoid having them added to your final map file, and to save some space.

You can then delete the zip file. In fact you probably should if you don't want to later on add it in the map by accident and have useless megabytes arbitrarily added to the map's size!
But what do these files actually do?
Now, I took this example on purpose because it has the biggest variety I know of different useful folders. You will not always have all of them. Sometimes, you will just have to extract the Materials folder. To make you feel better about what you are missing, let me do a quick tour of what these folders are actually used by the game for:
  • Maps contain files with configurations specific to this map. It can be the description of the map in the menu, the list of particle effects used in the level, the sounds the map is using instead of the default ones (useful for example to remove the fall damage noise, but will look at that in chapter 4). Files missing or with their name not matching the name of the .bsp file will not be ignored by the game.
  • Materials is used to contain…the materials! But what are they? Well, they are just small text files containing properties about textures. Wait textures! Now I see what it is. So the materials folder contain .vmt files, that are usually plain text less than a kilobyte, and .vtf files which are just basically pictures in the valve format. These can be a few megabytes, or even more if you really try. You can open and see them using VTFedit:

    So when you " apply a texture " to something, you are only applying the .vmt material file, which does contain a reference to the image of the texture (as well as things like its surface property, its scrolling animation, if it is transparent, etc. All of that is optional by the way). If you have a map with a missing texture, it can be because the game cannot load the refered .vtf file from the map file, then from the .vpk archives, then from your own game folders. But it can also be because you just don’t have the .vmt for it at these same places (stuff weirder than pink and black checkers can happen depending on how the missing .vmt was understood by the compiler).

    Here, let's have an idea of how massive .vtf files can be: The folders I showed in the screenshot is the entirety of what I have manually packed into surf_christmas2 in the final release, and its around 200MB. The size of the map with no compile is 36MB, so the resulting final map file is 236MB (without compression). The materials folder is approximately 136MB by itself. The .vmt files in it, all combined, are 100 KB and the .vtf files are 136 MB. Almost 60% of the size of the final map is just extra textures added to it. I say that because people usually think that the size of the map is proportional to how big the levels are and how complex the geometry is, which is normally a very intuitive way of thinking. The bigger a book is, the more pages it has and so the longer the story is. The bigger a video file is, the longer the video actually is. But for maps that usually are over 100MB, just consider them as books with 3 centimeter thick pages, or 16K 720fps videos!
  • Models contains all the .mdl files and their associated files, allowing you to place models in your Hammer level, often referred to as "props". They are usually used for things that are not made in Hammer, for example trees, players, weapons, etc. They cannot be edited in Hammer, but they are useful when you want to easily place repeating visual elements, animate something or save some Hammer geometry stats to ease the compiling. Missing models will show in-game as a floating "ERROR".
  • Particles contains a list of .pcf files, which have in them a list of different sprite motions and effects that can be displayed in-game. You can edit them in the particle editor which you can run by going in your steam library, right-clicking on Team Fortress 2 (you have Team Fortress 2, right?), go to properties, then in the " general " tab, click " set launch options " and type " -tools " in the box. Then when in-game go to Tools > Particle Editor and File > Open your particle.pcf file. Missing particles show as red cross in-game, or pink and black checkers if their materials have any issues.
  • Scripts will most likely contain a soundscapes_mapname.txt, which contains all the information the game needs, in order to manage specified sounds according to how soundscapes entities were configured in the map. Without it, on surf_christmas2 for example, the game would have no idea it has to play songs when you change level. It is very important that the " mapname " part matches exactly (casing ignored) the name of the map file for it to be functional. It can also contain a propdata.txt file with information related to physic props in your level.
  • -Sound contains all the sound files, usually .wav and .mp3 files. .wav are cool because they can be configured to loop automatically (with embed cue points), but .mp3 are also really nice because they take a lot less storage space. You can use Audacity ( to convert them if you feel like the format of a sound file is not appropriate to its usage in the map. It also helped me on bhop_arcane2_a06 to convert the sound files to a sampling frequency that can be played in-game.
All of these directories are implicit to the game. If you tell the game to use a sound, it will always look into the /sound folder as the parent directory. If it is a texture, it will always look for the .vmt in the materials folder. If it is a model, it will load the .mdl file from the models folder, then load its textures from the materials folder. Basically what I am trying to tell you, is that if you place the wrong type of files in the wrong folder, I think there is no way for the game to load it. This also makes it easier for you to look for things, in case you need to take a look at a specific element.

Anyway, once you have made sure to remove the /materials/maps folder from the extracted folders (as well as probably some game file duplicates in the /materials/tools) you can select all the folders, and copy paste them into your Steam\steamapps\common\Team Fortress 2\tf folder, and the content should merge with the other, already present, folders. Please be careful when moving a lot of files around, because if you place them somewhere you don't want to, its not always easy to undo compared to how long it takes you to realise.

As you port more and more maps, these folders will be filled with a lot of elements, so don't be suprised if some match the ones you have already extracted. If there is any conflict when copying, just hit "replace" for all of the matches. I used to help God Damnit Nappa with surf_twillight, which has a skybox with the same .vmt and .vtf names as surf_royal. So when 4 months later, I went ahead and did surf_royal_fix, I did not replace the match and the skybox turned night-themed instead of the sunrise one. So in case matches are different, I recommend you replace so you are sure that everything looks as intended.

Okay, so you have everything in your /tf folder. Now your game should be able to read directly from them and navigate through the folders to find all the content you need. The compiler will also be able to find them, as well as Hammer.

Do your stuff in hammer

Hammer world editor is a software you will use to edit text files representing Source levels, which the compiler will then be able to to transform into a playable level in-game. To launch Hammer, you go in Steam\steamapps\common\Team Fortress 2\bin and double click on Hammer.exe. What you actually do with it is the core of this tutorial, and will be covered in next chapters. Lets assume you are done editing the map in Hammer (its okay, carry on reading this chapter: its better to have an overview on what the process is, than to go more in-depth with the details).

Compiling the map

Woah, you already are done with editing the map? You are so fast!

To compile maps, you can press F9 in Hammer, but I don't like doing that because it occupies 100% of my processor and I can barely move the cursor on screen when doing that. Also the other alternative makes it easier to know what parameters you can play with when compiling things (they still occupy 100% of the processor, but they dynamically adjust to the part of it you are not using).

I used to always used VBCT to compile my maps, which works very well and, unlike Hammer, lets you even play the game at decent framerates while compiling maps. But in the process of writing this guide, I heard about CompilePal and gave it a try. Now I would recommend it, but only for the compiling process, and maybe to build cubemaps when you don't plan to playtest the map before releasing (when you recompile something because you realised you misspelled a timer trigger for example). I would still do the packing process " by hand ".

What is the difference between compiling in Hammer, in VBCT or in CompilePal? Nothing. They all call the 3 same compilers which are VBSP.exe, VVIS.exe and VRAD.exe, which you can find in the same folder as Hammer.exe. They are just different ways of making it easier for you to understand what you are actually doing.

Okay so once downloaded, extracted and launched, you should land on something that looks like this. It allows you to select which game to compile the map for, which influences which files the compilers will look at when doing the compile.
Select Team Fortress 2 and press "Launch".

You should land on the main compiling screen that looks like this:

On the top square, you can select the Hammer map files you want to compile. To remove a map, select it in the list and press " Remove ".

Then below you have two big tabs: "Config" and "Output".
  • Config is how you will configure the compiling (don't worry, its not hard or confusing to do at all, its just that you have a lot of flexibility over the different parameters).
  • Output is the text you will get when you compile maps. It will print each step it does, and show a 0…1...x…10 to show its progress. It will show warnings and errors if the compilers encounters issues with your level. You can submit your compile log here if you want need explanantion on the errors and what they mean: The nice thing about CompilePal is that it does that search on that site for you when you encounter errors when compiling you level, and shows the apropriate response.
Go to the config tab. On the left column are all the different compiling profiles you can use, which apply saved settings and makes it so you don't have to set everything again everytime you launch the software. The second column is which compilers/steps will be involved in the compiling. CompilePal not only lets you use the 3 compilers, but also offers extra stuff that you might need when you release a map. I don't feel like bothering you with in-depth details about what they are used for now, since this chapter is only meant to tell you how a file conversion works. If there is any specific compiling setting you need to configure later in this guide to get something to work, I will explain how, so don't worry!

By default, on the second column you will have VBSP, VVIS and VRAD enabled. That's because a normal compile goes through these three. The good thing about Compile Pal is that it explains to you what each step does when you click on the "Add" button. But I will explain what they are anyway:

VBSP is what will place everything you had in Hammer into your level, with all their settings and configurations ready to be used by the next compilers/the game itself. If you don't run it, you will not have a map file. You will notice that when opening the map using GCFScape, after running it alone, the folders we skipped the extractions of earlier made it in here already: they have been generated and configured to work with this level configuration. This compiler might, and will crash if your level exceeds the compiling limits, or if there is a leak in your level. Don't worry if it crashes by the way, its not your computer that is at issue. It's the compilers that have been designed to " brutally stop " if something is wrong. When it does, you will have to edit your level until VBSP likes it, but we will talk about that more in detail in the next chapters.

VVIS is what processes the visibility in your level. It uses subdivision of spaces in your level generated by VBSP, called " visleaf " (for visibility leaves in the visibility tree), and tries to draw rays between each cell to determine which area sees which. Then the result is stored in the map, and so whenever you are in a generated " visleaf ", you will only see the content of the other cells that have been declared visible by the VVIS compiler (Valve VISibility). Not running this compiler will result in you rendering every single existing element in your level all at once, when playing it, resulting in bad playing performance. Water will not appear either. I recommend you always run it at least in fast mode.

VRAD processes the static lighting in the level. Static light in Source (sunlight, light spots, lights, etc.) are not calculated at game runtime. Instead, the lighting values of each surface is being calculated and stored by VRAD directly into the map file, in a process known as "baking". It uses the lighting elements from VBSP and the visibility information from VVIS to do these calculations. Despite being the simplest step to explain, it's the one that most often takes the longest to process. Not running it results in every element of the map being shown at their maximum lighting value in-game, usually designated fullbright. When you want to test things that have nothing to do with lighting in the process of porting, you can skip running this compiler (unless the lack of contrast between the faces of some levels makes it unplayable for you, such as maps relying on lighting shades of flat textures).

Okay, so now that you have been introduced to each of these compilers (my pleasure!), we will get around to use them.

For the sake of this tutorial, we will create 2 new profiles instead of using the already existing one, so you get familiar with how it works. The first one allows us to compile a map within seconds or minutes in order to test the things that are put in the map. The second will be a compile with the best quality, which will run full VVIS computing and final VRAD lighting. I never compile VRAD in just Full, because Final never takes a noticeably longer amount of time to process anyway, while providing extra lighting bounces.

On the left column, click "ADD…". Call it "Fast Compile" then hit OK.

So for our fast compiling profile, we will always run VBSP (mandatory, doesn't take a long time and is the most likely of the 3 compilers to not accept compiling your level) and VVIS on fast setting. Depending on the cases, you might want some hastily generated lighting in your level. We are going to configure VVIS and VRAD for fast compiling, then you can check or uncheck VRAD if you need it.

Click on VVIS in the second column. At the bottom right, above the compile button, click the " ADD… " button. Then, doubleclick on " Fast ". Do the same for VRAD. And done!

Now let's create the other compiling profile set for final compiling (when you want to see how your map will look like at the end). Add a "Final Compile" profile on the left column, select VRAD on the second one, and above the compile button, press "ADD…" and double click "Final".
If you are having problems with VVIS taking days to compile, I recommend you take a look at this great optimizing tutorial in the wait for me to write its dedicated section in chapter 4. It will be heavily based on it anyway: ... pter=intro

Whatever you do, you always compile lighting in the map with Low Dynamic Range lighting by default. One thing you should ask yourself though before compiling the map is if you should compile it with High Dynamic Range (HDR) too or not. I used to always compile it with, since it is a graphics setting people can disable if they don't want it. But turns out that there are mappers who don't want their map to be run using HDR at all. Sometimes even, there are skyboxes that will turn Pink and Black checkers if you compile and run the map with HDR on.

So now when in doubt, I load up the original map in the original game with the console command "mat_hdr_level 2" (I'll explain how to open the console in the playtesting segment). If there is no lighting variation compared to using LDR (mat_hdr_level 0), then the map has been compiled with LDR and should not be compiled with HDR.
If the map runs HDR, then click the "Add" aoption button for VRAD and select "-both" (HDR will compile HDR alone, and its not a thing for Team fortress 2 maps).

If you are convinced that the auto-packer will be able to find all the elements needed in your map, and that there is nothing missing from it, you can go to the second column, click " ADD… " and select " COPY ", " NAV ", " CUBEMAPS ", " PACK " and " REPACK ". If you run all of these steps, then you can skip directly to the last section of this chapter, which is dedicated to uploading your map (assuming you tested it properly first). I never run them because I always keep all the custom elements I want to pack in a separate folder, some of them are not even in my game folders. So having these elements show in-game only after packing is one way for me to make sure that it is indeed in the map file, and not just my game picking it from my computer. I won’t force you do prefer doing something just because it is my own habbit.

Anyway, if you didn't skip to the last section yet, after remembering to select your map in the top section, press the compile button. Don't worry if 100% of your processor is used in the process, unless you know that your computer has some overheating issues. Once done, you are ready to playtest your level in-game.

Note: Using the " COPY " step will duplicate your map to /tf/maps, and ususally your maps are in /tf/download/maps. This is result in the game always loading /tf/maps first, and so if you do any modification to the one in the download folder, you will not get to see it in game. If you start noticing nothing of what you do in Hammer applies in-game, please make sure that a duplicated version isn't in /tf/maps before panicking!

Playtesting your level in-game locally on your computer

This is the part where you get to play your level in-game, and check if everything works the way you want it to. It is very important that you make sure that your level plays as close as possible to the intended way of playing it in the game(s) the map was made for. You will load levels using the console by typing "map mapname". However, you do not have default access to that console when booting up the game, nor do you have it when not having a key bound for it/enabled in the settings in the first place. So let's fix that!
When in the main menu, click the " Options " button at the bottom. Then in " Advanced… ", check the " Enable developer console ". Then scroll near the bottom of the Keyboard list, and assign a key to " Toggle developer console ". Now you should be able to bring it up when playing on a server…but what if you want to have it right away when loading the game?
When in the Steam game library, right-click on Team Fortress 2 in the list, select " Properties ", then in the " General " tab, click on " Set Launch Options… ". I think a box pops up the first time, saying that you should probably know what you are doing before touching this kind of stuff. Skip it and then in the box type " -console ". Now you should have a console available when loading the game.

So like I said, type " map mapname " in the console to load the map (it will disconnect you from any game you were playing to load the map offline on your computer). If you are porting a CSS map, you can also directly put it into your /tf/download/maps folder and load it from there in TF2, which is very usefull when you need to see how things originally were in the map, but also to measure the need of editing the map file in the first place. When testing a map, try to play it in different ways and make sure that it works correctly in each of them. Pay attention to details. You can also look for issues you have noticed in other ports and make sure you don't replicate the ones I have done in my previous ports so you can gain from my experience using chapter 5.

Getting surfing settings offline

To test offline surf maps, you can do so by first connecting to a server running surf settings, then typing the map command in console. The map you will run will have the same settings as the map you connected to.

You can also insert "sv_airaccelerate 150" or whatever value in your game launching options, and these will apply when you load a map offline.

You will not have the ability to bunnyhop though. If a map requires bunnyhopping, or you want to test how it plays using bunnyhops, then you will quickly get stuck without the plugin.

To be able to bhop offline, you will need to install Metamod: Source and Sourcemod, then put the bhop plugin in your game files while running the game with the " -insecure " launch option.

First, go to and download the latest Metamod: Source version for your computer. Metamod: Source is what will allow you to install different mods, such as Sourcemod. Once downloaded, open the zip file using 7z, and extract it to your game folder, in this case the steam/steamapps/common/Team Fortress 2/tf folder. It should create an " addons " folder if you don't have one (which is likely actually). Done! You have installed Metamod!

Sourcemod installation is very similar: download the latest version at and extract to your Team Fortress 2/tf folder. Sourcemod is the mod which will allow you to run an offline server using various stock plugins commonly used by servers, as well as some extract console commands (yes! You can now change the sv_airaccelerate value at will!).

Then, download and install this bhop plugin.

To install it, copy paste the tf2t.swx file in your common/Team Fortress 2/tf/addons/sourcemod/plugins folder.

It will get loaded when you boot up the game. If you press W at more than 100% speed when landing, you will transfer your horizontal velocity into vertical velocity. To disable this effect, just type tf2t_highjump 0 in console.

Warning: this bhop plugin makes you jump 4 units lower than you do in Counter-Strike, making some bhop maps impossible to test accurately offline. For these maps, you will need to upload the map to Deathly's test server in order to test the gameplay..

Don't forget the -insecure command in the game launching options. It's the same process as for the -console one, except here you just type space, then -insecure. The result should be " -console -insecure ".

Some useful commands:
  • sm_cvar sv_airaccelerate #: allows you to change the airacceleration of the server (default 10, surf 150, bhop 1000)
  • sm_cvar sv_maxvelocity #: allows you to change the maximum velocity setting at which you can go (default 3500).
  • sv_cheats 1: turns on cheats which allows you to use some extra commands considered as cheats
  • noclip: lets you fly in the map like you would when spectating
  • getpos: give the commands allowing you to set your position and angle to where you are. You can bind the output to a key and use it to teleport there.
  • buddha: cancels any received source of damage that could kill you
  • mp_waitingforplayers_cancel 1: skips the " waiting for players " timer at the start of each round.
Thats all I can think of for now other commands are more situational, and some of them will be mentionned later in this guide. You can set them to be loaded each time you load a map by opening /common/Team Fortress 2/tf/addons/cfg/sourcemod/sourcemod.cfg in notepad, and adding these commands at the end of it, skipping a line between them.

Packing required content into a map

You are happy with the result of your port, or just want to share the level with other people? Well you will need to insert the non-native content into map file so people can load them, in case they don't have them in their game folders (they usually don't have them!).

Whatever you do, keep in mind that you should only pack map files once. If you realised you forgot to put something in it after packing it, you will need to load a backup (or recompile if you don't have one) and pack it again, or else the map file will most likely get corrupted (trust me: you really don't want that to happen!). VIDE makes a .backup file and Pakrat a .bak file after packing. Removing these extensions from them will get you with the map file at the state it was before the packing process.

The way I do it, is what I think is the safest way to ensure you don't forget anything. I use the auto-packing feature of VIDE, extracting the result using GCFScape into the extraction folder I have made for the map when first extracting it. Then I remove the packed map and replace it with the backup VIDE made. Then I load pakrat, select the extraction folder in it and it automatically puts everything into the map. I do some small adjustements to the files names, and run a last pakrat scan to make sure nothing is forgotten. If it still finds things, I browse my game folders and copy paste them into their appropriate location in the extraction folders so they don't get forgotten next time. Once it's done, I save the map and it should be done. If, when people test it, there is still missing stuff, I add it to the extraction folder as well to make it easier to pack for next version of the map.

Note: I only do the VIDE part of the packing process once per map project. I never use it again after the first time I pack maps.

Download VIDE here if you happen not to have used it when extrating CSGO map content:

This is the moment where you are supposed to run the .bat file to remove the HL2 files from your folders, or else they will get re-added back to the map even though they shouldn't be, and it will waste some space.

Once extracted into your porting folder, launch it and select the "Packfile Lump Editor" (the last one on the right).

Then, its simple: press "Open" and look for your freshly compiled map file. Press the "Scan" button and set a path to browse (so here, your /tf folder). Press "Scan" again and wait. Once done, press "Auto", then "Apply." Finally, press "Save" and you should have a packed map. If you estimate that everything is packed in your map after this step, then you should probably have used CompilePal to do that in the first place, because it would have saved you this effort. In fact now that I think of it, you could have used it to get to this step…oh well thats okay, at least you get to know how to do it using this tool!

Alright, so, open your newly packed map using GCFScape, and extract it like we did the first time in the extraction folder, no /maps/graphs or /materials/maps folder. If it asks you if you want to replace something, say no, just in case you are replacing the original files you got from the map in the first place. You can now close GCFScape.
Delete your packed map file, we will make an other one using pakrat. Navigate to the folder that had your map: there you should find a mapname.bsp.backup lying around. It's the backup VIDE made when packing your map. Just edit its name, and remove the .backup at the end, and you should be back with your original map file that you had before packing.

Now download and install pakrat in your porting folder: ...

Download this to run it if you haven’t already: ... index.html

Then run it. You should land on a page asking for what map you need to pack, just navigate to the folder that has it, then select it.
Then press the Add button, select your extraction folder and press ok. Tadaa! All your carefully placed files are now ready to be packed (press "Yes to All" if a box pops-up).

Well almost actually. The script files and particles usually need their paths edited (pakrat is a bit old and doesn't fix their paths automaticaly). Click on the "path" column once or twice (depending on where you want these to appear), and at the top or bottom you should be able to see them. For each of them, select them and press "Edit" and in the path, either remove everything but past the last "/". If the field is blank, then try to guess in which folder it is supposed to go (you probably need to scroll past all the files with an empty path to find them). If its a .pcf file, then the path most likely is /particles, but check the mapname_particles.txt file in the /maps folder just in case it is loaded from a subfolder in it. If it is a soundscapes_mapname.txt file, then it goes in /scripts.

Also make sure the map specific scripting files have their names matching the maps. For example, I never release a map right away, I always make a mapname_test1.bsp, in case something is wrong with it. So I need to go ahead and change all the scripting files from mapname to mapname_test1 too, in order to make them work with this version. I don't have to do that for the final release though. Anyway, the edit button allows you to change the name of the file you put in it too, so you change them there. When later in the guide I say that a file has to have its name matching the maps to work, then it means you will need to make sure it does at this step of the port, to make it work.

Last step (and this is why we used VIDE before in addition) is to use pakrat's file finding feature and look for content that is still missing. Using both programs and keeping every extracted file from the map, should provide you with 3 levels of safety, ensuring everything required is in the map. Press the "Scan" button (unlike the auto one, Scan lets you decide which files to add). In the box at the top, put the path to your /tf folder, then press "Scan". Then, when it's done, press "Add Selected".

It will bring up a dialog for each file. If you think the file should be added, press Yes. If you think the file is not needed or already packed in (its the case for example for material files directly placed into the /materials folder instead of a sub-folder), then press the " Skip " button. That file will not be packed. The last file usually is maps/graphs/mapname.ain (I don't know what it does actually, but I put it in regardless), so if it's the only file it asks you to add, then it means that pakrat didn't find anything else to add to the map.

Even after that, it sometimes misses some textures. I recommend you double check if each of the /materials/sprites and /materials/decals materials and textures used in your map (do that using Hammer) are included in your map file, since they are known to not be registered properly by the map packers.

When you think you have everything, press save and confirm the map file replacement.
Congratulations, you have packed your map, and it is ready to be played by anyone who owns TF2!

Making the map lighter

The TF2 community has made a program that allows the map file to be compressed and so save a lot of space on peoples computer. For example, surf_christmas2.bsp uncompressed is 240MB, but onces processed through bsp_repack, it becomes 115MB.

All you have to do is in-game to type bsp_repack path_to_the_map path_to_save and let it process as you play your favourite map with your favourite friends! So here for example, I would have typed:

bsp_repack download/maps/surf_christmas2.bsp download/maps/surf_christmas2.bsp

If you have selected the option for it in CompilePal, then this step is done automatically for you.

Now you should be ready to upload the map.

Uploading the map and playing it on Deathly’s test server

Teaching how to use an uploader isn’t really the goal of this section: you just click and drag your file in and let it upload.

TheDeathly has a test server hosted in USA we can use to playtest maps, and it also has the bhop plugin set to Counter-Strike jumping height, which allows you to test these maps there if you need to (for example, I wouldn't have been able to prove bhop_aux_a9 or bhop_alvo were possible without it). You can also setup and run the Resurfed timer on it, which is a good way to make sure that they actually work before releasing your map.
  1. Go to and follow the instructions to create an account
  2. Then make a discord account, and join the resurfed discord:
  3. Then get into contact with TheDeathly so he can activate your test server account.
  4. Then log into your newly made account, click and drag the map files you want to upload, make sure you select both the fastdl server and the normal one, or else people won't be able to play it, then hit upload. You can then give the link to ... s2.bsp.bz2 and people will be able to download the map file on their computer (they will have to extract the .bz2 for it to work though, but 7zip does that very well). You can also go play it by adding the ip to your favourites and using the " stigsucks " password when connecting to it. Once there, type !map mapname to play the map you want. You can also have rcon access to it using, in case a badly uploaded map gets the server stuck for example. You can find all the uploaded maps at
When you are sure that the map is good to go, then you can release it. For example you can make a forum post here in map release to talk about it.

To conclude

Alright, this is the end of chapter 1. Now you should know how to:
  • Decompile a map
  • Extract custom content from it
  • Load it in hammer to do modifications
  • Compile the map
  • Playtest the map using surf and bhop settings
  • Pack the custom content back into the map
  • Compress the map
  • Upload the map

Chapter2 Tour and configure hammer + tips to save hours of work

In this chapter, you will learn how to open, configure and use hammer. It will look complicated at first, like anything you get familiar with at first. It is normal. That is because you will not be aware of all the different things hammer can allow you to do, so each time you will learn something new, you will most likely not see it coming, which can make it disorienting. They are too many to list, and even with my experience, I still probably know a low percentile of them.

Instead, what this chapter will teach you is the different kind of things hammer can do, and there are a lot less of them (10 at most). This will also allow you to mentally insert the various things you learn into these categories, and so make it easier for you to have a global vision of the tool. If you are already familiar with hammer, then I would advise you only take a look at the "Using hammer efficiently" section of this chapter in order to make sure you don't waste precious time doing tedious unnecessary manipulations.

  • Opening Hammer
    First of all, in case you were not listenning in chapter 1 (I mean, I too would get discouraged if I had to read a book in the form of a roll of toilet paper to be honest), if you own Team Fortress2, you own hammer. It is one of the various programs that is included with the installation of TF2. Just navigate in your steam folder, and go to steamapps>common>Team Fortress 2>bin. There should be a program called hammer.exe in this folder, just double click on it, and lets get started!

    (In action, this is how you reach it:)
    If you are like me and do not want to navigate 30 seconds in your folders every time you need to launch this software, I recommend you create a shortcut to it and place it somewhere more convenient ( I have made a folder dedicated to hammer tools where I have shortcuts to all the softwares I use when working on maps).

    It should look like this:
    So basicaly, a empty screen with icons everywhere around it that you will most likely forget about when you will be too focus on what you are doing. There is also a console that you will probably never use, and that basicaly says it loaded ressources like textures and stuff from different folders, and that will tell you when its loading maps and stuff.
  • Configure hammer for easier use
    Now, I know you are very excited and all, but before we can have fun with maps, lets do a little bit of configuration in order to make your lives easier. Of course, all of what is going to follow is only an advice,and you are free to do what you want.

    At the top, you will see a tab that says "Tools". Click on it and then click on "Options...". A window should pop up with various tabs, we wont be looking at all of them right now, but there are a few ones I want to make sure you take a look at before we start.

    Go to the General tab: we will change a couple settings that will save your lives! First, make sure the autosave is enabled,and set it to not more than 15 minutes. This will allow you to go back in the past if you have regrets, and in case something more sinister happens to hammer's execution, at least you will not lose all your progress if you forgot to save. Make sure you also increase the amount of undo you can do so you can go back very far in the past if you need to and dont get stuck in the present (I have mine set to 1000000!).

    Now go to the 3D views tab, and put the settings in the Performance region to maximum (if you can run TF2, then you probably can afford to do that).

    Then take a look at the Materials tab. There is nothing to touch, but I just want to point out that if you see a texture used in hammer that is under one of the folders listed in the "Material directory exclusion list", it will say that it is missing even though its not. Thats the only case where you don't have to worry if a texture is missing in hammer, but not in-game. Not all the games block them, for example, hammer for Counter Strike Source doesn't block them.

    You can hit "Ok" and exit the options menu.

    Now, lets get familiar with the editor! Go to the file menu at the top, and click new to create a new project.
  • The views and what they are for
    You should now see 4 grids appearing. The top left one is called a 3D view, in which you can navigate and fly in space like you would when spectating in-game. The 3 other ones are 2D views with grids. You will rarely focus on all the 4 views at once, but they are helpful to give you an accurate representation of what you are actually creating and how things are disposed. If you take a look at the top left corner of each view though, you can see that you can change what they represent as you want. So for example you can have a 3Dview that is showing the world in wireframe, and an other 3D view that shows it textured normally (I am just making this up by the way, I don't know any situation when I thought doing this was useful).

    In the 3D view, you can navigate by moving your cursor on it, then pressing z. Once in it, you can move your mouse around, and press w a s and d to travel. Feel free to go in the 3D views options of Tools>Options... to adjust the sensitivity and speed as you want.

    In the 2D views, well there us not much to say. It will be vey confusing, because when you see several things on top of each other you don't understand what is going on and the only kind of depth perception you have is horizontal and vertical. This is the reason why you have 3 of them: each shows a different perspective of your level, which helps knowing where things are in relation to each other. You can use your mouse scroll wheel in order to zoom in and out. If you zoom all the way out, you will see that the grid stops at some point. Something you need to keep in mind is that all of your map must fit inside this grid in order to be run in-game.
    If you hold the space button and hold and drag the mouse, you can move the view to the sides. I never do that though, because I already had the habit of scrolling out, then in where I want to move around before hearing about that feature. But I figured I might as well let you know in case you find it useful.

    Lets learn the use of our first little tiny icon! If you look at the 3rd and 4th icon below the File etc tab, you will see a grid symbol with +, and one with -. These change the size of the gap between each line in the 2D grids by either multiplying or dividing it by 2(goes from 1 to 512). The unit used to measure the distances in hammer is called... hammer unit! Isn't life simple? But we will just call them units from now on.
  • Different tools of Hammer and their usage

    What I call a tool is one of the modes you can use in order to interact with what you see on the 2D grid, the 3D grid or both. They are represented by the little icons on the left side, and each of them has a different usage. However, its not because they are different that it means that they are all as useful. So I am just going to go through the ones that are the most useful. Some of the tools are only useful in the context of the other ones, so this is why I am going to review them in my own order.

    -Block Tool: ... Block_Tool
    -Entity Tool: ... ntity_Tool
    -Selection Tool: ... ction_Tool
    -Vertex Tool: ... ertex_Tool
    -Texture application Tool: ... dit_Dialog
    -Cutting Tool: ... pping_Tool
    -Decal and Overlay Tools: ... Decal_Tool ... erlay_Tool
  • Time saving functonalities
    • Options you might want to change
    • Hot keys
    • Vertex tool to resize more things at once
    • Visgroups
    • Quickhiding things
    • Entity Report
    • Replace Textures
  • List of common entity types you will encounter and what they usually are for
Chapter3 The things that should be edited/fixed when porting maps

-Coming Less Soon-

Chapter4 Mapping + gameplay knowledge to try and make the map you work on even better

-Coming even later-

Chapter5 Mistakes I have made in the maps I have worked on

-Hopefully I'll be alive when I reach this part-
Last edited by Shadow Sheep on Tue Oct 08, 2019 1:12 pm, edited 7 times in total.
User avatar
Posts: 25
Joined: Wed Jan 27, 2016 11:47 pm

Re: Map Porting Guide

Post by Fury » Wed Jul 26, 2017 11:24 am

:lol: :D :) ;) :( :o :shock: :? 8-) :x :P :oops: :cry: :evil: :twisted: :roll: :!: :?: :idea: :arrow: :ugeek: :geek: :mrgreen: :|
Post Reply