2013/12/24
spirit@quaddicted.com

5 years ago a coder approached me for beta testing his Joequake-based engine for
Windows and Linux. I have been using that engine since then as it is simply the
best. I always tried to make him release it publically but it was not ready yet.

We were in loose contact, exchanging bug reports (me) for fixes plus gazillions
of new features (him). The last beta I got from him was more than 2 years ago.
Shortly after that our mail exchange dried up. I haven't heard from him for more
than 2 years now. I did mail him from time to time but got no reply.

At some point I asked for the sources to be included:

Spirit wrote:
> And I would really like to have the source code. I would not release it unless
> you vanish for a year.

jdhack wrote:
> That's probably a good idea. I'll trust your word, and include the source with
> the next release.  [And then I can torment you by disappearing for 360 days,
> only to emerge to say "Haw-haw!  Start counting again"

Since we lost contact I have been contemplating what to do (see eg my post at
http://forums.inside3d.com/viewtopic.php?f=1&t=5263 ). In the end I decided not
to attempt sending a letter through snail-mail as I did not want to intrude. It
still feels weird releasing this but I think it is the right thing to do.

So I stripped some personal details from the files, fixed a segfault (thanks to
Spike) and uploaded the source to https://github.com/SpiritQuaddicted/reQuiem .
I hope we can find a development team working on this or merging features with
Fitzquake or Quakespasm. While I am clueless about engine programming, we talked
quite a bit and I might be able to share some details if you are stuck in the
source. Just ask! I meant to make a nice website but did not manage to do so in
time. Are you a kick-ass web designer and like this engine? Right now, there is
https://www.quaddicted.com/engines/requiem but that is not too nice...

I probably screwed up a lot of things with the release zip so send me all your
bug reports (or file them at GitHub). This did not get the last minute testing
it deserved as the advent calendar at Quaddicted proved to be more stress than 
anticipated.

-Spirit

#####

2010/04/19
jdhack@hotmail.com

This readme is a work-in-progress.  It will be expanded in the future.
See changelog.txt for version history.


Description:
""""""""""""
reQuiem is a custom OpenGL Quake engine for Windows and Linux.  It's designed for 
maximum compatibility with all things Quake - past, present and future.  It's fast, 
reliable, and easy to configure.  In short: it fixes what was broken, improves what 
needed improving, and leaves the rest alone.


Features:
"""""""""
- expanded limits (edicts, models, lightmaps)
- mp3 and ogg music
- playback of demos from FitzQuake 0.85, aguirRe's engines, and QW
- demo pause, rewind, fast-forward and quick-seek
- dzip and zip/pk3; also compression of recorded demos
- Nehahra, -quoth, and multiple -game arguments
- md2 and md3
- console tab-completion for cvars, commands, and filenames (maps, demos, sky, etc)
- Options menu containing most useful settings, intuitively grouped
- support for non-US keyboard layouts


Included files:
"""""""""""""""
  - dzlib.dll/dzlib.so: compression and decompression of dzip and zip archives
  - fmod375.dll/libfmod-3.75.so: for playing music (mp3/ogg/mod/midi)
  - water_caustic.png, explosion.png, particlefont.png, zing1.png, 
    q3blood.tga, q3smoke.tga, flame0.mdl
      - JoeQuake files for water caustics and QMB particles (optional)
  - bigfont.lmp, fontsize.lmp: character set for menu
  - demo_fw.lmp, demo_rw.lmp, demo_bar.lmp: icons overlaid during demo playback

  NOTE: libpng12 is required for PNG support.  libjpeg is required for JPEG support.
        TGA & PCX support is built-in.


Some useful cvars:
""""""""""""""""""
Visual:
  - gl_contrast: default is 1; I like it a bit higher (~1.3)
  - gl_lightmode: determines how lightmaps look
        0 = original GLQuake (flat)
        1 = JoeQuake (more contrast) [default]
        2 = high contrast
        3 = overbright (like sw render)
  - gl_texbrighten [0/1]: if 1, a brighter palette is used for world textures [default 0]
  - gl_detail [0/1]: much faster than in JoeQuake, also subtler [default 0]
  - r_skytype: whether 0 or 1 is faster depends on your video card (2 should always be fastest)
        0 = MHQuake sky
        1 = original GLQuake sky [default]
        2 = solid color sky
  - r_oldsky [0/1]: if 1, regular sky will be used instead of skybox (where applicable)
  - gl_skyhack [0/1/2]: determines whether faster, but occasionally buggy, sky-drawing code is used
        0 = speed hacks not used
		1 = used only when drawing skyboxes
		2 = used when drawing skyboxes and MHQuake pseudo-skyboxes
  - scr_sbarsize [0 to 100]: percent of screen width status bar should occupy
       - default is 0, meaning it's drawn at "actual size" (320 wide, regardless of screen size)
  - cl_sbar [0/1]: governs appearance of status bar
        0 = bar is transparent, inventory is floating along right side of screen [default]
        1 = bar is solid, inventory is above (original Quake style)
  - crosshair [0 to 6]: appearance of crosshair (0 for none) [default 1]
  - crosshaircolor: if crosshair cvar is 2 or higher, this will determine its color.  Accepts 2 formats:
       1) 0 to 255: specifies index of color in Quake palette
       2) "<r> <g> <b>": specifies absolute value for color (each color is 0-255)
           eg. crosshaircolor "255 0 0" will be bright red
  - crosshairalpha [0 to 1]: dictates how transparent crosshair should be (1 is solid)
  - scr_conspeed: speed at which console drops/raises (default 600)
  - scr_hudscale: magnification for various items of the in-game onscreen display [default is 1.0]
       - affects centerprints, demo playback icons, scr_showfps, scr_showorigin, cl_clock

