Call of Duty 4: Compile Tools
CoD4 Compile Tools Documentation
CoD4 Compile Tools is your user interface for easy compiling, lighting, paths, reflections, lighting grids, and loading levels. It also gives easy access to launching the mod tool applications such as the level editor, effects editor, or asset manager.
Configuring CoD4 Compile Tools
The first thing you will need to do when you run CoD4 Compile Tools is configure the game path. Click the “Preferences” tab near the top of the application, click “Browse…” and point it to the directory where the game is installed. This will be the directory containing the game .exe files. Default install path is C:\Program Files\Activision\Call of Duty 4 – Modern Warfare\
Once you have told CoD4 Compile Tools where your game is installed you should see be able to click the “Level Compiling” tab and see a list of the provided sample maps in the list.
Using CoD4 Compile Tools
The “Level Compiling” tab is where you can keep track of your .map files and compile bsp, lighting, paths, and reflections for those .map files. You’ll notice 5 buttons numbered 1-5 on the bottom left. These are the steps needed to get your level compiled properly and into the game. I will go over them now.
Compile BSP
- Select the level that you wish to compile from the list. In this example I will use the level called “test” which is supplied with the mod tools. First you will need to compile the BSP for the level. This will convert the .map file that is made in the level editor to an optimized format that is read by the game engine. We’ll need to set some options for this found on the right hand side, right next to the list of levels. You can check boxes to tell it to compile BSP, lighting, and paths. If you made any changes to the .map file you’ll need to recompile the BSP. Lighting can be compiled right after the BSP is compiled, or at a later time, as long as the BSP has not changed. Paths can also be compiled later; however AI in single player levels will not work correctly until paths have been compiled. Multiplayer levels never need to compile paths since they are strictly for AI navigation in single player.
- Be sure to set up your BSP Options and Light Options before clicking the “1. Compile BSP” button. Most of the time no BSP options will be used but I’ll go over them anyways since occasionally they may need to be used. Some light options are commonly used however.
BSP Options
- Check the box for “onlyents” if you would like to do an only entity compile. Onlyents compiles don’t touch brush triggers, geometry, or lighting. This is useful if you want to quickly recompile a map that you only moved an entity in. (Note that if you move a model that casts a shadow, the lighting will not be recompiled by doing onlyents, so your shadow will still be in its old position, not where you moved that model to.)
- Check the box for “blocksize”, then set a value to set a custom grid size for regular BSP splits. A value of zero uses the biggest possible size, and is also the default value if this option is left unchecked. Most of the time this option will remain unchecked.
- Check the “samplescale” box, and then set a value if you would like to scale all lightmaps. A value of 2 will double the pixel size, a value of 0.5 halves it. Again, this option should remain unchecked in most cases.
- The “debugLightMaps” option is a great way to see in-game how the light maps were compiled and how they are being used. Using this option compiles colored light maps and when the level is loaded in-game you will see colored geometry everywhere that contains light maps. Different colors represent a different lightmap texture. This is great for tracking down why you might have encountered lightmap bleeding or seams.
Light Options
Most of these options will be unchecked; however I’ll explain them for the rare cases that you may want to use them. Often I use the “fast” option during testing for quick light compiles, but then use “extra” for final release as it gives better lightmap detail.
*Fast Use fast presets for several options (generates lower quality lighting but is much faster) *Extra Use high-quality presets for several options (generates high quality lighting but takes longer) *ModelShadow Allows model surfaces to cast shadows *NoModelShadow Prevents model surfaces from casting shadows *DumpOptions Displays current settings of most parameters *Traces Number of traces to do from each sample point *BounceFraction Higher values are more washed out, lower values darker *Jitter Breaks up aliasing from trace pattern (0 none, 1 max)
- Once you have all the options you wish to use, click the “1. Compile BSP” button to start the compile using your specified options. The BSP will be compile first ( if you chose that option ), then the lighting ( if you chose that option ), then the game will be loaded to compile the AI Paths ( if you chose that option and your level is single player ).
- This process can take anywhere from a few seconds to several hours depending on the complexity of your level and the computer you are compiling on. For a frame of reference, most of the retail levels shipped with the game take about 30 minutes to and hour to compile bsp and lighting on quad core CPUs.
- Part of lighting is the grid file. Entities (models, players, AI) in a map are lit by the lights in the map. In complex maps (as opposed to small test maps) calculating which lights affect which entities takes a lot of work. To prevent the engine from having to do this in real-time, this information can be written into the bsp using a mapname.grid file. If a map doesn’t have a grid, you will experience harsh hitches when entering new areas where entities are now visible. These hitches feel like texture thrashing. Grids are needed for both single player and multiplayer maps. A map must be recompiled after creating or modifying a grid. Select “make new grid” if you have never done a grid for the selected level, or “edit existing grid” to continue working on one that you previously made. The level will be loaded in grid mode. You’ll see lots of little dots throughout the level. You’ll need to walk around the level and touch as many of the dots as possible. This defines the areas a player will be able to go. For most areas however, you can just place a brush with the lightgrid material on it in CoD4Radiant and the touching dots will automatically be collected when the level is compiled. Doing a custom grid is really for certain detail areas. Most of the time you can just place brushes in CoD4Radiant to do the work for you.
Check out this section for more information on grid files.
Compile Reflections
- If your characters weapons and vehicles have red outlines you don’t have any reflection probes compiled for your map. Reflection probes are very important for the look of all shiny things in the game. Place one per room and one in each distinct outdoor area and additional ones near any especially shiny objects. They use memory but its reasonable to have 10-100 of them.
- After the BSP and Lighting have been compiled you will want to compile the reflections for the level. In order for reflections to be compiled properly the level needs to contain reflection probe entities throughout the map. Each reflection probe in the level will produce a cube map for that area during the reflection compile. The reflections used throughout the compiled level use the cube map from the nearest reflection probe entity so keep this in mind when you are placing the probes. The reflection probes use portals to determine which is the closest probe so you don’t usually need to worry about an inside probe affecting an outside model through the wall.
- Click the “2. Compile Reflections” button when you are ready to compile the reflections. This step may be skipped if you don’t care about proper reflections during the testing and development phase of a level but it should always be used when you want the level to look top notch. You may also skip this step if you have already compiled the reflection probes for the bsp and you have not made any changes to the reflection probes in the level. On compile it will use old reflection probes. You only need to do this step when it’s the first time you’ve compiled the bsp, or you are making changes to the probes or adding/removing probes.
Build Fast File
- In order for the level and all of it’s assets to be loaded into the game within a reasonable amount of time a fast file is needed to be made. A fast file is one big file that contains all of the data for the level and all of the assets it uses. Since it is all in one file it can quickly be loaded directly to memory, instead of your hard drive having to search for thousands of files and load them individually which takes much longer.
- The first time you try to build the fast file for the level it will tell you that no zone files exist and ask you if you would like to make them. You’ll want to say “yes” at this prompt. Doing so will create [root]\ zone_source\[levelname].csv, where root is the game install path.
- Within this .csv file is a list of assets the level uses. It will have some default assets in there that all levels use. This csv is looked at by the fast file builder and all the assets it references will be added to the level’s fast file. The fast file ends up containing the level BSP itself, plus all assets listed in [levelname].csv.
The fast file generated will be created at [root]\zone\[language]\[levelname].ff. This is the file you would want to give your friend or post online when you want to share your level since it contains all of the data used by the level. Anytime you change anything in the level, or any assets used in the level you’ll need to recompile the fast file so that those new or changed assets get put into the fast file for the game to read.
Update Zone File
Okay so I just talked about what fast files are and how to make them. I mentioned they contain all of the assets used or reference in a level. Suppose you add a new static model to your level, or you give the player a gun through script. These new assets wont be in the fast file, so they won’t actually show up, and may even give errors in the game. Updating the zone file ( the [levelname].csv file ) is necessary to make sure all of these new assets are put into the fast file.
Each time the level is ran and tries to load an asset that wasn’t found in the fast file an output file called missingassets.csv is created at [root]\main\missingassets.csv. This file contains a list of assets that the game tried to load but couldn’t (due to them not being stored in the fast file that was used). If missingassets.csv is not being generated then your level fast file and zone source are either up to date with all assets, or you may need to try running the level using the “developer” and “developer_script” option turned on ( found under the “5. Run Selected Map” button ).
These missing assets need to be added to the [levelname].csv zone file so that they get included next time you build the fast file. This is as simple as copying the asset list from missingassets.csv and pasting them at the bottom of the [levelname].csv zone source file, however CoD4 Compile Tools can make this easier for you.
When you click “4. Update Zone File” a new window opens showing the contents of both missingassets.csv and [levelname].csv and allows you to easily move over the assets you want and save the new file.
The text on the left is read from missingassets.csv and is all of the assets that were not loaded correctly. The list on the right is the current zone source file ([root]\zone_source\[levelname].csv). Add the missing assets to the zone source by highlighting the text, cut, and paste to the zone source file on the right. Be sure to not have two assets on the same line. One asset per line is required.
If you update your zone source file, rebuild the fast file, reload the level, and missingassets.csv is telling you more assets are missing, it’s perfectly normal. Often times this process has to be repeated a few times before all missing assets are caught. This is mainly because some assets are referenced by other assets. For instance you may get a weapon as the only missing asset in your level. Missingassets.csv will complain that the weapon isn’t in the fast file; therefore you add it to the zone source and rebuild the fast file. Next time you run the level it may complain about another weapon missing. Well why didn’t it tell me there was 2 missing weapons the first time? The reason is because the second weapon it complained about may be referenced by the first weapon in asset manager, such as an alternate fire mode. The game didn’t know that the second weapon was missing until it had the first weapon loaded correctly and tried to load its second fire mode.
When you’re updating your zone source make sure you run the level a second time or more until missingassets.csv hasn’t changed, or is empty. This will ensure that you’re added all assets that are required.
Run Selected Map
Runs the selected level in the game. You can turn on developer, developer_script, and cheats by checking the boxes below the button. Developer enabled will turn on a lot of profiling functions as well as errors and missingassets.csv output among other things. Developer_script will provide script debugging and script errors when encountering. Without developer_script enabled script errors will be bypassed. The cheats option turns on cheats allowing the player access to the cheat commands such as god mode and ufo mod which are handy when working on a level.
Launching Applications
The applications tab gives easy access to launching various applications for the mod tools. Here you can launch the level editor, effects editor, and asset manager. A description for what they are used for is provided for each.
