Introduction #

This guide gives an overview of all the steps required to officially port a map to Momentum Mod.
The goal of porting is two-fold:

• Ensuring the map functions correctly
• Conforming to a high standard of competitive integrity

Maps should not be significantly modified.
It’s very important to respect the spirit and intent of the map’s design.

You are free to port any publicly available map with some exceptions:

• Mappers can reserve/block porting of their maps using this form
• Before porting make sure the map isn’t on this spreadsheet
• You are not free to port maps created only for specific servers without explicit permission
• When in doubt, contact the mapper ( please don’t spam them )

Why aren't ports opt-in?

Due to a sheer amount of maps and how old some of them are, it’s not feasible to reach out to every single mapper for their permission.
This makes it especially important not to modify existing ports too drastically - respect the original mapper’s intentions!

If mappers are active (usually on Steam/Discord) we encourage you to reach out to them.

If a map gets ported that the original mapper is unhappy with, we’ll try find a resolution that doesn’t require resetting leaderboards, but ultimately if they want it removed that’s up to them. (If this is the case for your map, please reach out on our Discord)

Setup #

If you have any questions feel free to ask for help in #map-porting channel on our Discord!

Porting for gldsrc gamemodes (Conc, HL1Bhop, 1.6KZ) as well as Defrag is way more complicated and requires a different approach.
Please follow the gldsrc porting guide and the Quake 3 porting guide.

Tools #

Lumper - General porting toolkit. Only use for steps in the guide unless you know what you’re doing.
Entity Tools - In-game tools automating a lot of porting steps. Usage will be covered later in the guide. These are always preferred over Lumper.

Preparing the game for porting #

1. Download Lumper
2. Download the map you want to port (maps in .bz2 format can be extracted using 7zip):
   • fastdl.me - Contains a huge collection of Surf, Bhop, and KZ maps
   • gamebana.com - General modding forum. Often contains information required for submission such as credits, description, and release date
   • ksf.surf (preferred for Surf) - Main hub for competitive surf
   • jump.tf (preferred for RJ/SJ) - Main RJ/SJ forum
   • femboy.kz - CS:GO KZ maps
3. Rename the map
   • Some map names include version info like _a13, _b2, _njv etc. Rename the .bsp file to remove it
   • RJ/SJ maps use jump_ prefix. This should be changed to rj_ or sj_ depending on for which gamemode the map was originally made
4. Put the map (.bsp) in /momentum/maps folder
   • You can access it by right clicking Momentum Mod in your steam library and selecting Manage → Browse local files
5. Open the map using Lumper
6. Open the map in Momentum Mod by opening the console (~ by default, key below ESC) and typing map <map name>
7. Open the console again and enable cheats (sv_cheats 1) as well as Lumper synchronization (mom_lumper_sync 1)
8. Click the Connect to Game Sync button in Lumper

Porting #

Step 1: Remove Valve Assets #

Maps may include packed materials, models, and other asset ( similar to a .zip file).
Momentum Mod cannot legally redistribute Valve’s assets.
Valve’s assets may still be used on maps however it is necessary to remove them from the .bsp.

1. Go to the Jobs tab in Lumper
2. Add Remove Game Assets job
3. Run the job

Won't removing assets make the map look worse?

Momentum Mod automatically mounts assets from CS:S, CS:GO, TF2 and Portal 2 so players with those games installed will still be able to see them even after removal.
Use the Texture Browser in Lumper to see which game each texture comes from.
For other assets check the Required Games tab.

A small amount of assets from Source games other than CS:S, CS:GO, TF2 and Portal 2 can remain packed.
That can be done only if they are relatively generic and not fundamental to that game’s aesthetic.
When keeping Valve assets packed, it is required that you list them in the porting changelog during Map Submission.

Step 2: Modify Remaining Assets and Fix Cubemaps #

Textures #

1. Go to the Texture Browser and Right Click → Remove any explicit material or obvious copyrighted assets you may find
2. Consider resizing/reencoding any assets that take a lot of space (marked by yellow/red)
   • If the texture is at or above 2048x2048 it consider resizing it down a level
   • If the texture uses an uncompressed format consider reencoding it

What are the compressed formats and which ones do I use?

Compressed formats are DXT1, DXT5, and BC7.
When reencoding, if a texture has no alpha and is relatively flat with little detail, use DXT1.
For more detailed textures (e.g. containing text), use BC7.
Do NOT resize or reencode any animated textures or textures with multiple faces.
Please verify in the game that modified textures are not broken and still look good.

This should be evaluated on a case-by-case basis.
It’s perfectly fine to leave big assets unchanged, this step is not strictly enforced.
If you are not sure whether you should resize/reencode them, it’s better to leave then unmodified.

Sounds #

Music in Momentum Mod need to be categorized properly for volume sliders to work.

1. Go to the Pakfile Explorer in Lumper
2. Scroll to the bottom to see if /sound folder exists
3. If it does, listen to every sound to identify music files
   • You can use Open in External Program button or Right Click → Export the entire folder to listen to the sounds
4. Remove all copyrighted music
   • Right Click → Delete
5. Move remaining music files into the /music folder
   • Right click on /sound → Create Directory -> music, then drag and drop sounds into it. Click yes on the pop-up

Cubemaps #

If you renamed the map during the setup, reflections might be broken.
You can skip this step if you didn’t rename the map.

1. Go to the Pakfile Explorer in Lumper
2. Check if the map has /materials/maps/<old_map_name> folder
3. If it does Right Click → Rename that folder to the new map name. Click yes on the pop-up

Step 3: Fix Entities #

1. Go to the Entity Review tab in Lumper
2. Remove all invalid entities
   • Clicking the edit button on the right will bring you to Entity Editor. You can delete entities there by clicking the trash icon
3. Fix other entities by following the Entities Guide and comments in Lumper

Step 4: Compress the Map #

Compression will significantly reduce the filesize.

1. Check Save Compressed
2. Check Update filename-specific Content
3. Click Save

You should double check that your port has no remaining issues with the Map Summary tool.
You can find it in Tools -> Map Summary or by using the CTRL + H shortcut.

Step 5: Take Screenshots #

1. Fly around the map in noclip (g by default, noclip in console) to find good spots to screenshot
   • You can use maximum of 5 screenshots, 1 for the thumbnail, 4 for the gallery
2. Use mom_official_screenshot in console to take screenshots. This command will automatically apply all relevant settings.
   • Screenshots will be saved to /momentum/screenshots
   • You can bind the screenshot command to a key for ease of use in keybind settings or with console by typing bind <key> mom_official_screenshot

mom_official_screenshot among other things will set your brightness to 1 ( default ).
Maps should not require changing the brightness to be playable.
If you’re porting your own map, please make sure it’s properly lit.

Some mappers provide their own screenshots on gamebanana (Surf, Bhop, KZ) or jump.tf (RJ/SJ).
While you may not use those screenshots directly, feel free to recreate them using the steps above.

Step 6: Zone the Map #

Follow the Zoning Guide.
It will teach you how to add the Start and Endzone, Bonuses, Stages, and Checkpoints!

Step 7: Submit the Map #

You have successfully ported the map!
All that’s left to do is Submit the Files and all relevant information.
Follow the Map Submission Guide!