Renderer Configuration

The Quake2World renderer is highly configurable, and extremely performant on current generation hardware. It requires an OpenGL implementation of version 1.2.1 or better, and will use features from later versions (GLSL, VBO, ..) if available.

Variables

Commands

Movement & Controls

Location Files

Location files are strictly-formatted text files which contain coordinate-description pairs. They are used by Team Chat Macros to quickly report whereabouts to your team mates. You may create your own location files for any level. Simply spawn into a level, navigate to a key position in the level, and issue addloc My description. Repeat until you have captured a satisfactory number of locations -- you may store up to 1024 locations per level. When finished, issue savelocs before exiting the level. Your locations will be flushed to default/maps/level.loc, where level is the .bsp name.

Example: addloc above the rocket launcher

say_team I am %l with %h health.

newbie> I am above the rocket launcher with 94 health.

savelocs

You're encouraged to share your location files with friends, or post them in the Forums for others to download and use.

Team Chat Macros

Quake2World supports macro expansion for chat messages. This can be combined and embedded into chat binds to alert your teammates of your status. A table of available macros and their expanded values are listed below.

* Requires a valid location file for the current level. Example: bind MOUSE3 "say_team I am at %l with %h health and %a armor."

bind MOUSE4 "say_team Dropping %d at %l."

Aggressor

Originally created for Quake, Tyrann's classic Aggressor has been ported to numerous games -- a testament to its gameplay and build quality. The author describes the level:

"Brutal vertical action is the order of the day here. A medium sized base map that plays well with anywhere from 2-8 players, the more the bloodier."

Aggressor is an excellent level for one-versus-one games, and does just fine with small free-for-all groups too.

Type map aggressor at the console to play this map.

Aghast

Aghast is a dank, swampy deathmatch level originally created by Vondur for Quake. It's been reworked with textures from the Quake Retexture Project. This level is suited for small free-for-all or team deathmatch games.

Type map aghast at the console to play this map.

Catfight

Catfight is an original level created by Lava Croft and maintained by keres. This unique and overwhelmingly vertical arena is dressed up in the Andromeda texture set from Speedy, but with a frosty twist. Enjoy with 3-8 players free-for-all.

Type map catfight at the console to play this map.

Devolver

Devolver by TRaK is a moderately sized deathmatch level set in an abandoned, vaguely futuristic outpost. Adorned in a mix of textures from Evil Lair and Idolator, Devolver will comfortably hold 3 to 6 players free-for-all.

Type map devolver at the console to play this map.

Dies Irae

Dies Irae by Shadow is a large TDM and FFA map that is best suited for 6 or more players.

Type map diesirae at the console to play this map.

In The Arms of Lilith

This Quake2World original by spirit is a fast-paced tourney map best suited for some serious 1vs1 action. Set in a down-and-out chemical weapons plant on Saturn's moon Titan, this map offers no room to hide and demands precise and fast movement. Lots of vertical action, a good load of deadly weapons and a dense atmosphere make this rather small map a great place to fight your worst enemies and best friends alike.

The excellent textures were made by Rorshach.

Type map lilith at the console to play this map.

Stress Fractures

Stress Fractures is one of Jester's finest Quake2 deathmatch levels, and it's been given a dose of winter for Quake2World, complements of Yogi's Arctic texture set. Although suitable for stalking one-versus-one games, this map is ideal for 4 to 8 players free-for-all.

Type map fractures at the console to play this map.

The Frag Pipe

Everyone's (second?) favorite Quake2 level, The Frag Pipe, has been completely re-brushed and reworked for Quake2World by TRaK. Featuring textures from the Quake2Evolved project, The Frag Pipe will teleport you back to 1998 with style. Best for one-versus-one or small to medium sized free-for-all battles.

Type map q2wdm3 at the console to play this map.

Torn Glory

Torn Glory by Cardo is one of the most acclaimed Quake2 levels ever released. It's dressed in textures from Lunaran's Phobos set, and is superb for one-versus-one or small to medium sized free-for-all games.

