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.

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.

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...

• 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/

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 .

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.

• 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.

Video tutorial

For a video intro to file structure and packaging, see David Spell's video tutorial 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.

Now what?

• We have many links to more .

• Learn more about general practices.

Get the Quake Level Design Starter Kit

Download the Quake Level Design Starter Kit (Windows and Linux only) by Jonathan Linat, which contains a lot of recommended tools and assets for single player Quake 1 mapping, all collected in one convenient bundle. This is the easiest way to get started.

Communities

If you're interested in Quake mapping and modding, we strongly recommend joining a Quake community. It's the best way to learn! Experienced people can give you tech help, advice, and feedback on your work. Some have even been modding Quake for 20+ years.

• is the biggest public social hub, beginner-friendly with frequent single player design jams and social opportunities

  • For Quake 2, try instead.

  • For multiplayer Quake, try and instead.

Mapping

How to make Quake maps

• get TrenchBroom level editor (included in Level Design Starter Kit linked above)

for useful map measurements and combat stats + design advice, see

for more about releasing maps and mods, see .

Recommended reading

After you know the basics of map construction and feel somewhat comfortable in the editor, learn about more complex design and building patterns:

• (2001) on Quake architecture by Xenon

• (200x) on building "CZG curves" by Christian Grawert

  • + by David Spell

for more on Quake's influence on level design, see

Compiling Quake maps

To play Quake maps, you must compile (bake, package) the editable .MAP into a playable optimized .BSP file. You will need both tools and a graphical user interface (GUI).

• Compile tools: (already included in Quake Level Design Starter Kit)

  • qbsp.exe builds 3D mesh + detects "leaks" ()

  • vis.exe calculates to optimize map performance

Example map source files

• many mods package .MAP source files with the public release, just look in the mod folder

• trenchbroom_quake_map_source.zip is a collection of the original Quake 1 .MAP source files () but converted to modern file format (TrenchBroom compatible) + fixed texture references (with repackaged Quake101.wad), thanks to Atul "toolness" Varma

for more about parsing and working with .MAP files in code, see

Engines / source ports

To play Quake (and playtest your own maps or mods) you need a source port -- a Quake engine that "ports" the original 1996 engine code and add many new features / compatibility.

We only list free open source ports in active ongoing development. ()

Assets / textures

In Quake modding culture, it is generally considered normal and acceptable to rip models, sounds, and textures from other maps and mods, as long as you credit the original authors.

However, if you rip textures and assets from a .BSP, you'll usually have an incomplete fraction of the full kit. It'll likely be difficult to use. In these cases (e.g. the Makkon set) you're better off finding the full official public texture releases.

Texture WADs

Quake texture collections are stored in .WAD files. To use textures in a level, download a .WAD and then add the WAD path to the .MAP file using the level editor. (Note: this is not the same as a Doom WAD. Quake WADs are only for map textures.)

When compiling a map into a playable .BSP file, all used textures are automatically embedded directly inside the .WAD file. You can rip textures from compiled maps using a tool like .

• by Khreathor is useful for blockout and prototyping.

• contains all the Quake textures in one collection, or you can just download if you want to stay strictly within a traditional theme.

• is a medieval library themed texture set by Kell

Texture WAD archives

• contains many .WADs but it's somewhat unorganized.

• has a similar pile of unorganized WAD files

• has a small but growing archive of better organized WAD files

WAD Tools

• The most common WAD creating / editing tools are and , which can browse WADs and convert textures for you easily.

• If you are going to modify WADs frequently, you can automate the WAD building process via batch processing via command line interface (CLI) with .

• Use TexMex or to extract textures from a compiled .BSP map file

Skyboxes

Quake has two different sky systems. The original 1996 sky system is a two panel texture parallaxed over itself. Newer Quake engines support a more standard cubemap-style skybox made of 6 static .TGA textures, each corresponding to one side of the skybox.

Mods / dev kits

Mods add new functionality and features for mappers to use in their levels. Listed below are common Quake mods and toolkits used by single player Quake mappers.

Arcane Dimensions

is a popular recent mod / toolkit that adds many new monsters and features.

1. install the latest version of Arcane Dimensions ( as of January 2022) if you want to make your own mod based on AD, get the slimmed-down dev kit instead

2. add the /ad/ mod folder and ad_1_8.fgd in your map editor

3. read the included ad_v1_80_documentation.txt for info and advice

Alkaline

is a recent "base" themed mod / toolkit that adds sci-fi themed monsters and weapons.

1. install (minimal dev kit available)

2. add the /alkaline/ mod folder and alkaline.fgd in your map editor

3. read the included docs.html Alkaline mapping manual

Copper

is a minimalist "refinement" mod that rebalances vanilla Quake gameplay and adds quality-of-life features for mappers. It is good for a "vanilla+" feel without vanilla bugs.

1. install

2. add the /copper/ mod folder and copper.fgd in your map editor

3. read the for info and advice

Progs_dump

is a recent dev kit mod that adds new mapper features, but doesn't add any new monsters or weapons, it's still basically the same old vanilla Quake gameplay.

However, because it exposes so much functionality, it's possible for mappers to add some new game features without coding in QuakeC.

Horde mode (2021 re-release)

To map for the new "Horde" mode added in the Quake 2021 re-release:

1. download the special Horde mode .FGD file and load it into your map editor

2. in the editor, add a single horde_manager entity, this is the brain of horde mode

3. in the editor, add info_monster_start entities for where you want monsters to show up. You can also toggle a info_monster_start, which lets you do progression stuff.

See the example Horde mode .MAP source file for usage:

Modeling

for a list of 3D art tools, see

To make custom monsters, weapons, items, or props, you must export a 3D model.

The original Quake models are stored in .MDL files in a sub-folder called /progs/ . The MDL format reflects the memory limits of 1996 PCs:

• Max triangles: 2048; max vertices: 1024

• Textures: 8-bit palettized; max UVs: 1024

• Max vertex animation frames: 256 at 10 FPS

for more info on MDL file format and parsing, see

The 2021 re-release, as well as more recent fan engines, have added much more modern file support with much higher memory limits and skeletal animation support.

• Model data stored in .md5mesh file

• Animations stored in .md5anim file; can load multiple .md5anim files for one model

• Textures are .tga, bind with .mtr material definition file

Quake MDL

Get the by Taniwha, Khreathor, and Jazzmickle.

• see docs for , , , and

• by Fairweather

Fairweather has made some great beginner video tutorials on using Blender to model for Quake, no prior Blender or 3D experience required:

Quake MD5

Get the by KozGit.

• read the documentation thoroughly, it's a little complicated

• community is still figuring out best practices / pipeline... ask questions and shares notes in QM Discord #modeling-and-texturing

Coding

Quake game code is written in a special programming language called QuakeC. It has many historical quirks and it can be tricky to learn, but once you figure it out, it's fun.

QuakeC tutorials and documentation

Example QuakeC projects

• "clean and fixed" original Quake v1.06 source code with bug fixes:

  • useful as a base for a vanilla style mod

• progs_dump mapping toolkit source code:

QuakeC tools

There's a by Joshua Skelton.

FTEQCC is probably the most modern compiler available, with plenty of compilation options and enhancements. You can choose between GUI version and a command line version: