What are shaders Edit

Shaders are short text scripts which define the properties of a surface as it appears and functions in a world environment (in this case, the game world).[1] In Quake III these shaders are unrelated to programmable shaders found on GPUs or the directx shaders. QIII shaders aren't really a shading language used in modern games, but it has some opengl fixed functions to perform some basic operations such as alpha blends, alpha transparencies, scrolls or lightmaps.

A shader file consists of a series of surface attribute and rendering instructions formatted within braces: { and }.[2] It uses a syntax similar to the C programming language.

Limitations and common usages Edit

With shaders it's possible to:[3]

  • Make surfaces/volumes behave in certain ways ingame (water, lava, nonsolid, etc..)
  • Blend multiple textures together in various ways
  • Create surface sprites (useful for grass etc.)
  • Create blended terrain
  • Create scrolling, rotating textures.
  • Make textures glow ingame
  • Provide lighting to your map (light-emitting shaders)
  • Combinations of the above

It's important to note that, since these shaders here have no programmable functions, every texture property or parameter is fixed, static. QIII doesn't support dynamic shaders that affect / are affected by the world around, no realtime reliefs, no realtime shadow casting, no per pixel specularity / reflectivity or refractivity / bumps, etc. At best multiple pre-rendered textures could form an animated shader to simulate some dynamic effect.

Shader filenaming and conventions Edit

By convention, the documents which contain these scripts usually have the same name as the texture set which contains the textures being modified. Several specific script documents have also been created to handle special cases, like liquids, sky and special effects.

The full route to mark a specific texture with properties is textures/folder/name.

To better order your textures it's a good idea to sort them in a subfolder of the textures folder. Note that in radiant, textures are listed in groups of folders per shader file, no two levels deep subfolders. This name doesn't need to match the texture's filename.

Basic syntax Edit

Shaders need to be referenced by the map editor, compiler (Q3Map2) and game engine. Each of them uses a different part of the shader. This is a basic shader example:[4]

	deformVertexes wave sin 0 3 0 0.1
	q3map_tessSize 64
	surfaceparm lava
	qer_editorimage textures/common/lava.tga
		map textures/common/lava.tga
  • Line 1 is the shader name.
  • Line 3 is a General shader keyword. This keyword affects all the stages of this shader. It's the equivalent of Global Variables in programming languages.
  • Line 4 is a compiler-specific keyword. These keywords tell the the behaviour of a shader to the compiler.
  • Line 5 is a compiler-specific surface parameter keyword. These keywords tell the behaviour of a surface of the shader to the compiler.
  • Line 6 is an editor-specific keyword. These keywords tell the behaviour of a shader to the map editor.
  • Line 8 is a Stage-specific keyword. It affects only the stage it's placed on. It's the equivalent of Local Variables in programming languages.

Keywords Edit


Shader files and shaderlist.txtEdit

Shaders are contained into .shader files under "scripts" folder. So, your textures/liquids/lava-example shader may physically be located into a plain text file such as scripts/liquidstest.shader. A single .shader file can contain multiple shaders.
As all .shader files are in the same folder without further subfolders, you should try to be a bit "creative" for the filename, in order to minimize the risk of overriding a .shader file from someone else (e.g. "mapnameliquids.shader" would be better than "liquids.shader").

In order to have the map editor (NetRadiant, etc.) and the map compiler (Q3MAP2) actually access and use your shaders, you have to add your .shader to a file named shaderlist.txt, usually placed under your baseoa folder.
It's a quite simple file (just a list of shader files names, one per line, without the .shader extension), but it's very important. Without mentioning them there, the .shader files would be ignored by the editor and the compiler, so their shaders would not show up correctly in the editor, and many parameters would be ignored at map compile time, with bad results (e.g. light emitting shaders would emit no light).

The "OA gamepack" for the map editor should include a default shaderlist.txt which can be used as a starting point.

While you have to include your additional .shader files in the PK3 of your map when you will release it, you should NOT include your shaderlist.txt. If you wish, you may mention in its "readme file" that if someoneone will want to recompile your map, he should add the included shader files to his own shaderlist.txt.


  • Most "surfaceparm" changes require to recompile the map in order to be effective (e.g. surfaceparm water), but some may be interpreted by the game directly, without a map recompile (e.g. surfaceparm nomarks).
  • Usually, their order is not a problem... but in some cases, the different order of the "surfaceparm" keywords may cause some slightly different behaviors. If you are troubleshooting your shader, in a few cases changing the order of your surfaceparm keywords may fix an unexpected behavior.

Notes Edit

  1. Wikibooks' Shaders
  2. Wikibooks' Shader Syntax
  3. Wikibooks' What Shaders Can Do
  4. Q3MAP2 Shader Manual by Obsidian and ydnar

External links Edit

See alsoEdit

<< Previous (Creating dynamic features) Mapping manual (Terrains and liquids) Next >>

OpenArena's Mapping manual
Prologue /// Pre-mapping stage - Map gameplay /// Choosing an editor /// Your first map
Brush manipulation - 2D/3D clipping /// Curve manipulation /// Textures /// Introduction to Entities
Lighting - Advanced lighting /// Weapon/Item placement /// Triggers and movers - Dynamic features
Shaders /// Terrains and liquids /// Mapmodels /// Sounds /// Gametype support
Optimization and Troubleshooting - Hint brushes - Bot play - Troubleshooting
Final touches /// Compilation & packaging
Glossary of terms - Advanced features - Modelling a map - Editor differences - Default assets (Textures/Models/Sounds) - GPL
Community content is available under CC-BY-SA unless otherwise noted.