Become a Quake Modder

[MadGypsy]

Setting up the build menu in Radiant for Q1BSP compiling

NOTE: This tutorial was written and tested on/for winXP. This is not to say that it will not work if you have a different windows. I am saying that I personally do not know if it will work. Also, where I explain an apparent impossibility, it is because I have tried every logical and illogical thing I could think of to change the apparent impossibility and none of it worked. If you know something that I don't...please share it.

Understanding the Radiant build menu

Radiant uses an xml document to store build commands, it can be found in .../pathToRadiant/q1.game/(default_)build_menu.xml*. This file can be opened with any word processor. I personally deleted all the data in the stock build menu and wrote my own.

* default_ NetRadiant only

Before I begin I would like to state that you should know what compile tools you intend to use before modifying the build menu. There are many tools available and they all come with their own features that make them special. For the remainder of this tutorial I will be using hmap2.exe as it is an all-in-one compiler. If you choose to use something else, simply substitute my "hmap2.exe" with the proper name for what you are using (ie...Wvis.exe, etc). You need to put your compile tools in C:/Path/to/radiant/ as that is the system that this tutorial utilizes.

Making sure you are set-up properly

This is where it gets a little raw. If you are using GTKRadiant you do not have the power to set your GameName. Sure you can go to the local.prefs file (found in C:/Documents and Settings/username/application data/radiantsettings/1.5.0/q1.game/local.prefs) and change [GameName], but GTKRadiant will just set it back to "id1" when you click build. This means that GTKRadiant users will have to use a different method. I will explain both the GTK and portable Net radiant methods for setting up an auto- build and test menu. If you are not using NETRadiant with portability then I think the GTK radiant way applies to you, because there is a C:/Documents and Settings/username/application data/NETradiantsettings/ folder, that has all the same stuff that the gtk one does.

Note: The GTKRadiant merhod also works on NetRadiant portable. The only difference being where the files that you need to modify are located. Really it comes down to, do you want NETRadiant to determine your game directory or do you just want to type it into the .bat (GTK way). I like Netradiant way because the .bat is not static beyond the engine (I would make that dynamic too if I could figure out how.)

Open local.prefs -

GTKRadiant
C:/Documents and Settings/username/application data/radiantsettings/1.5.0/q1.game/local.prefs
NETRadiant (portable!)
C:\path\to\radiant\settings\1.5.0\q1.game\local.pr efs

first you want to make sure that this line points to the proper build_menu.xml file.

<epair name="BuildMenu">C:/path/to/radiant/q1.game/(default_)build_menu.xml</epair>

next make sure that your engine path is correct. This does not have to be C:/Quake. It is wherever your engine is located.

<epair name="EnginePath">C:\Quake</epair>

NETRadiant (portable style) ONLY

<epair name="GameName">QungFu</epair>

Creating our .bat

This is going to be a little "helper" file that allows us to load our game after it compiles. Regardless of Radiant type you need to open up a blank text document and save it in/as:
C:\path\to\engine\go.bat. From there choose the below method that suits your radiant.

GTKRadiant
go.bat

cd /d %~dp0
darkplaces.exe  -game "nameOfYourModFolder" +map  %~n1

-include the quotes

NETRadiant (portablized)
go.bat

cd /d %~dp0
darkplaces.exe  -game %1 +map  %~n2

Of course you can switch "darkplaces.exe" for any engine you like as long as you actually have it.

Defining the build menu

Let's look at the top of the document structure for (default_)build_menu.xml

<?xml version="1.0"?>

This is the beginning of any xml document ever, just leave it alone. Consider this the DOCTYPE if you know what such a thing is.

<project version="2.0">

This is opening the project "tree" where all build options will be categorized.

-------------

There are tokens (placeholders) that can be used in the build menu. Depending on what token you want to use and what radiant you are using, it is defined in local.pref. In the case of all Radiants [EnginePath] and [RadiantPath] are customizable tokens. In the case of only NetRadiant portable [GameName] is also a customizable token. I will approach the basic options that are universal first and then I will branch off into the 2 Radiant methods for automatically loading your map in an engine, using a mod folder.

  <var name="bsp">"[RadiantPath]hmap2.exe"</var>
  <var name="vis">"[RadiantPath]hmap2.exe"</var>
  <var name="light">"[RadiantPath]hmap2.exe"</var>

