Players Guide

From ioquake3 wiki
Jump to: navigation, search


Playing ioquake3

This guide will help you get started.

If there isn’t a solution for the problem you ran into on this page, please try asking on our forums or in our live chat channel.

You will need a legitimate copy of Quake 3: Arena. It is currently only available through Steam on Windows or if you'd like it on-disc second-hand markets like Ebay may have copies.

Why should I use ioquake3 instead of id software's 1.32c?

id software stopped fixing bugs, security issues, and adding features to Quake 3: Arena more than a decade ago. We've added many features and fixed too many bugs to count.



  1. Install ioquake3 via the traditional installers.
  2. Immediately upgrade to a test build by downloading the zip file, extract the ioquake3 files from the zip and overwrite the ones with the same names in your /ioquake3 directory.
  3. Copy pak0.pk3 from your baseq3 folder on your Quake III: Arena CD-ROM or Steam installation to your /ioquake3/baseq3 directory.
  4. Launch the test build's ioquake3 executable from the ioquake3 directory


Download a test build

Where are my files? I'm used to them being in the Quake 3 directory!

On Windows, all user specific files such as autogenerated configuration, demos, videos, screenshots, and autodownloaded pk3s are now saved in a directory specific to the user who is running ioquake3.

In order to access this directory more easily, you can also type %APPDATA%\Quake3\ in the file explorer and hit enter

On Windows 98 and ME, this is usually a directory named:

C:\Windows\Application Data\Quake3\

On Windows 2000 and XP

C:\Documents and Settings\%USERNAME%\Application Data\Quake3\

On Windows Vista, 7, 8, 8.1, and 10


I don't like this!

You can revert to the old single-user behavior by creating a shortcut to your ioquake3 executable with the fs_homepath cvar set to the directory where ioquake3 is installed. For example: ioquake3.exe +set fs_homepath "c:\ioquake3"

Mac OS X


  1. Install ioquake3 via the traditional dmg file.
  2. Immediately upgrade to a test build by downloading the zip file, extract the from the zip file and place it inside your /Applications/ioquake3 folder.
  3. Copy pak0.pk3 from your baseq3 folder on your Quake III: Arena CD-ROM or Steam installation to your /Applications/ioquake3/baseq3 folder.
  4. Launch from the Finder in your ioquake3 folder


Download a test build

Where are my files?

/Users/YOURNAME/Library/Application Support/Quake3/




Download a test build

Where are my files?



We don't currently have an official version of ioquake3 for mobile devices, there are many versions of ioquake3 that you will find if you search app stores for Quake 3. We didn't make them, we can't fix them. Please don't pay money for them, ioquake3 is free software.

Something isn't working right!!!!

Please upgrade to a test build.

I’m getting an error that says “User Interface is version 3, expected 6”

You need to install the patch data.

I’m getting some Sys_Error thing about a pak0.pk3, wtf?!?

You haven’t installed the pak0.pk3 from the Quake 3: Arena Disc or Steam into your baseq3 folder, you still need to buy Quake 3: Arena to play that game or any mods based on Quake 3.

HD/High Resolutions

Not only do we have instructions for setting a non-standard resolution, but in widescreen modes we will display Quake 3 more properly than id’s last version. You can find out your screen resolution from this link. For an older macbook, I’d use these commands in the console:

/r_mode -1
/r_customheight 800
/r_customwidth 1280

then if I’m in-game I would use /vid_restart to restart ioquake3’s video system with the new display resolution. If I want the game to be fullscreen you can use the /r_fullscreen 1 command. To set it back to windowed mode you can change the 1 to a 0 /r_fullscreen 0.

The in-game video preferences will not list your new resolution.

Using the new OpenGL 2 renderer

The OpenGL 2 renderer available only with ioquake3 test builds is compatible with most Quake 3 mods, supports HDR, tone-mapping and auto-exposure, cascaded shadow-maps, MSAA, texture upsampling, advanced materials, shading, and specular methods, LATC and BPTC texture compression support, and SSAO. Basically, it's the best thing to happen to Quake 3 since the rocket launcher. After installing a test build, run these commands in the console to enable OpenGL 2 support.

/cl_renderer opengl2

To go back to the old renderer, just change opengl2 to opengl1 and issue another /vid_restart.

Using HTTP/FTP Download Support

Want to download maps and mods faster? If the server you're using supports it, you can!

Just type /cl_allowdownload 1 in the console and hit the enter key.

Changing that number to 0 will disable downloads, here are some other options

cl_allowdownload 1
Enable HTTP/FTP and UDP downloads.
cl_allowdownload 2
Disable HTTP/FTP downloads, but enable UDP downloads.
cl_allowdownload 4
Disable UDP downloads, but enable HTTP/FTP downloads

QuakeLive mouse acceleration

