# Mapping manual/Compiling and packaging

## < Mapping manual

373pages on
this wiki

After all the hard work and testing done with our map, it's time to prepare and package it. In this page, we'll take a look at Q3Map2, BSPC and how to package our map.

Before going with the explanation of what each switch and option does, it's highly recommendable to use the latest versions of both BSPC and Q3MAP2. If you're using Q3Radiant, bear in mind that your map may not pass the GPL compliance because it was compiled with a pre-GPL set of compilers (normally the unsupported Q3MAP and an older, pre-GPL version of BSPC).

If you don't want to mess with commandlines, there are front-ends at the bottom of the page which may aid you with your compilation tasks.

## Q3Map2 Edit

This is the main utility we're going to use in order to compile our maps. This utility comes with the most recent editors, and its version depends from editor to editor.

### The BSP stage Edit

The first stage of the map compilation. It generates the .bsp file, the player-navigable space inside the world.[1]

How the BSP is created (and how to optimize it) is already covered in the Hint brushes page. Here we're going to mention the switches and what each one of them do.

The basic syntax is q3map2 -fs_basepath [oadir] -fs_game "baseoa" -game "oa" [options] [mapfileroute], where [oadir] is the directory/folder where OA is installed (i.e. c:\openarena or /home/user/openarena) [options] are the specified switches, and [mapfileroute] is the ruote of the .map file to be compiled (i.e. c:\openarena\baseoa\maps\mymap.map or /home/user/openarena/baseoa/maps/mymap.map).

The switches of the BSP stage do the following:[2][3]

Switch Description
-custinfoparms Enables custom surface flags for game mods without the need to recompile Q3Map2 itself. Custom surfaceparms are stored in custinfoparms.txt, in the "scripts" directory. Custom surfaceparms follow the format: { surfaceparmName 0x0000 }
-debuginset Enables debugging of surface triangle insetting.
-debugportals Draws the portals into the bsp as translucent polygons. If used during the bsp process and you do not -vis or -light, the portals will be colored. If you also -vis & -light, the portals will take on the color of your sky, but can still be easily distinguished. Omit the -vis and -light stages for best -debugportals results.
-debugsurfaces Colors every surface a different color. Omit the -vis and -light stages for best -debugsurfaces results.
-draw Enables realtime debug drawing output.[4]
-expand Expands all the brush planes and saves a new map out to allow visual inspection of the clipping bevels.[4]
-fakemap Creates a new .map file with a blank worldspawn entity and all the world brushes from your original .map file.
-flares Enable support for flares. They are used to generate a glare effect over bright light sources.
-flat Flatshading. Forces all texture coordinates for a given surface to the pixel that best fits the average color of the assigned texture. However, it is of very limited utility.[5]
-fulldetail Will cause all detail brushes to be handled as if they were structural.
-glview Writes a .gl file of the bsp tree for debugging.[4]
-leaktest Will cause Q3Map2 to abort compile if a leak is encountered.
-meta Creates meta surfaces from brush faces. This is a very useful switch. It decomposes brush faces into their component triangles, and makes a bsp more efficient by combining surfaces, removing coincident verts and lowering the surface + vert count across the map. Now, it has become the "magic" switch that is required for most of Q3Map2's advanced features. Always -meta, and always -v. Also, you must add the -forcesidesvisible to the BSPC line when using this. Either -meta or Q3Map2 in general makes for retarded bots without it. And the -forcesidesvisible switch should be placed before the -bsp2aas switch.
-mi <N> Sets the maximum per-surface index count to N.
-mv <N> Sets the maximum per-surface vertex count to N.
-nocurves Will not compile patch meshes into the .bsp.
-nodetail Will not compile detail brushes into the .bsp.
-nofog Will not compile fog brushes into the .bsp. Visible surfaces that cross fog boundaries will not be split along the bound. This can cause visually incorrect fog in the map.[4]
-nohint Will not compile hint brushes into the .bsp.
-nosubdivide Visible surfaces will not be split. Q3Map2 usually subdivides each drawsurf, as is required by shader tessellation. TessSize is ignored and brush faces are left alone, when this switch is used.
-notjunc Will not fix T-Junctions (can cause sparklies and LOD cracks).
-nowater Will not compile liquid brushes into .bsp.
-onlyents: Only changes the entities in the compiled .bsp. Needs a compiled .bsp and a new entity file (.ent)
-onlytextures Only change the textures in a .bsp file.[4]
-patchmeta Creates meta surfaces from patch meshes. This "bakes" a set LOD into patches in your .bsp.
-samplesize <n> Sets the lightmap pixel size to (nxn) units. The default is 16x16.
-skyfix Enables fix for some drivers not distinguishing between GL_CLAMP and GL_CLAMP_TO_EDGE. Always use this.
-snap Enables axial bevel plane snapping to reduce clipped model plane count (use with care).
-subdivisions <N> Specifies the number of subdivisions to make in your geometry. Larger values increase triangulation and as such, can decrease performance.
-texrange <N> Limits per-surface texel count to N.
-threads <N> Number of threads used to compile the map. For the fastest compile times the number of threads is set to the number of system processors.[4]
-tmpout Outputs files to a folder named tmp.
-v Enables verbose mode for the bsp phase. Always use this.