What the above is doing is creating a var named bsp and defining it's path. In essence: var bsp = "C:/path/to/radiant/hmap2.exe"
*re: for vis and light

----

Now that you have created the vars we can use them. Since hmap2.exe is an all-in-one compiler, it has to be -switched with the compile type you want to use. If none is specified it assumes you are using it to build the bsp. "[MapFile]" is dynamic and will be whatever the name of your map is. technically the token is [MapFile]. The quotes are added so the compiler(s) (and engine) treat it like a string.

 <build name="build">
    <command>[bsp]  "[MapFile]"</command>
    <command>[vis] -vis  "[MapFile]"</command>
    <command>[light] -light  "[MapFile]"</command>
  </build>

</project>

- this closes the project tree and consequentially the entire document. Anything you put after this will be considered garbage and wont be read.

-------

Understanding more

Earlier I stated that all the compilers come with their own little features that make them special. Since I have used hmap2.exe for my examples, I will continue to use it to illustrate compile options.

Hmap2.exe has a bsp option to allow huge polygons (-darkplaces). It also has vis options to remove ambient sound (-noambientsky), and a light option to increase the light in the darkest areas (-minlight 15 {can be any number 0 to 255, with 255 being fullbright}). There are many more options and whatever compiler you use, you should definitely read the read_me and learn what it is capable of. I explained one option for each level of compilation so I could show you how it should look in the build menu.

 <build name="build">
    <command>[bsp]  -darkplaces "[MapFile]"</command>
    <command>[vis] -vis  -noambientsky "[MapFile]"</command>
    <command>[light] -light -minlight 15 "[MapFile]"</command>
  </build>

You do not have to have just one option. You can have as many as you like.

<command>[light] -light -extra4x4 -minlight 15 "[MapFile]"</command>

---

So far your entire radiant build menu should resemble this

<?xml version="1.0"?>

<project version="2.0">

  <var name="bsp">"[RadiantPath]hmap2.exe"</var>
  <var name="vis">"[RadiantPath]hmap2.exe"</var>
  <var name="light">"[RadiantPath]hmap2.exe"</var>

 <build name="build">
    <command>[bsp] -darkplaces "[MapFile]"</command>
    <command>[vis] -vis -noambientsky "[MapFile]"</command>
    <command>[light] -light -extra4x4 -minlight 15 "[MapFile]"</command>
  </build>

</project>

The Road Forks

Here is where we create a new variable and use it as a command to start our engine, from a mod folder, on the map we just compiled. No matter what radiant you use, you need to add this line after "light" line:

<var name="go">"[EnginePath]go.bat"</var>

Then add the line below that applies to you

GTKRadiant
you need to add this after the [light] line.

<command>[go] "[MapFile]"</command>

NETRadiant (with portableness)
you need to add this after the [light] line.

<command>[go] "[GameName]" "[MapFile]"</command>

Multiple Builds
You can create multiple builds that utilize different features. Here would be an example of that

<?xml version="1.0"?>

<project version="2.0">

  <var name="bsp">"[RadiantPath]hmap2.exe"</var>
  <var name="vis">"[RadiantPath]hmap2.exe"</var>
  <var name="light">"[RadiantPath]hmap2.exe"</var>
  <var name="go">"[EnginePath]go.bat"</var>

 <build name="simple build">
    <command>[bsp] "[MapFile]"</command>
    <command>[vis] -vis "[MapFile]"</command>
    <command>[light] -light "[MapFile]"</command>
    <command>[go] "[GameName]" "[MapFile]"</command>
 </build>

 <build name="big map build">
    <command>[bsp] -darkplaces "[MapFile]"</command>
    <command>[vis] -vis -noambientsky "[MapFile]"</command>
    <command>[light] -light -extra4x4 -minlight 15 "[MapFile]"</command>
    <command>[go] "[GameName]" "[MapFile]"</command>
 </build>

</project>

Whatever you name a build, is the option that will appear in the Radiant build menu. So, if I clicked build in NETRadiant (using the above build data) I would be presented with the options "simple build" and "big map build".

How do I make NETRadiant portable?
1) Create a folder named "settings" in C:/path/to/NETRadiant/
2) start NETRadiant
that's it.

How did you figure out GTKRadiant's local.pref directory?
When you are compiling in radiant (any) the output window tells you where it saves junk.txt. That is your directory, no matter which radiant you use, that (apparently) will be the directory with all the configurations that are being used.