Type map torn at the console to play this map.

Textures and Texture Sources

Quake2World supports all popular image formats for world textures: TGA, PNG, JPG, and even Quake 2's WAL format. All of the textures distributed with Quake2World may be reused in other levels, provided you pass along whatever documentation comes with them. Please avoid creating levels with textures that may not be freely distributed.

Here are some sites which provide excellent quality, legally distributable textures:

• The Quake Revitalization Project
• Evil Lair
• SimonOC.com
• RAA Texture Pack
• TRaK
• PhilipK
• Speedy

Normalmaps and bump mapping

Quake2World's bump mapping (per-pixel lighting) uses a combination of deluxe mapping, dot3-bump mapping, and parallax mapping. This technique requires that you provide normalmap images for your world textures. Generally speaking, you'll want to provide a normalmap image for every opaque world texture appearing in your level. Materials textures like animations and pulses do not require normalmaps. The standard convention is to name your normalmaps with the _nm or _norm suffix. For example, if your texture is named torn/floor1.tga, the corresponding normalmap image should be named torn/floor1_nm.tga or torn/floor1_norm.tga. For parallax mapping, the format of your normalmap textures must be RGBA, with alpha channel encoded height. Creating proper normalmaps from diffuse textures can be difficult and tedious. We recommend that you elect to use textures specifically designed for this rendering technique, that should come with properly encoded normalmaps. Should you choose a texture set that does not, you might find this tutorial for creating normalmaps useful. There are several free tools available for creating and working with normalmaps:

• NVidia Photoshop Plugins
• GIMP Normalmap Plugin
• xNormal

The tutorial above is only one of many effective ways of creating normalmaps. There are several alternative methods, each with their own advantages:

• Recovering Detailed Normals from Photo Textures
• Creating Normalmaps with 3D Studio Max
• Baking Normalmaps in Blender

A script for batch-processing textures into normalmaps with the GIMP Normalmap plugin can be found in src/tools/batch-normalmaps. However, batch-conversion will generally produce lesser-quality normalmaps than ones that are hand-tuned.

Additionally, you can and should tune each texture's bump mapping properties via the materials system.

Surface and Contents Flags

Several surface flags are available in Quake2World that were not previously supported by Quake 2.

SURF_NODRAW

Comparable to Quake III Arena's caulk feature; disables rendering of any face to which it is applied. Useful on backs of beams, bottoms of crates, etc.. The BSP compiler automatically assigns this flag to any surfaces textured with common/caulk.

SURF_TRANS33 + SURF_TRANS66

Combining the two legacy alpha blend flags causes the renderer to use the texture's alpha channel for blending. This is useful for light volumes and decals.

SURF_ALPHATEST

Enables OpenGL alpha-test on surfaces to which it is applied, allowing for grates, foliage, railings, fences, and other textures with "holes".

SURF_PHONG

Marks surfaces for Phong Interpolation (Phong Shading) during the BSP compile process. This should only be used on curved or organic geometry such as pipes, pillars, and terrain.

The Worldspawn Entity

The worldspawn entity is the core of the .map file structure. All world brushes appear within the context of the worldspawn entity. Quake2World adds several new properties to the worldspawn entity which impact everything from atmospheric weather to gameplay modes to lightmap resolution.

Runtime Variables

The following worldspawn keys are resolved at runtime, and may be overridden at the server operator's discretion via maps.lst.

message

The map title string, e.g. ^2S^7tress ^2F^7ractures by ^2J^7ester. Color escape sequences are supported. Avoid newline characters.

sky

The skybox prefix, e.g. unit1_, thundersky_, etc..

weather

Atmospheric weather type for the level. Valid values are none, rain, snow. You may also append fog, and optionally a fog color specified as rgb floating point numbers, e.g. rain fog 1.0 0.9 0.8.

gravity

The world gravity constant for the level, defaults to 800.

gameplay

The default gameplay type for the level. One of deathmatch, instagib, or rocket arena.