(patch and this text written by TTimo from id)

I've been using an experimental mouse acceleration code for a while, and decided to make it available to everyone. Don't be too worried if you don't understand the explanations below, this is mostly intended for advanced players: To enable it, set cl_mouseAccelStyle 1 (0 is the default/legacy behavior)

New style is controlled with 3 cvars:

sensitivity cl_mouseAccel cl_mouseAccelOffset

The old code (cl_mouseAccelStyle 0) can be difficult to calibrate because if you have a base sensitivity setup, as soon as you set a non zero acceleration your base sensitivity at low speeds will change as well. The other problem with style 0 is that you are stuck on a square (power of two) acceleration curve.

The new code tries to solve both problems:

Once you setup your sensitivity to feel comfortable and accurate enough for low mouse deltas with no acceleration (cl_mouseAccel 0), you can start increasing cl_mouseAccel and tweaking cl_mouseAccelOffset to get the amplification you want for high deltas with little effect on low mouse deltas.

cl_mouseAccel<code> is a power value. Should be >= 1, 2 will be the same power curve as style 0. The higher the value, the faster the amplification grows with the mouse delta.

<code>cl_mouseAccelOffset sets how much base mouse delta will be doubled by acceleration. The closer to zero you bring it, the more acceleration will happen at low speeds. This is also very useful if you are changing to a new mouse with higher dpi, if you go from 500 to 1000 dpi, you can divide your cl_mouseAccelOffset by two to keep the same overall 'feel' (you will likely gain in precision when you do that, but that is not related to mouse acceleration).

Mouse acceleration is tricky to configure, and when you do you'll have to re-learn your aiming. But you will find that it's very much worth it in the long run.

If you try the new acceleration code and start using it, I'd be very interested by your feedback.

SDL Keyboard Differences

ioquake3 clients have different keyboard behavior compared to the original Quake3 clients.

