IOQ3 commit 1951

reaction/README

@@ -77,22 +77,30 @@ script to match your environment.
 The following variables may be set, either on the command line or in
 Makefile.local:
 
-  CFLAGS            - use this for custom CFLAGS
+  CFLAGS             - use this for custom CFLAGS
-  V                 - set to show cc command line when building
+  V                  - set to show cc command line when building
-  DEFAULT_BASEDIR   - extra path to search for baseq3 and such
+  DEFAULT_BASEDIR    - extra path to search for baseq3 and such
-  BUILD_SERVER      - build the 'ioq3ded' server binary
+  BUILD_SERVER       - build the 'ioq3ded' server binary
-  BUILD_CLIENT      - build the 'ioquake3' client binary
+  BUILD_CLIENT       - build the 'ioquake3' client binary
-  BUILD_CLIENT_SMP  - build the 'ioquake3-smp' client binary
+  BUILD_CLIENT_SMP   - build the 'ioquake3-smp' client binary
-  BUILD_GAME_SO     - build the game shared libraries
+  BUILD_GAME_SO      - build the game shared libraries
-  BUILD_GAME_QVM    - build the game qvms
+  BUILD_GAME_QVM     - build the game qvms
-  BUILD_STANDALONE  - build binaries suited for stand-alone games
+  BUILD_STANDALONE   - build binaries suited for stand-alone games
-  USE_OPENAL        - use OpenAL where available
+  USE_OPENAL         - use OpenAL where available
-  USE_OPENAL_DLOPEN - link with OpenAL at runtime
+  USE_OPENAL_DLOPEN  - link with OpenAL at runtime
-  USE_CURL          - use libcurl for http/ftp download support
+  USE_CURL           - use libcurl for http/ftp download support
-  USE_CURL_DLOPEN   - link with libcurl at runtime
+  USE_CURL_DLOPEN    - link with libcurl at runtime
-  USE_CODEC_VORBIS  - enable Ogg Vorbis support
+  USE_CODEC_VORBIS   - enable Ogg Vorbis support
-  USE_LOCAL_HEADERS - use headers local to ioq3 instead of system ones
+  USE_MUMBLE         - enable Mumble support
-  COPYDIR           - the target installation directory
+  USE_VOIP           - enable built-in VoIP support
+  USE_INTERNAL_SPEEX - build internal speex library instead of dynamically
+                       linking against system libspeex
+  USE_INTERNAL_ZLIB  - build and link against internal zlib
+  USE_INTERNAL_JPEG  - build and link against internal JPEG library
+  USE_LOCAL_HEADERS  - use headers local to ioq3 instead of system ones
+  DEBUG_CFLAGS       - C compiler flags to use for building debug version
+  COPYDIR            - the target installation directory
+  TEMPDIR            - specify user defined directory for temp files
 
 The defaults for these variables differ depending on the target platform.
 
@@ -107,6 +115,11 @@ New cvars
   cl_cURLLib                        - filename of cURL library to load
   cl_consoleKeys                    - space delimited list of key names or
                                       characters that toggle the console
+  cl_mouseAccelStyle                - Set to 1 for QuakeLive mouse acceleration
+                                      behaviour, 0 for standard q3
+  cl_mouseAccelOffset               - Tuning the acceleration curve, see below
+  cl_gamename                       - Gamename sent to master server in
+                                      getserversExt query
 
   in_joystickUseAnalog              - Do not translate joystick axis events
                                       to keyboard commands
@@ -146,26 +159,48 @@ New cvars
   s_alDriver                        - which OpenAL library to use
   s_alDevice                        - which OpenAL device to use
   s_alAvailableDevices              - list of available OpenAL devices
-
+  s_alInputDevice                   - which OpenAL input device to use
+  s_alAvailableInputDevices         - list of available OpenAL input devices
   s_sdlBits                         - SDL bit resolution
   s_sdlSpeed                        - SDL sample rate
   s_sdlChannels                     - SDL number of channels
   s_sdlDevSamps                     - SDL DMA buffer size override
   s_sdlMixSamps                     - SDL mix buffer size override
