yquake2/yquake2remaster
0
0
Fork 0
mirror of https://github.com/yquake2/yquake2remaster.git synced 2024-11-10 07:12:07 +00:00
Code Issues Projects Releases Packages Wiki Activity

Some clarifications, typo and grammar fixes to the documentation.

Browse source 
Make some things clearer and fix some small miss informations, overhaul
the timing guide. While at it fix typos and grammar mistakes.
This commit is contained in:
Yamagi Burmeister 2019-04-03 11:33:20 +02:00
parent 3b296c43a0
commit 4f20ac97d1
5 changed files with 95 additions and 91 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
doc/01_index.md
View file

@ -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:

27
doc/02_installation.md
View file

@ -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

95
doc/03_configuration.md
View file

@ -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:

54
doc/04_cvarlist.md
View file

@ -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.

2
doc/05_packaging.md
View file

@ -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.