Well, that ends the tutorial for now. It is "complete", but I can do better. This will be edited a few more times as I run more tests, revise the explanations and develop a "master" build menu that includes all (current) q1bsp compilers. Stay tuned.

[golden_boy]

Dude, nice tutorial! Props for helping others like that.

The default_build_menu.xml is always in a folder called q1.game, which is part of the gamepack. Under Linux, it might be located wherever your Radiant directory is, or in /home/username/.netradiant (the dot is important).

I think it's unlikely that there is a conflict between DP and Radiant; this because Radiant operates on .map files while DP operates on .bsp files.

What happens in the build script is:

Radiant tells the compiler to build a bsp file.

The compiler creates a bsp file and quits.

At this point, Radiant doesn't care about that file anymore.

For an engine to load a bsp file, make sure it is located either in quake/id1/maps or in quake/yourmod/maps. In the latter case, you need to use the -game yourmodname switch when running the engine.

Not sure what else could be the problem - hard to diagnose from here :-)

[MadGypsy]

I think it's unlikely that there is a conflict between DP and Radiant

Yeah, I doubted it too, for the same reasons you said. I was just grasping at straws to try and understand why DP can't find the game. I know that I have everything in the proper folders, no typos, etc. It just doesn't make sense.

[golden_boy]

In Radiant's Preferences you can check "Start engine after compiling" and in the gamepack's config file, you can tell it what the engine binary is.

I just did a test run like that - and it did start FTE after compiling. Which didn't start up correctly, similar to your case.

Not sure if you can pass parameters to the engine somehow, which would be required to start it up properly.

Actually, since you are already using bat files to start the engine, why not use a bat file to do all the map compiling too. Much more flexible?

[MadGypsy]

Much more flexible?

Hmmm, I'm not sure how it would be more flexible as I can include all the switches and compiling tools that I want in the build xml. I guess I could make it more flexible if I wanted to make an options interface out of the bat, but technically I could just add another <build> with those options.

I tried the "Start engine after compiling" option a few times in the past and it would never start the engine. It gave me an error saying that I need "something" turned on that either a)my computer can't handle or b) I can't figure out how to enable (can't remember which one it was). Oh wait, I do remember it was sort of the former. I enabled the thing it told me and then it gave me errors that sounded like my computer didn't like that option.

I'm going to do this differently. I have an idea. I am going to write a "start engine" bat that accepts a switch for the map name (probably identical to my bat above). Then instead of running it from radiant, I'm going to run it from the command line. When I get that to work without radiant, I will then tie it into radiant and see what happens. If it doesn't work I will at least be positive at that point that it is a radiant problem. From there I can (hopefully) determine why and fix it.

I have a feeling this has something to do with radiant and my engine being in 2 entirely different locations, hence the "cd /d %~dp0" in my bat. I need to echo %1 again. something tells me it is actually spitting out an entire path. If so i can easily strip the path down to the filename before processing it into darkplaces.

I'm going to figure this crap out and when I do I will edit my last tutorial to be complete and "all encompassing". Actually I am going to go even further than that. I am going to compile a "master" build xml that has various build options using all of the available compile tools for q1bsp (hmap2, txqbsp, wvis, light, etc) with the most common switches for compiling as options.

This will of course NOT be definitive as it would be impossible for me to cover every single solitary possible combination BUT it WILL

a) be an awesome example
b) need nothing more than to be edited as opposed to understood and completely rewritten

For instance (ex) -noambientsky will not be in any of my build options, but for those that need it they would simply need to add that switch to the <build><command> that applies. This can actually be done in radiant through the customize option in the build menu.

NOTE: If you are using NetRadiant configured to be portable, customizing through the build menu creates a "temp" file in the settings folder and radiant will no longer read the original build.xml (took me forever to realize this). The huge problem with this is that it will start giving you errors, cause the "temp" is broken and saves the xml as escape characters (ie &lt; instead of <). So net radiant + portability = can't faithfully customize from the build menu. I never do it this way anyway cause I can write the xml by hand faster than I can navigate the customization widget.


IDEA - What if I wrote a PHP script where you could go to my webpage, select the options you want to use, click a little button and my script would write the xml for you, gather the appropriate build tools, zip it up and give you a link?

