- 1 Playing ioquake3
- 2 Why should I use ioquake3 instead of id software's 1.32c?
- 3 Windows
- 4 macOS
- 5 Linux
- 6 Android/iOS
- 7 Something isn't working right!!!!
- 8 I’m getting an error that says “User Interface is version 3, expected 6”
- 9 I’m getting some Sys_Error thing about a pak0.pk3, wtf?!?
- 10 HD/High Resolutions
- 11 Using the new OpenGL 2 renderer
- 12 Using HTTP/FTP Download Support
- 13 QuakeLive mouse acceleration
- 14 SDL Keyboard Differences
- 15 I can’t bring down the console with the ` or the ~!
- 16 Help! Ioquake3 won't give me an fps of X anymore when setting com_maxfps!
- 17 Using shared libraries instead of qvm
- 18 Why can’t I run Team Arena or the Mission Pack?!?!?!
- 19 How do I enable Voice-Over-IP?
- 20 Using Demo Data Files
- 21 Will You Remove the CD-Key Check from Quake 3?
- 22 Does Punkbuster or other anti-cheat software work with ioquake3?
- 23 Useful Console Commands
- 23.1 Advanced OpenGL 2 renderer settings
- 23.1.1 Cvars for simple rendering features
- 23.1.2 Cvars for HDR and tonemapping
- 23.1.3 Cvars for advanced material usage
- 23.1.4 Cvars for image interpolation and generation
- 23.1.5 Cvars for the sunlight and cascaded shadow maps:
- 23.1.6 Cvars that you probably don't care about or shouldn't mess with
- 23.1.7 Cvars that have broken bits
- 23.1 Advanced OpenGL 2 renderer settings
- 24 What Quake 3 mods are compatible with ioquake3?
- 25 I want to run my own Dedicated Quake 3 Game Server
This guide will help you get started.
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.
- Install ioquake3 via the old installers.
- 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
/ioquake3directory where you chose to install it in step 1.
- Right click on ioquake3.x86_64.exe and create a new shortcut, place it on your desktop or wherever you would like. Old shortcuts to Quake 3 will continue to launch old versions of the game.
baseq3folder on your Quake III: Arena CD-ROM or Steam installation to your
- Launch the shortcut.
- Download a test build extract the ioquake3 files from the zip and overwrite the ones with the same names in your
- Right click on ioquake3.x86_64.exe and create a new shortcut, old shortcuts will continue to launch the old version of the game.
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:
On Windows 2000 and XP
C:\Documents and Settings\%USERNAME%\Application Data\Quake3\
On Windows Vista, 7, 8, 8.1, and 10
Can I re-enable a single-user mode?
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"
- Install ioquake3 via the traditional dmg file.
- Immediately upgrade to a test build by downloading the zip file, extract the ioquake3.app from the zip file and place it inside your
baseq3folder on your Quake III: Arena CD-ROM or Steam installation to your
ioquake3.appfrom the Finder in your
Download a test build
Where are my files?
Most Linux distributions have a version of ioquake3 available via the package manager. Please consult your distribution's documentation.
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.
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 a 1080p HD screen, I’d use these commands in the console:
/r_mode -1 /r_customheight 1080 /r_customwidth 1920
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
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
opengl1 and issue another
Using HTTP/FTP Download Support
Want to download maps and mods faster? If the server you're using supports it, you can!
/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:
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.
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?
- Make sure your network settings are set to broadband.
- /s_useOpenAL 1
- /bind q “+voiprecord”
- Hook up a microphone, connect to a VoIP-supporting server. (server.ioquake3.org, for example)
- 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