Search / View

[Breli]

 Introduction 

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.

Table of Contents

•  Radiant project files 
•  Compiling directly from Radiant 
•  compiling and testing your map from Radiant 
•  model generation from Radiant 
•  creating a map backup from Radiant 

[Breli]

 Radiant Project Files 

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.

The default_project.proj file looks like this:

Code: Select all

<?xml version="1.0"?>
<!DOCTYPE project SYSTEM "dtds/project.dtd">
<project>
<key name="version" value="2"/>
<key name="basepath" value="$TEMPLATEenginepath$TEMPLATEbasedir/"/>
<key name="rshcmd" value=""/>
<key name="remotebasepath" value="$TEMPLATEenginepath$TEMPLATEbasedir/"/>
<key name="entitypath" value="$TEMPLATEtoolspath$TEMPLATEbasedir/scripts/entities.def"/>
<key name="texturepath" value="$TEMPLATEenginepath$TEMPLATEbasedir/textures/"/>
<key name="autosave" value="$TEMPLATEuserhomepath$TEMPLATEbasedir/maps/autosave.map"/>
<key name="mapspath" value="$TEMPLATEuserhomepath$TEMPLATEbasedir/maps/"/>

<key name="bsp_Q3Map2: (single) BSP -meta" value="! &quot;$TEMPLATEapppathq3map2&quot; -v # -game quake3 -fs_basepath &quot;$TEMPLATEenginepath&quot; -meta $"/>

<key name="bsp_Q3Map2: (single) -vis" value="! &quot;$TEMPLATEapppathq3map2&quot; # -game quake3 -fs_basepath &quot;$TEMPLATEenginepath&quot; -vis $" />

... snipped several other declarations ...



A typical user0.proj like this

Code: Select all

<?xml version="1.0"?>
<!DOCTYPE project SYSTEM "project.dtd">
<project>
  <key name="user_project" value="1"/>
  <key name="brush_primit" value="0"/>
  <key name="bsp_Q3Map2: (simulate old style -light -extra) BSP -meta, -vis, -light -super 2" value="! &quot;C:/Programme/GtkRadiant-1.4/q3map2&quot; -v # -game quake3 -fs_basepath &quot;C:/Programme/Quake III Arena/&quot; -meta $ &amp;&amp; ! &quot;C:/Programme/GtkRadiant-1.4/q3map2&quot; # -game quake3 -fs_basepath &quot;C:/Programme/Quake III Arena/&quot; -vis -saveprt $ &amp;&amp; ! &quot;C:/Programme/GtkRadiant-1.4/q3map2&quot; -v # -game quake3 -fs_basepath &quot;C:/Programme/Quake III Arena/&quot; -light -super 2 $"/>

... snipped several other declarations ...

</project>


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.

Lets take a closer look at default_project.proj now:

Code: Select all

... snip

<key name="mapspath" value="$TEMPLATEuserhomepath$TEMPLATEbasedir/maps/"/>

<key name="bsp_Q3Map2: (single) BSP -meta" value="! &quot;$TEMPLATEapppathq3map2&quot; -v # -game quake3 -fs_basepath &quot;$TEMPLATEenginepath&quot; -meta $"/>

... snip


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.

[Breli]

 Compiling directly from Radiant 

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:

Code: Select all

<key name="bsp_Q3Map2: (single) BSP -meta" value="! &quot;$TEMPLATEapppathq3map2&quot; -v # -game quake3 -fs_basepath &quot;$TEMPLATEenginepath&quot; -meta $"/>


Here is the problem: $TEMPLATEapppath points to the wrong direction. It points to the compiler that comes with Radiant aka the vanilla version of q3map2. We can simply change that like this:

Code: Select all

<key name="bsp_Q3Map2: (single) BSP -meta" value="! &quot;$TEMPLATEtoolspathq3map2&quot; -v # -game smokinguns -fs_basepath &quot;$TEMPLATEenginepath&quot; -meta $"/>


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 them
3. Shut down Radiant and open it up again
4. 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.

[Breli]

 One Click: compiling and testing your map from Radiant 

Here is something that is very useful for me: I test my map very often during the first stages of development in order to check for scale and general layout. Here is how you can automate that:

Make the following entry in your default_proj.proj file:

Code: Select all

<key  name="bsp_AAS: compile and run (bsp, vis, light)" value="!  &quot;$TEMPLATEtoolspathcompile_run.bat&quot; $ &quot;$TEMPLATEenginepath&quot;" />


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!):

Code: Select all

"C:\Programme\Smokin' Guns Development\Zero Radiant\q3map2.exe" -game smokinguns -fs_basepath %2 -meta -v %1
"C:\Programme\Smokin' Guns Development\Zero Radiant\q3map2.exe" -game smokinguns -fs_basepath %2 -vis -saveprt %1
"C:\Programme\Smokin' Guns Development\Zero Radiant\q3map2.exe" -game smokinguns -fs_basepath %2 -light -fast %1

cd\
cd c:
cd programme\"Smokin' Guns Development"

smokinguns.exe +sv_pure 0 +devmap %~n1


Delete your user project files as usual and restart Radiant.

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.

[Breli]

 One Click: model generation from Radiant 

Here is another neat thing: creating models with one click.

Code: Select all

<key  name="bsp_AAS: makemodel" value="!  &quot;$TEMPLATEtoolspathmakemodel.bat&quot; $ &quot;$TEMPLATEtoolspathq3map2&quot; &quot;$TEMPLATEenginepath&quot;" />


Here is the batch file (Adjust the paths!):

Code: Select all

%2 -game smokinguns -fs_basepath %3 -meta -patchmeta -subdivisions 6 %1
%2 -game smokinguns -fs_basepath %3 -convert "%~dp1%~n1.bsp"

move "%~dp1%~n1.ase" "c:\Programme\Smokin' Guns Development\smokinguns\models\ase"

del "%~dp1%~n1.bsp"
del "%~dp1%~n1.tex"
del "%~dp1%~n1.srf"
del "%~dp1%~n1.prt"
del "%~dp1%~n1.bak"


Delete your user project files as usual and restart Radiant.

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

[Breli]

 One Click: creating a map backup 

It is prudent to backup your map. Particularly before you start to do major changes. Rather than copying the map file back and forth, you can do that more easily:

Code: Select all

<key  name="bsp_AAS: create map backup" value="!  &quot;$TEMPLATEtoolspathcreatemapbackup.bat&quot; $ ;" />


The corresponding batch file (Adjust the paths!):

Code: Select all

copy /y "C:\Programme\Smokin' Guns Development\smokinguns\maps\%~nx1" "c:\Dokumente und Einstellungen\Christian\Eigene Dateien\Daten\Smokin' Guns\Backup\%date:~6,4%%date:~3,2%%date:~0,2%-%time:~0,2%%time:~3,2%-%~nx1"


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).