-
-  com_ansiColor                     - enable use of ANSI escape codes in the tty
-  com_altivec                       - enable use of altivec on PowerPC systems
-  com_standalone                    - Run in standalone mode
-  com_maxfpsUnfocused               - Maximum frames per second when unfocused
-  com_maxfpsMinimized               - Maximum frames per second when minimized
   s_backend                         - read only, indicates the current sound
                                       backend
   s_muteWhenMinimized               - mute sound when minimized
+  s_muteWhenUnfocused               - mute sound when window is unfocused
+
+  com_ansiColor                     - enable use of ANSI escape codes in the tty
+  com_altivec                       - enable use of altivec on PowerPC systems
+  com_standalone (read only)        - If set to 1, quake3 is running in
+                                      standalone mode
+  com_basegame                      - Use a different base than baseq3. If no
+                                      original Quake3 or TeamArena pak files
+                                      are found, this will enable running in
+                                      standalone mode
+  com_homepath                      - Specify name that is to be appended to the
+                                      home path
+  com_maxfpsUnfocused               - Maximum frames per second when unfocused
+  com_maxfpsMinimized               - Maximum frames per second when minimized
+  com_busyWait                      - Will use a busy loop to wait for rendering
+                                      next frame when set to non-zero value
+  com_pipefile                      - Specify filename to create a named pipe 
+                                      through which other processes can control
+                                      the server while it is running. 
+                                      Nonfunctional on Windows.
+
   in_joystickNo                     - select which joystick to use
+  in_availableJoysticks             - list of available Joysticks
   in_keyboardDebug                  - print keyboard debug info
-  r_ext_texture_filter_anisotropic  - anisotropic texture filtering
+
   sv_dlURL                          - the base of the HTTP or FTP site that
                                       holds custom pk3 files for your server
+  sv_banFile                        - Name of the file that is used for storing
+                                      the server bans
+  sv_heartbeat                      - Heartbeat string sent to master server
+  sv_flatline                       - Heartbeat string sent to master server
+                                      when server is killed
 
   net_ip6                           - IPv6 address to bind to
   net_port6                         - port to bind to using the ipv6 address
@@ -179,9 +214,21 @@ New cvars
                                       ipv6 servers on the local network
   net_mcastiface                    - outgoing interface to use for scan
 
+  oldprotocol                       - when encountering a server/client that
+                                      only supports the version configured in
+                                      this cvar, ioquake3 will use the old and
+                                      less secure protocol from quake3 1.32c.
+                                      (startup only)
+
+  protocol                          - Allow changing protocol version that is
+                                      sent to the server (startup only)
+
+  r_allowResize                     - make window resizable (SDL only)
+  r_ext_texture_filter_anisotropic  - anisotropic texture filtering
   r_zProj                           - distance of observer camera to projection
                                       plane in quake3 standard units
-  r_greyscale                       - render black and white images
+  r_greyscale                       - desaturate textures, useful for anaglyph,
+                                      supports values in the range of 0 to 1
   r_stereoEnabled                   - enable stereo rendering for techniques
                                       like shutter glasses (untested)
   r_anaglyphMode                    - Enable rendering of anaglyph images
@@ -199,16 +246,27 @@ New cvars
                                       See also
                                       http://wiki.ioquake3.org/Stereo_Rendering
                                       for more information
+  r_marksOnTriangleMeshes           - Support impact marks on md3 models, MOD
+                                      developers should increase the mark
+                                      triangle limits in cg_marks.c if they
+                                      intend to use this.
   r_sdlDriver                       - read only, indicates the SDL driver
                                       backend being used
