README

                       * ****************************** *
                       *        Yamagi Quake II         *
                       *  http://www.yamagi.org/quake2  *
                       *    http://github.com/yquake2   *
                       * ****************************** *

===============================================================================

This is the Yamagi Quake II Client, an enhanced Version of id Software's Quake
II. The main focus is single player, the gameplay and the graphics are
unchanged, but many bugs were fixed. Unlike most other Quake II ports Yamagi
Quake II is full 64 bit clean so it works perfectly on modern amd64 (x86_64)
processors and operating systems. This code should run on Windows XP or later,
Mac OS X 10.6 or higher (unsupported!) and on most unix-like operating systems
(only FreeBSD, Linux and OpenBSD are officially supported and tested, for other
systems you'd at least have to edit the Makefile), just type "make" or "gmake"
to compile.

This code is based upon Icculus Quake II, which itself is built upon id
Software's original code drop. Additional code and patches by many contributers
were used. It's released under the terms of the GPL version 2. See the LICENSE
file for further information.

===============================================================================

Content of this file:
--------------------
 1. Installation on (Free|Open)BSD and Linux
   1.1 Supported Systems
   1.2 Retail Version
   1.3 Demo Version
   1.4 Addons
   1.5 Compiling
   1.6 Default Configuration

 2. Installation on Microsoft Windows
   2.1 Supported Systems
   2.2 Retail Version
   2.3 Demo Version
   2.4 Addons
   2.5 Binary Installation
   2.6 Compiling
   2.7 Default Configuration

 3. Installation on OS X
   3.1 Supported Systems
   3.2 Retail Version
   3.3 Demo Version
   3.4 Addons
   3.5 Binary Installation
   3.6 Compiling
   3.7 Default Configuration

 4. OGG/Vorbis playback
   4.1 Setup for the original soundtrack
   4.2 Setup for other music and playlists
   4.3 Manual control
   4.4 Console variables

 5. Configuration
   5.1 Video
   5.2 Input
   5.3 Sound
   5.3.1 The classic sound system
   5.3.2 The OpenAL sound system

 6. Bugreports

 7. FAQ

===============================================================================

1. Installation on (Free|Open)BSD and Linux
===========================================
Note: If you're using Debian Linux or a derived distribution like Ubuntu, you
probably want to use the packages that are linked in the Download section at
http://www.yamagi.org/quake2/debian.html They'll even assist you in installing
the game data.

1.1 Supported Systems:
----------------------
Officially, only FreeBSD, Linux and OpenBSD on i386 (x86), amd64 (x86_64),
sparc64 and compatible CPUs are supported. Other (Unix-like) Operating Systems
and hardware architectures are untested and may need small changes, at least in
the Makefile. Yamagi Quake II needs OpenGL 1.1 (better: 1.4) support in hardware
and libGL; OpenGL ES will not work. The only tested compilers are gcc 4.2 (or
later) and clang 3.0 (or later). Patches (or better Github pull request) for
other platforms are welcome. :-)

1.2 Retail Version:
-------------------
If you own Quake II, first get the official point release to Quake II 3.20:
ftp://ftp.idsoftware.com/idstuff/quake2/q2-3.20-x86-full-ctf.exe Use this and
only this file! Unofficial "linux pointreleases" or something like that will 
not work and may crash your game!

Create a new directory "quake2/" and extract (with unzip) the file you just
downloaded into it. Even if the file extension is ".exe" it's a self-extracting
zip file. Now delete the following files and directories:
- 3.20_Changes.txt
- quake2.exe
- ref_gl.dll
- ref_soft.dll
- baseq2/gamex86.dll
- baseq2/maps.lst
- ctf/ctf2.ico
- ctf/gamex86.dll
- ctf/readme.txt
- ctf/server.cfg
- xatrix/gamex86.dll
- rogue/gamex86.dll

Now put the Quake II CD-ROM into your cd drive and copy the file "pak0.pak"
and the directory "video/" to the "baseq2/" directory of your installation.

1.3 Demo Version:
-----------------
If you haven't got Quake II, try the demo version. Get it here:
ftp://ftp.idsoftware.com/idstuff/quake2/q2-314-demo-x86.exe

