Q3Map2Toolz manual

By Hero "Hr.O" Walter de Haan

Thanks to:

-Lanzelot for developing Q3Map Explorer on which this program’s GUI is based

-Equim for developing mapacker (not mappacker) a pk3 building app that is shipped with Q3map2Toolz.

-Ydnar for developing q3map2 the map compiler for Quake3 engine games I made this program for.

-the peeps from irc.enterthegame.com #lvldesign and #q3map

-The quake3world level editing- and map-center- forum  members.

-And the peeps I forgot to mention :-)

 

Setup screen:

 

 The screen on the left is the first thing you will be presented with when you start Q3Map2Toolz for the very first time.

The first thing to do is to select the game you will be working with. Currently they are: Quake3Arena, Return to Castle Wolfenstein, Wolfenstein - Enemy Territory, Startrek Voyager Elite Force, Soldiers of Fortune 2 and Jedi Knight2. Both single and multiplayer are supported.

If you select a game you have been working with before, the paths of the game.exe and bspc.exe are automatically filled in 

Next thing on the list is to browse to the folder that contains the game executable. You do this by clicking on the browse button. Do the same for q3map/sof2map and if needed the botfile compiler (bspc).

I also provided an option to use a custom log-file path. By default it's a subfolder of the  Q3Map2Toolz  folder.

Few extra things;

"preserve compiler path" prevents Q3Map2Toolz from erasing the paths to q3map/sof2map when changing the game.

"more compilers" in case you'd like to use more then one version of a map compiler, you can check this box and two extra thingies will show up.

If you filled in all the paths the Ok button should become enabled. Press it to go on to the main program

note: I expect you have a full mapping installation running on your system, but if you do not have a "maps" folder you will be prompted by the program to create one. 

 

 

Main screen:

 

 This is the main program screen.

 

-Select files:

here you can select the file you want to work with.

on top you can select the type (*.map, *.bsp or *.reg)

underneath you can change the base folder, it will only display the ones that contain a \maps subfolder.

Down the bottom there are two buttons, Devmap for instantly running the selected file (if there's a *.bsp)

and the Refresh List which does just that.

 

-Command lines:

Nothing much to say about that, but everything you do will end up in this window. next to it is the 

 

-Build button:

This simply copies the contents of the Command lines window into a compile.bat file and executes it :-)

 

Now before we go into the tabs let's first run you through the menus.

 

The Files menu contains three items.

-"Build" which is just the same as the build button,

-"Save as Batch" which allows you to save the contents of the command lines window into a custom batch-file.  -"Exit" the option that closes Q3Map2Toolz.

 

The Edit menu contains just two options.

-"Edit extra options" which allows you to edit the extra options. I will go into these later in this document. 

-"Configuration Tool" Will bring up the configuration tool to add, remove, and edit games, switches, arenas or reset the registry.

-"Set Paths" that brings you back to the screen you saw the first time you ran Q3Map2Toolz.

 

The View menu contains eight items.

-"Show arena editor" this one allows you to create or edit arena files. It depends on the game/type you work with if this item is enabled. Beneath it is the

-"Show Mapacker" this tool by Equim allows you to pack your map into a pk3 file. See the mapacker manual for more on that. Then there is

-"Show buildoption longnames" this is a checkable item which by means of tooltips allows you to view the complete title of a build option that is wider then the build options window. More on build options later in this document. The fourth item is the

-"Show explanatory hints" This enables tooltips for most of the buttons/checkboxes. After that comes my pride and joy.

-"Minimize to tray" if you check this option, next time you minimize Q3Map2Toolz it will use the system tray. use the right mouse button to display the tray-menu

-"Double-click function of tray-icon" if you check one of it's sub-options, the next time you double-click the tray-icon that function will be executed.

-"Minimize compiler window". This option does just that, If checked it will run the compiler in a minimized window.

-"Open monitor window" Clicking this option will open the q3map monitor window. more on that later on.

 

The Compiler logging menu also contains six items.

-"Make info file" if you have a *.bsp version of your map you can use this item to obtain some extra information about it. Use the

-"View Logs" item to view the infofile or log files of the currently selected map.

-"View a (log)file is a small browser window that allows you to browse for and view any text/log file on your computer.