Informative:
  - scr_showfps [0/1]
  - r_showbboxes [0/1/2/3]: draws bounding boxes around models
        0 = no bounding boxes [default]
        1 = bounding boxes on brush models that are visible to player
        2 = bounding boxes on all models that are visible to player
        3 = bounding boxes on all models
  - scr_showorigin [0/1]: if 1, player's coordinates will be shown in the bottom-right
  - cl_clock [0/1/2/3/4]: determines if and how the current time should be displayed
        0 = not displayed
        1 = display time in AM/PM format
        2 = display time in 24-hour format
        3 = display date plus AM/PM time
        4 = display date plus 24-hour time
  - cl_clock_x: specifies horizontal position of clock
        0 is at left side of screen; higher values move it that many columns to the right
  - cl_clock_y: specifies vertical position of clock
        positive values are counted from the top of the screen, negative from the bottom

Gameplay:
  - cl_deadbodyfilter [0/1/2]: determines if and when dead bodies are removed
        0 = not removed [default]
        1 = removed once they hit the ground
        2 = removed the instant they die
  - cl_gibfilter [0/1]: determines whether or not body parts are removed

Miscellaneous:
  - sv_protocol [0/15/10002]: which protocol reQuiem uses for server/client communication
        0 = auto-select: uses 15 or 10002, whichever is appropriate for the current map [default]
       15 = standard Quake: enforce all original Quake limits
    10002 = extended: force aguirRe's (Bengt Jardrup) BJP3 protocol
  - host_matchfilecase [0/1]: whether filename matching is case-sensitive. Affects:
       - loading of files, both within paks and outside
       - map & demo menus: whether alphabetizing distinguishes between upper & lower case
       - console filename tab-completion: whether entered text must match case of filename
  - _windowed_mouse [0/1/2]: in windowed mode, controls whether mouse is handled by reQuiem
        0 = no (cursor visible, movement not captured)
        1 = yes if a map is active, no if in menu or console [default]
        2 = yes (cursor not visible, movement controls player)
  - bgmvolume [0 to 1]: adjust the volume of CD audio or mp3/ogg/mod/midi
  - cfg_savevars [0/1/2]: determines which cvars and keybindings will be saved to reQuiem.cfg
        0 = those that are marked for archival, and whose value has changed [default]
        1 = those that are marked for archival, and whose value is not the default
        2 = all cvars and bound keys
  - host_maxfps: maximum number of frames per second that will be rendered (default 72)
  - cl_demo_compress [0/1/2]: whether a newly recorded demo should be compressed via dzip
        0 = never
        1 = ask each time
        2 = always
  - cl_advancedcompletion [0/1/2]: determines behavior of tab key in console
        0 = fills in first match
        1 = lists all matches, fills in first match; <tab> cycles through list [default]
        2 = lists all matches, fills in shared beginnings (JoeQuake-style)