Unzip this file (again, it's a self-extracting zip file). Create a new
"quake2/" directory with a "baseq2/" sub-directory and put the
"pak0.pak" and the "players/" sub-directory into it - you can find them
within the unzipped files in Install/Data/baseq2/ -  in your "baseq2/"
directory. No patching is needed for the demo, in fact it would break
it.

1.4 Addons
----------
Due to license issues - Yamagi Quake II is covered by the GPL and the
addons are under the id Software SDK license - the addons are
distributed separately. You can get them at http://www.yamagi.org/quake2,
both contain installation instructions. But nevertheless you'll need an
installation of the full Quake II game with our client for playing them.
The same applies to the "ctf" capture the flag addon.

1.5 Compiling:
--------------
After you have set up the game data (from the full version or the
demo), you have to compile the Yamagi Quake II client.

You will need the following dependencies (by editing the Makefile
the requirement of most of this depencenies can be removed, but
it'll lead to the loss of features):
 - A libGL implementation (Mesa3D, nVidia, AMD Catalyst, etc.)
 - OpenGL system headers
 - libjpeg (version 8 or higher)
 - libogg with development headers
 - libvorbis with development headers
 - OpenAL with development headers
 - SDL 1.2 or 2.0 (the later is recommended) with development headers
   and sdl-config(1)
 - ZLib

Extract the source, change into the new created directory and type "make"
(Linux) or "gmake" (FreeBSD, OpenBSD). After the compilation finished, copy the
following files from "release/" to your installation directory preserving the
directory structure:
- q2ded
- quake2
- baseq2/game.so

1.6 Default Configuration
-------------------------
Quake II ships with an old and for today standards "insane" default
configuration. This is no problem since you can alter everything. To make your
life easier Yamagi Quake II contains an updated default configuration.
If you want to use it just copy "stuff/yq2.cfg" to your "baseq2/" folder.

Now you are ready to start your brand new Quake II. Have fun.

===============================================================================

2. Installation on Microsoft Windows
====================================
Yamagi Quake II has full support for Microsoft Windows. All features are
supported, including the IPv6 network code and the OpenAL sound backend.
Installation can be done by using the binary release (this is highly 
recommended) or by compiling the source with MinGW.

2.1 Supported Systems
---------------------
Yamagi Quake II should run on Windows XP or higher, older versions are not
supported. You'll need a graphics card with support for at least OpenGL 1.1
(OpenGL 1.4 is recommended). Both x86 and x86_64 Windows installations are
supported, but x86 is much more tested.

2.2 Retail Version
------------------
If you own Quake II, first get the official point release to Quake II 3.20:
ftp://ftp.idsoftware.com/idstuff/quake2/q2-3.20-x86-full-ctf.exe
Use this and only this file! Unofficial pointreleases or something like
that will not work and may crash your game!

Extract the file into a new directory (we recommend quake2\) and remove
the following files and directories:
- 3.20_Changes.txt
- quake2.exe
- ref_gl.dll
- ref_soft.dll
- baseq2\gamex86.dll
- baseq2\maps.lst
- ctf\ctf2.ico
- ctf\gamex86.dll
- ctf\readme.txt
- ctf\server.cfg
- xatrix\gamex86.dll
- rogue\gamex86.dll

Now put the Quake II CD-ROM into your cd drive and cancel the installation. 
Copy "pak0.pak" and the directory "video\" to the "baseq2\" directory of your
installation.

2.3 Demo Version
----------------
If you haven't got Quake II, try the demo version. Get it here:
ftp://ftp.idsoftware.com/idstuff/quake2/q2-314-demo-x86.exe

Extract this file into a new directory and delete everything but
"baseq2\pak0.pak" and the "baseq2\players\" directory. No patching
is needed for the demo, in fact it would break it.

2.4 Addons
----------
Due to license issues - Yamagi Quake II is covered by the GPL and the
addons are under the id Software SDK license - the addons are
distributed separately. You can get them at http://www.yamagi.org/quake2,
both contain installation instructions. But nevertheless you'll need an
installation of the full Quake II game with our client for playing them.
The same applies to the "ctf" capture the flag addon. Please note, that
support for the addons is included in the binary release (see below).

2.5 Binary Installation
-----------------------
We highly recommend, that you use our binary release of Yamagi Quake 2. 
Just extract it over the directory created in step 2.3 or 2.4. If you
want to copy the files by hand, just copy them over by preserving the
directory structure. Please make sure that openal32.dll is copied too.
Otherwise Yamagi Quake 2 may use a systemwide installed library, which
may cause problems including a non starting game.

2.6 Compiling
-------------
Compiling Yamagi Quake II from source is unnecessary as long as you do not
want to use the github version or want to develop on Windows. If you really
want to compile Yamagi Quake II by yourself follow these steps:

1. Grab an up to date version of the MinGW build environment from
   http://deponie.yamagi.org/quake2/windows/build/, extract it to C:\MinGW
   and start either the 32 bit or the 64 bit version by C:\MinGW\MSYS32
   or C:\MinGW\MSYS64.
2. Navigate to your Yamagi Quake II source. If you need to check it out
   from git, first install git from http://git-scm.com/. Type "make" to
   compile. Please note, that compilation on network shares is somewhat
   shaky.

After compiling, copy the following files from "release\" to your Quake II
installation preserving the directory structure:
- q2ded.exe
- quake2.exe
- baseq2\game.dll

You'll need an "openal32.dll". You can use and rename the OpenAL DLL that
that is provided by OpenAL Soft (see http://kcat.strangesoft.net/openal.html).
Please note that the name of the DLL is always "openal32.dll", even if it's
a 64 bit library.

2.7 Default Configuration
-------------------------
Quake II ships with an old and for today standards "insane" default
configuration. This is no problem since you can alter everything. To make your
life easier Yamagi Quake II contains an updated default configuration.
If you want to use it just copy "stuff\yq2.cfg" to your "baseq2\" folder.

Now you are ready to start your brand new Quake II. Have fun.

===============================================================================

3. Installation on OS X
=======================
Yamagi Quake II has full support for Apple OS X. All features are
supported, including the IPv6 network code and the OpenAL sound backend.
Installation can be done by using the binary release (this is highly
recommended) or by compiling the source.

ATTENTION: OS X is currently unsupported. I neither have a Mac nor the time to
maintain this platform. If you're interested in spending work on OS X please
write an e-mail to quake2@yamagi.org.

3.1 Supported Systems
---------------------
Yamagi Quake II should run on every Mac with Intel CPU and OS X 10.6
or higher.

3.2 Retail Version
------------------
If you own Quake II, first get the official point release to Quake II 3.20:
ftp://ftp.idsoftware.com/idstuff/quake2/q2-3.20-x86-full-ctf.exe
Use this and only this file! Unofficial pointreleases or something like
that will not work and may crash your game!

Extract the file into a new directory (we recommend quake2\) and remove
the following files and directories:
- 3.20_Changes.txt
- quake2.exe
- ref_gl.dll
- ref_soft.dll
- baseq2\gamex86.dll
- baseq2\maps.lst
- ctf\ctf2.ico
- ctf\gamex86.dll
- ctf\readme.txt
- ctf\server.cfg
- xatrix\gamex86.dll
- rogue\gamex86.dll

Now put the Quake II CD-ROM into your cd drive and copy "pak0.pak" and
the directory "video\" to the "baseq2\" directory of your installation.

3.3 Demo Version
----------------
If you haven't got Quake II, try the demo version. Get it here:
ftp://ftp.idsoftware.com/idstuff/quake2/q2-314-demo-x86.exe

Extract this file into a new directory and delete everything but
"baseq2\pak0.pak" and the "baseq2\players\" directory. No patching
is needed for the demo, in fact it would break it.

3.4 Addons
----------
Due to license issues - Yamagi Quake II is covered by the GPL and the
addons are under the id Software SDK license - the addons are
distributed separately. You can get them at http://www.yamagi.org/quake2,
both contain installation instructions. But nevertheless you'll need an
installation of the full Quake II game with our client for playing them.
The same applies to the "ctf" capture the flag addon. 
 
3.5 Binary Installation
-----------------------
We highly recommend, that you use our binary release of Yamagi Quake 2.
Extract the zip archive and right click on the app. Select "Show Contents",
a new finder window will open. Navigate to Contents/Resources/baseq2 and
copy the contents of the baseq2/ folder (created while preparing the game
data, see above) into it. Close the finder windows. Yamagi Quake II is
now ready.

3.6 Compiling
-------------
Compiling Yamagi Quake II from source is unnecessary as long as you will not
use the github version or want to develop on OS X. If you really want to
compile Yamagi Quake II by yourself follow these steps:

1. Make sure that you've installed XCode with the "Unix Develoment Tools".
   Depending on your OS X version the name of these can be different.
2. Extract the framework found in stuff/osx-frameworks to /Libraries/
   Frameworks. It's generally a good idea to use our versions since
   other builds might be incompatible.
3. Open a terminal and navigate to the Yamagi Quake II source code. Type
   "make" to compile it. After that the binaries can be found in the release/
   directory.

The binaries can be put into an app-bundle (see 3.5 Binary Installation) or
used in the classic classic unix way. In the latter case the game be started 
at the command line. Be aware that the app-bundle support has to be deactivated
in the Makefile, otherwise the game is unable to find it's libraries!

3.7 Default Configuration
-------------------------
Quake II ships with an old and for today standards "insane" default
configuration. This is no problem since you can alter everything. To make your
life easier Yamagi Quake II contains an updated default configuration.
If you want to use it just copy "stuff\yq2.cfg" to your "baseq2\" folder.

Now you are ready to start your brand new Quake II. Have fun.

===============================================================================

4. OGG/Vorbis playback
======================
Since most modern CD-ROM and DVD drives don't have an analog audio output and
most sound codecs don't have the appropriate input header, it's not possible to
use CD audio as background music on such systems. With SDL 2.0 CD audio is
unsupported Therefore OGG/Vorbis music support has been added to Yamagi Quake 
II.

4.1 Setup for the original soundtrack:
--------------------------------------
Put your Quake II CD-ROM into your drive, start your favorite CD extractor and
rip the audiotracks into OGG/Vorbis files. These files must be named after their
track number, beginning with 02, because the first track is data.
If everything is done correct, you should have: 02.ogg, 03.ogg, ..., 11.ogg.
Alternatively you can use a script which can be found in the folder "stuff/".
It needs cdparanoia and oggenc and should work with the main game and both
addons.
Drop these files in "baseq2/music/", start Quake II, enter the "Options" menu
and set "OGG music" to enabled. "CD music" will be automaticly disabled.
Quake II will now play the OGG/Vorbis files instead of the Audio-CD.

4.2 Setup for other music and playlists:
----------------------------------------
You can put any OGG/Vorbis files into "baseq2/music/" or "your_mod/music/".
If shuffle is enabled, Quake II will shuffle through all files, otherwise it
will loop through the track associated with the map.
A playlist is also supported. Just put the filenames into music/playlist
(a plain text file) and start the game.

4.3 Manual control:
-------------------
For manual control of ogg playback the following console commands are available:

- ogg_play {file | #n | ? | >n | <n}
 Play a file, the argument can be one of (n is always a number, e.g. 42):
  * A file in "music", without the path and ".ogg" extension.
  * #n to play the n-th file in the playlist.
  * ? which indicates to play a random file.
  * >n which indicates to advance n positions (defaults to 1).
  * <n which indicates to go back n positions (defaults to 1).

- ogg_stop
 Stop playback

- ogg_pause
 Pause playback

- ogg_resume
 Resume playback

- ogg_seek {n | >n | <n}
 Go to a determinated position of the current file in seconds, the argument can
 be one of the following:
  * n, which indicates to go to the n-th second.
  * >n, which indicates to advance n seconds.
  * <n, which indicates to go back n seconds.
 You can use "ogg_seek >0" and "ogg_seek <0" to get the current position without
 changing it.

- ogg_status
 Display status ("playing a file", "paused", "stopped", etc).

4.4 Console variables:
----------------------
- ogg_enable {0 | 1}
 Enables the Ogg Vorbis subsystem if set to "1". Defaults to "0".

- ogg_playlist {name}
 Use "name" as a list of files instead of listing the contents of "music".
 Note that the files must be in "music" and follow ogg_play's syntax for
 files. Defaults to "playlist".

- ogg_sequence {next | prev | random | loop | none}
 When a file ends, start playing another one, depending on the value:
  * next: play the next file.
  * prev: play the previous file.
  * random: play a random file.
  * loop: play the same file again.
  * none: stop playing.
 Defaults to "loop".

- ogg_volume
 Volume of the music between 0 and 2. Defaults to "0.7".

===============================================================================

5. Configuration
================
While configuring Quake II is straight forward some rough edges can arise.
Before reporting bugs or mailing us please read this section all the hints
covered in it!

5.1 Video
---------
For most people the options in the "Video" menu are sufficent. But there
are some things that can and in some cases must be tuned via cvars. Here
the most common questions are answered.

- Yamagi Quake II has full support for widescreen setups. Just select your
  favorite resolution via the video menu.

- If your resolution is not in the list, it's also possible to set custom
  resolutions via the console: Set gl_customwidth and gl_customheight to the
  desired values. Change gl_mode to -1 or enter the "Video" menu and select
  "Custom" as video mode.

- Sync problems resulting in tearing and artifacts in the lower half of
  the screen: These orginiate in the fact, that in 1997 LCD flat panels were not
  widely used because they were very expensive and much too slow for gaming.
  Thus Quake II has problems when played on most flat panel monitors.
  The solution for this problem is simple: Just set "cl_maxfps" to about
  95 FPS and enable the vsync by setting "gl_swapinterval" to 1.
  This should supress all of the problems.

- Particle effects are broken. They're just squares and not perfectly
  round: This is a problem by your graphics driver, not implementing
  a special filter mode for "points". Set "gl_ext_pointparameters" to 0
  to get better (but not perfect) particles.

- The game is bright enough but it's also washed out and dull: You need
  more saturation. Just adjust the cvar "intensity". The default 2
  should be enough for most cases, but some setups require higher
  levels.

- If the colors look over-saturated try setting the cvar "intensity" to a lower
  value, e.g. 1.

- Yamagi Quake II offers hardware gamma control in realtime in the "Video" menu.
  If Quake II is still too dark, set the "vid_gamma" cvar by hand to values
  above 1.5.

- Yamagi Quake II can draw shadows. Just set "gl_shadows" to 1. You most
  likely want to set "gl_stecilshadow" to 1 too. This enables high
  quality stencil buffer shadows.

- Yamagi Quake II has support for anisotropic filtering. Activating it
  improves texture drawing over large distances a bit.
  Enter "gl_anisotropic_avail" in your console for the maximum amount of
  filtering supported by your video card and set the cvar "gl_anisotropic" to
  the desired value. It must be a power of 2, in most cases 2, 4, 8 or 16.

- Yamagi Quake II has support for the high resolution retexturing pack, created
  by the community. Installation is easy:
   1. Download q2_textures.zip and/or models.zip from
        http://www-personal.umich.edu/~jimw/q2/
   2. Extract one or both files into the "baseq2/" directory of your Quake II
      installation, so that the new directories "baseq2/textures/" and/or
      "baseq2/models/" are created.
   The retexturing pack is used by default if it's installed. It can be switched
   off at any time by setting "gl_retexturing" to "0" and executing
   "vid_restart" aftwards.

- Yamagi Quake II has support for antialiasing. Set gl_msaa_samples to the
  desired antialiasing factor (most graphic cards support 2, 4, 8 and 16),
  followd by a vid_restart. Please note that very old graphic cards may not
  support antialiasing at all.

- It's possible to upscale nearly all 2D artwork. This is especially usefull on
  high resolution displays were the cosole and HUD can become very small or even
  unreadable. Scaling support is devided into 3 parts which are controlled by
  cvars:
   - gl_consolescale: Scale the console and most in-game texts
   - gl_menuscale: Scales the menu. Please note that the menu was never ment to
                   be scaled and slight disalignement (especially in the "Player
                   Setup" menu) are unavoidable. That's not considered a bug.
   - gl_hudscale: Scales the in-game HUD
 All 3 cvars work the same way. They're set to the scale factor. A factor of 1
 (defaults) means no scaling at all. Values smaller than 1 but bigger than 0
 downscale the artwork, it becomes smaller. A value of 0 means no artwork at
 all. Values greater than 1 enlarge the artwork. Please note that full numbers
 will give best results. For example 1.7 will lead to small distortions while
 2 will not. Most users will set all 3 cvars to -1. In that case the game
 calculates a more or less optimal scaling factor, matching the artwork size
 at a resolution of 640x480.

5.2 Input
---------
Quake II had a rather simple input system, even back in 1997. It just mapped
Windows 95 mouse directly on movements. That was a very acurate way to do it,
Quake II was - like all other id Software games - much more acurate than most
games out there. But there were some problems. First the mouse input depends on
the operation systems mouse driver. Another operating system or even another
mouse and the input changed drastically. That sucked.

Yamagi Quake II features a from scratch rewritten mouse backend based on SDL.
It gives you the same mouse behavior, regardless of your operating system or
hardware. But sadly it can't emulate the old behavior in all cases.

There are some cvar to adjust:

- in_mouse -> Set to 0 to disable the mouse.

- sensitivity -> The sensistivity of the mouse. Adjust to your needs, via the
  cvar or via the "Options" menu.

- in_filter -> A mouse filter. This was added in one of the countless point
  releases but it was broken. We fixed it. The effect is the same as in
  Quake III Arena, instead of using the raw movement signals, two of them are
  combined, filtering vibrations and things like that out.

- exponential_speedup -> "0" is disabled. A very simple approach to mouse
  acceleration, much simpler than modern mouse acceleration. Sadly it's nearly
  impossible to add modern acceleration to Quake II since most of the needed data
  isn't available to the input backend.

5.3 Sound
---------
Quake II featured one of the best sound systems of it's time (for example it had
support for realtime calculated stereo effects) but sadly it was totaly broken.
Therefore id Software rewrote it once, later it was rewritten again for the
linux port. That fixed the most visible problems, but the code was just crap and
broke again as time passed and sound on PCs evolved. For Yamagi Quake II 3.0 the
sound system was overhauled, featuring a complete code audit of the upper layers
with many bugfixes and memory leak plugs. The backend was rewritten from
scratch. This should solve most if not all problems. Yamagi Quake II 4.20
featured an optional OpenAL sound system, enabling better stereo calculations
and even surround support.

5.3.1 The classic sound system
------------------------------
This is the original sound implementation, as used in the first release of Quake
II in 1997. It featured stereo calculations for most samples. It's disabled by
default and can be reenabled by setting "s_openal" to "0", followed by
"snd_restart. Common problems with the classic sound system are:

- The earthquake sound sample is distorted
  This is not a fault of the sound code but of the sound sample itself.
  It's mostly made of very low frequency noices and sampled in only 22kHz,
  bringing cheap onboard soundcards to the limit. The only solution would be to
  change the sample...

- The sound is stuttering and cracking
  This is most likely a problem on your side! First make sure that your SDL
  sound backend is installed properly. Does the sound work in other SDL games
  like ioquake3? If possible remove all sound servers from your stack and use
  plain OSS or ALSA via libasound. If everything fails try create an ~/.asoundrc
  with this contents:

   pcm.!default {
   type hw
   card 0
   }

   ctl.!default {
   type hw
   card 0
   }

5.3.2 The OpenAL sound system
-----------------------------
This is a sound system based upon the popular OpenAL audio library. It features
surround playback which gives a huge improvement in sound quality and gameplay
experience. It's enabled by default, but can be disabled by setting "s_openal"
to "0", followed by a "snd_restart". To work correctly it's in the need of a
correctly configured OpenAL implementation! On OS X and Windows the default
configuration is okay. On FreeBSD, Linux and OpenBSD OpenAL is configured in the
file ~/.alsoftrc (for the openal-soft implementation, other implementations may
vary). The most important options (tested with OpenAL Soft 1.14) are:

- channels = surround51 -> Enable 5.1 surround support. Other values are "mono",
  "stereo", "quad", "surround61" and "surround71".

- stereodup = true -> If set to "true" all raw stereo samples (in Quake II the
  background music and video sounds) are duplicated behind the listener.
  Otherwise they're played only through the front speakers.

- resampler = cubic -> Use cubic resampling. While this requires more cpu power
  than the default linear resamling it's highly recommended since Quake II has
  several hard to resamples sound effects. Especially the earthquake sound can
  distort if a low quality resampler is employed!

- hrtf = true -> When playing with headphones this gives a much better surround
  experience, even with only two channels. But playback will sound "broken" on
  normal speakers.

If the sound is distorted and cracking, most likely the ingame volume is set too 
high. Lower it by setting the "s_volume" CVAR to 0.3 or even less and use the 
system mixer instead! If everything failes set s_openal_maxgain to a lower value
like 0.3 to clamp the maximum preamplification gain. But beware! The side effect
is a limited dynamic range!

===============================================================================

6. Bugreports
=============
Something is not working as expected? An elevator is broken? An enemy doesn't
move? Or the whole game is just crashing? Just open a new github issue at
https://github.com/yquake2/yquake2. Please include a problem description and
- if possible - a screenshot of the problematic situation and the name of the
problematic map. In case of crashes, further helpful information (and
instructions) are printed to stdout (your terminal, ...\Documents\YamagiQ2\
stdout.txt on Windows).

But first, read this little FAQ:

My SDL sound is not working!
 - Most reported sound problems exist between keyboard and chair. Please make
   sure, the the correct SDL sound backend is installed and configured!
   Does the sound work in other SDL games? Does your setup support at least five
   virtual channels? In most cases it's better to not use sound servers like
   Pulseaudio but the plain sound system like OSS or ALSA with libasound instead.
   Also see the "Sound" section in this file!

My OpenGL is not working!
 - Make sure, that OpenGL is working in other games. Use "glxinfo" and
   "glxgears" to make sure, that hardware rendering is available.
   Otherwise, fix your setup. If reporting OpenGL bugs please include a copy of
   your xorg.conf (if available) and the Xorg.0.log.

The game is crashing!
 - Make sure that your installation is complete. Missing files will crash Quake
   II on random occasions and will produce strange backtraces! This just wastes
   our time, so please check first and report then!

Valgrind reports many, many memory leaks!
 - Yeah it does. But they're usually false positives due to Quake IIs caching
   architecture. There are some real memory leaks in SDL, Mesa3D, X11 and so on
   but they're out of our scope. So before reporting memory leaks please read 
   the code, understand the code and be sure that's a real leak!

===============================================================================

7. FAQ
======

How do I open the console?
 - Press "^" or "~", depending on your keyboard layout.

How do I get the frame counter?
 - Set "cl_drawfps" to 1

How do I make a benchmark?
 - Set "timedemo" to 1 and play a demo.

How do I play demos?
 - "demomap name.dm2". Note that the extension .dm2 is important!

How do I record a demo?
 - "record name" and "stop" to stop.

When playing in window mode my cursor is locked onto the window. Can I change
that, so that Quake II behaves like a normal window?
 - Open the console by pressing ~ or ^ or drop into the menu. If you want Quake
   II to never  grab the mouse set "in_grab" to 0, if Quake II should never
   release the mouse set 1, for releasing the mouse when the console or the
   menu is opened set to 2. The default is 2.

Hey, my screensaver crashes Quake II or I experience strange crashes after a
fixed amount of time!
 - This is a known bug in some linux distributions. SDL fails to disable
   the screensaver even if we tell him to do so. See this Ubuntu bugreport:
   https://bugs.launchpad.net/ubuntu/+source/gnome-screensaver/+bug/32457
   As a work around use the startscript in stuff/quake-start.sh It deactivates
   the screensaver before starting Quake II and reenables it after exiting the
   game.

Okay, Yamagi Quake II is for single player and coop. But what's with us
deathmatch and / or CTF freaks?
 - Use another client. There are clients out there which offer far better multi-
   player experiences. They're featuring greatly improved network code and a
   better client<->server integration. Take a look at EGL, r1q2 or AprQ2. At
   least r1q2 should work on unixlike operating systems.

The movement is fucked up! I can jump much higher and longer as it used
to be! What's wrong?
 - You're experiencing the Quake II version of the famous Q3A 125hz bug.
   When Quake II draws more than about 100 FPS the movement calculations go
   wrong and you can jump much higher. To solve this set "cl_maxfps" to about
   95 FPS. And no, we won't fix it since it would be very invasive and most
   likely break a lot of other things.

I'm creating a package or port for my system. Is a system wide install
possible without patching the source?
 - Yes. Just set -DSYSTEMWIDE. If you want to change the default
   directory from /usr/share/games/quake2/, just set -DSYSTEMDIR
   to the desired path. Also have a look into the Makefile.

How do I disable friendly fire in coop mode?
 - The same way as in team deathmatch. Via the menu select "deathmatch options"
   and set teamplay to "by skin" or by "by model" and friendly fire to disabled.
   Make sure, that all players have the same model or skin! If you're using the
   dedicated server or are already in the game, open the console and type
   "dmflags 336" für skinbased teamplay and  "dmflags 400" for modelbased
   teamplay.

Can I connect to an IPv6 server?
 - Yes, the same way as connecting to an IPv4 server. Since the Quake II console
   has problems with the characters ":", "[" and "]" we suggest to submit the
   connection command as command line argument:
     ./quake2 +connect "[2001:db8::1]"
   If you want to connect to a server with a non-standard port use the following
   syntax:
     ./quake2 +connect "[2001:db8::1]:12345"
   For your server to show up in the server list you need to supply a multicast
   interface to both the client and the server:
     ./q2ded +set multicast eth0
     ./quake2 +set multicast eth0
   Normaly the server will listen to all IPv4 and IPv6 addresses. You can bind
   it to an address with:
     ./q2ded +set ip "[2001:db8::1]"

Where can I find the configuartion file?
 - It's located at ~/.yq2/game/config.cfg (FreeBSD, Linux, OpenBSD and OS X) or
   ...\Documents\YamagiQ2\game\config.cfg (Windows). Replace "game" by the mod
   name, e.g. "baseq2/" for the main game.

My mod crashes at startup.
 - This is known problem of some mods. A workaround is to create the working
   directory by hand:
     mkdir -p ~/.yq2/$moddir (FreeBSD, Linux, OpenBSD and OS X)
     ...\Documents\YamagiQ2\$moddir (Windows)

Only parts of the maps are rendered!
 - By default the maximum view distance is 2300 units. You can widen it up
   to 4096 units by setting "gl_farsee" to "1".

Why has Yamagi Quake II no support for joysticks?
 - Because nobody has implemented it yet and egoshooters like Quake II
   are not really meant to be played with joysticks, gamepads or anything
   like that. If you really need joystick support you can use a joystick
   to keyboard translator like joytran (for FreeBSD, Linux and OpenBSD): 
     http://chiselapp.com/user/beyert/repository/joytran/index

What is yq2.cfg for?
 - yq2.cfg is an alternate startup script, used to override some bad
   decisions in the original defaults.cfg. Please do not alter it,
   unless you know what you're doing! It may beak the game!

Why isn't there an "underwater sound effect" when playing under OS X?
 - That's a limitation of OS X. Apples OpenAL implementation doesn't
   support sound effects.

Why is the FOV different than in id Softwares client?
 - id Softwares client was designed to work an 4:3 screens only. Setting
   the FOV kept the aspect ratio, expanded the view angle in height and 
   width. Setting a higher FOV on wider screens was common, but the image
   distorted lightly. Yamagi Quake II calculates a correct FOV without
   distortions. You can get the old behavior if you select an aspect
   ratio other than "auto" in the video menu or by setting the "horplus"
   cvar to "0".

Why doesn't gl_showtris work?
 - gl_showtris requires gl_ext_multitexturing set to 0.

How do I disable the vsync?
 - Set gl_swapinterval to 0 and type vid_restart. Beware that this may
   not work with SDL 1.2 due to bugs in SDL.

==============================================================================