The perks to this is, I would have to include every option switch for each individual tool. So aside from the ease factor, people would be able to see the options that each tool provides and make a decision which build tools are right for them.

This is just an idea. i am not committing myself to this. If it's like 1 or 2 people that want this, I'm not going to go to all the trouble. If it's like 100's of people that want this. I'll skip the php and make it a downloadable flash/maybe AIR app. That way you will already have everything on your comp and my app will simply "orchestrate" the information for you according to your specifications.

[golden_boy]

One reason why I think it is more flexible is because Radiant is no longer actively maintained. Faster to roll your own than try and get radiant to cooperate. But I'm curious if it's possible to get this working, of course.

[MadGypsy]

I will get it working. The only way I will not get it working is if it is completely impossible (which I refuse to believe is true since I can get darkplaces to load on command). The only "roadblock" is getting it to load the actual map. The ONLY reason this can be is because %1 is wrong in some way. I know I echoed it before and it spit out what I expected. Maybe something else was wrong at that time. Time to start from scratch and go over each step one at a time.

Faster to roll your own than try and get radiant to cooperate.

I agree. I have this thing though where I want ONE program to do what the program was intended to do. Creating an external bat is not as elegant as having the xml do what the xml was intended to do. Also xml is a simple little format that has a very simple to (humanly) read structure. .bat files are a mess, just line after line of arbitrary commands and the basic user could get lost very easily if they wanted to modify it. The .bat I am attempting to perfect will never need to be modified. It will do nothing but accept an argument and pass it to darkplaces. The argument will be determined by the name of the map and passed by radiant. In a sense, my bat is "silent". It's like your boss hands you a check, you hand the check to the bank and the bank hands you back money. Using an external bat to handle the entire compile is like: your boss hands you a check, you counterfeit it, hand it to the bank and the bank hands you back money. In a perfect world i'll get this working on a "direct deposit" level.

nana nana nana nana .bat Man (?lol)

[MadGypsy]

Oh man! (heehee) I not only have it working 100%, I have it working from a mod folder 100%. I don't know why I struggled so hard for no results before, cause I walked right to success on the 3rd try this time and even expanded the idea away from ID1 folder.

THE FIX:

run_from_radiant.bat - %1 is the first argument I pass [GameName], %2 is the second [MapName] which is the map, but I prepend it with ~n to strip out the directory "C:/some/crap/I/dont/want/mymap" becomes "mymap".

cd /d %~dp0
darkplaces.exe  -game %1 +map  %~n2

default_build_menu.xml - of course you will need to add your own switches, this is bare minimum.

<?xml version="1.0"?>

<project version="2.0">

  <var name="bsp">"[RadiantPath]hmap2.exe"</var>
  <var name="vis">"[RadiantPath]hmap2.exe"</var>
  <var name="light">"[RadiantPath]hmap2.exe"</var>
  <var name="go">"[EnginePath]run_from_radiant.bat"</var>
 <build name="build">
    <command>[bsp]   "[MapFile]"</command>
    <command>[vis]    "[MapFile]"</command>
    <command>[light]  "[MapFile]"</command>
    <command>[go] "[GameName]" "[MapFile]"</command>
  </build>

</project>

local.prefs - change these values to suit you. QungFu is my mod folder inside of C:/Quake

<epair name="EnginePath">c:/Quake</epair>
<epair name="GameName">QungFu</epair>

I will rewrite my tutorial at a later time.

[golden_boy]

This is how Radiant tried to start the engine when I checked that option:

/home/jonas/quake/fteqw.gl +set sv_pure 0 +set fs_game scouts +devmap map01_q3

There are several problems with that.

1) What are those extra arguments; why is it not using -game and +map to load the map?

Turns out, when I looked into Radiant's code, they are hardcoded. It does some primitive lookup of what the game is and decides on command line options like this:

inline void GlobalGameDescription_string_write_mapparameter(St ringOutputStream& - Pastebin.com

I guess I could change those and just recompile radiant. But that's not viable for the normal user.

2) It assumes the map is in the correct place and does no check on this. Ideally it should check where it loaded the .map from and copy the .bsp over before running the engine.

Meh.

edit; your solution looks good, the problem I described only happens when checking the "run engine after compiling" checkbox, ie trying to do it completely without external scripts.

[MadGypsy]

1) What are those extra arguments; why is it not using -game and +map to load the map?