SDL > 1.2.9 does not support disabling dead key recognition. In order to send dead key characters (e.g. ~, ', `, and ^), you must key a Space (or sometimes the same character again) after the character to send it on many international keyboard layouts.

The SDL client supports many more keys than the original Quake3 client. For example the keys: "Windows", "SysReq", "ScrollLock", and "Break". For non-US keyboards, all of the so called "World" keys are now supported as well as F13, F14, F15, and the country-specific mode/meta keys.

On many international layouts the default console toggle keys are also dead keys, meaning that dropping the console potentially results in unintentionally initiating the keying of a dead key. Furthermore SDL 1.2's dead key support is broken by design and Q3 doesn't support non-ASCII text entry, so the chances are you won't get the correct character anyway.

If you use such a keyboard layout, you can set the cvar cl_consoleKeys. This is a space delimited list of key names that will toggle the console. The key names are the usual Q3 names e.g. "~", "`", "c", "BACKSPACE", "PAUSE", "WINDOWS" etc. It's also possible to use ASCII characters, by hexadecimal number. Some example values for cl_consoleKeys:

"~ ` 0x7e 0x60" Toggle on ~ or ` (the default) "WINDOWS" Toggle on the Windows key "c" Toggle on the c key "0x43" Toggle on the C character (Shift-c) "PAUSE F1 PGUP" Toggle on the Pause, F1 or Page Up keys

Note that when you elect a set of console keys or characters, they cannot then be used for binding, nor will they generate characters when entering text. Also, in addition to the nominated console keys, Shift-ESC is hard coded to always toggle the console.

I can’t bring down the console with the ` or the ~!

Press the Shift and Escape keys at the same time, this will bring down the console on any system.

Help! Ioquake3 won't give me an fps of X anymore when setting com_maxfps!

ioquake3 now uses the select() system call to wait for the rendering of the next frame when com_maxfps was hit. This will improve your CPU load considerably in these cases. However, not all systems may support a granularity for its timing functions that is required to perform this waiting correctly. For instance, ioquake3 tells select() to wait 2 milliseconds, but really it can only wait for a multiple of 5ms, i.e. 5, 10, 15, 20... ms. In this case you can always revert back to the old behavior by setting the cvar com_busyWait to 1.

Using shared libraries instead of qvm

To force ioquake3 to use shared libraries instead of qvms run it with the following parameters: +set sv_pure 0 +set vm_cgame 0 +set vm_game 0 +set vm_ui 0

Why can’t I run Team Arena or the Mission Pack?!?!?!

Did you buy Team Arena? It comes with some modern versions of Quake 3, but most people who just have Quake 3, don’t have Team Arena (which is the same as the mission pack).

To install Team Arena, copy the pak0.pk3 from the missionpack directory on your cd-rom to the missionpack directory under your ioquake3 directory.

How do I enable Voice-Over-IP?

  1. Make sure your network settings are set to broadband.
  2. /s_useOpenAL 1
  3. /snd_restart
  4. /bind q “+voiprecord”
  5. Hook up a microphone, connect to a VoIP-supporting server. (, for example)
  6. Hold down the ‘q’ key and talk.

If none of the above works, please read the VOIP README file.

Using Demo Data Files

Copy demoq3/pak0.pk3 from the demo installer to your baseq3 directory. The qvm files in this pak0.pk3 will not work, so you have to use the native shared libraries or qvms from this project. To use the new qvms, they must be put into a pk3 file. A pk3 file is just a zip file, so any compression tool that can create such files will work. The shared libraries should already be in the correct place. Use the instructions above to use them.

Please bear in mind that you will not be able to play online using the demo data, nor is it something that we like to spend much time maintaining or supporting.

Will You Remove the CD-Key Check from Quake 3?

No, we will not be removing the CD-key check. The Quake III: Arena game is not free, and you must purchase a CD or buy it from Steam to play it. It's the engine that is open source, and is absolutely 100% free software. When someone makes a new game based on the source code that does not use the Quake 3: Arena or Team Arena data, they of course don’t need to and should not require a CD key in their game.

Does Punkbuster or other anti-cheat software work with ioquake3?

No. Punkbuster is closed-source software that we cannot implement. There is no good software replacement. Good administrators on your server who can watch out for cheaters, review logs, and review recorded demo files are the only anti-cheat option at this time.

Useful Console Commands

Advanced OpenGL 2 renderer settings

Cvars for simple rendering features

Automatically compress textures. 0 - No texture compression. (default) 1 - DXT/LATC texture compression if supported. 2 - BPTC texture compression if supported.
Multisample Anti-aliasing. 0 - None. (default) 1-16 - Some. 17+ - Too much!
Enable screen-space ambient occlusion. Currently eats framerate and has some visible artifacts. 0 - No. (default) 1 - Yes.

Cvars for HDR and tonemapping

Do scene rendering in a framebuffer with high dynamic range. (Less banding, and exposure changes look much better) 0 - No. 1 - Yes. (default)
Cheat. Alter brightness, in powers of two. -2 - 4x as dark. 0 - Normal. (default) 0.5 - Sqrt(2)x as bright. 2 - 4x as bright.
Enable post-processing. 0 - No. 1 - Yes. (default)
Enable tone mapping. Requires r_hdr and r_postProcess. 0 - No. 1 - Yes. (default)
Cheat. Override built-in and map tonemap settings and use cvars r_forceToneMapAvg, r_forceToneMapMin, and r_forceToneMapMax. 0 - No. (default) 1 - Yes.
Cheat. Map average scene luminance to this value, in powers of two. Requires r_forceToneMap. -2.0 - Dark. -1.0 - Kinda dark. (default). 2.0 - Too bright.
Cheat. After mapping average, luminance below this level is mapped to black. Requires r_forceToneMap. -5 - Not noticeable. -3.25 - Normal. (default) 0.0 - Too dark.
Cheat. After mapping average, luminance above this level is mapped to white. Requires r_forceToneMap. 0.0 - Too bright. 1.0 - Normal. (default). 2.0 - Washed out.
Do automatic exposure based on scene brightness. Hardcoded to -2 to 2 on maps that don't specify otherwise. Requires r_hdr, r_postprocess, and r_toneMap. 0 - No. 1 - Yes. (default)
Cheat. Override built-in and map auto exposure settings and use cvars r_forceAutoExposureMin and r_forceAutoExposureMax. 0 - No. (default) 1 - Yes.
Cheat. Set minimum exposure to this value, in powers of two. Requires r_forceAutoExpsure. -3.0 - Dimmer. -2.0 - Normal. (default) -1.0 - Brighter.
Cheat. Set maximum exposure to this value, in powers of two. Requires r_forceAutoExpsure. 1.0 - Dimmer. 2.0 - Normal. (default) 3.0 - Brighter.

Cvars for advanced material usage

Enable normal mapping for materials that support it, and also specify advanced shading techniques. 0 - No. 1 - Yes. (default) 2 - Yes, and use Oren-Nayar reflectance model. 3 - Yes, and use tri-Ace's Oren-Nayar reflectance model.
Enable specular mapping for materials that support it, and also specify advanced specular techniques. 0 - No. 1 - Yes, and use tri-Ace. (default) 2 - Yes, and use Blinn-Phong. 3 - Yes, and use Cook-Torrance. 4 - Yes, and use Torrance-Sparrow.
Enable deluxe mapping. (Map is compiled with light directions.) Even if the map doesn't have deluxe mapping compiled in, an approximation based on the lightgrid will be used. 0 - No. 1 - Yes. (default)
Enable parallax mapping for materials that support it. 0 - No. (default) 1 - Use parallax occlusion mapping. 2 - Use relief mapping. (slower)
Set the specular reflectance of materials which don't include a specular map or use the specularReflectance keyword. 0 - No. 0.04 - Realistic. (default) 1.0 - Ack.
Set the glossiness of materials which don't include a specular map or use the specularExponent keyword. 0 - Rough. 0.3 - Default. 1.0 - Shiny.
Set the scale of the X values from normal maps when the normalScale keyword is not used. -1 - Flip X. 0 - Ignore X. 1 - Normal X. (default) 2 - Double X.
Set the scale of the Y values from normal maps when the normalScale keyword is not used. -1 - Flip Y. 0 - Ignore Y. 1 - Normal Y. (default) 2 - Double Y.
Sets the scale of the parallax effect for materials when the parallaxDepth keyword is not used. 0 - No depth. 0.01 - Pretty smooth. 0.05 - Standard depth. (default) 0.1 - Looks broken.

Cvars for image interpolation and generation

Use interpolation to artifically increase the resolution of all textures. Looks good in certain circumstances. 0 - No. (default) 1 - 2x size. 2 - 4x size. 3 - 8x size, etc
Maximum texture size when upsampling textures. 1024 - Default. 2048 - Really nice. 4096 - Really slow. 8192 - Crash.
Type of interpolation when upsampling textures. 0 - None. (probably broken) 1 - Bad but fast (default, FCBI without second derivatives) 2 - Okay but slow (normal FCBI)
Naively generate normal maps for all textures. 0 - Don't. (default) 1 - Do.

Cvars for the sunlight and cascaded shadow maps:

Cheat. Force sunlight and shadows, using sun position from sky material. 0 - Don't. (default) 1 - Do. 2 - Sunrise, sunset.
Cheat. Scale map brightness by this factor when r_forceSun 1. 1.0 - Default
Cheat. Scale sun brightness by this factor when r_forceSun 1. 1.0 - Default
Cheat. Scale sun ambient brightness by this factor when r_forceSun 1. 0.5 - Default
Enable sunlight and cascaded shadow maps for it on maps that support it. 0 - No. 1 - Yes. (default)
Specify the method used to add sunlight to the scene. 0 - No. 1 - Multiply lit areas by light scale, and shadowed areas by ambient scale. (default) 2 - Add light. Looks better, but is slower and doesn't integrate well with existing maps.
Enable filtering shadows for a smoother look. 0 - No. 1 - Some. (default) 2 - Much.
Size of each cascaded shadow map. 256 - 256x256, ugly, probably shouldn't go below this. 512 - 512x512, passable. 1024 - 1024x1024, good. (default) 2048 - 2048x2048, extreme. 4096 - 4096x4096, indistinguishable from 2048.

Cvars that you probably don't care about or shouldn't mess with

Optimize number of calls to glMultiDrawElements(). 0 - Don't. 1 - Do some. (default) 2 - Do more than necessary (eats CPU).
Merge surfaces that share common materials and a common leaf. Speeds up rendering. 0 - Don't. 1 - Do. (default)
Recalculate the normals when loading an MD3. Fixes normal maps in some cases but looks ugly in others. 0 - Don't. (default) 1 - Do.
Do a depth-only pass before rendering. Speeds up rendering in cases where advanced features are used. Required for r_sunShadows. 0 - No. 1 - Yes. (default)
Split map light into ambient and directed portions when doing deluxe mapping. Not very useful. 0 - Don't. (default). 0.3 - 30% ambient, 70% directed. 1.0 - 100% ambient.
Merge the small (128x128) lightmaps into 2 or fewer giant (4096x4096) lightmaps. Easy speedup. 0 - Don't. 1 - Do. (default)
Near plane for shadow cascade frustums. 4 - Default.
Far plane for shadow cascade frustums. 3072 - Default.
Z-bias for shadow cascade frustums. -256 - Default.
Gamma level for material textures. (diffuse, specular) 1.0 - Quake 3, fastest. (default)
Gamma level for light. (lightmap, lightgrid, vertex lights) 1.0 - Quake 3, fastest. (default)
Gamma level for framebuffers. 1.0 - Quake 3, fastest. (default)
Gamma applied after tonemapping. 1.0 - Quake 3, fastest. (default)

Cvars that have broken bits

Change how dynamic lights look. 0 - Quake 3 style dlights, fake brightening. (default) 1 - Actual lighting, no shadows. 2 - Light and shadows. (broken)
Virtual camera distance when creating shadowmaps for projected shadows. Deprecated.
Old shadow code. Deprecated.

What Quake 3 mods are compatible with ioquake3?

Check out our Mod Compatibility List

I want to run my own Dedicated Quake 3 Game Server

Please read the Sys Admin Guide