teams

Controls teams play. 0 is off, 1 is on, and 2 tries to enforce balanced teams.

ctf

Controls capture the flag. 0 is off, 1 is on, and 2 tries to enforce balanced teams.

match

Controls match mode, where players must ready-up for a match to begin. 0 is off, 1 is on.

fraglimit

Specifies maximum score a player may reach before an intermission.

roundlimit

Specifies the maximum rounds played before an intermission. Usually used in conjunction with rocket arena gameplay.

capturelimit

Specifies the maximum captures to transpire before an intermission. Only useful for ctf levels.

timelimit

Specifies maximum time, in minutes, that will transpire before an intermission.

give

A comma-delimited items list which each player will receive upon respawn, e.g. rocket launcher, super shotgun.

Compile-time Variables

The following worldspawn keys are resolved at compile time, and must be set before BSP compilation.

ambient_light

Specifies ambient light, or the minimum global lighting value for all light samples, as an rgb color, e.g. 0.07 0.06 0.06. A small ambient factor is recommended for most levels.

brightness

Controls light scale. This is used to uniformly brighten or darken your level. 1.0 is default, all positive floating point values are valid.

contrast

Controls light contrast. This can be used to create darker dark areas and lighter light areas. The default value is 1.0. Values significantly higher than 1.0 are not recommended.

lightmap_scale

Controls lightmap resolution, which is relative to texture size. Default is 16 (1/16). A value of 8 will produce sharper lightmaps, but will dramatically lengthen your static lighting compile times. In fact, setting this to 32 during development is a nice trick for speeding up your level design process.

saturation

Controls light saturation, or color influence. This can be used to make a level look more colorful, or more pale. The default value is 1.0. Values from 0.5 to 3.0 are most useful.

subdivide

Controls maximum surface size for the bsp stage of the compile. Generally, the default value 1024 is recommended. Lower values may reduce artifacts, while higher values may reduce r_speeds.

sun_angles

Controls sunlight direction, specified as pitch and yaw in degrees, e.g. -80 220.

sun_color

Controls sunlight color, specified as rgb floating point values, e.g. 1.0 0.9 0.8.

sun_light

Controls sunlight intensity. Values from 0 to 255 are valid, 40 to 150 typically produce best looking results.

The Emit Entity

The misc_emit entity is a client-sided entity type used to enrich your levels with non-vital information such as static meshes, particle torches, flickering lights, and ambient sounds. As many as 512 misc_emit entities may be added to a given level. This entity is highly customizable based on several key-value pairs.

Similar to Quake 2's spawnflags key-value pair, a set of flags exists for enabling certain misc_emit features. Whenever possible, these are automatically resolved by the game engine based on the key-value pairs you have set on the entity. Still, you will sometimes need to add these values to the flags key-value pair manually.

    EMIT_LIGHT      1
    EMIT_SPARKS     2
    EMIT_STEAM      4
    EMIT_FLAME      8
    EMIT_CORONA     16
    EMIT_SOUND      32
    EMIT_MODEL      64

flags

A bit-masked integer value; see above. When possible, flags are automatically resolved by the game engine based on the presence of other key-value pairs described below. However, some flag values must manually be set.

angles

3 positive floating point values in degrees, these provide directional information. Applicable to EMIT_SPARKS EMIT_MODEL.

color

3 positive floating point values, these provide rgb color information. Applicable to EMIT_LIGHT EMIT_CORONA.

count

A positive integer value which provides particle count information. Applicable to EMIT_SPARKS. Default is 12.

drift

A positive floating point value which provides some variance to event frequency. Values greater than 0.0 and smaller than 5.0 are most useful. Applicable to EMIT_LIGHT EMIT_SPARKS EMIT_STEAM EMIT_FLAME EMIT_SOUND. Default is 0.01.

hz

A positive floating point value which provides an event frequency baseline. Applicable to EMIT_LIGHT EMIT_SPARKS EMIT_STEAM EMIT_FLAME EMIT_SOUND. Use the drift key to add variance. Sane defaults are used where possible.

