shithub: qk1

ref: a4c481713877e422e186d66c9038154b53bb6199
dir: /README/

View raw version
qk1 - (9) quake
===============
Port of linux/x11 quake and quakeworld to plan9front.  Tested and known to
work on amd64, 386 and arm, but currently broken on zynq.

For details, see: http://nopenopenope.net/posts/quake

Hereafter `qk1' refers to the project as a whole, and `quake' and `quakeworld'
refer to the actual games.


Installation and start up
-------------------------
Besides building and installing qk1, you still need .pak files to play.  Both
shareware and registered versions work, as well as the official expansions,
and mods.
The data files are to be installed in /sys/games/lib/quake/$gamename, where
$gamename is 'id1' for plain old quake.  Savegames, configuration files and
other user-specific data is saved in $home/lib/quake/$gamename, if it exists.

To install quake:

	; mk install
	; mkdir -p $home/lib/quake/id1
	; cp /n/quakecd/id1/*.pak $home/lib/quake/id1
	; games/quake >/dev/null

To install quakeworld:

	; cd qw
	; mk install

To install an expansion or mod, for example rogue:

	; mkdir /sys/games/lib/quake/rogue
	; cp /n/roguecd/*.pak /sys/games/lib/quake/rogue
	; mkdir $home/lib/quake/rogue

To start quake:

	; games/quake >/dev/null

Mods:

	; games/quake -g rogue >/dev/null

quakeworld's client:

	; games/qwcl >/dev/null

quakeworld's server:

	; games/qwsv


Memory limit
------------

By default, qk1 allocates 64 MB of memory for its internal heap.  This amount
can be controlled via the -m command line parameter like so:

	; games/quake -m 192
	# quakeworld:
	; games/qwcl -mem 192
	; games/qwsv -mem 192

It is necessary to increase it when playing on larger resolutions, else qk1
might crash with errors such as 'Hunk_Alloc: failed on 548512 bytes'.  Mods
may require more memory as well.  The old default was 12 MB, so it can also
be lowered in the unlikely case that it's necessary.


Mouse usage
-----------

Both quake and quakeworld now grab the mouse and have free mouse look by
default.  Mouse grabbing is controled via a console variable at runtime:

	] m_windowed 1

Mouse look on the other hand is enabled with a command:

	] +mlook

To disable mouse look, use `-mlook'.


Screen resolution
-----------------

The rio(1) window running qk1 can be resized at will and at runtime, but must
the drawing area's size must be between 320x160 and 2047x2048.  To help with
drawing speed, scaling up from a fixed resolution has been implemented.  When
enabled, qk1 will behave like doom(1), where window size determines at
runtime a scaling factor.  Currently, the way to enable this is different
between quake and quakeworld.

quake:
	
	; games/quake -s 320 200

quakeworld:

	; games/qwcl -scale 320 200


Framerate and performance
-------------------------

To play the games comfortably the framerate should be above 72.  There are
several things to note:

- lowering the resolution (window size) improves performance
- scaling up graphics from a lower resolution improves performance
- performance influences sound output and can cause underflows (see below)

In quakeworld, the framerate is controlled by one of two console variables,
`cl_maxfps' and `rate' and can be between 30 and 72.  If `cl_maxfps' is not
set, framerate is set to `rate' / 80.  `cl_maxfps' is now set to 72 by
default.

A simple way to benchmark is to play a demo with an uncapped framerate (one
must be provided for quakeworld beforehand):

	] timedemo demo3


Audio and music
---------------

On low framerates, devaudio's delay must be increased appropriately, up to
4410 (for a rate of 44.1 kHz), or sound will cut up.  This applies to
quakeworld as well, for which the framerate can also be capped lower.

qk1 reads /mnt/cd/[au]NNN files as in cdfs(1) to play music.  The directory
needn't be populated by cdfs(1), so long as the files are in the format
described by audio(3).  CD playback requires mixfs(1).


Known bugs
----------

- rendering broken on zynq
- regression: cd audio with actual cd's broken
- a rare crash at d_sprite.c:/D_SpriteDrawSpansd can occur when running for
a long time
- an infinite loop in world.c:/SV_TouchLinks can sometimes occur
- (amd64) entities visible through walls right when emerging from/immerging
  into water
- resolutions other than 4:3: some vertical and horizontal strips on the edge
  of the screen aren't drawn
- sprites are not scaled correctly on higher resolutions and become=
disproportionate
- #define PARANOID reveals several points of failure that are otherwise ignored
- both stdio(2) and print(2) are used due to the way colored strings are, how
to handle this gracefully is unknown
- questionable pr_edict.c:/PR_Str hack may cause problems
- refactoring: manpages, command line args, merge quakeworld, FIXME's in code


Legal
-----
Quake, hence qk1, is licensed under the GPLv2. see COPYING for details.