### The VIS stage Edit

VIS is short for Visibility. The relevant part of this process is the creation of the PVS Table for the Portals in the map. As the player's viewpoint moves around a FULLY vis'ed bsp different areas become visible or hidden, depending on which area the viewpoint is in.[1]

Another stage already explained at the Hint brushes page. Here we're going to mention the switches and what each one of them do.[6][7]

Switch Description
-fast Calculates only a very loose visibility list. It doesn't take much time to calculate, but a lot more polygons will be drawn by the Q3 engine than necessary. Quick and dirty, not actually useful for VIS purposes.
-hint Will merge the bsp leaves (except for hint portals) before calculating the visiblity list. Enabling this switch enables -merge, but will not merge hint portals.
-merge Will merge the bsp leaves before calculating the visibility list. This will speed up the vis calculations, but a lot more polygons will be drawn by the Q3 engine than necessary.
-nopassage Disables the passage visiblity algorithm. Passage VIS is a bit faster and tighter than the old algorithm.
-nosort Disables the sorting of portals by complexity. Sorting speeds up visiblity calculations, because portals that are more complex can use information from less complex portals.
-passageOnly Will use the passage visibility algorithm only.
-saveprt Disables the automatic deletion of the .prt portal file after VIS finishes.
-threads <N> Number of threads used to compile the map. For the fastest compile times the number of threads is set to the number of system processors.[4]
-tmpin <path> The input files will be read from a folder called tmp.
-tmpout <path> The output files will be written to a folder called tmp.
-v Enables verbose mode. Always use this.

### The Light stage Edit

This is the lighting stage, where lightmaps are generated for every world surface in the map. It has no effect on bsp, hints, vis or r_speeds.[1]

This stage is already explained in the Lighting page. Here we're going to mention the switches and what each one of them do.[8][9]

