1 ,---------------------------------------. 2 | _ _ ____ | 3 | (_)___ __ _ _ _ __ _| |_____|__ / | 4 | | / _ \/ _` | || / _` | / / -_)|_ \ | 5 | |_\___/\__, |\_,_\__,_|_\_\___|___/ | 6 | |_| | 7 | | 8 `---------- http://ioquake3.org --------' 9 10The intent of this project is to provide a baseline Quake 3 which may be used 11for further development. Some of the major features currently implemented are: 12 13 * SDL backend 14 * OpenAL sound API support (multiple speaker support and better sound 15 quality) 16 * Full x86_64 support on Linux 17 * VoIP support, both in-game and external support through Mumble. 18 * MinGW compilation support on Windows and cross compilation support on Linux 19 * AVI video capture of demos 20 * Much improved console autocompletion 21 * Persistent console history 22 * Colorized terminal output 23 * Optional Ogg Vorbis support 24 * Much improved QVM tools 25 * Support for various esoteric operating systems 26 * cl_guid support 27 * HTTP/FTP download redirection (using cURL) 28 * Multiuser support on Windows systems (user specific game data 29 is stored in "%APPDATA%\Quake3") 30 * PNG support 31 * Many, many bug fixes 32 33The map editor and associated compiling tools are not included. We suggest you 34use a modern copy from http://www.qeradiant.com/. 35 36The original id software readme that accompanied the Q3 source release has been 37renamed to id-readme.txt so as to prevent confusion. Please refer to the 38web-site for updated status. 39 40 41--------------------------------------------- Compilation and installation ----- 42 43For *nix 44 1. Change to the directory containing this readme. 45 2. Run 'make'. 46 47For Windows, using MinGW 48 1. Download and install MinGW and MSys from http://www.mingw.org/. 49 2. Open an MSys terminal, and follow the instructions for compiling on *nix. 50 51For Mac OS X, building a Universal Binary 52 1. Install MacOSX SDK packages from XCode. For maximum compatibility, 53 install MacOSX10.4u.sdk and MacOSX10.3.9.sdk, and MacOSX10.2.8.sdk. 54 2. Change to the directory containing this README file. 55 3. Run './make-macosx-ub.sh' 56 4. Copy the resulting ioquake3.app in /build/release-darwin-ub to your 57 /Applications/ioquake3 folder. 58 59Installation, for *nix 60 1. Set the COPYDIR variable in the shell to be where you installed Quake 3 61 to. By default it will be /usr/local/games/quake3 if you haven't set it. 62 This is the path as used by the original Linux Q3 installer and subsequent 63 point releases. 64 2. Run 'make copyfiles'. 65 66It is also possible to cross compile for Windows under *nix using MinGW. A 67script is available to build a cross compilation environment from 68http://www.libsdl.org/extras/win32/cross/build-cross.sh. The gcc/binutils 69version numbers that the script downloads may need to be altered. 70Alternatively, your distribution may have mingw32 packages available. On 71debian/Ubuntu, these are mingw32, mingw32-runtime and mingw32-binutils. Cross 72compiling is simply a case of using './cross-make-mingw.sh' in place of 'make', 73though you may find you need to change the value of the variables in this 74script to match your environment. 75 76The following variables may be set, either on the command line or in 77Makefile.local: 78 79 CFLAGS - use this for custom CFLAGS 80 V - set to show cc command line when building 81 DEFAULT_BASEDIR - extra path to search for baseq3 and such 82 DEFAULT_LIBDIR - extra path to search for libraries (FreeBSD only) 83 HOMEPATH - alternative home directory (FreeBSD only) 84 BUILD_SERVER - build the 'ioq3ded' server binary 85 BUILD_CLIENT - build the 'ioquake3' client binary 86 BUILD_CLIENT_SMP - build the 'ioquake3-smp' client binary 87 BUILD_GAME_SO - build the game shared libraries 88 BUILD_GAME_QVM - build the game qvms 89 BUILD_STANDALONE - build binaries suited for stand-alone games 90 USE_OPENAL - use OpenAL where available 91 USE_OPENAL_DLOPEN - link with OpenAL at runtime 92 USE_CURL - use libcurl for http/ftp download support 93 USE_CURL_DLOPEN - link with libcurl at runtime 94 USE_CODEC_VORBIS - enable Ogg Vorbis support 95 USE_LOCAL_HEADERS - use headers local to ioq3 instead of system ones 96 COPYDIR - the target installation directory 97 98The defaults for these variables differ depending on the target platform. 99 100 101------------------------------------------------------------------ Console ----- 102 103New cvars 104 cl_autoRecordDemo - record a new demo on each map change 105 cl_aviFrameRate - the framerate to use when capturing video 106 cl_aviMotionJpeg - use the mjpeg codec when capturing video 107 cl_guidServerUniq - makes cl_guid unique for each server 108 cl_cURLLib - filename of cURL library to load 109 cl_consoleKeys - space delimited list of key names or 110 characters that toggle the console 111 112 s_useOpenAL - use the OpenAL sound backend if available 113 s_alPrecache - cache OpenAL sounds before use 114 s_alGain - the value of AL_GAIN for each source 115 s_alSources - the total number of sources (memory) to 116 allocate 117 s_alDopplerFactor - the value passed to alDopplerFactor 118 s_alDopplerSpeed - the value passed to alDopplerVelocity 119 s_alMinDistance - the value of AL_REFERENCE_DISTANCE for 120 each source 121 s_alMaxDistance - the maximum distance before sounds start 122 to become inaudible. 123 s_alRolloff - the value of AL_ROLLOFF_FACTOR for each 124 source 125 s_alGraceDistance - after having passed MaxDistance, length 126 until sounds are completely inaudible 127 s_alDriver - which OpenAL library to use 128 s_alDevice - which OpenAL device to use 129 s_alAvailableDevices - list of available OpenAL devices 130 131 s_sdlBits - SDL bit resolution 132 s_sdlSpeed - SDL sample rate 133 s_sdlChannels - SDL number of channels 134 s_sdlDevSamps - SDL DMA buffer size override 135 s_sdlMixSamps - SDL mix buffer size override 136 137 com_ansiColor - enable use of ANSI escape codes in the tty 138 com_altivec - enable use of altivec on PowerPC systems 139 com_standalone - Run in standalone mode 140 com_maxfpsUnfocused - Maximum frames per second when unfocused 141 com_maxfpsMinimized - Maximum frames per second when minimized 142 s_backend - read only, indicates the current sound 143 backend 144 s_muteWhenMinimized - mute sound when minimized 145 in_joystickNo - select which joystick to use 146 in_keyboardDebug - print keyboard debug info 147 r_ext_texture_filter_anisotropic - anisotropic texture filtering 148 sv_dlURL - the base of the HTTP or FTP site that 149 holds custom pk3 files for your server 150 151 net_ip6 - IPv6 address to bind to 152 net_port6 - port to bind to using the ipv6 address 153 net_enabled - enable networking, bitmask. Add up 154 number for option to enable it: 155 enable ipv4 networking: 1 156 enable ipv6 networking: 2 157 prioritise ipv6 over ipv4: 4 158 disable multicast support: 8 159 net_mcast6addr - multicast address to use for scanning for 160 ipv6 servers on the local network 161 net_mcastiface - outgoing interface to use for scan 162 163 r_zProj - distance of observer camera to projection 164 plane in quake3 standard units 165 r_greyscale - render black and white images 166 r_stereoEnabled - enable stereo rendering for techniques 167 like shutter glasses (untested) 168 r_anaglyphMode - Enable rendering of anaglyph images 169 red-cyan glasses: 1 170 red-blue: 2 171 red-green: 3 172 To swap the colors for left and right eye 173 just add 3 to the value for the wanted 174 color combination. For red-blue and 175 red-green you probably want to enable 176 r_greyscale 177 r_stereoSeparation - Control eye separation. Resulting 178 separation is r_zProj divided by this 179 value in quake3 standard units. 180 See also 181 http://wiki.ioquake3.org/Stereo_Rendering 182 for more information 183 r_sdlDriver - read only, indicates the SDL driver 184 backend being used 185 186New commands 187 video [filename] - start video capture (use with demo command) 188 stopvideo - stop video capture 189 190 print - print out the contents of a cvar 191 192 banaddr <range> - ban an ip address range from joining a game on this 193 server, valid <range> is either playernum or CIDR 194 notation address range. 195 exceptaddr <range> - exempt an ip address range from a ban. 196 bandel <num> - delete ban <num> 197 exceptdel <num> - delete exception <num> 198 listbans - list all currently active bans and exceptions 199 rehashbans - reload the banlist from serverbans.dat 200 flushbans - delete all bans 201 202------------------------------------------------------------ Miscellaneous ----- 203 204Using shared libraries instead of qvm 205 To force Q3 to use shared libraries instead of qvms run it with the following 206 parameters: +set sv_pure 0 +set vm_cgame 0 +set vm_game 0 +set vm_ui 0 207 208Using Demo Data Files 209 Copy demoq3/pak0.pk3 from the demo installer to your baseq3 directory. The 210 qvm files in this pak0.pk3 will not work, so you have to use the native 211 shared libraries or qvms from this project. To use the new qvms, they must be 212 put into a pk3 file. A pk3 file is just a zip file, so any compression tool 213 that can create such files will work. The shared libraries should already be 214 in the correct place. Use the instructions above to use them. 215 216 Please bear in mind that you will not be able to play online using the demo 217 data, nor is it something that we like to spend much time maintaining or 218 supporting. 219 22064bit mods 221 If you wish to compile external mods as shared libraries on a 64bit platform, 222 and the mod source is derived from the id Q3 SDK, you will need to modify the 223 interface code a little. Open the files ending in _syscalls.c and change 224 every instance of int to intptr_t in the declaration of the syscall function 225 pointer and the dllEntry function. Also find the vmMain function for each 226 module (usually in cg_main.c g_main.c etc.) and similarly replace the return 227 value in the prototype with intptr_t (arg0, arg1, ...stay int). 228 229 Add the following code snippet to q_shared.h: 230 231 #ifdef Q3_VM 232 typedef int intptr_t; 233 #else 234 #include <stdint.h> 235 #endif 236 237 Note if you simply wish to run mods on a 64bit platform you do not need to 238 recompile anything since by default Q3 uses a virtual machine system. 239 240Creating mods compatible with Q3 1.32b 241 If you're using this package to create mods for the last official release of 242 Q3, it is necessary to pass the commandline option '-vq3' to your invocation 243 of q3asm. This is because by default q3asm outputs an updated qvm format that 244 is necessary to fix a bug involving the optimizing pass of the x86 vm JIT 245 compiler. 246 247Creating standalone games 248 Have you finished the daunting task of removing all dependencies on the Q3 249 game data? You probably now want to give your users the opportunity to play 250 the game without owning a copy of Q3, which consequently means removing cd-key 251 and authentication server checks. In addition to being a straightforward Q3 252 client, ioquake3 also purports to be a reliable and stable code base on which 253 to base your game project. 254 255 However, before you start compiling your own version of ioquake3, you have to 256 ask yourself: Have we changed or will we need to change anything of importance 257 in the engine? 258 259 If your answer to this question is "no", it probably makes no sense to build 260 your own binaries. Instead, you can just use the pre-built binaries on the 261 website. Just make sure the game is called with: 262 263 +set com_standalone 1 +set fs_game <yourgamedir> 264 265 in any links/scripts you install for your users to start the game. Note that 266 the com_standalone setting is rendered ineffective, if the binary detects pk3 267 files in the directory "baseq3", so you cannot use that one as game dir. 268 269 If you really changed parts that would make vanilla ioquake3 incompatible with 270 your mod, we have included another way to conveniently build a stand-alone 271 binary. Just run make with the option BUILD_STANDALONE=1. Don't forget to edit 272 the PRODUCT_NAME and subsequent #defines in qcommon/q_shared.h with 273 information appropriate for your project. 274 275 While a lot of work has been put into ioquake3 that you can benefit from free 276 of charge, it does not mean that you have no obligations to fulfil. Please be 277 aware that as soon as you start distributing your game with an engine based on 278 our sources we expect you to fully comply with the requirements as stated in 279 the GPL. That includes making sources and modifications you made to the 280 ioquake3 engine as well as the game-code used to compile the .qvm files for 281 the game logic freely available to everyone. Furthermore, note that the "QIIIA 282 Game Source License" prohibits distribution of mods that are intended to 283 operate on a version of Q3 not sanctioned by id software: 284 285 "with this Agreement, ID grants to you the non-exclusive and limited right 286 to distribute copies of the Software ... for operation only with the full 287 version of the software game QUAKE III ARENA" 288 289 This means that if you're creating a standalone game, you cannot use said 290 license on any portion of the product. As the only other license this code has 291 been released under is the GPL, this is the only option. 292 293 This does NOT mean that you cannot market this game commercially. The GPL does 294 not prohibit commercial exploitation and all assets (e.g. textures, sounds, 295 maps) created by yourself are your property and can be sold like every other 296 game you find in stores. 297 298cl_guid Support 299 cl_guid is a cvar which is part of the client's USERINFO string. Its value 300 is a 32 character string made up of [a-f] and [0-9] characters. This 301 value is pseudo-unique for every player. Id's Quake 3 Arena client also 302 sets cl_guid, but only if Punkbuster is enabled on the client. 303 304 If cl_guidServerUniq is non-zero (the default), then this value is also 305 pseudo-unique for each server a client connects to (based on IP:PORT of 306 the server). 307 308 The purpose of cl_guid is to add an identifier for each player on 309 a server. This value can be reset by the client at any time so it's not 310 useful for blocking access. However, it can have at least two uses in 311 your mod's game code: 312 1) improve logging to allow statistical tools to index players by more 313 than just name 314 2) granting some weak admin rights to players without requiring passwords 315 316Using HTTP/FTP Download Support (Server) 317 You can enable redirected downloads on your server even if it's not 318 an ioquake3 server. You simply need to use the 'sets' command to put 319 the sv_dlURL cvar into your SERVERINFO string and ensure sv_allowDownloads 320 is set to 1 321 322 sv_dlURL is the base of the URL that contains your custom .pk3 files 323 the client will append both fs_game and the filename to the end of 324 this value. For example, if you have sv_dlURL set to 325 "http://ioquake3.org", fs_game is "baseq3", and the client is 326 missing "test.pk3", it will attempt to download from the URL 327 "http://ioquake3.org/baseq3/test.pk3" 328 329 sv_allowDownload's value is now a bitmask made up of the following 330 flags: 331 1 - ENABLE 332 2 - do not use HTTP/FTP downloads 333 4 - do not use UDP downloads 334 8 - do not ask the client to disconnect when using HTTP/FTP 335 336 Server operators who are concerned about potential "leeching" from their 337 HTTP servers from other ioquake3 servers can make use of the HTTP_REFERER 338 that ioquake3 sets which is "ioQ3://{SERVER_IP}:{SERVER_PORT}". For, 339 example, Apache's mod_rewrite can restrict access based on HTTP_REFERER. 340 341Using HTTP/FTP Download Support (Client) 342 Simply setting cl_allowDownload to 1 will enable HTTP/FTP downloads 343 assuming ioquake3 was compiled with USE_CURL=1 (the default). 344 like sv_allowDownload, cl_allowDownload also uses a bitmask value 345 supporting the following flags: 346 1 - ENABLE 347 2 - do not use HTTP/FTP downloads 348 4 - do not use UDP downloads 349 350 When ioquake3 is built with USE_CURL_DLOPEN=1 (default on some platforms), 351 it will use the value of the cvar cl_cURLLib as the filename of the cURL 352 library to dynamically load. 353 354Multiuser Support on Windows systems 355 On Windows, all user specific files such as autogenerated configuration, 356 demos, videos, screenshots, and autodownloaded pk3s are now saved in a 357 directory specific to the user who is running ioquake3. 358 359 On NT-based such as Windows XP, this is usually a directory named: 360 "C:\Documents and Settings\%USERNAME%\Application Data\Quake3\" 361 362 Windows 95, Windows 98, and Windows ME will use a directory like: 363 "C:\Windows\Application Data\Quake3" 364 in single-user mode, or: 365 "C:\Windows\Profiles\%USERNAME%\Application Data\Quake3" 366 if multiple logins have been enabled. 367 368 In order to access this directory more easily, the installer may create a 369 Shortcut which has its target set to: 370 "%APPDATA%\Quake3\" 371 This Shortcut would work for all users on the system regardless of the 372 locale settings. Unfortunately, this environment variable is only 373 present on Windows NT based systems. 374 375 You can revert to the old single-user behaviour by setting the fs_homepath 376 cvar to the directory where ioquake3 is installed. For example: 377 ioquake3.exe +set fs_homepath "c:\ioquake3" 378 Note that this cvar MUST be set as a command line parameter. 379 380SDL Keyboard Differences 381 ioquake3 clients have different keyboard behaviour compared to the original 382 Quake3 clients. 383 384 * "Caps Lock" and "Num Lock" can not be used as normal binds since they 385 do not send a KEYUP event until the key is pressed again. 386 387 * SDL > 1.2.9 does not support disabling dead key recognition. In order to 388 send dead key characters (e.g. ~, ', `, and ^), you must key a Space (or 389 sometimes the same character again) after the character to send it on 390 many international keyboard layouts. 391 392 * The SDL client supports many more keys than the original Quake3 client. 393 For example the keys: "Windows", "SysReq", "ScrollLock", and "Break". 394 For non-US keyboards, all of the so called "World" keys are now supported 395 as well as F13, F14, F15, and the country-specific mode/meta keys. 396 397 On many international layouts the default console toggle keys are also dead 398 keys, meaning that dropping the console potentially results in 399 unintentionally initiating the keying of a dead key. Futhermore SDL 1.2's 400 dead key support is broken by design and Q3 doesn't support non-ASCII text 401 entry, so the chances are you won't get the correct character anyway. 402 403 If you use such a keyboard layout, you can set the cvar cl_consoleKeys. This 404 is a space delimited list of key names that will toggle the console. The key 405 names are the usual Q3 names e.g. "~", "`", "c", "BACKSPACE", "PAUSE", 406 "WINDOWS" etc. It's also possible to use ASCII characters, by hexadecimal 407 number. Some example values for cl_consoleKeys: 408 409 "~ ` 0x7e 0x60" Toggle on ~ or ` (the default) 410 "WINDOWS" Toggle on the Windows key 411 "c" Toggle on the c key 412 "0x43" Toggle on the C character (Shift-c) 413 "PAUSE F1 PGUP" Toggle on the Pause, F1 or Page Up keys 414 415 Note that when you elect a set of console keys or characters, they cannot 416 then be used for binding, nor will they generate characters when entering 417 text. Also, in addition to the nominated console keys, Shift-ESC is hard 418 coded to always toggle the console. 419 420Mouse Input On Windows 421 ioq3 uses SDL to abstract away as much as possible from platform specific 422 implementation details. Unfortunately, SDL 1.2 suffers from a number of bugs 423 and limitations with respect to mouse input on the Windows platform. We 424 provide a patch against the SDL subversion 1.2 branch which fixes the 425 following problems: 426 427 * DirectX (and thus DirectInput) driver not functional when using an 428 OpenGL SDL_Surface. 429 430 * DirectX (and thus DirectInput) driver not functional in windowed mode. 431 432 * Mouse buttons 4-7 unusable with the DirectX driver due to DirectInput 5 433 not exposing the required functionality. Use DirectInput 7 instead. 434 435 * Low quality mouse input data when using the windib driver due to use of 436 WM_MOUSEMOVE events. Use GetCursorPos API call instead. 437 438 The patch can be found in misc/sdl-win32-fixes.diff. 439 440PNG support 441 ioquake3 supports the use of PNG (Portable Network Graphic) images as 442 textures. It should be noted that the use of such images in a map will 443 result in missing placeholder textures where the map is used with the id 444 Quake 3 client or earlier versions of ioquake3. 445 446 Recent versions of GtkRadiant and q3map2 support PNG images without 447 modification. However GtkRadiant is not aware that PNG textures are supported 448 by ioquake3. To change this behaviour open the file 'q3.game' in the 'games' 449 directory of the GtkRadiant base directory with an editor and change the 450 line: 451 452 texturetypes="tga jpg" 453 454 to 455 456 texturetypes="tga jpg png" 457 458 Restart GtkRadiant and PNG textures are now available. 459 460Building with MinGW for pre Windows XP 461 IPv6 support requires a header named "wspiapi.h" to abstract away from 462 differences in earlier versions of Windows' IPv6 stack. There is no MinGW 463 equivalent of this header and the Microsoft version is obviously not 464 redistributable, so in its absence we're forced to require Windows XP. 465 However if this header is acquired separately and placed in the qcommon/ 466 directory, this restriction is lifted. 467 468 469------------------------------------------------------------- Contributing ----- 470 471Please send all patches to bugzilla (https://bugzilla.icculus.org), or join the 472mailing list (quake3-subscribe@icculus.org) and submit your patch there. The 473best case scenario is that you submit your patch to bugzilla, and then post the 474URL to the mailing list. 475 476The focus for ioq3 is to develop a stable base suitable for further development 477and provide players with the same Quake 3 experience they've had for years. As 478such ioq3 does not have any significant graphical enhancements and none are 479planned at this time. However, improved graphics and sound patches will be 480accepted as long as they are entirely optional, do not require new media and 481are off by default. 482 483 484--------------------------------------------- Building Official Installers ----- 485 486We need help getting automated installers on all the platforms that ioquake3 487supports. We don't neccesarily care about all the installers being identical, 488but we have some general guidelines: 489 490 * Please include the id patch pk3s in your installer, which are available 491 from http://ioquake3.org/patch-data/ subject to agreement to the id 492 EULA. Your installer shall also ask the user to agree to this EULA (which 493 is in the /web/include directory for your convenience) and subsequently 494 refuse to continue the installation of the patch pk3s and pak0.pk3 if they 495 do not. 496 497 * Please don't require pak0.pk3, since not everyone using the engine 498 plans on playing Quake 3 Arena on it. It's fine to (optionally) assist the 499 user in copying the file or tell them how. 500 501 * It is fine to just install the binaries without requiring id EULA agreement, 502 providing pak0.pk3 and the patch pk3s are not refered to or included in the 503 installer. 504 505 * Please include at least an SDL so/dylib/dll on every platform. 506 507 * Please include an OpenAL so/dylib/dll, since every platform should be using 508 it by now. 509 510 * Please contact the mailing list when you've made your installer. 511 512 * Please be prepared to alter your installer on the whim of the maintainers. 513 514 * Your installer will be mirrored to an "official" directory, thus making it 515 a done deal. 516 517------------------------------------------------------------------ Credits ----- 518 519Maintainers 520 Ludwig Nussel <ludwig.nussel@suse.de> 521 Thilo Schulz <arny@ats.s.bawue.de> 522 Tim Angus <tim@ngus.net> 523 Tony J. White <tjw@tjw.org> 524 Zachary J. Slater <zachary@ioquake.org> 525 526Significant contributions from 527 Ryan C. Gordon <icculus@icculus.org> 528 Andreas Kohn <andreas@syndrom23.de> 529 Joerg Dietrich <Dietrich_Joerg@t-online.de> 530 Stuart Dalton <badcdev@gmail.com> 531 Vincent S. Cojot <vincent at cojot dot name> 532 optical <alex@rigbo.se> 533 Aaron Gyes <floam@aaron.gy> 534