Compiling
An example map and compile batch file are included with these tools and can be found in \game\main\maps.
The stages of a compile are as follows:
q3map mapname.map
builds the bsp
q3map -vis mapname.bsp
options are q3map -vis or q3map -vis -fast
vis info is used for the server sending entity info to the client so multiplayer maps should use –vis but single player maps can just use –vis –fast
will not work if the map leaked
flare mapname.bsp
generates the lightmaps
will not work if the map leaked
CoDSP.exe +set r_vc_compile 2 +devmap mapname
generates the vc log (see VClog section below)
CoDSP.exe +set g_connectpaths 2 +devmap mapname
generates the path data for the AI (opens the game and then closes it automatically after compiling)
Optional
q3map -info mapname.bsp
displays data size information about your bsp
Flare
flare args mapname.bsp
where args is 0 or more of the following
-Verbose Turns on verbose prints
-Fast Use fast presets for several options
-Extra Use high-quality presets for several options
-MaxPolys Maximum number of polys to use during light compile (can be used to increase the default for larger maps)
-MaxVerts Maximum number of vertices to use during light compile (can be used to increase the default for larger maps)
-MaxBrushes Maximum number of brushes to use during bsp solid check
-MaxOccluders Maximum number of occluders to use during light compile (can be used to increase the default for larger maps)
-Visual Activates visual preview / debugging
-DiffuseSun Forces diffuse sunlighting
-NoDiffuseSun Doesn't do diffuse sunlighting
-FastDiffuseSun SampleDiffuseSun uses a single vertical sky trace
-ExtraDiffuseSun SampleDiffuseSun uses multiple sky traces
-ModelShadow Allows model surfaces to cast shadows
-NoModelShadow Prevents model surfaces from casting shadows
-ModelAlphaShadow Allows transparent model surfaces to cast shadows
-NoModelAlphaShadow Prevents transparent model surfaces from casting shadows
-SunDiffuseSamples Hemicube edge size for SampleDiffuseSun (3N^2 samples) (Lower numbers will cause extra ghost shadows from the diffuse sun. 6-10, even values are recommended.)
-DumpOptions Displays current settings of most parameters
You can see all the options to flare by running the program with no arguments.
VClog
What is a VClog?
Entites (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 realtime, this information can be written into the bsp using a mapname.vclog file. If a map doesn’t have a VClog, you will experience harsh hitches when entering new areas where entities are now visible. These hitches feel like texture thrashing. VClogs are needed for both single player and multiplayer maps. Anywhere our example says “CoDSP.exe”, just replace it with “CoDMP.exe” for multiplayer and the same process applies.
Creating a VClog (visibility cache data)
This log can be made once and forgotten about until you make a significant change to geometry in your map which would allow models, players, or AI to exist in new areas; it will still be valid after almost any tweak to geometry, including those that alter shadows. The typical way to make this log is to set "r_vc_showlog 1", and then to run around playing "pacman" trying to get rid of the green dots in areas where you expect players to go. You still find visibility data when "r_vc_showlog" is 0, and it runs a little faster, but it is easy to miss spots. "pacman" mode only works if you have a viewmodel on-screen.
You must set “r_vc_makelog 1” or “r_vc_makelog 2” to enable making a log. A value of 1 creates a brand new log, a value of 2 appends to an existing log. "r_vc_showlog" is not all that useful with "r_vc_makelog 2", since any dots that were already in the old logfile will never go away, no matter how many times you go near them.
CoDSP.exe +set r_graymap 1 +set r_vc_makelog 1 +set r_vc_showlog 1 +devmap mapname
You can change the amount of dots you see in the map by changing the “r_vc_showlog” value.
Four is a good value to use, but any of these are valid: 2, 4, 6, 8, 10, 12, 16
You can bind a key to increase/decrease the value.
Example:
bind F3 "toggle r_vc_showlog 2 4 6 8 12 16"
bind F4 "toggle r_vc_showlog 16 12 8 6 4 2"
You must NOT set "dedicated", or you will not get the compiled visiblity cache data. Setting r_graymap is not necessary but saves a little time by not loading textures.
Compiling a VClog
Once your map is basically geometry complete, make "mapname.vclog" by going around your map with "r_vc_makelog 1". From then on, you need only compile the map with "+set r_vc_compile 2" as follows.
CoDSP.exe +set r_vc_compile 2 +devmap mapname
With r_vc_compile 2 the game quits after compiling visibility cache data; 1 compiles and finishes loading. Also, if you do r_vc_compile 1, then the compiled visibility will not be available until you do a vid_restart or load the map again. A map_restart or loaded savegame is not sufficient. Additionally, CoDSP.exe is hardcoded to look for the .vclog file in the maps directory and the CoDMP.exe is hardcoded to look in maps/mp/. Basically, the .vclog MUST be in the same place as the .bsp.
Confirming a VClog
To confirm whether or not the VClog has been compiled into a .bsp use the “r_vc_stats” console command to see the performance statistics for the light visibility cache. Load the .bsp in the game. Once the map has loaded, pull down the console and type “r_vc_stats”. The VClog has been successfully compiled into the .bsp if the “entries used” number is greater than “entries filled in at runtime”.
Example:
light visibility cache performance:
74606 entries used (28.5%)
21 max associativity
0 entries flushed
1216 entries filled in at runtime instead of read from disk
Note:
If the “entries filled in at runtime” number is the same as the “entries used” number, then the VClog has NOT been compiled into the .bsp.