-  sv_banFile                        - Name of the file that is used for storing
+  r_noborder                        - Remove window decoration from window
-                                      the server bans.
+                                      managers, like borders and titlebar.
+  r_screenshotJpegQuality           - Controls quality of jpeg screenshots
+                                      captured using screenshotJPEG
+  r_aviMotionJpegQuality            - Controls quality of video capture when
+                                      cl_aviMotionJpeg is enabled
 
 New commands
   video [filename]        - start video capture (use with demo command)
   stopvideo               - stop video capture
+  stopmusic               - stop background music
+  minimize                - Minimize the game and show desktop
 
   print                   - print out the contents of a cvar
+  unset                   - unset a user created cvar
 
   banaddr <range>         - ban an ip address range from joining a game on this
                             server, valid <range> is either playernum or CIDR
@@ -221,8 +279,12 @@ New commands
   flushbans               - delete all bans
 
   net_restart             - restart network subsystem to change latched settings
+  game_restart <fs_game>  - Switch to another mod
 
------------------------------------------------------------- Miscellaneous -----
+  which <filename/path>   - print out the path on disk to a loaded item
+
+
+--------------------------------------------------------- README for Users -----
 
 Using shared libraries instead of qvm
   To force Q3 to use shared libraries instead of qvms run it with the following
@@ -240,101 +302,15 @@ Using Demo Data Files
   data, nor is it something that we like to spend much time maintaining or
   supporting.
 
-64bit mods
+Help! Ioquake3 won't give me an fps of X anymore when setting com_maxfps!
-  If you wish to compile external mods as shared libraries on a 64bit platform,
+  Ioquake3 now uses the select() system call to wait for the rendering of the
-  and the mod source is derived from the id Q3 SDK, you will need to modify the
+  next frame when com_maxfps was hit. This will improve your CPU load
-  interface code a little. Open the files ending in _syscalls.c and change
+  considerably in these cases. However, not all systems may support a
-  every instance of int to intptr_t in the declaration of the syscall function
+  granularity for its timing functions that is required to perform this waiting
-  pointer and the dllEntry function. Also find the vmMain function for each
+  correctly. For instance, ioquake3 tells select() to wait 2 milliseconds, but
-  module (usually in cg_main.c g_main.c etc.) and similarly replace the return
+  really it can only wait for a multiple of 5ms, i.e. 5, 10, 15, 20... ms.
-  value in the prototype with intptr_t (arg0, arg1, ...stay int).
+  In this case you can always revert back to the old behaviour by setting the
-
+  cvar com_busyWait to 1.
-  Add the following code snippet to q_shared.h:
-
-    #ifdef Q3_VM
-    typedef int intptr_t;
-    #else
-    #include <stdint.h>
-    #endif
-
-  Note if you simply wish to run mods on a 64bit platform you do not need to
-  recompile anything since by default Q3 uses a virtual machine system.
-
-Creating mods compatible with Q3 1.32b
-  If you're using this package to create mods for the last official release of
-  Q3, it is necessary to pass the commandline option '-vq3' to your invocation
-  of q3asm. This is because by default q3asm outputs an updated qvm format that
-  is necessary to fix a bug involving the optimizing pass of the x86 vm JIT
-  compiler.
-
-Creating standalone games
-  Have you finished the daunting task of removing all dependencies on the Q3
-  game data? You probably now want to give your users the opportunity to play
-  the game without owning a copy of Q3, which consequently means removing cd-key
-  and authentication server checks. In addition to being a straightforward Q3
-  client, ioquake3 also purports to be a reliable and stable code base on which
-  to base your game project.
-
-  However, before you start compiling your own version of ioquake3, you have to
-  ask yourself: Have we changed or will we need to change anything of importance
-  in the engine?
-
-  If your answer to this question is "no", it probably makes no sense to build
-  your own binaries. Instead, you can just use the pre-built binaries on the
-  website. Just make sure the game is called with:
-
-    +set com_standalone 1 +set fs_game <yourgamedir>
-
-  in any links/scripts you install for your users to start the game. Note that
-  the com_standalone setting is rendered ineffective, if the binary detects pk3
-  files in the directory "baseq3", so you cannot use that one as game dir.
-
-  If you really changed parts that would make vanilla ioquake3 incompatible with
-  your mod, we have included another way to conveniently build a stand-alone
-  binary. Just run make with the option BUILD_STANDALONE=1. Don't forget to edit
-  the PRODUCT_NAME and subsequent #defines in qcommon/q_shared.h with
-  information appropriate for your project.
-
-  While a lot of work has been put into ioquake3 that you can benefit from free
-  of charge, it does not mean that you have no obligations to fulfil. Please be
-  aware that as soon as you start distributing your game with an engine based on
-  our sources we expect you to fully comply with the requirements as stated in
-  the GPL. That includes making sources and modifications you made to the
-  ioquake3 engine as well as the game-code used to compile the .qvm files for
-  the game logic freely available to everyone. Furthermore, note that the "QIIIA
-  Game Source License" prohibits distribution of mods that are intended to
-  operate on a version of Q3 not sanctioned by id software:
-
-    "with this Agreement, ID grants to you the non-exclusive and limited right
-    to distribute copies of the Software ... for operation only with the full
-    version of the software game QUAKE III ARENA"
-
-  This means that if you're creating a standalone game, you cannot use said
-  license on any portion of the product. As the only other license this code has
-  been released under is the GPL, this is the only option.
-
-  This does NOT mean that you cannot market this game commercially. The GPL does
-  not prohibit commercial exploitation and all assets (e.g. textures, sounds,
-  maps) created by yourself are your property and can be sold like every other
-  game you find in stores.
-
-cl_guid Support
-  cl_guid is a cvar which is part of the client's USERINFO string.  Its value
-  is a 32 character string made up of [a-f] and [0-9] characters.  This
-  value is pseudo-unique for every player.  Id's Quake 3 Arena client also
-  sets cl_guid, but only if Punkbuster is enabled on the client.
-
-  If cl_guidServerUniq is non-zero (the default), then this value is also
-  pseudo-unique for each server a client connects to (based on IP:PORT of
-  the server).
-
-  The purpose of cl_guid is to add an identifier for each player on
-  a server.  This value can be reset by the client at any time so it's not
-  useful for blocking access.  However, it can have at least two uses in
-  your mod's game code:
-    1) improve logging to allow statistical tools to index players by more
-       than just name
-    2) granting some weak admin rights to players without requiring passwords
 
 Using HTTP/FTP Download Support (Server)
   You can enable redirected downloads on your server even if it's not
