From Custom Map Makers Wiki
Jump to: navigation, search
Roadworks.png This page is work in progress!

Official Support Forum @Splashdamage

The latest version is Q3Map2_2.5.16

Q3Map2 is a BSP compiler for games based on the Quake III Arena engine. It compiles .map files, which are editable with an editor, into .bsp files, which are understandable for the game and not editable. It currently supports the following platforms:

  • ioUrban Terror
  • Nexuiz
  • Open Arena
  • Quake 3 Arena/Team Arena
  • Return to Castle Wolfenstien
  • Soldier of Fortune II
  • Star Trek Elite Force
  • Star Wars Jedi Knight: Jedi Academy
  • Star Wars Jedi Knight II: Jedi Outcast
  • Tenebrae (Quake1 Engine Modification Project)
  • Tremulous
  • War§ow
  • Wolfenstein: Enemy Territory
  • World of Padman

note: Future support for Call of Duty is a possibility.

Q3Map2 was designed to replace the Q3Map.exe that comes with QERadiant, GtkRadiant and GMAX Tempest. However, there are significant enhancements that require a little twiddling to use, such as faster lighting and enhanced surface production.


Q3Map2 is a command-line utility. In general, users make use of Q3Map2 in one of three ways:

It should be noted that the default command lines given in the GtkRadiant bsp menu are by no means a complete showcase of the available Q3Map2 options and switches. You may edit the bsp menu command lines from the GtkRadiant preferences, but for total control of your Q3Map2 compile writing a batch file or using one of the front ends is probably a better idea.

Q3Map2 command lines generally follow the format:

"C:\path\to\Q3Map2.exe" [<general option>] [<major switch> [<minor switch> <minor switch>...]] "C:\path\to\maps\"


General options

-connect <hostname/ip address>
  • Enables output of Q3Map2 logging to a remote host. This switch allows all other (non-solitary) switches.
  • Analyzes a compiled bsp and outputs information to the screen or log. This switch is solitary, and allows for only the path to a compiled bsp (not .map, it should be noted) afterward.
-game <quake3|wolf|et|etut|ef|jk2|ja|sof2|tenebrae|qfusion>
  • Enables support for games other than Quake III: Arena. This switch allows all other (non-solitary) switches.
Info.png Game switch "q3ut4" is commonly refered in Urbanterror mapping tutorials. It actually does not exist, q3map2 silently defaults to quake3 settings.

-fs_game <mod name>
  • Enables support for game mods other than the basic game defined in your -game switch. This switch allows all other (non-solitary) switches.
-fs_basepath <"C:\path\to\game\directory">
  • Required in order for Q3Map2 to read assets directories of games other than Quake III: Arena. This switch allows all other (non-solitary) switches.
-convert [-format <ase|map|quake3|wolf|et|etut|ef|jk2|ja|sof2|tenebrae|qfusion>]
  • Converts a compiled .bsp to another format. This switch is solitary, and allows for only the path to a compiled bsp (not .map, it should be noted) afterward.
  • With no -format sub-switch, -convert converts a compiled .bsp to an .ase model. Q3Map2 -convert outputs mapname.ase to the "maps" directory.
  • Other formats are available via the -format sub-switch:
    • map "decompiles" a .bsp back to a .map (most entities are lost, as is texture alignment information). Q3Map2 -convert -format map outputs in the "maps" directory.
    • quake3 "cross-compiles" a .bsp from some other game's .bsp format (this "other" game is specified in the -game switch) to Quake III: Arena. For example, to cross-compile from Wolfenstein: Enemy Territory to Quake III: Arena, "-game et -convert -format quake3" would be used. This feature is still a work in progress, and should be treated as experimental for the time being; differences in surfaceparm bitflags can cause weirdness in cross-compiled .bsps. Q3Map2 -convert -format quake3 outputs mapname_c.bsp in the "maps" directory.
    • the other game shortnames work similarly to quake3, but for their respective games instead.
-scale <N.N>
  • Scales a compiled .bsp by the prescribed factor. For example, Q3Map2 -scale 0.25 will output a new .bsp that is 25% of the original .bsp's size, while Q3Map2 -scale 2.0 will output a new .bsp that is twice as large. Q3Map2 -scale outputs mapname_s.bsp in the "maps" directory. This switch is solitary, and allows for only the path to a compiled bsp (not .map, it should be noted) afterward.
  • Exports internal lightmaps from a compiled .bsp to external .tga images. This switch is solitary, and allows for only the path to a compiled bsp (not .map, it should be noted) afterward.
  • Imports external .tga lightmaps back into a compiled .bsp. Imported lightmaps will only work on the unmodified BSP they were exported from. This switch is solitary, and allows for only the path to a compiled bsp (not .map, it should be noted) afterward.

-threads <number of threads Q3Map2 should use>
  • Specifies a number of threads to use during compiling. On Windows, Q3Map2 automatically detects the number of CPUs present, and sets the threadcount accordingly. The -threads switch can be used to override this behavior.
  • Linux users will need to manually set -threads in order to activate SMP support in Q3Map2.
  • Enables verbose mode. This is generally a good idea.

  • Used to fix an issue with misc_model entities in SOF2. If your misc_models show up unlit and completely black, use the -rename switch.

Major switches

  • Compiles a .map file into a binary space partition (BSP) file for use with the Quake III: Arena engine. Also writes a .prt (portal information) file and a .srf (surface) file. It is not necessary to add -bsp to your command line; it is the default switch.
  • Creates visibility sets based on the portal file.
  • Calculates lighting data. With no -light sub-switches enabled, less than desirable output will be achieved.

Minor switches

The three major switches (-bsp, -vis, and -light) all have many options that can be accessed via their respective minor switches. There are quite a few minor switches, so in the interest of readability the lists of minor switches have been organized on separate pages of the Q3Map2 wiki.

BSP phase minor switches

Q3Map2 BSP phase minor switches have their own page at Compiling:q3map2/BSP

VIS phase minor switches

Q3Map2 VIS phase minor switches have their own page at Compiling:q3map2/VIS

Light phase minor switches

Q3Map2 Light phase minor switches have their own page at Compiling:q3map2/LIGHT

Q3Map2-specific entities


  • Specifies a decal to be projected. Should contain one or more patch meshes and target an info_null entity. The targetting line drawn between the center of the _decal entity and the targetted info_null is the axis and distance of projection. It helps to think of the _decal mesh as if it were a light gel, the info_null were the target of a spotlight, and that you were "shining" this decal onto map geometry.


  • The _skybox entity is a true miracle: It specifies the origin of a skybox (a wholly contained, seperate area of the map), similar to some games' portal skies. When compiled with Q3Map2, the skybox surfaces will be visible from any place where sky is normally visible. It will cast shadows on the normal parts of the map, and can be used with cloud layers and other effects. Please see the Mapping:Sky for usage info.

Q3Map2-specific entity keys

Q3Map2-specific entity keys have their own page at Compiling:q3map2/Entity keys.

FS Q3map Radbump

FS_q3map_Radbump_4a is a modification of the Q3Map2 compiler developed by TwentySeven. It integrates support for normal, bump, and specular maps.

FS_q3map_Radbump_4a is available from [Q3Map2 bumpmapping modifications at Urbanterror forums]

A brief usage description [FS_q3map_Radbump_4a at Urbanterror level design tutorials]