Compiling your Map

Compiling is done by a 3rd party .BSP compiler program called Q3Map2. Generally speaking, it is the 'industry modding standard' tool for compiling maps in JKA. Netradiant-custom has this compiler packaged into it along with some nice bug fixes along the way to help with decompiling or other important aspects in that realm.

## Compiling your map

Especially to new mappers, the final process of actually building your map in Netradiant can feel very overwhelming. I will do my best to explain things simply, and if you are curious about more information regarding each stage (bsp/vis/light), read the next chapter below in this post.

The basic idea is this, for your map to build, it goes through three stages. The one you will customize the most per map is your light stage.[1]

To compile your map, you simply click one of the builds within the Build menu. These are the default builds you can choose by default. None of these are very good for what we need.

   Don't worry, once you learn what each switch does (the switches are anything with the dash in them), this will feel a lot less confusing.

Let's create out first test build.

1. In this same menu, click the Customize button. Scroll down to the '...', click that and name your build anything you want. In this example I will name it 'Quick Compile'.
2. We want to follow the same format of the other builds, which look similar to this:
	* *Double click in the command line area to bring up a text box*

```
[bsp] -nameofswitch" [MapFile]"
[vis] -nameofswitch" [MapFile]"
[light] -nameofswitch "[MapFile]"
```
Replace 'nameofswitch' with the switches applicable to what you need for this compile. It's important to note that there are spaces between the brackets and the switches, be sure to remember this when making your own builds.\*Now we want to add in our most important switches, you can take a look at the default ones to get an idea for what those are, but this is my suggestion:

```
[bsp] -meta -leaktest [MapFile]"
[vis] -saveprt -v [MapFile]"
[light] -fast -samples 1 -filter -patchshadows -debugsamplesize "[MapFile]"
```

This is a solid fast compile setting for any basic map. You can look up what these switches and more do by looking in Help>General>'Complete list of Q3Map2 command line parameters'

1. Now make yourself a final compile build, to do so look at the Compiling Your Map wiki post and adding various switches (as well as removing the -fast switch). Experimentation is key.

Here is what I used for mb2\_Citadel

```
[bsp] -meta -leaktest [MapFile]"
[vis] -saveprt -v [MapFile]"
[light] -samples 4 -dark -patchshadows -areascale 1.3 -bounce 1 -bouncescale 0.75 "[MapFile]"

```

Most maps in MBII use -samples 4 -thresh 0.1 -patchshadows. They also add -deluxe -bounce, -bouncescale- and -filter, in their final compile. Lately it seems as though -fastbounce may help speed things up while not slowing down compile. Most MBII maps use these switches. Recently Rend2 support was added to MBII, so -deluxe compiles will help with any player models which have pbr materials.

Of course, if you really want to learn about compiling, read on. ^\_^

### Decompiling a map

New versions of Netradiant allow you to simply 'import' a map into your editor via File->Import (select the .bsp and voila).

Older versions of Netradiant use a slightly more complicated method:

1. The .bsp file must be in the same directory and the same name as your new map. To be sure this will work correctly, let's use gamedata/base/maps directory
2. Rename your current map to the exact same name as that bsp.
3. Create a new compile by clicking the '...' at the bottom of the Build Menu
4. This is where you give your compile a name, in this case do 'Decompile'
5. Add this into the command line: [bsp] -convert -format map\_bp "[BspFile]"
	1. You can also create a fast decompile via [bsp] -convert -fast -format map\_bp "[BspFile]" for varying results
6. Run this compile setting on your empty map which is named the same as the .bsp you are trying to decompile.
7. This will run the decompile and create a a nameofmap\_converted.map in the same folder!

### Entity-Only compile

You'll find out rather quickly that decompiles don't usually work perfectly, usually something gets messed up, be it textures, lighting or otherwise. If you are looking to simply tweak the entities on a map, what you can do is decompile it and then do an only-ent compile. This will essentially only change the entities and is a fun way to add things to a server. I used it to move spawns for dueling variants of maps and also to add various NPCs or training droids to my dueling server. Here's how to do it:

1. After you have decompiled a map, or if you just want to change only entities and not do a full compile, create and name a new "only ents" compile with this as your line: [bsp] -onlyents "[MapFile]"
2. When you run this compile, it should work incredibly quick since it is only really changing a few text assets.

But what really happens when a map compiles? It goes through 3 stages: BSP, VIS and LIGHT.

## Stage 1 - "BSP"

The .bsp file contains all of the geometry and collision information for a level; this is the only file that a map requires. This is the fastest output to compile.

#### What does the BSP stage do?