-"Delete logs" removes all the *.log files from the logging folder.

-"Log all compiler output" does just that. if this item is checked every compile will be logged.

-"Delete logs before compile" with this item checked every time you start a compile the log file for that map will be removed. Else the logging option will append to the existing log file.

 

The Help menu contains three items

-"Q3Map2Toolz readme" which opens this document :)

-"Mapacker readme" opens the mapacker readme file. Try it to find out more about mapacker.

-"about" which is just that. It displays information about your Q3map2Toolz.

 

The Tray menu mentioned above has seven option

-"Restore" brings Q3Map2Toolz back to it's original size

-"Build" Does the same thing as the Build button

-"Devmap "Starts the game with the selected map

-"Refresh file list" reloads the filelists of Q3map2Toolz

-"Filelist" displays a list of all the files available

-"Buildlist" display a list of all builds available

-"End" closes Q3Map2Toolz

When you open the tray menu, you will find that one of the first three options is highlighted, This is the double-click function of the tray-icon

 

Next come the tabs:

 

Build options

First thing that catches the eye is the big window. it contains prefabricated build options. select a build and Q3Map2Toolz will automatically set the appropriate switches and options. The only thing you have to do is to press the build button.

You can add, remove, or edit this list with the three buttons underneath the window.

note: when mapping for jk2/sof2 you might as well delete the "prefabs" that contain BSPC since jk2/sof2 don't need *.aas files

 

Here is a quickie on how to add to the list: first click the "**NONE**" option, then go trough the following  tabs to select the build you want to create. Next you go back to the build options tab and click the add button. it will open a little dialog box with a few checkboxes and a text window. in the box you type a name, say "my lines" then you check the boxes of the stages you want to be recorded. finally you click the ok button and hey presto your new build will show up in the build options list. Editing works pretty much the same, it just that you first select a build.

 

The following options will affect Bsp, Vis, and Light stages.

 -fs_base  IMHO it  is pretty useless in this state :-)

- threads. Although q3map uses win32 multithreading you can manually set the number of processors in your system with this switch.

