diff --git a/doc/01_index.md b/doc/01_index.md index 646625f0..5a2c8cd1 100644 --- a/doc/01_index.md +++ b/doc/01_index.md @@ -9,10 +9,10 @@ Some general hints: * No matter what's the current keyboard layout or on which platform the game is running, the console is always opened and closed by pressing **Left Shift + Escape**. -* Yamagi Quake II saves its configuration, savegames and screenshots - to *~/.yq2* (unixoid platforms) or *My Documents\YamagiQ2* (Windows). - If Yamagi Quake II is started with the `-portable` switch all data - is saved in the same directory as the executables. +* Yamagi Quake II saves its configuration, savegames and screenshots to + *~/.yq2/* (unixoid platforms) or *My Documents\YamagiQ2\* (Windows). + If Yamagi Quake II is started with the `-portable` switch all data is + saved in the same directory as the executables. The documentation is split into several documents: diff --git a/doc/02_installation.md b/doc/02_installation.md index 839861ca..c0dc6bfd 100644 --- a/doc/02_installation.md +++ b/doc/02_installation.md @@ -1,8 +1,7 @@ # Installation -This guide shows how to install Yamagi Quake II from scratch. All -fully supported platforms and both the full version and the demo -version are covered. +This guide shows how to install Yamagi Quake II from scratch. All fully +supported platforms, both the full and the demo version are covered. ## The Full Version @@ -16,7 +15,7 @@ Over the years Quake II was distributed in a myriad of ways: * etc. Yamagi Quake II is compatible with all of these versions. While some of -these versions come with all patches applied it's highly recommended to +these versions come with all patches applied, it's highly recommended to follow this guide step by step and to reapply the patch by hand. Not all distributors patched the game correctly, leading to serve problems like missing assets or even crashes. @@ -130,7 +129,7 @@ just *music/*, next to *baseq2/*. **Not** inside *baseq2/*. ### Alternate Startup Configuration Yamagi Quake II ships with an alternative startup config that overrides -some gloibal settings to saner defaults. To use is copy *stuff/yq2.cfg* +some global settings to saner defaults. To use is copy *stuff/yq2.cfg* into the *baseq2/* directory. @@ -208,8 +207,9 @@ system. The gamedata is searched at: commandline argument. - In *$HOME/.yq2* -If you're a package maintainer, please look at our documentation at -the [Packaging Guide](05_packaging.md) +If you're a package maintainer, please look at our packaging guide at +the [Packaging Guide](05_packaging.md). + ## Compiling from source @@ -220,7 +220,7 @@ To compile Yamagi Quake II from source the following dependencies * A LibGL implementation with system headers. * An OpenAL implementation, *openal-soft* is highly recommended. * SDL 2.0. -* libcurl +* libcurl. While Yamagi Quake II ships with an CMakeFile.txt using the GNU Makefile for release builds is recommended. The GNU Makefile offers more options @@ -233,9 +233,10 @@ On Windows a MinGW environment is needed. A preconfigured environment with all necessary dependencies and compatibles compilers can be found at: https://deponie.yamagi.org/quake2/windows/build/ -The environment must be extracted into *C:\MSYS2\* (other directory will -likely work but are unsupported). Either the 32 bit version can be -started through *C:\MSYS2\msys32.exe* or the 64 bit version through +The environment must be extracted into *C:\MSYS2\*. Other directores +will likely work, but are unsupported. So don't complain if you +experience problems. Either the 32 bit version can be started through +*C:\MSYS2\msys32.exe* or the 64 bit version through *C:\MSYS2\msys64.exe*. At this time Yamagi Quake II can't be compiled with Microsoft Visual @@ -252,7 +253,7 @@ The build dependencies can be installed with: * On MacOS the dependencies can be installed with Homebrew (from https://brew.sh): `brew install sdl2 openal-soft` -Other distributions or platforms often have package names similar to the +Other distributions or platforms often have package named similar to the Debian or FreeBSD packages. @@ -261,7 +262,7 @@ Debian or FreeBSD packages. Download the latest release from https://www.yamagi.org/quake2 or clone the source from https://github.com/yquake2/yquake2.git, change into the *yquake2/* source directory and type *make* (Linux, MacOS and Windows) -or *gmake* (FreeBSD). After the build finished copy everything from the +or *gmake* (FreeBSD). After the build finished, copy everything from the *release/* directory to the Yamagi Quake II installation directory. For the addons download or clone their source, change into the source diff --git a/doc/03_configuration.md b/doc/03_configuration.md index 49646c87..fe7b6119 100644 --- a/doc/03_configuration.md +++ b/doc/03_configuration.md @@ -11,23 +11,23 @@ with the defaults and the options that can be set through the menu. Yamagi Quake II ships with 3 renderers: * The **OpenGL 3.2** renderer: This renderer was developed for the needs - of modern hardware and is usually the best choice for OpenGL 3.2 - capable graphics cards. It provides a very detailed look and feel, + of modern graphics hardware and is usually the best choice for OpenGL + 3.2 capable graphics cards. It provides a very detailed look and feel, matching the dark and dirty atmosphere on Stroggos. The texturing - renderer of the OpenGL 3.2 renderer looks mostly the same on all GPU - drivers. The default lighting may be too bright or too dark, it can be + renderer looks mostly the same on all GPU drivers. Depending on the + display the default lighting may be too bright or too dark, it can be adjusted through the menu or through the *vid_gamma* cvar. * The **OpenGL 1.4** renderer: This is a slightly enhanced version of - the original OpenGL renderer shipped in 1997 with Quake II. It's - provided for older graphics cards, not able to run the OpenGL 3.2 + the original OpenGL renderer shipped in 1997 with the retail release. + It's provided for older graphics cards, not able to run the OpenGL 3.2 renderer. The OpenGL 1.4 renderer has some limitations. The look and feel is highly dependent on the GPU driver and the platforms OpenGL implementation, especially the texture rendering may vary to a wide margin. The global lighting may not be rendered correctly, especially liquids may be too dark or too bright. * The **Software** renderer: Shipped for historical reasons only. - Setting the OpenGL 3.2 renderer to match the software renderers looks - and feel is often the better choice since it's faster and provides + Setting the OpenGL 3.2 renderer to match the software renderers look + and feel is often the better choice, since it's faster and provides colored lighting. The software renderer may show some rendering errors on widescreen resolutions. @@ -37,15 +37,15 @@ Yamagi Quake II ships with 3 renderers: Yamagi Quake II ships with 2 sound system: * The **OpenAL** sound system: This is the default and highly - recommended. It provides full surround sound support and even HRTF. - But also the plain stereo playback is much better then in the original - sound system. The setup is done mostly through OpenAL, have a look at - the documentation of your OpenAL library. + recommended. It provides full surround sound support and even HRTF for + headphones. But also the plain stereo playback is much better than in + the original sound system. The setup is done mostly through OpenAL, + have a look at the documentation of your OpenAL library. * The **SDL** sound system: This is the classic sound system, providing an experience like the original client. Set `s_openal` to `0` and - execute an `snd_restart` to activate it. The classic sound system - may be problematic on modern systems like Windows 10 or Linux with - Pulseaudio. + execute an `snd_restart` to activate it. The classic sound system may + be somewhat problematic on modern systems like Windows 10 or Linux + with Pulseaudio. ## Tuning for Precise Timings @@ -62,9 +62,9 @@ network protocol and the whole look and feel depends on them. We can just try work around them. Additionally modern high resolution LCD displays are much more prone to -tearing and missed frames then the low resolution CRT displays of the -1990th. This is a big problem because precise timings and keeping the -frame rate constant are at least partly mutual exclusive. So players +tearing and missed frames than the low resolution CRT displays of the +late 1990th. This is a big problem, because precise timings and keeping +the frame rate constant are at least partly mutual exclusive. So players have the choice: * Keep an accurate frame rate, rendering exactly as many frames as the @@ -89,27 +89,28 @@ the GPU driver and the preferences of the player. You'll never get precise timing and tearing- and / or micro stuttering free gameplay with busy waits switched off! * `r_vsync` can be set to `0`. Enabling the vertical synchronization - allows the GPU driver to wait for the display, thus stealing time from - Yamagi Quake II. This stolen time is missing to the internal time - accounting, while Yamagi Quake II tries to determine how much time was - lost that's always an imprecise guess. Disabling vertical - synchronization will always cause tearing! -* `cl_maxfps` must be set to a value lower than `vid_maxfps`. The margin - between the two values should be at least 3 frames per second, better - 5 frames per second. Yamagi Quake II internally enforces a margin of - 5%. If `cl_maxfps` is set too high (above 90) the good old 125hz bug - will trigger and the physics will be off. That may be desired. + allows the GPU driver to wait for the display, thus "stealing" time + from Yamagi Quake II. This stolen time may add some variance to the + internal timing. Disabling vertical synchronization will always cause + tearing! +* `cl_maxfps` must be set to a value lower than the renderer frame rate. + With `r_vsync` set to 1 that's the display refresh rate and otherwise + the value of `vid_maxfps`. Yamagi Quake II enforces this restriction + with an margin of 5%. For example, if `r_vsync` is set to 1 on an 60hz + display 60 * 0.95 = 57 FPS. if `cl_maxfps` is set too high (above 90) + the famous 125hz bug will trigger and the physics will be off. That + may be desired. * `vid_displayrefreshrate` must be set to the framerate of the display. The default is `-1` which means autodetect. In most cases that's okay, but for precise timings it's a good idea to override the autodetected value and set the display refresh rate by hand. The displays EDID info - or the GPU driver may be lying. Only full numbers can be given. If - round up there's a risk for imprecise timing. When round down the risk - if micro stuttering increases. -* When running with vertical synchronisation enabled `vid_maxfps` can be - set to any value higher then the display refresh rate. If the vertical - synchronisation is disabled `vid_maxfps` should be set to the desired - target frame rate. + or the GPU driver may be lying. Only full numbers can be given, e.g. + 59 or 60 for a 59.95hz display. If round up there's a small risk for + imprecise timing. If round down micro stuttering may occure. +* When running with vertical synchronisation enabled, `vid_maxfps` can + be set to any value higher than the display refresh rate. If the + vertical synchronisation is disabled `vid_maxfps` should be set to the + desired target frame rate. Putting it all together we come up with three so to say standard configurations that can be used as a baseline for experiments: @@ -135,15 +136,15 @@ configurations that can be used as a baseline for experiments: And there's always the option to disable the asynchronous client all together by setting `cl_async` to `1`. In that case `cl_maxfps` and -`vid_maxfps` are tight together, like in the original Quake II release -each renderframe is a clientframe. With that both precise timings and +`vid_maxfps` are tied together, just like with the original client each +renderframe is also a clientframe. With that both precise timings and tearing / micro stuttering free rendering can be archieved by setting `cl_maxfps` to a value higher then the displays refresh rate and -activating the vertical syncrhonization by setting `r_vsync` to `1`. -But if `cl_maxfps` is set above about 90 frames per second the 125hz -bug will trigger and the physics will be off. Additionally it will -flood servers with packages, at least one package per frame. That may -be considered abuse. +activating the vertical synrchonization by setting `r_vsync` to `1`. +But if `cl_maxfps` is set too high (about 90) second the 125hz bug will +trigger and the physics will be off. Additionally it will flood servers +with packages, at least one package per frame. That may be considered +abuse. ## Getting a classic look and feel @@ -216,15 +217,15 @@ support colored lighting. General cvars: -* `cl_lights` set to `0` disables the dynamic lights. -* `gl_texturemode` set to `GL_NEAREST_MIPMAP_LINEAR` disabled the - texture filtering, giving a nice pixel look. +* `cl_lights` set to `0` disables the dynamic lightning. +* `gl_texturemode` set to `GL_NEAREST_MIPMAP_LINEAR` disables the + texture filtering, giving a classic pixel look. The OpenGL 1.4 renderer: * `gl1_pointparameters`: When set to `0` the particles are rendered as - squares. May be already the case if the GPU driver doesn't support - point parameters. + blurry octagon. May be already the case if the GPU driver doesn't + support point parameters. The OpenGL 3.2 renderer: diff --git a/doc/04_cvarlist.md b/doc/04_cvarlist.md index b1182097..39189bd5 100644 --- a/doc/04_cvarlist.md +++ b/doc/04_cvarlist.md @@ -17,7 +17,7 @@ have been renamed. The prefixes are: * `vid_`: Video backend. All cvars may be given at command line trough `+set cvar value` or typed -into the console. The console can be opended with *shift-esc*. +into the console. The console can be opended with *Left Shift + Esc*. ## Command line arguments @@ -41,7 +41,7 @@ it's `+set busywait 0` (setting the `busywait` cvar) and `-portable` * **busywait**: By default this is set to `1`. causing Quake II to spin in a very tight loop until it's time to process the next frame. This - is a very accurate way to determine the internal timing but comes with + is a very accurate way to determine the internal timing, but comes with a relatively high CPU usage. If set to `0` Quake II lays itself to sleep and tells the operating system to send a wakeup signal when it's time for the next frame. The later is more CPU friendly but rather @@ -58,10 +58,13 @@ it's `+set busywait 0` (setting the `busywait` cvar) and `-portable` * In case that the vsync is active, *vid_maxfps* must not be lower than the display refresh rate. - If *cl_async* is set to `0` *vid_maxfps* is the same as *cl_maxfps*, - use *cl_maxfps* to set the framerate. + Both contraints are enforced. -* **cl_showfps**: Shows the framecounter. + If *cl_async* is set to `0` *vid_maxfps* is the same as *cl_maxfps*, + use *cl_maxfps* to set the framerate. + +* **cl_showfps**: Shows the framecounter. Set to `2` for more and to + `3` for even more informations. * **in_grab**: Defines how the mouse is grabbed by Yamagi Quake IIs window. If set to `0` the mouse is never grabbed and if set to `1` @@ -92,15 +95,15 @@ it's `+set busywait 0` (setting the `busywait` cvar) and `-portable` * **s_openal**: Use OpenAL for sound playback. This is enabled by default. OpenAL gives a huge quality boost over the classic sound - system and supports surround speakers and HRTF. + system and supports surround speakers and HRTF for headphones. OpenAL + is much more reliable than the classic sound system, especially on + modern systems like Windows 10 or Linux with PulseAudio. * **s_underwater**: Dampen sounds if submerged. Enabled by default. ## Graphics (all renderers) -* Most old `r_*` cvars, but renamed to `gl_*` - * **vid_displayrefreshrate**: Sets the displays refresh rate. The default `-1` let the game determine the refresh rate automatically. Often the default setting is okay, but some graphics drivers report @@ -130,10 +133,9 @@ it's `+set busywait 0` (setting the `busywait` cvar) and `-portable` * **horplus**: If set to 1 (the default) the horplus algorithm is used to calculate an optimal horizontal and vertical field of view, - independent of the window or screen aspect ratio or resolution. If - enabled *fov* is forced to `90`. + independent of the window or screen aspect ratio or resolution. -* **vid_gamma**: The value used for gamma correction. Higher value looks +* **vid_gamma**: The value used for gamma correction. Higher values look brighter. The OpenGL 1.4 and software renderers use "Hardware Gamma", setting the Gamma of the whole screen to this value in realtime (except on MacOS where it's applied to textures on load and thus needs @@ -146,7 +148,8 @@ it's `+set busywait 0` (setting the `busywait` cvar) and `-portable` crosshair. The value given is the scale factor, a factor of `1` means no scaling. Values greater `1` make the objects bigger, values lower 1 smaller. The special value `-1` (default) sets the optimal scaling - factor for the current resolution. + factor for the current resolution. All cvars are set through the + scaling slider in the video menu. * **r_customheight** / **r_customwidth**: Specifies a custom resolution, the windows will be *r_customheight* pixels high and *r_customwidth* @@ -160,8 +163,8 @@ it's `+set busywait 0` (setting the `busywait` cvar) and `-portable` `cl_maxfps` is used as maximum framerate. See `cl_async` description above for more information. *Note* that vsync (`r_vsync`) also restricts the framerate to the monitor refresh rate, so if vsync is - enabled, the game won't render more than 60fps on most displays (or - 120 on a 120hz display etc). + enabled, the game won't render more than frame than the display can + show. * **r_vsync**: Enables the vsync: frames are synchronized with display refresh rate, should (but doesn't always) prevent tearing. @@ -194,25 +197,24 @@ it's `+set busywait 0` (setting the `busywait` cvar) and `-portable` * **gl_zfix**: Sometimes two or even more surfaces overlap and flicker. If this cvar is set to `1` the renderer inserts a small gap between - the overlapping surfaces to mitigate the flickering. This may lead to - small render errors. + the overlapping surfaces to mitigate the flickering. This may make + things better or worse, depending on the map. ## Graphics (OpenGL 1.4 only) -* **gl1_intensity**: Sets the color intensity used for 3D rendering. - Must be a floating point value, at least `1.0` - default is `2.0`. - Applied when textures are loaded, so it needs a `vid_restart`! +* **gl1_intensity**: Sets the color intensity. Must be a floating point + value, at least `1.0` - default is `2.0`. Applied when textures are + loaded, so it needs a `vid_restart`. * **gl1_overbrightbits**: Enables overbright bits, brightness scaling of lightmaps and models. Higher values make shadows less dark. Possible - values are `0` (no overbright bits), `1` (correct lighting for water), - `2` (scale by factor 2) and `3` (scale by factor 3). Applied in - realtime, does not need `vid_restart`. + values are `0` (no overbright bits), `1` (more correct lighting for + water), `2` (scale by factor 2) and `3` (scale by factor 3). Applied + in realtime, does not need `vid_restart`. * **gl1_stencilshadow**: If `gl_shadows` is set to `1`, this makes them - look a bit better (no flickering) by using the stencil buffer. (This - is always done in OpenGL 3.2, so not configurable there) + look a bit better (no flickering) by using the stencil buffer. ## Graphics (OpenGL 3.2 only) @@ -226,13 +228,13 @@ it's `+set busywait 0` (setting the `busywait` cvar) and `-portable` Similar to OpenGL 1.4 `gl1_intensity`, but more flexible: can be any value between 0.0 (completely dark) and 256.0 (very bright). Good values are between `1.0` and `2.0`, default is `1.5`. Applied in - realtime via shader, so it does *not* need a `vid_restart`. + realtime via shader, so it does not need a `vid_restart`. * **gl3_intensity_2D**: The same for 2D rendering (HUD, menu, console, videos) * **gl3_overbrightbits**: Enables overbright bits, brightness scaling of - lightmaps and models. Higher values make shadows less dark. Similar + lightmaps and models. Higher values make shadows less dark. Similar to OpenGL 1.4 `gl1_overbrightbits`, but allows any floating point number. Default is `1.3`. In the OpenGL 3.2 renderer, no lighting fixes for water are needed, so `1.0` has no special meaning. diff --git a/doc/05_packaging.md b/doc/05_packaging.md index 6fdd7be6..dd5e0c79 100644 --- a/doc/05_packaging.md +++ b/doc/05_packaging.md @@ -35,7 +35,7 @@ but if it's not found in the binary directory, it will look for it in all directories that are also searched for game data. This is for better compatibility with mods that might ship their own game.so. -You can **just symlink the executables to a directory into the $PATH**, +You can **just symlink the executables to a directory in the $PATH**, like */usr/bin/*. There's one exception to this rule: OpenBSD does not provide a way to get the executable path, so a wrapper script is needed.