Note: This is work in progress and will be updated every now and then.

This tutorial describes means to automate certain tasks in Radiant. In essence, it allows you to extend Radiant menus so that you can execute arbitrary scripts directly from Radiant. That gives you great flexibility and may make your mapping life a little easier. Additionally, it will give you a better understanding of some of Radiant files, when, how and why they are processed and what settings can be configured with them.

The tutorial assumes that you have a basic understanding of Radiant and the overall SG mapping installation. You should be generally familiar with the file structure and should know your way around in config files with a text editor.

I am using Zero Radiant (aka GtkRadiant 1.6.1) and my SG mapping installation is in C:\Programme\Smokin’ Guns Development. Obviously, you will have to change the paths to fit your installation. I will not point this out at every occasion. It is better to leave these files alone in case you don’t know what you are doing. All the changes should work with older versions of Radiant. However, I haven’t tested it yet. A tutorial for setting up Zero Radiant will added to the level editing section soon.

It goes without saying that you can easily break your installation when fooling around in these config files. I strongly recommend that you backup all files before you edit them. However, I never run into any problem I couldn’t recover from. Additionally, we are going to "abuse" Radiant a little since it was probably never intended to be used in this way. This solution is by no means elegant and there might be better alternatives out there. That being said, it works for me just fine

The tutorial proceeds as follows. Firstly, we’ll give an overview of some key configuration files of Radiant and explain what they do. Secondly, we are going to edit them so that you can compile directly from Radiant. Thirdly, we will run arbitrary DOS-scripts to get even more flexibility.

Radiant stores project specific settings in project files which are usually stored under …\smokinguns\scripts. In general, there are two types: a template file (called default_project.proj) and user files (called user#.proj where # is a number). The user project file contains the configuration settings of the current Radiant project. This one is loaded during startup and mainly controls any paths settings Radiant requires to execute other programs.

It is important to understand the following relationshop between these files: Radiant checks for a user project file each time it starts up. If there is one, it will load it and configure itself to the settings therein. In case there is no user project file, Radiant processes the default_project.proj file and creates a new user project file. Thus, any changes we are doing in default_project will be applied to every new user project file. We can simply delete the existing user files in order to get a new one (of course, this also means that the user file can be edited directly).

We will only change the default_project.proj fie for the purpose of the tutorial since I am trying to come up with a better version for our (i.e. SG) needs. You can probably make things easier (but less generic) when changing your user project settings.

Note: project files do not contain any “settings”. If you are after that, you should open “local.pref” which is located in your mapping tools directory (typically ..\Smokin’ Guns Development\Radiant-1.4.0\ or similar). In case you ever “lost” your default_project.proj file you can recover it from your radiant installation since Radiant comes with a default default_project.proj so to say.

The general structure is fairly simple. Basically, these are declarations that set a specific variable to specific setting. The thing is that anything with the dollar in front is a variable which expands to a concrete value when processed by Radiant. For instance, the variable $TEMPLATEapppath represents “c:\Programme\ Zero Radiant\” in my installation. Note: the values are taken from the sg.game file.

The variable “$” is a special case: it represents the current map file (including the path to it). Thus, when you are working on your project “thegreatestsgmapever.map” the dollar sign will equate to something like “c:\Programme\Smokin’ Guns Development\smokinguns\maps\ thegreatestsgmapever.map”. It is important to note that this variable is NOT replaced whenever the user project files are created. To sum up this whole business is about creating “strings” that execute programs with proper parameters.

This sounds more difficult than it’s actually is. So lets get to some examples.

Last edited by Breli on Sun Feb 01, 2009 11:15 am, edited 2 times in total.

SG name: =SG=BRELI

Harmonica: Did you bring a horse?Gunmen: Looks like we are short on one horse!Harmonica: No. You brought two too many.

As you know, we cannot compile directly from Radiant (by using the bsp menu) since we have to use “our” compiler. However, we can simply hack the default_project.proj file in order to point Radiant in the right direction. Here is what you need to do:

1. Locate your default_project.proj file under ..\smokinguns\scripts and open it with a texteditor.The entries that invoke q3map2 look like this:

Ok, what happened? I replaced $TEMPLATEapppath with $TEMPLATEtoolspath. Thus, whenever Radiant processes this file it’ll expand this variable to "C.\Programme\Smokin’ Guns Development\Zero Radiant\" instead of "C:\Programme\Zero Radiant\". That is the directory which contains our q3map2 version. I also changed the game switch from quake3 to smokinguns so that the compiler finds our files.

That’s it. You can simple replace $TEMPLATEapppath with $TEMPLATEtoolspath for all BSP_Q3Map2 entries in your default_project file. However, to make it finally work you need to do the following:

2. Locate your user#.proj files in ..\smokinguns\scripts and delete them3. Shut down Radiant and open it up again4. Radiant will create a new user project file and the BSP menu should now work just fine

Note: Radiant will not start up if you screw up the default_proj.proj file. Undo your last changes in that case. Usually, you have a syntax error somewhere.

Last edited by Breli on Sun Feb 01, 2009 11:16 am, edited 3 times in total.

SG name: =SG=BRELI

Harmonica: Did you bring a horse?Gunmen: Looks like we are short on one horse!Harmonica: No. You brought two too many.

This will do the following: the BSP menu will be extended by an entry called "AAS: compile and run (bsp, vis, light)". The entry will invoke a batch file called "compile_run.bat" which is located in your tools directory. This is usually "C:\Programme\Smokin’ Guns Development\Zero Radiant" or "C:\Program Files\Smokin’ Guns Dev\Radiant-1.4" or similar. Moreover, it will pass two parameters to the batch file.

Create a batch file "compile_run.bat" in your toolspath and copy the following code into it (Adjust the paths!):

That’s it. The parameters contain the map filename you are working on and the basepath. Delete your user project files as usual and restart Radiant. Your map will compile and be fired up in devmode whenever you click the new entry in Radiant.

This is a good example of what can be done: Radiant doesn't really care of what is invoked or not. Thus, you can call any script you want and, what is even more important, pass parameters to it so that you can flexibly automate things.

Last edited by Breli on Sun Feb 01, 2009 11:19 am, edited 2 times in total.

SG name: =SG=BRELI

Harmonica: Did you bring a horse?Gunmen: Looks like we are short on one horse!Harmonica: No. You brought two too many.

The batch file will compile your map respectively will make an ase model out of it. It’ll move your ase model in the right directory and will get rid of unneeded files. All within one click

The files are a bit difficult to read and look confusing. But once you get the hang of it, it is actually fairly simple to automate certain tasks. Thats it. So much for the little tutorial ... thanks for reading and let us know if you have any additions or questions. I will make additions to this list as they come to my mind. Next task for me is to create a primitive backup and versioning script ...

Cheers

Breli

SG name: =SG=BRELI

Harmonica: Did you bring a horse?Gunmen: Looks like we are short on one horse!Harmonica: No. You brought two too many.

I had trouble with the paths so I decided to hardcode them in the batch. The batch will create a copy of your map in the directory specified above. The copy will be named like this: 20090201-1803-yourmap.map where the numbers are date and time.

It is crude, yes, and not really nice but it'll do the job (at least for me).

SG name: =SG=BRELI

Harmonica: Did you bring a horse?Gunmen: Looks like we are short on one horse!Harmonica: No. You brought two too many.