Switch Description
-approx <N> Approximates lightmaps within a byte tolerance of N. Q3Map2 -light -approx forces simple surfaces without much shadow detail to be vertex lit, thus saving lightmaps. The range is from 0-255, 0 being default (no approximation). Try -approx 50.
-areascale <N.N> This scales the intensity of area lights by the prescribed factor. Q3Map2 -light -areaScale 0.25 will result in area lights that are only 25% as bright as those in a .bsp compiled with -light -areaScale 1.0.
-border Creates a debugging border around each lightmap, and helps you to correlate areas of your map to areas in the lightmap when you export the lightmap or use external lightmaps.
-bounce <N> Enables Q3Map2 radiosity. It will re-diffuse the light emitted onto a surface (n) times. In addition, it will write out the bsp after every pass, so it can be cancelled without loss. The tint of light that's reflected is the lightmap/vertex * texture color, and subsampled to certain granularity across every lit surface. Use q3map_lightimage in a shader to override the reflected color.
-bouncegrid Allows bounced light to affect the lightgrid. The lightgrid is used for the lighting of game models and game entities, such as player models, ammo boxes, powerups and so forth. This also affects vertex lighting.
-bouncescale <N.N> Scales up radiosity lights by the prescribed factor.
-cheap Stops Q3Map2 from calculating light on a sample after it exceeds (255, 255, 255). This may produce odd artifacts on maps with lots of saturated colored lighting. Also, do not use cheap with radiosity if you want to preserve all the emitted light.
-cheapgrid Stops Q3Map2 from calculating light on a sample after it exceeds (255, 255, 255), but only for the lightgrid.
-compensate <N.N> Scales back lightmap values to adjust for overbrighting when -gamma is used. For Quake III: Arena, a good compensate value is 4, though some experimentation may be needed to find an aesthetic that suits your particular map.
-cpma Enables full vertex lighting including occlusion on all surfaces, including lightmapped. Causes incorrect handling of -approx in OA even with special shaders.
-dark Enables darkening of lightmaps at brush/lightmap seams. Sort of like a half-assed occlusion pass, ends up looking a bit Unreal 1-ish. Very subtle.
-debug Enables lightmap debugging.
-debugaxis Colors lightmaps based on their projection axis.
-debugcluster Colors lightmaps based on the PVS cluster the luxel falls into.
-debugorigin Colors lightmaps based on the luxel origin relative to the raw lightmap's bounding box.
-debugsurfaces This colors lightmaps by surfacenum % 6, and will color every surface with a different color.
-debugunused Colors unused luxels hot pink.
-dirty Enables ambient occlusion or "dirtmapping". Ambient occlusion approximates light attenuation due to occlusion. Basically, less-visible areas (such as nooks and crannies, cracks and crevices) will become darker.[10]
-dirtdepth <N> Use with -dirty. Sets maximum depth of occlusion checking in game units (default 128).
-dirtmode <N> Use with -dirty. Controls the mode in which the dirtmap is calculated. The Uniform Mode tries to create a very smooth looking dirtmap, while the Noise Mode is, uh, noisy. 0 = Uniform Mode (default) 1 = Noise Mode.
-dirtscale <N.N> Use with -dirty. Scales up the "darkness" of the dirtmapping effect by the prescribed factor.
-dump Dumps radiosity lights into numbered prefabs, for each bounce. (maps/<map>_bounce_<bouncenum>.pfb)
-export This exports internal lightmaps in the .bsp to .tga images.
-extra Sets -super 2. A straight line is traced from four extra points on each lightmap pixel in addition to the original one. The average of the result is taken, which helps to smooth out jagged shadows. Unfortunately it also makes -light take five times as long.[1] Use -extra if you're too lazy to type -super 2.
-extrawide Sets -super 2. Sets -filter. Use -extrawide if you're too lazy to type -super 2 -filter.
-fast Enables light envelopes for area (shader) lights, and enables light culling. This includes radiosity lights. With some maps, using it could speed up light calculations by 50x or more. For maps with large numbers of dim surface lights, it also has the side effect of producing dimmer maps, so you'll need to tweak your lighting. Results in a much quicker -light compiles, but darkens all enveloped light sources considerably—this can be compensated for easily by raising your surfacelight values. Fast makes for great final compiles though, as long as you light accordingly.
-fastbounce Enables -fast style calculations, but only for radiosity light passes.
-faster Enables -faster light calculation. Faster is a debug test mode only, and produces really crappy results (but quickly). Use only when your compiles are taking forever for testing. Fast is the mode you should be using for normal/final compiles.
-fastgrid Enables -fast style calculations, but only for lightgrid calculation.
-filter Gives you a gaussian blur for shadows, and applies a 3x3 box filter (similar to Photoshop's blur) to the lightmap, smoothing out shadows. It breaks down on the edges of a lightmap, because there isn't anything to sample from off the edge. Filter averages a given luxel with 3 of it's neighbors. This is what the old extrawide did, but filter is a bit smarter about it. Sounds good in theory, but -filter doesn't play nice with a lot of the more interesting effects. Use -samples instead.
-gamma <N.N> Creates a more realistic color ramp between "light" and "dark." Good values are in the 1.4-2.2 range. OA will need those cvars disabled unless -compensate is used accordingly.
-lightmapsize <N> Limits the lightmap size. Default is 128.
-lomem Trades increased compile time for decreased memory usage. If you are getting safe_malloc errors (or just running out of RAM), try this switch.
-nocollapse Disables collapsing of identical lightmaps. Collapse compares raw lightmap a to raw lightmap b. Then if they are exceedingly similar, (off by (0.0025 in 3 * x * y)), they are merged. This switch is required for Q3Map2 lightstyles.
-nogrid Disables calculation of the lightgrid for dynamic model lighting.
-normalmap Colors lightmaps based on the facings of their vertex normals, and is good for debugging phong shading.
-nosurf Disables the surface tracing of detail brushes and patch meshes for shadow casting.
-notrace No light tracing is performed. As a result, no shadows will be cast.
-novertex Disables the calculation of vertex lighting.
-pointscale <N.N> Scales up point (entity) lights by the prescribed factor.
-samples <N> Enables intelligent antialiasing of shadow edges in lightmaps. A value of 2 both looks good and compiles quickly, while a value of 3 looks great but compiles somewhat more slowly.
-samplesize <N> This sets the lightmap pixel size to (nxn) units. Writes the prescribed samplesize argument to the .srf surface file. The .srf file (and thus -samplesize) affects the -light phase of compile. A lower -samplesize value produces more sharply defined lightmaps. The default samplesize is 16; a samplesize value of 8 produces a blurry, but good quality compile, suitable to call "final" if you aren't looking for extreme detail. A value of 4 produces a more detailed one, but small artifacts may start appearing occasionally. A samplesize value of 1 produces the most possible detailed lightmap, but also creates "stadium lights" artifacts, a much larger BSP file size and lower game performance. Note that the .srf surface file is generated by the -bsp phase of the compile, so -samplesize must be added to the -bsp phase aswell as to the -light phase to make any effect. It is overridden by surfaces with explicit lightmap sample sizes. (q3map_lightmapsamplesize)
-scale <N.N> Scales up all light sources by the prescribed factor.
-shadeangle <N> Phong shading enabled with a breaking angle of N degrees. This also turns on phong shading, and gives you the ability to specify the angle of light determined by N.
-sky <N.N> Scales up all sun/sky light sources by the prescribed factor. In this new era of -gamma -compensate, -sky 3 can allow "old style" sky shaders to be used without manually rewriting them.
-smooth Smart version of -extra. Only subsamples lightmap pixels that are shadowed. Produces results comparable to -extra in roughly 1/3 the time. Can also be used with -extra or -extrawide for 16- or 48-tap sampling respectively (smoother shadows).[4]
-sunonly Computes sun/sky light only, no other light sources.
-supersample <N> Enables arbitrarily ordered grid supersampling of lightmaps. This replaces extra & extrawide. This replacement does true n-tap supersampling, rather than the weird filter that extrawide did. note that -super requires an argument >= 2 and is much, much, much slower than -samples, by the way.
-threads <N> Number of threads used to compile the map. For the fastest compile times the number of threads is set to the number of system processors.[4]
-thresh <N.N> Sets the recursive triangle subdivision threshold. The range is 0.0-1.0. In order to determine the luxel normal for phong shading and bumpmapping, Q3Map2 recursively subdivides the map's triangles until no side is longer than the distance specified in -thresh (T) times samplesize (S). The reason lower values of -thresh are used are for when you want more accurate phong and bumpmapping. Lower values = smaller triangles = more samples per luxel (lightmap pixel) = more accurate normal = smoother shading.
-trisoup Converts brush faces to triangle soup (merge?)
-v Enables verbose mode. Always use this.

## BSPC Edit

Also called BSP-to-AAS compiler. This stage uses the bspc tool, and generates an Area file mapname.aas. The Area file is used by bots to navigate the map. BSPC is a separate process from the other compile stages, and and it has no effect on and ignores any information created in those stages. BSPC requires only a mapname.bsp which does not leak.[1]

How this stage works is already explained in the bot play page. Here we're going to mention the switches and what they do.[11]

Switch Description
-bsp2aas <[pakfilter/]filter.bsp> Converts BSP to AAS.
-reach <filter.bsp> Computes reachability & clusters.
-cluster <filter.aas> Computes clusters.
-aasopt <filter.aas> Optimizes aas file.
-aasinfo <filter.aas> Shows AAS file info.
-output <output path> Sets the output path.
-cfg <filename> Uses this cfg file.
-optimize Enables optimization.
-noverbose Disables verbose output.
-nobrushmerge Don't merge brushes.
-noliquids Don't write liquids to map.
-freetree Frees the bsp tree.
-nocsg Disables brush chopping.
-forcesidesvisible Forces all sides to be visible.
-grapplereach Calculate grapple reachabilities.

## Front-ends Edit

These tools do away with the troubles of writing the compilation command lines by using a GUI.

## Some building script examples Edit

Remember to replace "/path/to/" and "C:\path\to\" with the routes to your editor installation. Also remember to use the latest versions of both q3map2 and bspc.

Test compile script (Windows):

"C:\path\to\q3map2.exe" -leaktest -v -verboseentities "C:\path\to\mapname.map" "C:\path\to\q3map2.exe" -vis -saveprt -v "C:\path\to\mapname.map" "C:\path\to\q3map2.exe" -light -v "C:\path\to\mapname.map" "C:\path\to\bspc.exe" -bsp2aas "C:\path\to\mapname.bsp"

Test compile script (Linux):

/path/to/q3map2 -leaktest -v -verboseentities /path/to/mapname.map /path/to/q3map2 -vis -saveprt -v /path/to/mapname.map /path/to/q3map2 -light -v /path/to/mapname.map /path/to/bspc -bsp2aas /path/to/mapname.bsp

Final compile script (Windows):

"C:\path\to\q3map2.exe" -flares -meta -patchmeta -skyfix -v -verboseentities "C:\path\to\mapname.map" "C:\path\to\q3map2.exe" -vis -v "C:\path\to\mapname.map" "C:\path\to\q3map2.exe" -light -dark -dirty -fast -patchshadows -v -samples 3 -bounce 8 -gamma 2 -compensate 4 "C:\path\to\mapname.map" "C:\path\to\bspc.exe" -bsp2aas -forcesidesvisible -optimize -grapplereach "C:\path\to\mapname.bsp"

Final compile script (Linux):

/path/to/q3map2 -flares -meta -patchmeta -skyfix -v -verboseentities /path/to/mapname.map /path/to/q3map2 -vis -v /path/to/mapname.map /path/to/q3map2 -light -dark -dirty -fast -patchshadows -v -samples 3 -bounce 8 -gamma 2 -compensate 4 /path/to/mapname.map /path/to/bspc -bsp2aas -forcesidesvisible -optimize -grapplereach /path/to/mapname.bsp

## Packaging the map Edit

After compiling your map, you need to package it in a way that OA recognizes it as a game package. Game packages have the extension .pk3, and are just renamed zip files.[12] You can pack them the manual way or let a program pack your map for you.

This is something you should have considered since the beginning, however don't forget the general rule that your assets (bsp, textures, sounds...) should NOT have the same exact "path+name" of stock OpenArena assets. For shaders, this is true for both shader file name and for every single shader contained.

After you finish packaging, it's a good practice to also test your pk3 on a different, "clean" OA installation,[13] to check you included all the required sfuff. Everything has to work with /sv_pure 1.

### The manual way Edit

This is how the package must be built:

• The following files should always be included:
• maps/mymap.bsp
• maps/mymap.aas
• The levelshot also shows a preview of the level:
• levelshot/mymap.tga or levelshot/mymap.jpg (the first is recommended, created by using apposite "levelshot" command in-game)
• The .arena file allows your map to appear in the Skirmish and Create Server menus, and allows it to be votable via GUI.
• scripts/mymap.arena
• Additional resources used for the construction of your maps go in these folders. Remember to respect the paths or else your map will contain missing assets:
• models/* (for mapmodels)
• music/* (for background music)
• sound/* (for sounds)
• textures/* (for textures)
Warning: that "*" does not mean to place "ALL files from that folder" in the pk3, but instead "all your files there which are used by the map" (pay attention to do not inflate the package with useless files from older maps). To avoid any risk of overriding someone else's one, it is advisable to do not directly include your own scripts/shaderlist.txt file in the pk3[14].
• For GPL compliance (seen in detail in the Appendix F) you must also include:
• COPYING file (found on the OA folder)
• maps/mymap.map (the .map file for your map)
• For cleanness sake, a separate folder with the sources of the assets you have created, for example:
• A plain text "readme.txt" file with infos you wish about the map, its author, license name, supported gametypes, known bugs, compiling options used, etc. See also Readme Model. If you distribute the .pk3 inside a .zip file, it is a good practice to place a copy of it inside both of them.

To keep the .pk3 filesize smaller, you may opt to distribute it inside a .zip file, and place assets "source" files (e.g. those of textures or sounds) in the zip file instead. In that case, don't forget to include in the .pk3 the infos required to download the complete zip package (example: "Texture sources are available in mymap.zip file which you can download from OpenArena section of www.mysite.com: http://www.mysite.com/openarena/downloads/mymap.zip" inside readme.txt), and a copy of COPYING file in both.

### Packaging programs Edit

There are dedicated packages which package your maps and the used assets for you. These are some of them:

## Notes Edit

1. 1.0 1.1 1.2 1.3 1.4 SmallPileOfGibs's Q3map explanation
2. BSP Stage at Q3Map2 manual in Wikibooks
3. BSP stage at Q3Map2 Manual in Shaderlab
4. 4.0 4.1 4.2 4.3 4.4 4.5 4.6 4.7 4.8 Q3Map Compiling manual
5. Flat is a sort of hack that was added to test pre-existing maps with celshading. For new maps that you intend to be cel-shaded, you would probably want to use simple, flat colored textures.
6. VIS Stage at Q3Map2 manual in Wikibooks
7. VIS stage at Q3Map2 Manual in Shaderlab
8. Light Stage at Q3Map2 manual in Wikibooks