Some useful commands:
"""""""""""""""""""""
  - cmdlist/cvarlist/maplist/demolist: can be used alone, or with an argument
	that specifies the first few letters of the items to list
	  (eg. "cvarlist gl" will list all cvars starting with "gl")
  - toggle/cycle/inc/dec: change the value of a cvar in different ways 
      (useful for key bindings)
  - fog: works similar to FitzQuake
  - cd: now also controls mp3/ogg playback
  - create: spawns an entity (eg. "create monster_knight"; "create item_shells")
  - gamedir: changes to a different game directory.  If more than one argument is present,
      the directories are added in the given order.  Directories that were added via a 
      mission pack switch (eg. -hipnotic) will normally remain in the searchpath even
      when the gamedir changes.  To remove these from the searchpath, use "gamedir id1".
  - printtxt: output the contents of a text file to the console


Some command-line options:
""""""""""""""""""""""""""
  -no24bit: disable external hi-res textures
  -nomusic: disable mod/midi/mp3/ogg
  -quoth: same as "-game quoth"; also enables Hipnotic HUD
  -snddev: on Linux, lets you specify which sound device to use (default is "/dev/dsp")
  -cddev: on Linux, lets you specify which CD drive to use (default is "/dev/cdrom")
  -stdout: on Linux, enables output of extra info to stdout terminal
  -uskbd: forces reQuiem to use a standard US keyboard layout 
  -condebug: logs all console output to a file (qconsole.log, which will be created
      in the current gamedir when reQuiem first starts)
  

Console:
""""""""
  When you use tab-complete, a list of all matches will be displayed, and the 
  first match will automatically be filled in.  Pressing tab again will cycle
  through the rest of the matches (in alphabetical order).  Shift-tab cycles 
  in the reverse direction.  This works for cvars, commands, and filenames.


MP3/OGG audio:
""""""""""""""
  This is handled via the fmod lib.  When a map specifies a CD track, reQuiem
  first checks if a music file exists.  These must be named either trackxx, 
  trackxxx, or Txx (where xx or xxx is the 2- or 3-digit track number).  They
  must have either the .mp3 or .ogg suffix, and they must be in a folder named 
  "sound/cdtracks".

    Examples:
	  1) start.bsp specifies CD track 4.  If you've got a file named, say, 
	     id1/sound/cdtracks/track04.ogg reQuiem will play it instead
	  2) distrans provided a complete soundtrack for his Travail episode.  
	     The files are named T01.mp3 to T11.mp3, so if you put them in 
	     travail/sound/cdtracks/, they will get played


Demo playback:
""""""""""""""
  - the playdemo command can also play demos in a different gamedir
      eg. "playdemo ../my_demos/demo1"
  - when playing a demo, the arrow keys control the direction and speed of playback:
                     U: speed up
      L: reverse     D: slow down     R: forward
  - the mouse can also be used (left-click reverses, right-click plays forward,
      wheel controls speed)
  - the enter key sets playback to forward at normal speed (also middle-click)
  - the number keys 0 through 9 jump to various points in time in the demo
      eg. 0 jumps to beginning, 5 jumps to 50%, 9 jumps to 90%


Cutscenes:
""""""""""
  Cool feature that probably doesn't need testing, but I'm kinda proud of:
  smooth camera movement during cutscenes!  
      eg: Operation Urth Majik (oum1, oum3, oum4) 
          Zerstorer (zer1m2, zer1m3, zer1m6, zer1m7, zerend)
  Toggle host_cutscenehack [0/1] to see the difference.