model

The game path of a model file, e.g. outpost/tree. The model must be a static mesh (i.e. not animated). It will be positioned according to the angles key. Applicable only to EMIT_MODEL, which is set when this key is present.

radius

A single floating point value which provides radius information. Applicable to EMIT_LIGHT EMIT_CORONA EMIT_FLAME. Defaults are 1.5, 12.0 and 1.0 respectively.

sound

The game path of a sound sample, e.g. aghast/drip. When no hz value is provided to emits which have a sound key, they are treated as looped ambient sounds. Applicable only to EMIT_SOUND, which is set when this key is present.

velocity

3 floating point values in units, these provide directional velocity information. Applicable to EMIT_STEAM

attenuation

Determines the size of the area in which a given sound is heard. Default is 1. Lower values will increase the range of the sound, whereas higher values will make the sound more localized. Setting this to -1 will make a sound play globally. Applicable to EMIT_SOUND

Examples

A torch flame, automatically accompanied by a crackling fire sound effect:

{
    // entity 1
    "classname" "misc_emit"
    "origin" "-24 512 256"
    "flags" "8"
 }

An ambient drip:

{
    // entity 2
    "classname" "misc_emit"
    "origin" "786 1284 16"
    "sound" "aghast/drip"
}

A flickering light with sparks:

{
    // entity 3
    "classname" "misc_emit"
    "origin" "-224 640 -64"
    "angles" "0 270 0"
    "flags" "3"
    "color" "1.0 0.9 0.5"
    "radius" "1.25"
    "count" "20"
    "hz" "0.25"
    "drift" "0.5"
}

A steam emitter, pointing downward and slightly north-east, and automatically accompanied by a hissing sound effect:

{
    // entity 4
    "classname" "misc_emit"
    "origin" "216 -48 512"
    "flags" "4"
    "velocity" "10 10 -40"
}

A static mesh tree:

{
    // entity 5
    "classname" "misc_emit"
    "origin" "-1024 -42 168"
    "model" "outpost/tree"
    "angles" "4 270 0"
}

Legacy Entities

The vast majority of Quake2World entities are carryovers from Quake 2. You'll notice, however, that several items have been removed, and a few new ones are available. Also, some old items have new spawnflags to alter their behavior. They are as follows:

item_*

All items in Quake2World (ammo, armor, weapons, ..) can be made to float in space, rather than drop to the floor upon spawning (which is the default behavior in Quake 2). Set spawnflags to 4 on any item to enable this behavior.

trigger_push

This is the accelerator pad entity so common in Quake 3 Arena, and also fairly popular in later Quake 2 levels. Setting spawnflags to 2 for these entities will make them emit a "rising rings" effect to help them stand out.

weapon_lightning

This is the lighting gun weapon, which Quake2World adds as a nod to classic Quake.

The BSP Compiler

Quake2World provides its own cross-platform BSP compilation tool called q2wmap. The compiler is based on the original Quake 2 tools, but in addition offers the following:

• Support for large surfaces, reducing r_speeds by up to 30% on some levels.
• High-color texture support during light stage.
• Performance optimizations, such as not subdividing or lighting sky surfaces.
• Configurable sunlight, ambient, brightness, saturation, contrast, and lightmap resolution via worldspawn entity.
• Phong Interpolation (Phong Shading) for simulating curved or organic surfaces.
• Integrated pak authoring for generating standard distribution Pakfiles for your levels.
• Integrated materials file generation for getting started with the materials system.
• Multi-threading for machines with more than one processor or core.

In addition to these things, the q2wmap source code is Valgrind clean. The stock tools are riddled with dangerous instructions and memory leaks.

Invoking the compiler is simple and straightforward. You should consider running it via a command prompt or shell rather than through GtkRadiant's build menu.

Standard full compile:

q2wmap -bsp -vis -light maps/my.map

Fast vis, extra light, two threads:

q2wmap -t 2 -bsp -vis -fast -light -extra maps/my.map

Materials file generation:

q2wmap -mat maps/my.map

Pakfile generation (produces map-my.pak):

q2wmap -pak maps/my.map

The Materials System

The materials system provides a flexible framework to enhance your levels with animations, light flares, environment maps, terrain blending, and other effects. If you are familiar with Quake 3 Arena's "shaders" system, you'll be right at home with materials.

A material is a set of directives and parameters for an individual world texture. Each texture in your level can have zero or one material definition. Materials are defined in a plain text file called materials/mymap.mat, where mymap is the name of your .bsp file. The BSP compiler can generate a default materials file for your level to get you started: q2wmap -mat maps/my.map

General Structure

Materials are comprised of a material definition, and then zero or more layers called stages. Each stage can describe one or more effect, and each effect is blended with the result of the prior stages. The basic structure of a materials file is:

{
    # Material definition
    material path/to/texture1
    parameters
    {
        # Stage definition
        texture path/to/texture2
        parameters 
    }
    ...
}

Material Definition

The material definition specifies the texture name and per-pixel lighting parameters.

normalmap path/to/normalmap

Normalmap overriding is used to apply common normalmap textures to several materials. By default, the engine tries ${texture}_nm and ${texture}_norm. Typically, this directive is omitted. See normalmaps and bump mapping

bump b

Bump amplification is used to tune bump mapping effects. Higher values increase the "bumpiness" of surfaces. The b parameter is required, and must be a positive floating point value, or 0.0. The default value is 1.0.

parallax p

Parallax amplification is used to tune the depth of bump mapped surfaces. Using values higher than 1.0 requires high-quality normalmaps, with properly encoded height values. The p parameter is required, and must be a positive floating point value, or 0.0. The default value is 1.0.

hardness h

Hardness is a multiplier for the specular component of bump mapped surfaces, and can be used to amplify or mute a material's reflectiveness. Organic materials benefit from lower values, while polished metals and glass benefit from higher ones. The h parameter is required, and must be a positive floating point value, or 0.0. The default value is 1.0.

specular s

Specular amplification is used to tune the specularity of bump mapped surfaces. The s parameter is required, and must be a positive floating point value, or 0.0. The default value is 1.0.

It is a best practice to define all material parameters for your opaque world surfaces, as they are eligible for per-pixel lighting. Quake2World provides safe defaults when you omit these parameters, but tuning them will often benefit the appearance of your level.

{
    material evil6/stone_floor
    bump 3.0
    hardness 1.5
    parallax 1.2
    specular 3.0
}

Note that blended materials such as glass or foliage do not support per-pixel lighting, and so you may safely omit the material parameters for them.

{
    material office/glass
    {
        envmap office/glass
    }
}

Stage Definition

There are four types of stages: texture envmap lightmap flare. A stage must start with a type declaration, e.g. texture lunaran/pad1_fx, envmap 0, lightmap, flare 1, etc..

Texture Stages

Texture stages are the most versatile and complex type, and must always declare a valid texture image, e.g. texture lunaran/pad1_fx. The following listing describes the texture stage directives.

anim frames hz

Frame-based animations are used to animate surfaces like computer screens. The stage texture name should end in 1, e.g. lunaran/computer1, with subsequent frames following in sequence. The frames parameter specifies the number of textures which comprise the animation. The hz parameter specifies the frequency of the effect. Both are required, and must be a positive integer and positive floating point number respectively.

blend src dest

The blend directive exposes OpenGL's GL_BLEND function. This is used for textures which lack an alpha channel, where additive blending is typically required. The src and dest parameters are GL constants, e.g. blend GL_ONE GL_SRC_ALPHA. The default blend function is GL_ONE GL_ONE_MINUS_SRC_ALPHA.

color r g b

The color directive is used to influence the stage's default color. This directive is often used in conjunction with other directives such as pulse or stretch. The parameters r g b are each required, and must each be floating point numbers between 0.0 and 1.0.