"monitor q3map output" uses -connect to set up a network connection (using ip and port next to it) between q3map and Q3Map2Toolz. When checked, upon starting a compile this option will open a text window which displays the output from the compiler. (I find this useful when logging compiles. Pity though  bspc doesn't support monitoring) note: this option does not work with sof2map.

 

BSP

On the upper left of this tab there are three option buttons

-none which does nothing

-normal which is a standard first stage for a compile

-custom This enables the checkboxes in the options frame

 

Underneath those are three more option buttons. with these you can select one of the three possible compilers you can select in the paths/preferences window.

(if you haven't selected a second or third compiler these option buttons are invisible)

 

On the left there are two checkboxes:

-"Wait after BSP" this option will pause after the bsp-stage and ask you to press the any key :-)

-"log BSP stage" enables logging of this stage of the compile. note: This will disable q3map feedback in the dos window, You might want to use the monitor q3map output function to compensate.

 

Underneath there is the "Run BSP" button which does just that. any option button or check box you select will be used, but keep in mind, it will not use the text in the command lines window

 

finally the BSP options, I'm not going into the switches.

Read the q3map2 manual to get more info (I'm planning to ask the responsible peeps to add the extra documentation.)

 

NOTE: if you use any but the latest version of Ydnar's q3map2 some of the switches/options might not work. 

 

VIS

On the upper left of this tab there are four option buttons

-none which does nothing

-fastvis which is a fast but very loose visibility calculation

-fullvis which is the standard visibility calculation

-custom This enables the checkboxes in the options frame

 

Underneath those are three more option buttons. with these you can select one of the three possible compilers you can select in the paths/preferences window.

(if you haven't selected a second or third compiler these option buttons are invisible)

 

On the left there are two checkboxes:

-"Wait after VIS" this option will pause after the vis-stage and ask you to press the any key :-)

-"log VIS stage" enables logging of this stage of the compile. note: This will disable q3map feedback in the dos window, You might want to use the monitor q3map output function to compensate.

 

Underneath there is the "Run VIS" button which does just that. any option button or check box you select will be used, but keep in mind, it will not use the text in the command lines window

 

finally the VIS options, Read the q3map2 manual to get more info (I'm planning to ask the responsible peeps to add the extra documentation.)

NOTE: if you use any but the latest version of Ydnar's q3map2 some of the switches/options might not work. 

 

LIGHT

On the upper left of this tab there are five option buttons

-none which does nothing

-fast which is a quick light calculation. downside of it is a bit darker level as opposed to -light

-light which is a standard light calculation.

-super 2 which is a more extensive/precise light calculation.

-custom This enables the checkboxes in the options frame

 

Underneath those are three more option buttons. with these you can select one of the three possible compilers you can select in the paths/preferences window.

(if you haven't selected a second or third compiler these option buttons are invisible)

 

On the left there are two checkboxes:

-"Wait after Light" this option will pause after the light-stage and ask you to press the any key :-)

-"log Light stage" enables logging of this stage of the compile. note: This will disable q3map feedback in the dos window, You might want to use the monitor q3map output function to compensate.

 

Underneath there is the "Run Light" button which does just that. any option button or check box you select will be used, but keep in mind, it will not use the text in the command lines window

 

Finally the Light options, I'm not going into the switches.

Read the q3map2 manual to get more info (I'm planning to ask the responsible peeps to add the extra documentation.)

 

NOTE: if you use any but the latest version of Ydnar's q3map2 some of the switches/options might not work.

 

BSPC

On the upper left of this tab there are four option buttons

-none which does nothing

-normal which creates a standard *.aas file

-normal which creates a optimized (read smaller) *.aas file

-custom This enables the checkboxes in the options frame

 

On the left there are two checkboxes:

-"Wait after BSPC" this option will pause after the bspc-stage and ask you to press the any key :-)

-"log BSPC stage" although bspc creates a log-file every time you run it, this option provides the possibility to use Q3Map2Toolz's default log folder

 

Underneath there is the "Run BSPC" button which does just that. any option button or check box you select will be used, but keep in mind, it will not use the text in the command lines window

 

finally the BSPC options, I'm not going into the switches.

Read bspc.txt to get more info. You can find it in the GTKRadiant\compile_manual folder

Just a short word on the -cfg switch, If you plan on using a *.c or *.cfg file you will need to put it in the same folder as bspc.exe is in.

 

NOTE for RTCW-SP: Q3Map2Toolz  will by default use the cfg-files mentioned in the RTCW + GTKRadiant, Getting Started Guide. Oh and due to the limitations of bspc.exe, upon running bspc Q3Map2Toolz will delete the old *.aas files of the map.

 

Game

Last of the tabs is the "Game" tab

This tab can differ depending on the game and  mp/sp

 

On the upper left again there are some option buttons.

They define the mode you map is being run in.

Generally there are map and Devmap, Devmap  allows for cheats, map doesn't. if SP is in front of them, bots will be loaded in game. (In some instances you will need a so called *.arena file, use the arena editor to create one)

 

Next to it is the "Run Game" button which does just that. any option button or check box you select will be used, but keep in mind, it will not use the text in the command lines window

 

below it are if the game/modus provides for them, the game types. I think they speak for themselves :-)

 

NOTE2: Running a singleplayer game Will cause you to lose your current savegame, so back it up (current.svg for RTCW)

 

Q3Map Monitor

The Q3map Monitor is a feature of Q3map2Toolz which allows a mapper to view the state of his build. In a way it's a form of logging your build but there is more to it. First of all in this way you can look at and scroll back while your build is still running. Even worse, you can watch what your build is doing even when your are logging it :-p. And if that's not enough, you can watch a compile from over a network.

 

This is what the monitor looks like when you open it by clicking the "Open monitor window" or starting a build using the "Monitor q3map output" option.

If you start a build  using the later one, the "instances" will tell you the amount of stages that is currently being monitored. If you opened the monitor via the view menu you can fill in the amount of connections (read stages)  the monitor is to be expecting. (max is 9)

Beneath it is a bit of blue text. this will give you the state of Q3map2Toolz's server state. it has three stages: "No Connection", "Listening", and "Connected" I think the 1st and 3rd option speak for itself.. the 2nd one means that the server is waiting for Q3Map to connect.

Next to those is the start/stop button. With this button you can manually stop or start ("instances" times)  Q3Map2Toolz's server.

 

The other functions are pretty much self explanatory so I'll leave the explanation at that.

 

Configuration tool:

-With this new version of Q3Map2Toolz you can edit/add/remove your own games, switches, and arenas. You can do this by using the configuration tool.

You can start this tool in two ways. Via the edit menu in Q3Map2Toolz, or the shortcut in the Q3Map2Toolz menu (start > programs > q3map2toolz)

To add a new Game:

   -fill in a long name (Quake3 Arena)

   -Fill in a shortname(Quake3)

   -Fill in the -game statement (wolf for RTCW etc.)

   -Fill in the base folder (the folder with the game content)

   -Don't forget to add the name of the game-exe

   -If the game uses bspc.exe, set the bspc-radio button to yes

   -If the game has a single player option set the spmap-radio button to yes

   -Some games use +set nextmap to run a level, set this radio button to yes if this is the case

If you have all that, you can press the 'add' button. And presto, you have one new game

To edit/replace the game. Just select the game from the dropdown menu. Edit the option you want to change and press the replace button.

 Deleting a game works about the same, select the game from the dropdown menu, and press the delete button

 

To add a new Switch:

  - First select the game, or generic

(all switches files are in the switches folder, they are called sw<short name of the game>.dbl. If that file doesn't exist, one will be created from the generic file called switches.gnr)

  - Select the stage

 (these correspond with the tabs in Q3map2Toolz except for *game, this one is for the gametypes on the 'game' tab, the configuration tool will change accordingly)

  - Now if you add a switch you can fill in the name (don't forget the minus - sign), if you want to edit a switch, you need to select it first

  - Next thing on the list is to decide if it needs an additional variable and what type it is (like the 3 in -bounce 3). I think the list is pretty much self explanatory

  - Last bit is the socalled tooltiptext, this is the text that pops up if you hold your mousepointer over a switch (providing you checked the 'show explanatory hints' option in the 'view' menu)

If you have all that, you can press the 'add' button. And you got yourself one new switch

To edit/replace a switch. Just select the switch from the dropdown menu. Edit the option you want to change and press the replace button.

 Deleting a switch works about the same, select the switch from the dropdown menu, and press the delete button

 

To add a new Arena:

  - First thing to decide is if you need to provide for bots, so set that radio button accordingly

  - Now if you want to edit an arena, you select the game from the upper 'Existing arenas' dropdown box

  - If you want to add an arena, select the game from the lower 'possible new arenas' box

  - Next there are three checkboxes that enable some extra input. This part is still under consideration and probably will change

  - Coming onto the gametypes, in this dropdown box you can add, remove, replace the names of gametypes the game supports (like ffa, ctf )

  - Last bit only counts if you provide for bots, in this dropdown box you can add, remove, replace the names of the bots the game supports

The rest is the same as switches and games

 

Last tab on the tool is the registry, no explanation from me, the buttons and tooltips do all the explaining :-þ

 

Ohh before i forget, if you click any of the 'Close' buttons, you will automaticaly restart Q3Map2Toolz, use the exit button on the last tab or the little 'x' on the top-right if you don't want to start Q3Map2Toolz.

 

note: whatever you do with the tool, Do not use comma's (,) These are used as separators. You can seriously fugde up the parsing of files which can cause all sorts of errors (Q3Map2Toolz exploding)

 

Troubleshooting:

-There have been reports of Q3Map2Toolz not showing up on the desktop. If this happens to you, Exit Q3Map2Toolz go to start > programs > Q3Map2Toolz. You will find a shortcut called "configuration tool" Run it, go to the last tab and click the "Clear Locations" button. After that Q3Map2Toolz should run as normal.

 

-Some Win NT/2K/XP users have reported an error When clicking the build-button. I'm not sure what's causing this. The only thing i can think of is to install Q3Map2Toolz when logged-in as an administrator.  

 

-If you run into a so called "runtime error " make sure you have  installed the Visual Basic6 Runtime library. You can find this package at www.microsoft.com

 

I think that is about it there is to be said, the arena editor generally speaks for itself

 

If you have any questions or suggestions (bug reports are welcome too) please do email me at: hro@planetquake.com

Oh and don't forget to visit my website http://planetquake.com/hro for the latest version of Q3Map2Toolz.