Video Options Menu:
"""""""""""""""""""
For your convenience, the Video Options menu has a few preset configurations to choose from.
This is a list of the cvars that are affected, and their values under each configuration.

                                 FAST    CLASSIC   STANDARD   MAX FX
                                 """"    """""""   """"""""   """"""
gl_texturemode (see note)        none   lin. mips  bilinear  trilinear
gl_picmip                         3         0         0         0
gl_detail                         0         0         1         1
gl_externaltextures_world         0         0         1         1
gl_externaltextures_bmodels       0         0         1         1
gl_externaltextures_models        0         0         1         1
gl_fb_world                       0         1         1         1
gl_fb_bmodels                     0         1         1         1
gl_fb_models                      0         1         1         1
crosshair                         0         0         1         1
gl_loadlitfiles                   0         0         1         1
r_dynamic                         0         1         1         1
gl_vertexlights                   0         0         0         1
r_shadows                         0         0         1         1
gl_glows                          0         0         1         1
gl_flashblend                     0         0         0         1
r_powerupglow                     0         0         0         1
r_skytype                         2         1         0         0
r_oldsky                          1         1         0         0
gl_caustics                       0         0         1         1
gl_waterfog                       0         0         0         1
r_wateralpha                     1.0       1.0       0.4       0.4
gl_part_*  (12 vars)              0         0         0         1
gl_interpolate_animation          0         0         1         1

NOTE: for gl_texturemode, none="", linear mips="GL_NEAREST_MIPMAP_LINEAR", 
      bilinear="GL_LINEAR_MIPMAP_NEAREST", trilinear="GL_LINEAR_MIPMAP_LINEAR"




External texture support:
"""""""""""""""""""""""""
reQuiem supports several schemes for naming textures.
(note: I use square brackets [..] to indicate optional bits.  Filenames must
       have a recognized image extension - .tga, .png, .jpg, or .pcx)

Map textures:
   pathname: textures/, textures/<bspname>/  (eg. "textures/e1m1/")
   filename: <as named in bsp>   (with the * prefix on liquids replaced by #)

Brush models:
   pathname: textures/, textures/bmodels/
   filename: see map textures

Alias models: 
   pathname: textures/, textures/models/, <path of mdl> (usually "progs/"), textures/<mdlpath>/
   filename: name[.mdl]_skinnum[_framenum]
      (eg. player_0, player.mdl_0, armor_2, b_explob_0_1)

Sprites:
   pathname: textures/, textures/sprites/, <path of spr> (usually "progs/")
   filename: name[.spr]_framenum[_groupframenum]
      (eg. s_explod_2, s_explod.spr_2, impball.spr_0_4)

QMB Particles:
   pathname: textures/particles/
   filename: particlefont, explosion, q3blood, q3smoke, zing1

Skyboxes:
   pathname: env/, gfx/env/
   filename: name_suffix, namesuffix   (suffix = rt,bk,lf,ft,up,dn)

gfx.wad:
   pathname: textures/wad/, gfx/
   filename: <as named in wad>

Crosshairs:
   pathname: crosshairs/, textures/crosshairs/
   filename: <any>

Character sets:
   pathname: textures/charsets/
   filename: <any>

Console background:
   pathname: gfx/  (or gfx/menu/ for Hexen II)
   filename: conback


Miscellaneous:
""""""""""""""
  - the "give" command can now be used for armor too (eg. "give a 150")
  - the "give" command can be used to resurrect a dead player
      (eg. "give h 100" will resurrect the player and give him 100 health)
  

Known issues & limitations:
"""""""""""""""""""""""""""
  - no in-game changing of video modes or console width/height; command-line switches 
    must be used.  (I'll fix this eventually)
  - md3 support is limited (vertices & textures only)
  - on gamedir change: palette change (if any) is not applied to any textures 
    already loaded
  - detail textures get drawn only when the player gets close to a surface.  
    In certain maps, with certain textures, this can result in the texture 
    of an object suddenly changing.
  - demo rewind can't go beyond start of current "run" (if demo has more than 1 attempt)
  - demo quick-seek navigation works only with the current "run"
  - QWD playback may sometimes be jerky; this could be fixed, but would require adding
     all of QW's player prediction code
  - demos recorded when playing "oversized" (limit-breaking) maps won't work engines 
    other than reQuiem and aguirRe's
  - r_lightmap cvar doesn't work if multitexturing is on
  - gl_externaltextures* cvars (_world, _bmodels and _models) don't affect textures 
    that are already loaded
  - fmod may fail to load with some sound cards or on Linux (when multiple programs
    cannot use the sound hardware simultaneously)
  - Linux: host_matchfilecase=0 doesn't apply to directory names within a gamedir
  - Linux: if gl_zfightfix is 1, it may cause crash or missing models (old ATI drivers?)
  - Linux: no custom app icon yet
  - Linux: no ALSA sound support (just OSS)
  - Linux: -snddev switch doesn't affect which card fmod uses for music
  - Linux: dedicated server mode is not supported