BSP stands for "Binary Space Partitioning." It's a technique used in computer graphics and game development to optimize the rendering and performance of 3D environments. BSP trees are data structures that divide a 3D space into a hierarchical arrangement of convex regions, making it easier to determine what parts of a scene are visible and need to be rendered.

In the context of game mapping:

Binary: Each division in the tree splits the space into two parts.

Space Partitioning: The process of dividing the 3D space into smaller sections.

The main goal of using BSP trees is to quickly eliminate parts of a scene that are not visible to the player's camera. This helps improve rendering performance because the graphics engine doesn't waste time rendering objects that can't be seen. BSP trees are particularly important in the rendering of complex scenes where there might be many objects that could potentially be visible.

BSP trees are used in various game engines to efficiently manage rendering and optimize the rendering process. They are especially important in games with fast-paced action or large, open environments, where rendering efficiency is crucial to maintaining a smooth gameplay experience.

Put simply, this stage during compile establishes where a player can be. This part of the compile process creates a .srf (surface) file. Further elaborating, the player-navigable space inside the World is split into convex volumes bounded by planes. These convex volumes are called Leaf Nodes. The Leaf Nodes are stored in a binary tree called a BSP Tree. The simplest way to explain this part of the compile process is that the .bsp process essentially informs the player what is solid and what is not. This process is also taking into account the structural brushes you have used and any shader properties of your brushes. There are certain shader properties which will impact the compile process.

#### Essential switches:

##### -meta

-This switch is an essential step that involves creating the structural and collision data for the level. It creates meta surfaces from brush faces. 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.

##### -v

- This switch uses a lot of new 'verbose' features to improve your compile. It enables verbose console output.

##### -samplesize

A lower -samplesize value produces more sharply defined lightmaps. The default samplesize is 16. Which value you choose will depend on your needs. Keep in mind the limit for the jamp engine is 256 max bsp lightmaps. Check the console output if you are nearing this limit and adjust your -samplesize accordingly. A higher samplesize will increase the speed of your compile.

#### Recommended (but not necessary switches:

##### -leaktest

Compiler immediately shuts down if a leak is detected.

##### -debugsamplesize

Warning if your -samplesize is too small. The warning will say, "\_ too large for samplesize \_, reducing to \_". If you see these warnings, you will know to then adjust your sample size via this switch. Other solutions are to reduce surface size for that particular brush which is too large or increase the lightmap size for it.

## Stage 2 - "VIS"

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.

#### How is the PVS created?

Every Portal in the portal file is checked against every other Portal for visibility. Portal 1 is visible to Portal 2 if a straight line of sight can be drawn between any part of Portal 1 and Portal 2 without passing through a structural brush. Think about your player's viewpoint as the 'line'. The compiler basically draws a ton of lines from hypothetical lines of sight. This information is the Potentially Visible Set and is stored in the PVS Table, exported as a .prt file.

> The basic idea here is that if the the portal the player is in can 'see' the other portal, this region will be rendered by the player.
>
>

The Leaf Nodes remaining in the BSP Tree after the outside Leaf Nodes are removed are bounded either by other nodes or by structural brush faces. A Portal is created for every face of a Leaf Node that is bounded by another Leaf Node. What does this mean? Well, each Portal is like a window from one node looking outwards into another. If you see one of these windows, that area will render. Every Leaf Node has one or more Portals (unless there is only one node in the BSP tree).

Effectively, solid structural brushes block visibility between the contents of Leaf Nodes. Curves, detail brushes and Entities do not block visibility. Visibility between two areas will only be blocked when both areas are completely hidden from each other. Generally, the more Leaf Nodes visible from the Leaf containing the Viewpoint, the more objects will be drawn. The aim when optimizing for visibility, is to have the smallest number of other Leaf Nodes visible from any one Leaf Node. This is why you want to keep your structural brushes as simple as possible to avoid creating unnecessay portals or confusing the VIS process. You can reduce the number of Leaf Nodes created by reducing the number of unique structural Planes in the map, by making all unnecessary structural Face-Planes into detail Brushes.

The Portal information is not needed in the BSP, but it is essential to VIS, so it is stored in the portal file "mapname.prt". This .prt file is especially useful with the handy plugin .prtviewer which is built into Netradiant. You can open up your .prt using this plugin and view the portals in your map. There are a few articles linked at the bottom of this page for information on using hint brushes to help optimize your map. You will need to use the switch -saveprt in your vis stage of your build in order to use this plugin.

#### Controlling Vis with the use of Hints

