This tutorial will give a brief introduction to the Quake 3 Arena Shader Editor (q3ase) developed by Bert Peers. We will go through how to set up the editor and how it works, and we’ll make a couple of shaders using the editor.
I am assuming a fairly good knowledge of Q3radiant: if you have only just started with radiant then don’t go learning about shaders yet. Learn radiant and then learn shaders.
You will need a copy of the shader manual (from www.quake3world.com/editing). It is simply not possible to make shaders properly without having read and understood most of it. The shader manual is dense and often technically difficult. To most people it is at first impenetrable, but part of the joy of q3ase is that it allows you to experiment with what you find in the manual and get good understanding of how everything works.
You should read as many basic tutorials on shaders as you can find. Read the tutorials. Read the shader manual. Don’t worry if you don’t understand all of it (you won’t), but read it through just to get a sense of how it is laid out and some of the basic concepts. And then start playing with q3ase.
Extract q3ase.zip file. It would be sensible to place all files in a folder called baseq3/tools/q3ase. Run the q3ase.exe file to start the editor. I suggest that you create a shortcut pointing to q3ase.exe to sit on your desktop or in your start bar.
When you run the editor for the first time, there are a couple of things that need setting up. First, the editor has to try to see if it can do 32 bits per pixel. Then it will prompt you to set up your .pk3 files. This is important because otherwise you won’t be able to see any textures. In the dialogue box go to your baseq3 directory and select the pak0.pk3. I would then suggest you add any other .pk3 files you are likely to want to use – including the q3ase.pk3 file. From the File Menu select Edit Pakfiles. Add in any .pk3 files and also add in your baseq3 directory. This will allow you to use any textures that aren’t in .pk3 files. Don’t add the actual folder the textures are in – this will confuse things – just the baseq3 directory.
The
global keywords that are usually found at the start of a shader
and which generally deal with how the shader behaves in
the game world will be dealt with later in this tutorial. For
the moment we will concentrate on how the shader looks.
A shader is built up of a number of stages. Many shaders have only one stage, some have as many as five or six. Almost all stages will use a texture and manipulate it to produce an effect. We control how the stage looks using the stage menu.
When you first load q3ase, there are no shaders in the tree view apart from a default blank shader. Click on the + symbols until the tree view is fully expanded as shown here. Clicking on a - symbol will contract that part of the tree view – very useful as the tree view can get cluttered when lots of shaders are loaded up.
To bring up the stage menu, right click on the words Stage 1 in the q3ase tree view.
Loading up a texture
Bring up the stage menu and
select Edit Texture Source. This brings up a dialogue box.
Map should already be selected so we’ll just click the Texture
button and the Texture selection box is brought up (see right).
In the bottom left hand corner make sure the Preview box is
ticked, so that you can see what the texture looks like. In
the main box you should see a long list of files - we’ll use
the filter option. In the Prefix box, type textures and
click the Filter button. This means that this box only
shows textures. Now type textures/base_wall and press Filter.
Currently the preview window (shown) shows the q3ase logo (you may need to maximize it from the start bar). Now select the base_wall/atechengine_ax.tga texture from the window - it will appear in the preview window. Now click OK. Note that a new keyword has been entered under Stage 1 in the Tree View.
If
we wanted to change the texture we could right click on that keyword
and select Edit.
Now
we want to play with how the texture looks. We are going to
do some ugly things with this texture that we wouldn’t want
to see in the game, but there’s a lot of detail in the
texture which allows us to see very clearly what each tcMod does.
You create a tcMod keyword by right clicking on the stage name (We only have Stage 1 at the moment), select Add tcMod and then the particular tcMod you want to look at. This will bring up a dialogue box. I’ve given some appropriate values for each tcMod but these are just starting points. Play around with different values and refer to the shader manual (Section 7.6) for full details. Note that the relevant keyword is created automatically in the tree view. Right-clicking on the keyword will bring up a menu where you can either Remove or Edit the tcMod. Look at each tcMod separately and don’t forget to try minus values where appropriate. Then try combining some tcMods.
Note:
if some tcMods have no effect, go here.
This
is an obvious one to start with. Scrolls the texture.
Start with s=1, t=0. Don’t forget to try out minus
values.
There
appears to be an error in the shader manual here. A value
of 0.5 will double the size of the texture on that axis. A
value of 2 will halve it. It’s not much fun to play
with but it’s very useful.
For
a detailed understanding you will need to refer to the shader
manual. A base value of 1, will make the texture stretch
and contract around its normal size. Start with values of base
value=0.8, amplitude = 0.4, phase = 0, frequency = 0.2, waveform
= sin. And then play. With some values, you will get
very ugly looking effects. If you are using a Scroll in the
same stage, I have found it better to have the Scroll after
the Stretch.
Back
and forth, side to side, swirling motion. The base value is
ignored, so best to leave it on 0. Start with base value=0,
amplitude=0.4, phase=0, frequency = 0.2, waveform = sin. Refer
to the shader manual for full details.
This is just what it says. Stick a value in and watch it spin. Make it a negative value and it spins the other way.
Like the manual says – this is not for level designers. But you could play with it anyway.
Now we are going to blend
two stages together. First of all, get rid of what we have
so far by right clicking on Stage 1 and selecting Remove. We
should be right back where we started, with the q3ase logo in the
preview window.
Let’s create a stage like the one on the right – you should see moving blue flames in the preview window – if not refer to the sections above. We add a second stage by bringing up the Stage Menu and selecting New Stage and then after this. Stage 2 should appear and the Preview window should revert to the q3ase logo. This is because no texture has been loaded up for this stage and at the moment this stage is completely opaque – we can’t see through it to the stage below.
Let’s
load up the base_wall/atechengine_ax.tga texture again but this
time in Stage 2. Now bring up the stage menu by right-clicking
on the words 
Stage 2, select blendfunc
and then add. We can now see both stages at the same time.
The blendfuncs can be edited and removed just like the tcMods.
Look at each of them in turn.
Add: simply adds the stage to whatever lies beneath it (which in this case is only Stage 1). It is very commonly used. If you want to make transparent shaders (e.g. Water or glass) then you need to have a blendfunc add in Stage 1.
Filter: the texture in this stage will act as a filter. A dark part of a texture in either stage will appear dark in the final mix. Blendfunc filter is always used in lightmap stages and is otherwise relatively rare.
Blend: allows parts of the texture to be transparent so that we can see through to the stage below. This is clearly what we want to use here. The texture must have an alpha channel (usually indicated by the .tga extension) otherwise there will be no transparency. Refer to the shader manual for more information.
Custom: this allows complete control over the mixing. Refer to the shader manual for full details. The best way to understand the relevant section (7.2.2) is to read it in conjunction with playing with this blendfunc.
The rgbGen allows us to change the brightness of a texture. An rgbGen Identity keyword is normally added by q3ase to every stage – you can ignore it unless you need to change it. Many of the rgbGen options are not designed to be used by level designers – but what we will use is the rgbGen wave function.
Load up a texture and select Edit RGB Source from the Stage Menu. Identity will be selected but change that to Waveform – the texture in the preview window should pulsate. If we click the Edit button we can change the way it pulsates. The variables should be familiar by now. A base value of 1 is the normal brightness of the texture, 0 is blackness. The rest are obvious. Experiment with the different wave forms.
The other use of rgbGen is to dim a texture without pulsating it. To do this set base=0.5 (or whatever) and everything else to 0. You will see countless examples of this in the id shaders.
This is how we get those cool reflections. Load up effects/tinfx. Then bring up the Stage Menu and select tcGen/environment. The texture will stretch but will otherwise look unimpressive. To see the tcGen in all its glory, select Geometry/Spinning Box from the Preview menu. If you don’t see what is different – remove the tcGen environment.
A stage can have up to 8 animation frames. From the Stage Menu select Edit Texture Source. Select Animation and then click the Frames button. The Texture Animation window is very similar to the Texture window. The only difference is that you select a texture and then click the arrow to put it into one of the 8 frames. You don’t need to use all 8. Load in the sfx/b_flame set in order, then click OK. In the Texture Source box, you can adjust the frames per second. The default is 1, which is too slow for this animation. Try setting it to 10.
Most shaders have a lightmap stage, which causes the shader to be affected by the surrounding lighting. Bring down the Stage Menu and select Edit Texture Source. Select Lightmap. The Preview Window will go white. The lightmap needs to be combined with a blendfunc filter. If the lightmap is the first stage then the next stage up should have a blendfunc filter. If the lightmap is not the first stage then there should be a blendfunc filter in the lightmap stage.
If you forget to put a lightmap stage in then when you save the shader q3ase will prompt you to put a lightmap stage as the last stage of the shader. This is usually fine, though with light blend effects you may want to put it earlier.
If this seems complicated, then don’t worry about it for now, just leave the lightmap stage out and accept the prompt when you save.
Q3ase v0.6 allows you to see how your
shader will look under different lighting states. Click here.
That’s as far as this tutorial goes in regard to the Stage Specific Keywords. It’s enough to get you going. The rest of the Keywords are covered in the Shader Manual and they are set in exactly the same way, through the Stage Menu.
These are all set by right-clicking on General Keywords in the Tree View. All these Keywords are covered in Sections 3, 4, and 5 of the Shader Manual. It is in most cases obvious how to set them. If you don’t understand a particular Keyword then it’s the Shader Manual for you, and then the id shaders and then the editing forums. Just as in the stage menu, when you set a Keyword it appears in the tree view and you can edit it or remove it by right-clicking.
The Preview menu let’s you control how q3ase previews a shader.
Flat: the default mode. The texture as it is…
Box: essential if you are using the deformVertexes keyword.
Spinning Box: essential if you use the tcGen environment keyword
Cascade: will show each stage separately. I haven’t used it much, but perhaps useful for analysing complex blend effects.
Sky: (doh) for making skies.
These allow you to look at the separate stages of a shader. Very useful for tweaking how a shader looks.
Select different lightmap previews to see how the shader would look in different lighting states. Note that changing the lightmap preview will change how the shader looks in the editor not in the game. It’s very useful when making shaders for lights for checking that the lightmap stage is in the right place. (If you get it wrong your light won’t be seen if it’s in a dark corner!)
You can change the buffer colour. Most of the time you won’t notice the difference, but it can be useful when playing with alpha blends. And it’s necessary to see what a transparent shader looks like.
If some of the tcMods don’t function, for example, you set a rotate but the texture doesn’t rotate, then select this option. It’s a video card issue. If, like me, you have a Matrox G400, you will want to leave this ticked permanently.
Version 0.6 of q3ase has greatly simplified the process of saving shaders and allows the invaluable option of opening pre-existing shader files.
It couldn’t be simpler. Click on
the File menu and select Open…. You are presented with
a dialogue box listing all the shader files available to you.
If you can’t find the shader file you’re looking for in
here then you may need to use the Edit pakfiles… option,
also under the File menu.
Let’s select the base_floor.shader
file. And press OK. The file opens but we’re
presented with a warning dialogue box. This can usually be
ignored but provides useful information for debugging. Press
OK. Once we expand the tree view we can see all the shaders
in the base_floor group for us to edit and learn from at our
leisure. You can have as many shader files open at one time
as you like.
We’re going to cover how to save a shader and how to make it show up in q3r. First make the shader on the right.
You should see a blue fuzz through a hole in the floor. If you have any problems getting that then refer back to earlier sections of this tutorial.
The surfaceparm and the qer_editorimage were added by right clicking on General Keywords.
Note the name (added by right-clicking). It’s important to include a path from the baseq3 directory in the name. This will cause the shader to show up in the tutorial folder in q3r. If a shader doesn’t show up in q3r, the first thing to check is that you have not just typed a name but that you have typed a pathname.
To
save the shader right-click where it says File: <unsaved>
and choose Save As… and then save the file as normal with a
Windows document. You should, of course, save it in your
baseq3/scripts folder. For the purposes of this tutorial
name the new file tutorial.shader.
You’ll be prompted to save a lightmap stage. Click Yes.
Our shader has now been saved.
If you are working with a file that already exists (ie one opened from the File menu) then you can use the Save option rather than the Save As…. The id shader files that shipped with the game are write-protected by the editor. You can only save them as a new file.
Before we can use the shader in q3radiant there are a couple of things we must do.
1. In the baseq3/scripts folder, open shaderlist.txt and add the word tutorial to the list. Make sure you keep the last line of this file blank – it seems to be important.
3. Now go to your baseq3/textures folder and create a new folder called tutorial. When you’re making your own shaders then any custom textures would go in here. We’re going to leave it empty – but it’s important that we create it anyway because the name of our shader is going to include the path to this directory and if it doesn’t exist then the shader won’t show up in q3radiant.
Obviously you will name all these files and folders something different when you’re working on a map and not the tutorial (something like l33tdm24.shader?).
Let’s see what our shader really looks like. Open up tutorial.shader using a text editor.
You should see something like this…
textures/tutorial/testshader
{
qer_editorimage
textures/base_floor/clangdark_ow3.tga
surfaceparm
metalsteps
{
map textures/sfx/proto_zzztblu2.tga
rgbGen identity
tcMod turb 0 0.5 0 9.6
tcMod scale 2 2
tcMod scroll 9 5
}
{
map textures/base_floor/clangdark_ow3.tga
blendfunc blend
rgbGen identity
}
{
map $lightmap
rgbGen identity
blendfunc filter
}
}
The similarity to the Tree View in q3ase is obvious. But there are a couple of things to note.
1. A lightmap stage has been added at the end. Generally, as I said earlier, this is fine.
2. An rgbGen identity has been added to every stage.
This shader is an exact copy of an id shader, so let’s compare our shader with id’s.
textures/base_floor/clangdark_ow3
{
surfaceparm metalsteps
// This makes a
noise like running on metal
{
map textures/sfx/proto_zzztblu2.tga
tcMod turb 0 .5 0 9.6
tcmod scale 2 2
tcmod scroll 9 5
blendFunc GL_ONE GL_ZERO
rgbGen identity
}
{
map textures/base_floor/clangdark_ow3.tga
blendFunc
GL_SRC_ALPHA GL_ONE_MINUS_SRC_ALPHA
rgbGen identity
}
{
map $lightmap
blendFunc GL_DST_COLOR GL_ONE_MINUS_DST_ALPHA
rgbGen identity
}
}
Note the following:
1. The id shader has no qer_editorimage keyword. This is because the name of the texture has an exact equivalent texture and it will use this in the editor. However this can cause problems with texture robbing and I would advise you to use a qer_editorimage keyword.
2. In the first stage, id has a blendFunc GL_ONE GL_ZERO which we don’t have. It’s not necessary – it simply means make the texture opaque, which it is anyway.
3. The blendFuncs are different in stages 2 and 3. They are equivalent. Refer to the Shader Manual (Section 7.2) for further details.
4. The rgbGen identity keyword is in a different place. It’s not important where this appears within the stage.
5. There is a comment. Actually there isn’t in the original shader script, but I added it to make a point. Anything after // on a line will be ignored.
This is as far as this tutorial goes. We’ve covered how to make a basic shader using the q3ase tool. The many other features and keywords are all covered in the Shader Manual and/or the q3radiant Manual – and to use them within q3ase should now be reasonably obvious. (The sky features are particularly good).
The best way to go forward from here is to study the id shaders and recreate them using q3ase. It’s difficult to see how some effects are achieved until you break them down using q3ase. In conjunction with the Shader Manual, you should quickly build up a good working knowledge of shader scripts and that’s the best time to start making your own…
-fatmanfat-