+gamedir and +map works. I just tried -game and +map and that works too. Is -game +map the standard? I'm assuming it must be if you are asking me why I am not using it. I will change my example to suit.

edit. I changed my example and corrected an error. The error was in my explanation, not the code.

[golden_boy]

Oh, this is a misunderstanding. I'm not asking you why you're not using it - my post was written before I had seen your last, long post.

What I wrote pertained to Radiant's own code and what Radiant does when you check the box "start engine after compiling" in the Preferences menu.

It has nothing to do with your bat script / the build menu XML; I was complaining about the hardcoded way to start the engine in Radiant's c++ code, which IMO sucks.

[MadGypsy]

Ah, I went back and re-read. Yeah I don't know how I missed that, you made it really clear.

I rewrote the hell out of the tutorial. I'm sure there are grammatical errors and typos. It definitely needs editing, but it is complete.
Build Menu Tutorial

[Mike_Tyson]

Personally, I'm not a huge fan of the skybox for Quake. My current map has no sky, nothing, black. It makes you feel very alone and screwed. Like, even if you get out of wherever you are there is nothing to escape to. I realize that this works because of the theme of the map and the textures I chose. That is exactly my point. Getting caught up in amazing skyboxes is easy to do and in that you could easily junk up your map. Imagine if I added small, whispy, cloud-like particle clouds that lazily wafted by, at random altitudes, against the black and within the "play area". Totally creepy and probably realistic (using particle fonts). This is something you should consider before just throwing some amazing skybox around your map. What does your map want? My map wants solitude, not Desert Ruin...

Thanks MadGypsy for this description and also the clarification about the file name mixup at (http://quakeone.com/forums/quake-hel...tml#post114547). With this info I managed to include skyboxes in my maps!

Just as a side note: I am also interested in how to actually make the skymaps themselves. I'm not there yet but one program that can be used for this is terragen I think. Also I could imagine povray can come in handy. I haven't learned yet how to do this in detail, but I think it should be possible to make novel skymaps from computer generated scenes as well as from photographs.

About the esthetics of skyboxes: in principle I agree that a black sky can be more effective than any fancy skybox. However I think it really depends on the level and the effect you want in a map. For example in the excellent Altar of Storms, necros used a very bright, lush, totally un-quake skybox to really great effect.

Another thing that I think could be really great, if you have a cramped, claustrophobic map with very small windows, which lets you glimpse at scenery like a big castle or a megalopolis; by this contrast, enhancing the claustrophobic feel even more.

Ah, and what are particle fonts?

[MadGypsy]

Sorry for the late reply. I have been busy and I didn't realize that my thread had a recent post. I'm glad you were able to get the skybox going.

Darkplaces actually has a way to turn a map into a skybox. You wouldn't take (ex) e1m1 and turn it into a skybox. This is because the skybox will be painted (i believe) relative to the player position. So, let's assume you were in the beginning of e1m1 and you told darkplaces to make a skybox. It would just look like the room you started in.

You would have to make a special map that only contains the "distance", skybox it and add it to your real map. I'm about 90% sure that I'm right on this. I KNOW DP makes skyboxes but I never tested it so I'm going off of memory of the DP docs on what actually gets painted to the skybox. If I am not mistaken - it is everything that can be seen from the players position in every direction. You could almost consider it like each side of the players bbox is a "lens". This may even be how LordHavoc did it, but it is beyond me to do more than assume such a thing.

A particle font is a collection of monochrome images that are used to stylize particle appearance/animation. Seven uses this often in SMC for things like fire, explosions, steam, rocket/bullet trails, etc. Consider a particle font to be a library of images to be used for special effects.

[Mike_Tyson]

I just tried this out. Interesting feature. However I don't think the envmap command is meant to generate actual skyboxes, but to generate what-ever-it's-called for environment mapping. My guess is, this is meant for environment mapping where you want the outside to reflect on a smaller object. For example if you had a shiny metal crate or similar object, and you want the immediate level architecture to fake-reflect on that object. In other words, this is for environment maps onto which you look from the outside, unlike skyboxes at which you look from the inside. Maybe to be used in conjuction with Q3-type shaders. Just my guess.

Side notes:
Yes, the rendering is relative to the player position.

Under Windows 7, the resulting images are saved (in TGA format) at a not obvious location, namely.

C:\Users\userid\Saved Games\darkplaces\id1\env