@@ -352,7 +328,6 @@ Using HTTP/FTP Download Support (Server)
   sv_allowDownload's value is now a bitmask made up of the following
   flags:
     1 - ENABLE
-    2 - do not use HTTP/FTP downloads
     4 - do not use UDP downloads
     8 - do not ask the client to disconnect when using HTTP/FTP
 
@@ -440,25 +415,207 @@ SDL Keyboard Differences
   text. Also, in addition to the nominated console keys, Shift-ESC is hard
   coded to always toggle the console.
 
-Mouse Input On Windows
+QuakeLive mouse acceleration (patch and this text written by TTimo from id)
-  ioq3 uses SDL to abstract away as much as possible from platform specific
+  I've been using an experimental mouse acceleration code for a while, and
-  implementation details. Unfortunately, SDL 1.2 suffers from a number of bugs
+  decided to make it available to everyone. Don't be too worried if you don't
-  and limitations with respect to mouse input on the Windows platform. We
+  understand the explanations below, this is mostly intended for advanced
-  provide a patch against the SDL subversion 1.2 branch which fixes the
+  players:
-  following problems:
+  To enable it, set cl_mouseAccelStyle 1 (0 is the default/legacy behavior)
 
-    * DirectX (and thus DirectInput) driver not functional when using an
+  New style is controlled with 3 cvars:
-      OpenGL SDL_Surface.
 