pulse hz

Pulses are used to animate surfaces like jump pads or light fixtures. The stage texture is interpolated over the base material using a sin function. The hz parameter specifies the frequency of the effect. It is required and must be a positive floating point number.

rotate hz

Rotation directives are used for fan blades, Yin-Yangs, and other surfaces which should appear to rotate. The hz parameter specifies the speed of the rotation. It is required, and must be a positive floating point number.

scale.s s, scale.t t

The scale directives are used to scale texture stages, and can be used when a stage texture is of a different resolution than the base material texture. S and T are the two texture coordinate axis. Each directive takes exactly one required parameter, which must be a positive floating point number.

scroll.s s, scroll.t t

The scroll directives are used to slide texture stages across the underlying base material. This is used for computer screen redraw lines, layered water surfaces, and trim lighting. S and T are the two texture coordinate axis. Each directive takes exactly one required parameter, which must be a floating point number.

stretch amp hz

Stretch directives are used to create continuous expanding and contracting effects. The amp parameter specifies the scale of the stretch, while hz specifies the frequency. Both are required, and must be positive floating point numbers.

terrain ceil floor

Terrain directives are used to achieve simple height-based terrain blending. The ceil and floor parameters specify the highest and lowest Z-axis coordinates where blending will occur. At Z coordinates less than floor, the base material texture will appear; at Z coordinates greater than ceil, the stage texture will appear. Linear interpolation is used to blend the two textures at Z coordinates between ceil and floor. Both parameters are required, and must be floating point numbers.

dirtmap intensity

Dirtmap directives are used to add randomized, blended artifacts to primary or terrain surfaces. This can effectively create unique looking surfaces, as generally no two polygons will receive the same set of artifacts. The intensity parameter specifies the overall amplification of the effect. It is required, and must be between 0.0 and 1.0.

Both terrain and dirtmap stages support per-pixel lighting, thus it is possible to create bumpmapped terrain. To do this, declare your terrain stage texture with a material definition prior to the base material.

{
    material organics/grass
    ...
}
{
    material organics/dirt
    ...        
    {
         texture organics/grass
         terrain 32.0 128.0
    }
}

Envmap Stages

Environment map stages are used to simulate reflections on metal, water, glass, etc. For convenience, they may be declared with numeric values to take advantage of several built-in effect textures, e.g. envmap 0. Alternatively, a unique texture can also be provided, e.g. envmap envmaps/my_envmap.

Environment map stages do not currently support any unique directives, but do support blend color scroll.s scroll.t, described above. If a color is not provided to the stage definition, Quake2World automatically uses the surface's average static lighting color to shade the environment map.

{
    material office/glass
    {
        envmap office/glass_envmap
        blend GL_SRC_ALPHA GL_ONE
        color 0.9 0.9 1.0
    }
}

Lightmap Stages

Lightmap stages are used to blend in statically computed lighting information. This is typically applied as the last drawn stage, and is useful for shading opaque or mostly opaque stages such as animations. Lightmap stages are declared by simply beginning the stage with the lightmap type name. Lightmap stages do not support any unique directives.

{
    material lunaran/computer0
    ...
    {
        anim 4 0.3
    }
    {
        lightmap
    }
}

Flare Stages

Flare stages are used to add flares (coronas) to surfaces such as light fixtures. For convenience, flare stages may reference numeric values to take advantage of several built-in effect textures, e.g. flare 1. Alternatively, a unique texture can also be provided, e.g. flare flares/my_flare.

Flare stages do not currently support any unique directives, but do support color scale.s scale.t described above. If a color is not provided to the stage definition, Quake2World automatically uses the surface's average static lighting color to shade the flare. Either of the scale.s or scale.t directives can be used to influence the size of the flare produced by this stage.

{
    material tech/small_light
    ...
    {
        flare tech/flare1
        scale.s 1.5
    }
}

More Examples

The best way to learn the materials system is to study some of the materials files that come with Quake2World. These are conveniently available in the Subversion repository.