Players Guide

So, you’ve decided to start 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 channels on the Nuclear Monster Discord.

You will need a legitimate copy of Quake 3: Arena. It is currently only available through Steam on Windows and gog.

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 fifteen years ago. We’ve added many features and fixed too many bugs to count.

Windows Setup

Installation

1. Install ioquake3 via the old 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 where you chose to install it in step 1.
3. 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.
4. Copy pak0.pk3 from your baseq3 folder on your Quake III: Arena CD-ROM or Steam installation to your /ioquake3/baseq3 directory.
5. Launch the shortcut.

Updating

1. Download a test build extract the ioquake3 files from the zip and overwrite the ones with the same names in your  /ioquake3 directory.
2. 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. This allows multiple people to play ioquake3 on the same computer with separate files per-users.

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

On Windows Vista, 7, 8, 8.1, and 10 you’ll usually find your files here:
C:\Users\%USERNAME%\AppData\Roaming\Quake3\

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"

macOS Setup

Installation

1. Install ioquake3 via the traditional dmg file.
2. Immediately upgrade to a test build by downloading the zip file, extract the ioquake3.app 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. Download the latest Patch Data for Quake III: Arena and extract it to a folder. From that folder’s baseq3 folder, copy the eight files (pak1.pk3 to pak8.pk3) to your /Applications/ioquake3/baseq3 folder.
5. Launch ioquake3.app from the Finder in your ioquake3 folder

Updating

Download a test build

Where are my files?
/Users/YOURNAME/Library/Application Support/Quake3/

Linux Setup

Installation
Most Linux distributions have a version of ioquake3 available via the package manager. Please consult your distribution’s documentation.

Updating
Download a test build.

Where are my files?
~/.q3a/

Android/iOS
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, the upgrade may immediately solve your issue.

I’m getting an error that says “User Interface is version 3, expected 6” when I try to join a server.
Please install the patch data in order to correct this issue.

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 or gog into your baseq3 folder, you still need to buy Quake 3: Arena to play that game or any mods based on Quake 3.

How do I change the Field of View or FOV?
Bring down the console with the key to the left of the 1 on your keyboard. On US ANSI keyboards it is the ` key or you can always press the Shift and Escape keys at the same time. Then type /cg_fov 90 or replace 90 with the FOV you would like.

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. 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 you 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
/vid_restart

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:

Console Command	Description
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 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.

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.

SDL Keyboard Differences
ioquake3 clients have different keyboard behavior compared to the original Quake 3 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 Quake 3 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 different and Quake 3 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 and the directory is named missionpack).

To install Team Arena, copy the pak0.pk3 from the missionpack directory on your CD-ROM, or Steam or gog installation, to the missionpack directory under your ioquake3 directory.

How do I enable in-game Voice-Over-IP?
Make sure your network settings are set to broadband in the menus before starting this process.

1. /s_useOpenAL 1
2. /snd_restart
3. /bind q “+voiprecord”
4. Hook up a microphone, connect to a VoIP-supporting server. (xaero.ioquake3.org, for example)
5. Hold down the ‘q’ key and talk.

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 zip files will work, just rename the zip file. 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, and we don’t really test the demo often so we hope it works but it isn’t guaranteed.

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 that game. 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.

Every so often we are approached with new ideas about anti-cheat, we haven’t seen a truly functional idea yet. As computer vision and other research improves it will become increasingly difficult to combat cheating without humans reviewing gameplay. It’s cool to research new anti-cheat ideas! Please keep trying.

Useful Console Commands

Advanced OpenGL 2 renderer settings
Cvars for simple rendering features

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

Cvars for HDR and tonemapping

Console Command	Description & Options
r_hdr	Do scene rendering in a framebuffer with high dynamic range. (Less banding, and exposure changes look much better) 0 – No. 1 – Yes. (default)
r_cameraExposure	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.
r_postProcess	Enable post-processing. 0 – No. 1 – Yes. (default)
r_toneMap	Enable tone mapping. Requires r_hdr and r_postProcess. 0 – No. 1 – Yes. (default)
r_forceToneMap	Cheat. Override built-in and map tonemap settings and use cvars r_forceToneMapAvg, r_forceToneMapMin, and r_forceToneMapMax. 0 – No. (default) 1 – Yes.
r_forceToneMapAvg	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.
r_forceToneMapMin	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.
r_forceToneMapMax	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.
r_autoExposure	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)
r_forceAutoExposureMin	Cheat. Override built-in and map auto exposure settings and use cvars r_forceAutoExposureMin and r_forceAutoExposureMax. 0 – No. (default) 1 – Yes.
r_forceAutoExposureMax	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

Console Command	Description & Options
r_normalMapping	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.
r_specularMapping	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.
r_deluxeMapping	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)
r_parallaxMapping	Enable parallax mapping for materials that support it. 0 – No. (default) 1 – Use parallax occlusion mapping. 2 – Use relief mapping. (slower)
r_baseSpecular	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.
r_baseGloss	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.
r_baseNormalX	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.
r_baseNormalY	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.
r_baseParallax	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

Console Command	Description & Options
r_imageUpsample	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
r_imageUpsampleMaxSize	Maximum texture size when upsampling textures. 1024 – Default. 2048 – Really nice. 4096 – Really slow. 8192 – Crash.
r_imageUpsampleType	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)
r_genNormalMaps	Naively generate normal maps for all textures. 0 – Don’t. (default) 1 – Do.

Cvars for the sunlight and cascaded shadow maps:

Console Command	Description & Options
r_forceSun	Cheat. Force sunlight and shadows, using sun position from sky material. 0 – Don’t. (default) 1 – Do. 2 – Sunrise, sunset.
r_forceSunMapLightScal	Cheat. Scale map brightness by this factor when r_forceSun 1. 1.0 – Default
r_forceSunLightScale	Cheat. Scale sun brightness by this factor when r_forceSun 1. 1.0 – Default
r_forceSunAmbientScale	Cheat. Scale sun ambient brightness by this factor when r_forceSun 1. 0.5 – Default
r_sunShadows	Enable sunlight and cascaded shadow maps for it on maps that support it. 0 – No. 1 – Yes. (default)
r_sunlightMode	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.
r_shadowFilter	Enable filtering shadows for a smoother look. 0 – No. 1 – Some. (default) 2 – Much.
r_shadowMapSize	Size of each cascaded shadow map. 256 – 256×256, ugly, probably shouldn’t go below this. 512 – 512×512, passable. 1024 – 1024×1024, good. (default) 2048 – 2048×2048, extreme. 4096 – 4096×4096, indistinguishable from 2048.

What Quake 3 mods are compatible with ioquake3?
We don’t have a list of compatible mods right now, but most mods should work just fine.

Where can I find good maps to download?
LvL World has many great maps created by the Quake 3 community.

I want to run my own Dedicated Quake 3 Game Server
Please read the Sys Admin Guide