How to package a Quake map/mod

General rules and guidelines for packaging and publishing playable Quake files

This page is about how to package a Quake map / mod release.

These rules and guidelines are based on how most Quake engines work, as well as general community etiquette and consensus developed over the past few decades.

Quake was made in 1996, its core technology is over 26 years old. And like any 26 year old, it's too late to change anything bad or annoying about them. We have to figure out how to live with it.

Folder and file names

• No spaces in any folder or file names.

• All lowercase letters. (Some Quake engines + OS are case-sensitive, some aren't.)

• Avoid using numbers or punctuation at the start.

• Use common .ZIP compressed format, do not use uncommon esoteric formats like .7Z or .RAR that require special tools.

Package types

• Map package (simple): put everything in the root of the ZIP, no subfolders.

  • Good for simple single map releases / your first map.

• Mod package (complex): put everything in a mod folder, then ZIP the whole mod folder.

  • This way you can include custom assets and game code.

  • It's also common to do this for small releases too, even if they aren't full mods.

Map package (simple)

If you are only distributing map-related files (.BSP / .LIT / .MAP / .TXT) then it is OK to do the simplest packaging method:

To package a single map, place all files at the root of the ZIP file, with no folders or subfolders inside the ZIP.

📦 myzipfile.zip
     ↳ mymap.bsp
     ↳ mymap.lit
     ↳ mymap_readme.txt

A common structure where players understand they must unzip it to the correct maps folder themselves. We assume this is /Quake/id1/maps/ unless there are instructions otherwise.

Mod package (complex)

If you use custom code or assets, then package your Quake release as a mod:

To package a mod, place all files in a big "mod folder" inside the ZIP file.

However, mod folders must follow specific folder names and structure...

📦 myzipfile.zip
     ↳ 📁 mymodfolder
          ↳ 📁 gfx
               ↳ 📁 env
                    ↳ skybox_up.tga
                    ↳ (etc)
          ↳ 📁 maps
               ↳ mymap.bsp
               ↳ mymap.lit
          ↳ 📁 sound
               ↳ 📁 mymodname
                    ↳ mysound.wav
          ↳ progs.dat
          ↳ readme.txt

• Mod folder name must be all lowercase alphanumeric with no spaces.

• Map files (.BSP, .LIT) must be in a mod subfolder /maps/

  • Do not use any subfolders. Maps must stay at the root of /maps/ or else engines cannot find them.

• Skyboxes (.TGA) must be in mod subfolder /gfx/env/

  • Again, do not use any other subfolders.

• Sounds (.WAV) must go in mod subfolder /sound/

  • Additional subfolders encouraged here. Use a unique sound subfolder name to avoid file conflicts, e.g. /sound/mymodname/

• Models (.MDL) must go in subfolder /progs/

  • Additional subfolders encouraged, like with sounds.

• Game code (progs.DAT) must be in the root of the mod folder.

Some mods package everything inside a .PAK file to simplify distribution and avoid this file folder soup. A .PAK file is like a .ZIP file, Quake engines load the files inside it with folders intact. For more info on PAKs, see QuakeWiki.org: PAK.

Partial mod packages

To package a partial mod, include several mod subfolders at the root but no main mod folder.

Include clear instructions about where to unzip.

📦 myzipfile.zip
     ↳ 📁 gfx
          ↳ 📁 env
               ↳ skybox_up.tga
               ↳ (etc)
     ↳ 📁 maps
          ↳ mymap.bsp
          ↳ mymap.lit
     ↳ 📁 sound
          ↳ mysound.wav
     ↳ mymod_readme.txt

• Good for when you have only a few custom assets.

• Mostly for maps intended as add-on for a big existing mod like Arcane Dimensions.

  • It is impractical to include the entirety of the parent mod with your release. Users likely have their own existing mod install already.

  • However, it is considered very bad etiquette to overwrite the parent mod's existing files, e.g. don't include a progs.dat file.

Video tutorial

For a video intro to file structure and packaging, see David Spell's video tutorial "Quake Mapping: Release Your Map" from 4:08 onwards:

Test yourself: Quake packaging examples

Test yourself. Is this a good or bad example? Click the arrow to reveal the answer.

MyMod.zip

BAD. Filename uses uppercase letters.

mymod.zip/MyMap.bsp

BAD. Filename uses uppercase letters.

mymod.zip/mymap.bsp

OK. The filenames are all lowercase with no spaces, and the BSP file is at the root of the ZIP with no subfolders. If the author is just releasing map files and no other mod files, then this is acceptable.

mymod.zip/mymodfolder/mymap.bsp

BAD. It's a mod folder, but the BSP is not in a subfolder called /maps/.

mymod.zip/mymodfolder/maps/mymap.bsp

GOOD. All file and folder names are lowercase with no spaces, and the BSP is in a subfolder /maps/ of the mod folder /mymodfolder/.

mymod.zip/mymodfolder/maps/mymod/mymap.bsp

BAD. The BSP is in a maps subfolder called "mymod", so Quake engines will not be able to detect the map file.

mymod.zip/mymodfolder/env/skybox_up.tga

BAD. The TGA file is in /env/, but not /gfx/env/.

mymod.zip/gfx/env/skybox_up.tga

OK MAYBE. This is a partial mod approach, and it will work as long as the user knows which mod folder to unzip the files.

mymod.zip/mymodfolder/gfx/env/skybox_up.tga

GOOD. The skybox TGA is in the correct location.

mymod.zip/mymodfolder/sounds/mymod/mysound.wav

BAD. "sounds" is the incorrect folder name. It has to be in "sound". Yes, I know.

mymod.zip/mymodfolder/gfx/env/skybox_up.tga + mymod.zip/mymap.bsp

BAD. This is packaging one file in a mod folder, and packaging the map file at the root. Don't mix two different approaches.

Now what?

• We have many links to more Quake resources.

• Learn more about general Release practices.