-    * DirectX (and thus DirectInput) driver not functional in windowed mode.
+  sensitivity
+  cl_mouseAccel
+  cl_mouseAccelOffset
 
-    * Mouse buttons 4-7 unusable with the DirectX driver due to DirectInput 5
+  The old code (cl_mouseAccelStyle 0) can be difficult to calibrate because if
-      not exposing the required functionality. Use DirectInput 7 instead.
+  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.
 
-    * Low quality mouse input data when using the windib driver due to use of
+  The new code tries to solve both problems:
-      WM_MOUSEMOVE events. Use GetCursorPos API call instead.
 
-  The patch can be found in misc/sdl-win32-fixes.diff.
+  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 forth it in the
+  long run.
+
+  If you try the new acceleration code and start using it, I'd be very
+  interested by your feedback.
+
+
+---------------------------------------------------- README for Developers -----
+
+64bit mods
+  If you wish to compile external mods as shared libraries on a 64bit platform,
+  and the mod source is derived from the id Q3 SDK, you will need to modify the
+  interface code a little. Open the files ending in _syscalls.c and change
+  every instance of int to intptr_t in the declaration of the syscall function
+  pointer and the dllEntry function. Also find the vmMain function for each
+  module (usually in cg_main.c g_main.c etc.) and similarly replace the return
+  value in the prototype with intptr_t (arg0, arg1, ...stay int).
+
+  Add the following code snippet to q_shared.h:
+
+    #ifdef Q3_VM
+    typedef int intptr_t;
+    #else
+    #include <stdint.h>
+    #endif
+
+  Note if you simply wish to run mods on a 64bit platform you do not need to
+  recompile anything since by default Q3 uses a virtual machine system.
+
+Creating mods compatible with Q3 1.32b
+  If you're using this package to create mods for the last official release of
+  Q3, it is necessary to pass the commandline option '-vq3' to your invocation
+  of q3asm. This is because by default q3asm outputs an updated qvm format that
+  is necessary to fix a bug involving the optimizing pass of the x86 vm JIT
+  compiler.
+
+Creating standalone games
+  Have you finished the daunting task of removing all dependencies on the Q3
+  game data? You probably now want to give your users the opportunity to play
+  the game without owning a copy of Q3, which consequently means removing cd-key
+  and authentication server checks. In addition to being a straightforward Q3
+  client, ioquake3 also purports to be a reliable and stable code base on which
+  to base your game project.
+
+  However, before you start compiling your own version of ioquake3, you have to
+  ask yourself: Have we changed or will we need to change anything of importance
+  in the engine?
+
+  If your answer to this question is "no", it probably makes no sense to build
+  your own binaries. Instead, you can just use the pre-built binaries on the
+  website. Just make sure the game is called with:
+
+    +set com_basegame <yournewbase>
+    
+  in any links/scripts you install for your users to start the game. The
+  binary must not detect any original quake3 game pak files. If this
+  condition is met, the game will set com_standalone to 1 and is then running
+  in stand alone mode.
+  
+  If you want the engine to use a different directory in your homepath than
+  e.g. "Quake3" on Windows or ".q3a" on Linux, then set a new name at startup
+  by adding
+  
+    +set com_homepath <homedirname>
+  
+  to the command line. You can also control which kind of messages to send to
+  the master server:
+  
+    +set sv_heartbeat <heartbeat> +set sv_flatline <flatline>
+    +set cl_gamename <gamename>
+  
+  The <heartbeat> and <flatline> message can be specific to your game. The
+  flatline message is sent to signal the master server that the game server is
+  quitting. Vanilla quake3 uses "QuakeArena-1" both for the heartbeat and
+  flatline messages.
+  The cl_gamename message is for dpmaster to specify which game the client
+  wants a server list for. It is only used in the new ipv6 based getServersExt
+  query.
+  
+  Example line:
+  
+    +set com_basegame basefoo +set com_homepath .foo
+    +set sv_heartbeat fooalive +set sv_flatline foodead
+    +set cl_gamename foo
+
+
+  If you really changed parts that would make vanilla ioquake3 incompatible with
+  your mod, we have included another way to conveniently build a stand-alone
+  binary. Just run make with the option BUILD_STANDALONE=1. Don't forget to edit
+  the PRODUCT_NAME and subsequent #defines in qcommon/q_shared.h with
+  information appropriate for your project.
+
+  While a lot of work has been put into ioquake3 that you can benefit from free
+  of charge, it does not mean that you have no obligations to fulfil. Please be
+  aware that as soon as you start distributing your game with an engine based on
+  our sources we expect you to fully comply with the requirements as stated in
+  the GPL. That includes making sources and modifications you made to the
+  ioquake3 engine as well as the game-code used to compile the .qvm files for
+  the game logic freely available to everyone. Furthermore, note that the "QIIIA
+  Game Source License" prohibits distribution of mods that are intended to
+  operate on a version of Q3 not sanctioned by id software:
+
+    "with this Agreement, ID grants to you the non-exclusive and limited right
+    to distribute copies of the Software ... for operation only with the full
+    version of the software game QUAKE III ARENA"
+
+  This means that if you're creating a standalone game, you cannot use said
+  license on any portion of the product. As the only other license this code has
+  been released under is the GPL, this is the only option.
+
+  This does NOT mean that you cannot market this game commercially. The GPL does
+  not prohibit commercial exploitation and all assets (e.g. textures, sounds,
+  maps) created by yourself are your property and can be sold like every other
+  game you find in stores.
+
+Network protocols
+  There are now two cvars that give you some degree of freedom over the reported
+  protocol versions between clients and servers: "protocol" and "oldprotocol".
+  The reason for this is that some standalone games increased the protocol
+  number even though nothing really changed in their protocol and the ioquake3
+  engine is still fully compatible.
+
+  In order to fix a vulnerability in the network protocol as outlined in
+  
+    http://aluigi.altervista.org/papers/q3noclient.txt
+    
+  a new network protocol was introduced that defends against such attacks.
+  Unfortunately, this protocol will be incompatible to the original quake3 1.32c
+  which is the latest official release from id.
+  Luckily, ioquake3 has backwards compatibility, on the client as well as on the
+  server. This means ioquake3 players can play on old servers just as ioquake3
+  servers are able to service old clients.
+
+  The cvar "protocol" denotes the protocol version for the new hardened
+  protocol, whereas the "oldprotocol" cvar denotes the protocol version for the
+  legacy protocol.
+  If the value for "oldprotocol" and "protocol" is identical, then the legacy
+  protocol is always used. If oldprotocol is set to 0, then support for the
+  legacy protocol is disabled.
+  
+  Mods that use a standalone engine obviously do not require dual protocol
+  support, and it is turned off if the engine is compiled with STANDALONE per
+  default. You can enable it in q_shared.h if desired by defining
+  PROTOCOL_SUPPORT_OLD.
+
+cl_guid Support
+  cl_guid is a cvar which is part of the client's USERINFO string.  Its value
+  is a 32 character string made up of [a-f] and [0-9] characters.  This
+  value is pseudo-unique for every player.  Id's Quake 3 Arena client also
+  sets cl_guid, but only if Punkbuster is enabled on the client.
+
+  If cl_guidServerUniq is non-zero (the default), then this value is also
+  pseudo-unique for each server a client connects to (based on IP:PORT of
+  the server).
+
+  The purpose of cl_guid is to add an identifier for each player on
+  a server.  This value can be reset by the client at any time so it's not
+  useful for blocking access.  However, it can have at least two uses in
+  your mod's game code:
+    1) improve logging to allow statistical tools to index players by more
+       than just name
+    2) granting some weak admin rights to players without requiring passwords
 
 PNG support
   ioquake3 supports the use of PNG (Portable Network Graphic) images as