You can control visibility by placing Subtle Hints or Hints (a system brush) to create the Leaf Nodes and their Portals exactly where you want them to be, splitting the space into more Leaf Nodes only in areas where they are needed. A Hint brush (system/hint) will be invisible in Q3, but is structural, so it will affect the BSP Tree and create more Leaf Nodes. This gives you a lot of control over WHERE the Leaf Nodes are created. Placing a hint brush in an area of open space will force creation of a Leaf Node within the area of that hint brush. Hints can also intersect with other structural solid brushes or Hints, creating multiple Leaf Nodes or isolating groups of Leaf Nodes. Hint brushes use a shader which makes the brushes nonsolid and nodraw, meaning it will be invisible to the player and not seen.

Hints are best used to make large axial cuts along planes shared by other structural brushes, to maximize the amount of area hidden by each vis-blocking structural brush, by minimizing the number and size of the Leaf Nodes visible.

Intelligent use of detail and Hint brushes in combination can reduce vis time and r\_speeds in almost any map. However the map must be designed from the start with this in mind. Redoing an inefficiently made map is a lot of work. One of the best ways to see what is drawn from your VIS compile is to get in-game and type r\_showtris (with cheats on) to see how these portals are culling visibility to your player.

##### Essential switches for VIS builds:

###### -saveprt

This keeps the .prt file after running vis

Instead of creating the .prt file and deleting it upon the vis finishes compiling, the .prt file is stored in the same directory as your .bsp (useful when wanting to use the prtviewer plugin)

## Stage 3 - "LIGHT"

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 (performance cvar).

For the most part when it comes to adding or removing parameters to your various builds, the light stage has the main switches to consider which to add or remove.

#### What is a lightmap?

A lightmap at it's simplest definition is how the compile process stores and changes the brightness of surfaces. Your easiest way to see how this is gets compiled is to type r\_lightmap (with cheats on) in-game. A lightmap is actually a singular 2D map which gets put inside your .bsp file (and if you want, it can even be exported into a subfolder outside of your .bsp to be edited.

The Q3map -light algorithm creates a lightmap pixel for every 16 game world units on a brush, and every 20 units on a patch, stored in 128\*128 pages. Lightmaps are blended with the textures by multiplying the lightmap RGB values with the RGB values of the texture (see the Shader Manual: blendfunc filter).

Creating good lighting for your map takes time and patience.

### What is a lightgrid?

Another stage of the lighting process, the light is used for lighting models. The lightgrid is an array of data to use during in-game lighting of dynamic models. It contains lighting information for points in space. Character models and things like misc\_model\_static choose the closest one, to be lit by it. You can use system/lightgrid brushes to create a hull around your map where any models are. A smaller lightgrid will improve compile time.

### What is vertex lighting?

This is essentially the exposure of your textures as it corresponds to your lightmap.

### Recommended Lighting Compile Switches

There are a lot of switches to consider for your -light compile settings. Do you want the light to be harsh or diffused? For harsh light, avoid using the switches which diffuse your light too much. If your map is mostly lit by a skybox, you need to keep in mind that Netradiant is applying the shader properties of that skybox to your map as well, so refer to the shader manual. Any shader which has the q3map\_ prefix applied to it will be something that gets considered in the compile by Netradiant.
Generally speaking for a regular compile, -samples 4 -thresh 0.1 -patchshadows are essential. From there adding -deluxe, -bounce, -filter

### Essential compile switches

##### -faster

Super quick-but-not-accurate light calculation. Not suggested for anything other than a test compile.

##### -fast

Greatly speeds up the compilation process for light, but with a loss of quality. This is not recommended for final compiles because as soon as you take this switch out, your lighting will change. However, the loss of quality could be good in proportion to the compile time saved. This switch is generally recommended for use when testing other areas of your map outside of lighting.

   Avoid using -fast for final compiles if you are noticing blotchy shadows or light formation. Important to note that with the proper balance, you can diffuse these blotches out of your lightmap with the proper combination of diffusion switches. If you have a computer which is chugging on nonfast compiles, just know there is a way to smooth things out from a -fast with enough experimentation.

##### -fastbounce

This is a new netradiant switch which uses the -fast algorithm but only for more specifically for diffusing (bouncing) light. This seems to have a better diffusion effect than using -fast, and can be used for final compiles.

##### -fastgrid

This also uses the -fast algorithm but only for the lightgrid. Both this and -fastbounce can be used to speed up compile times.

##### -faster

-faster makes the compilation process of the light stage even faster than -fast , but noticeably worsens the quality of the lighting. I advise against using this switch unless you are in a hurry.

##### -patchshadows

– patchshadows activates shadow casting for patches. If you have patches in your map, this should be used.

### Diffusion:

These switches affect the way light gets diffused. Essentially these are different methods (that can be combined) to help soften harsh shadows in your lightmap.

##### -samples

-samples should ensure finer light and shadow edges, but lengthens the compile process. You should play around with

##### -filter

-filter essentially applies a blur to the lightmap, this helps to reduce the jagged effect on diagonal light or shadow edges. The downside to this is that shadows will lose sharpness as a result.

##### -bounce

-bounce also referred to as radiosity. -bounce calculates how strongly light is reflected from other surfaces and in turn illuminates other surfaces. The number behind -bounce indicates how many light reflections should be calculated. This can be also used with -bouncescale switches. Many maps in MBII employ bounce but with a bouncescale of 0.75 to avoid the light washing out too much and to speed up compile times.

The compiler automatically ends its work when there is not enough light information left to calculate further bounces. It is therefore possible that you specify 8 bounces, but only 5 are carried out.

##### -super

-super works similarly to -filter / -samples in that is diffuseshard shadow edges, but it also increases the compile time significantly. From what I have gathered, -samples is more modern and takes less time to compile.

##### -deluxe

A necessary switch for Rend2 compiles. Deluxe compiles a separate lightmap that is essentially a world-normal map for surfaces so that normal maps, reflections can be properly calculated.

### Tightening-up corners and crooked areas

##### -dark

-dark creates shadows on the edges of adjacent brushes, similar to the effect of Ambient Occlusion .

##### -dirty

-dirty is a better alternative to dark, but also requires more compile time. -dirty ensures that niches, corners and other crooked areas that are in the shadows absorb even more light in a realistic way and thus become darker. The effect is based on the ambient occlusion lighting of modern games.

Here are a couple of good starting switches I would suggest trying in your compile:

- patchshadows

- samples 2-4 (this slows down your light compile process but is important for quality purposes, generally 2 is good for tests and 4 is good for final)

- bounce (try different combinations.)

- fastbounce (always use this to save time when using bounce)

- filter (adds a blur to your shadows)

Keep in mind if you need to just test out entities and are not worried about light, your fastest way to compile is with no light compile at all! Just -meta! in your .bsp compile!

### Worldspawn keys can affect diffusion or exposure of your lightmap

Your worldspawn is essential your overall map settings, and can be found by selecting any brush and looking at the entity properties of it. To select your worldspawn, press L and scroll down to the bottom of your entities and click worldspawn. Read the entity definitions. Here are some relevant settings to consider with regards to how your map compiles:

#### Light:

##### gridsize

Dynamic Light Granularity - granularity of the lightgrid created by q3map. Value is three integers separated by spaces, representing number of units between grid points in X Y Z. Default gridsize value is 128 128 256. Use larger powers of 2 to reduce BSP size and compile time on very large maps.
##### \_keeplights

an important new key (by default set to 0) which allows your map to keep the light entities so that the decompiling process is a lot easier.

##### \_ls or \_lightmapscale

Floating point value scaling the resolution of lightmaps on brushes/patches in the world. You can use this as an advanced way to get more detailed lightmaps on tricky func\_groups by scaling those \_ls up more. Default is 1.0.

##### \_mingridlight

Amount of minimum grid light (dynamic entity light)

##### \_minlight

Amount of minimum light - does not add like ambient, also uses color

##### ambient

Tends to flatten out the contrast, useful for more cloudy or foggy map, \_color changes this base ambient (nice way to color grade your .map a bit, good if used subtly)

##### \_cs

Allows per entity control over shadow casting. Defaults to 0 on entities, 1 on world.

##### \_rs

Allows per entity control on whether that entity should receive shadows. This is particularly useful if you are struggling with an area that is receiving an unwanted shadow from somewhere. Turn it into a func\_group and apply \_rs 0,

#### Optimization worldspawn Keys

##### gridsize

Dynamic Light Granularity - granularity of the lightgrid created by q3map. Value is three integers separated by spaces, representing number of units between grid points in X Y Z. Default gridsize value is 128 128 256. Use larger powers of 2 to reduce BSP size and compile time on very large maps.

##### \_minlight

Minimum light value, levelwide. Uses the \_color key to set color. Does not add unlike ambient.

##### \_blocksize

BSP Block Size - q3map always splits the BSP tree along the planes X=\_blocksize\*n and Y=\_blocksize\*n. Default \_blocksize value is 1024. Increase the blocksize using larger powers of 2 to reduce compile times on very large maps with a low structural brush density.

##### \_farplanedist

Limit on how many units the vis phase of compilation can see. Used in combination with level-wide fog, it can help reduce r\_speeds on large, open maps.