## MBSPC -- BSP converter and editing utility

### Copyright (C) 2004-2012 Laszlo Menczel (laszlo.menczel@gmail.com)

This program is distributed under the terms of the GNU General Public License version 2 as published by the Free Software Foundation. A copy of it is in the file GPL.TXT. This program comes with ABSOLUTELY NO WARRANTY.

### Introduction

This program is based on version 2.1 of the BSPC utility (part of the toolkit created for the Quake series of games). Originally it used to be a MAP to BSP converter. For Quake 3 it is mainly used for the creation of AAS file from BSP files. An AAS file is a file containing area information used by the Quake III Arena bots to navigate and understand a map.

MBSPC is a modified (enhanced) version of this utility. I have (re)added some functions that were either not present originally or were removed from this version for some reason. So you can also do the following tricks with MBSPC:

- convert BSP files to editable MAP format
- update the entity list in a BSP file
- extract the entity list from a BSP file to a text file (new)
- create a list of the textures used in a BSP file (new, only for Q3A at present)

When MBSPC is used for converting BSP files to MAP files, the correct texture name is written for every brush side. However, correct texture alignment info (shift, scale, rotation) is not written to the MAP file, when converting Quake 3 maps. As for Quake 1/2, SiN and Half-Life, alignment info is half right for regular map format (-bsp2map) and is correct, when using Valve 220 one (-bsp2map220).

### Usage

      bspc -option [ -option ... ] input-file

At least one option must be given to specify the desired action. The rest of the option(s) within the brackets are optional. Examples:

      mbspc -bsp2aas d:\quake3\baseq3\maps\mymap?.bsp
      mbspc -bsp2aas d:\quake3\baseq3\pak0.pk3\maps/q3dm*.bsp
      mbspc -bsp2map -output d:\tmp d:\quake3\baseq3\maps\q3dm1.bsp

### Options

The first section in the table contains obligatory options, i.e. one of them must be specified so that MBSPC knows what to do. The second section contains optional parameters that modify the way the action is done. The third section contains options that are useful only if you want to use MBSPC for compiling a BSP from a MAP. These are kind of obsolete because for Quake 1/2/3 there are now better compilers (e.g. q3map2), so MBSPC should not be used for this purpose.

List of options recognized by MBSPC:

       option           argument        explanation                          output
       ---------------------------------------------------------------------------------------
       entlist          file.bsp        extract entity list                  file.ent
       onlyents         file.bsp        update entity list from file.ent(*)  file.bsp
       texinfo          file.bsp        extract texture list                 file.txi
       bsp2map          file.bsp        create MAP from BSP                  file.map
       bsp2map220       file.bsp        create Valve 220 MAP from BSP        file.map
       bsp2aas          file.bsp        create AAS from BSP                  file.aas
       reach            file.bsp        compute reachability and clusters    file.aas
       cluster          file.aas        compute clusters                     file.aas
       aasopt           file.aas        optimize aas file                    file.aas
       ---------------------------------------------------------------------------------------
       output           output-path     set output path
       threads          N               set number of threads to N
       cfg              file            use configuration data in 'file'
       noverbose                        disable verbose output
       ---------------------------------------------------------------------------------------
       optimize                         enable optimization
       breadthfirst                     breadth first bsp building
       nobrushmerge                     don't merge brushes
       freetree                         free the bsp tree
       nocsg                            disables brush chopping
       noliquids                        don't write liquids to map
       forcesidesvisible                force all sides to be visible

(*) The '.ent' file must exist! You can make one using the '-entlist' option. The '.ent' file can be edited by using a text editor (e.g. you may change entity types and coordinates) as long as the format of entity specifications remains valid.

Several metacharacter may be used in the paths of the input file:

      *          match any string of zero or more characters
      ?          match any single character
      [abc...]   match any of the enclosed characters; a hyphen can
                 be used to specify a range (e.g. a-z, A-Z, 0-9)

.pk3 files are accessed as if they are normal folders. For instance use "d:\quake3\baseq3\pak0.pk3\maps/q3dm1.bsp" to access the map q3dm1.bsp from the pak0.pk3 file.

Multiple files may be listed after the switches bsp2map, bsp2aas, reach, cluster and aasopt.

If a BSP file is being converted to an AAS file and no output path is entered on the command-line then the AAS file will automatically be stored in the same folder as the BSP file. However if the BSP file was stored in a .pk3 file then the AAS file will be stored in a folder with the name 'maps' outside the .pk3 file.

### How updating the entity lump affects the AAS file?

If an AAS file is already available for a BSP file and you ONLY change the entities inside this BSP file (using the map editor or MBSPC with the '-onlyents' option) then you only have to recalculate the reachabilities. This way you can move items, platforms etc. around without the need to recalculate the whole AAS file which can save quite some compile time. You can recalculate the reachabilities as follows:

      bspc -reach file.bsp

where 'file.bsp' is the updated BSP file. 'file.aas' must exist and must be in the same folder as 'file.bsp' or in the output folder specified with the '-output' option.

Note: the option '-reach' does not work on optimized '.AAS' files.

Keep in mind that as soon as ANY geometry in the map changes the whole AAS file HAS to be recalculated in order to play with bots.

### Testing AAS files

One of the easiest ways to test the AAS file is to load the map in Quake3 in teamplay mode (type /set g_gametype 3 on the console before loading the map). Enter a team and add a bot to your team. Use the team order menu (by default bound to the key F3) to command the bot to follow you. Walk around the map and see if the bot is able to follow you everywhere.

Map bugs can sometimes cause certain places in the map to show up 'solid' in the AAS file. The bots cannot travel through these 'solid' areas. To test for these 'solid' places set the cvar bot_testsolid to 1 on the console. (type /set bot_testsolid 1) The map has to be started with devmap instead of map before the cvar bot_testsolid can be set. When the cvar is set to 1 then either "empty area" or "SOLID area" will be printed on the screen while traveling through a map.

Several map bugs can cause these 'solid' places in the AAS file.

    - Sometimes microscopic brushes are left over after a brush CSG. Search
      for such brushes in the problem area and delete them.

    - Tiny brush faces (not curves) can also cause problems. Due to vertex
      snapping in the q3map tool those tiny brush faces can be snapped out
      of existence. Such faces will not show up in Quake3 and you'll see
      tiny peek holes or slits where you can view through the geometry.
      Allign vertexes of and edges of adjacent brushes to remove and avoid
      such tiny faces. Placing a clip brush in front of the face that is
      snapped out of existence will also remove the 'solid' area but ofcourse
      it's much better to remove the peek holes and slits.

    - Another cause could be a brush with a collapsed side. Check how many
      sides a brush has and how many sides actually have a surface. Rebuild
      brushes with collapsed sides.

    - All faces contained within liquid brushes using a shader without
      "surfaceparm trans" set will be removed. Those contained surfaces will
      not be visible and can cause the lava to appear "solid" in the aas file.

Clusters can be tested with the cvar bot_testclusters. (type "/set bot_testclusters 1" on the console)

Jumppads can also be tested. Type the following on the Quake3 console before loading your map:

    /set bot_maxdebugpolys 1024
    /set bot_visualizejumppads 1
    /set bot_forcereachability 1

Now load the map. A counter will be shown and goes from 0% to 100%. When the counter has reached 100% type /set r_debugSurface 2 on the console. For every jumppad the default arch of travel (without using air control) will be visualized.