DarkPlaces engine readme : updated 20060614

About the DarkPlaces glquake engine:
DarkPlaces engine was started because I was unsatisfied with the other engines
available soon after the quake source release (which did little more than add
some flashy effects), and craved modding features for my DarkPlaces mod, and
wanted some real enhancements to the online gaming experience as well.

DarkPlaces engine is the result, I hope everyone likes it.

See the end of this file for information on how to install Quake from CD on
Windows, Mac OSX, and Linux.

I am not very good at writing documentation, so this readme is organized as a
feature list, with information on each feature, I hope it is still adequate
documentation.

If you have any suggestions for features to document in detail in the readme or any other questions/comments/bugreports/suggestions/etc, send me an email at lordhavoc@ghdigital.com



Input Tips:
If mouse movement is jerky but framerate is high, try typing "gl_finish 1"
(without quotes) into the console (makes cpu wait for gpu before ending frame,
which gives lousy input drivers a chance to catch up).



Graphics Tips:
Visit the Color Control submenu of Options, it's near the top, fiddle with
gamma (or grey level if using the color levels mode) until the grey box
surrounding the white/black dither pattern matches up with the grey you see
while looking at the dither from a distance, this will calibrate quake to look
approximately as id Software intended, and ensure everyone sees it the same.
Note: Different resolutions may be different intensities depending on monitor.
Note2: ATI Radeon Catalyst 3.10 drivers seem to have a weird gamma limiting
'feature' which rejects gamma settings it doesn't like, feel free to complain
to ATI about this if it gets in your way (it probably will).

Visit the Effects Options submenu of Options, and check out the options.

Networking tips:
Visit the Player Setup submenu of the Multiplayer menu to configure your
network speed (as well as the usual settings from quake like name and colors).

To host a server behind a router/firewall, simply set up a port forward on the
UDP port you are running the server on (default is 26000), to forward incoming
UDP packets on that port to the server, then people can connect.

To make your server show up on the server browser (in the Join Game menu),
either set sv_public 1 in the console, or use the multiplayer new game menu
and check the Public server checkbox.



Thanks to:
Tomaz for adding features, fixing many bugs, and being generally helpful.
Andreas 'Black' Kirsch for much work on the QuakeC VM (menu.dat, someday clprogs.dat) and other contributions.
Mathieu 'Elric' Olivier for much work on the sound engine (especially the Ogg vorbis support)
MoALTz for some bugfixes and cleanups
Joseph Caporale for adding 5 mouse button support.
KGB|romi for his contributions to the Quake community, including his rtlights project and many suggestions, his id1 romi_rtlights.pk3 is included in darkplaces mod releases.
Zombie for making great levels and general DarkPlaces publicity.
FrikaC for FrikQCC and FrikBot and general community support.
Transfusion Project for recreating Blood in the world of Quake.
de-we for the great icons.
|Rain| for running my favorite anynet IRC server and his bot feh (which although a bit antisocial never seems to grow tired of being my calculator).
VorteX for the DP_QC_GETTAGINFO extension.
Ludwig Nussel for the ~/.games/darkplaces/ user directory support on non-Windows platforms (allowing games to be installed in a non-writable system location as is the standard on UNIX but still save configs to the user's home directory).



Supported games:
Quake : -quake, this is active by default, gamedirs: id1
Quake: Scourge of Armagon : -hipnotic or hipnotic in executable name or path, gamedirs: hipnotic, id1
Quake: Dissolution of Eternity : -rogue or rogue in executable name or path, gamedirs: rogue, id1
Nehahra : -nehahra or nehahra in executable name or path, gamedirs: nehahra, id1
GoodVsBad2 : -goodvsbad2 or gvb2 in executable name or path, gamedirs: rts
BattleMech : -battlemech or battlemech in executable name or path, gamedirs: base
PrydonGate : -prydon or prydon in executable name or path, gamedirs: prydon
These games are considered officially supported, if any problems are seen,
please make sure you are running the latest version of the game and engine,
if you are, please report the problem.



Future supported games:
Nexuiz : -nexuiz or nexuiz in executable name or path, gamedirs: data
Zymotic : -zymotic or zymotic in executable name or path, gamedirs: data
Fniggium : -fniggium or fniggium in executable name or path, gamedirs: data
Setheral : -setheral or setheral in executable name or path, gamedirs: data
SonOfMan : -som or som in executable name or path, gamedirs: data
These have incomplete support and will likely change before their release.



Graphics features:
Redesigned effects including smoke, blood, bubbles and explosions.
Better looking dynamic lights.
External texture support (see Replacement Content section below)
Realtime bumpmapped lighting/shadowing support (see r_shadow_help in game)
.rtlights file support (improves performance/appearance of realtime lighting)
.rtlights file editing (see r_editlights_help in game)
Alpha blended sprites (instead of glquake's masked sprites).
Interpolated entity movement and animations (both models and sprites).
Overbright and fullbright support on walls and models (like winquake).
Colormapping support on any q1 model (like winquake).
Fog (set with "fog density red green blue" command)
Skybox (loadsky "mtnsun_" will load "env/mtnsun_ft.tga" and so on).
Sky rendering improved (no more glquake distortion).
Sky polygons obscure geometry just like in winquake.
Color calibration menu to ensure a proper Quake experience.
Improved model lighting (directional shading).
No messy .ms2 model mesh files (no glquake dir anymore either).
New improved crosshair (team color coded).
Improved image loading (smoother menus and such).
Ability to disable particle effects (cl_particles* cvars).
Decals (cl_decals cvar to enable).
Stainmaps (cl_stainmap cvar to enable).
Sorted transparent stuff to render better.
Improved multitexture support (r_textureunits (1-4 supported), needs gl_combine 1 because of overbright)
Improved chase cam (chase_active 1 no longer goes into walls)
More configurable console background (scr_conalpha and scr_conbrightness)
Optional fullbrights (r_fullbrights 0/1 followed by r_restart)
Dynamic Farclip (no distance limits in huge maps)
Improved gl_flashblend (now renders a corona instead of an ugly blob)
DynamicLight coronas (more realism)
Transparent statusbar (sbar_alpha) that does not block your view as much.
No 8bit texture uploads (fixes 'green' walls in the distance).
Fixed view blends (glquake was quite broken).
JPEG texture support using libjpeg (Thanks Elric)
PK3 archive support with compression support using zlib (Thanks Elric)



Sound features:
Ogg and wav file overrides for cd tracks (example: sound/cdtracks/track01.ogg or .wav) (Thanks Elric)
Streaming ogg sounds to save memory (Ogg sounds over a certain size are streamed automatically) (Thanks Elric)
Ogg Vorbis sound support (all .wav sounds look for .ogg if the .wav is missing, useful for making mods smaller, particularly for ambientsound() music) (Thanks Elric)
Stereo wav support (useful for music as ambientsound() calls)



Client features:
showtime cvar.
showdate cvar.
-benchmark option to run automated timedemo benchmarks (-benchmark demo1 does +timedemo demo1 and quits immediately when finished)
automatic timedemo logging to gamedir/benchmark.log
Slightly improved aiming on quake servers (does not support proquake aiming).
-sndspeed samplerate (default: 44100, quake used 11025)
snd_swapstereo cvar (for people with backwards SB16 sound cards)
Saves video settings to config and restores them properly
Ability to change video settings during game (video options menu or vid_* cvars)
showfps cvar.
Video Options, Color Control, and Effects Options menus added, and more options.
Sends 20fps network packets to improve modem play instead of one per frame. (sys_ticrate controls network framerate)
Allow skin colormaps 14 and 15 (freaky :)
Longer chat messages.
No more 72fps limit, host_maxfps lets you decide.
Support for more mouse buttons (mouse1-mouse16, mwheelup/mwheeldown are aliases to mouse4 and mouse5).
Server browser for public (sv_public 1) darkplaces servers.
log_file cvar to log console messages to a file.
condump command to dump recent console history to a file.



Server features: (Note server only supports darkplaces clients)
Allows clients to connect through firewalls (automatic feature)
Works behind firewalls unlike NetQuake (must port forward UDP packets on the relevant port from the firewall to the server, as with any game)
More accurate movement and precise aiming.
64 player support.
sv_cheats cvar controls cheats (no longer based on deathmatch).
slowmo cvar controls game speed.
No crash with the buggy 'teleport train' in shub's pit.
Allow skin colormaps 14 and 15 (freaky :)
sys_ticrate applies to listen (client) servers as well as dedicated.
sv_public cvar to advertise to master server.
log_file cvar to log console messages to a file.
condump command to dump recent console history to a file.



Modding features:
HalfLife map support (place your HalfLife wads in quake/id1/textures/ or quake/MODDIR/textures/ as the maps need them)
Larger q1 and hl map size of +-32768 units.
Colored lighting (.lit support) for q1 maps.
Q3 map support (no shaders though), with no limits.
Q2 and Q3 model support, with greatly increased limits (256 skins, 65536 frames, 65536 vertices, 65536 triangles).  (Note: md2 player models are not supported because they have no skin list)
Optimized QuakeC interpreter so mods run faster.
Bounds checking QuakeC interpreter so mods can't do naughty things with memory.
Warnings for many common QuakeC errors.
Unprecached models are now a warning (does not kill the server anymore).
External texture support (see dpextensions.qc DP_GFX_EXTERNALTEXTURES).
Fog ("fog" key in worldspawn, same parameters as fog command).
.spr32 and halflife .spr sprites supported.  (Use Krimzon's tool to make spr32, and lhfire can render directly to spr32, or just use replacement textures on .spr).
Skybox ("sky" key in worldspawn, works like loadsky and quake2).
Stereo wav sounds supported.
Ogg Vorbis sounds supported. (Thanks Elric)
ATTN_NONE sounds are no longer directional (good for music).
play2 sound testing command (ATTN_NONE variant of play).
r_texturestats and memstats and memlist commands to give memory use info.
Lighting on sprites (put ! anywhere in sprite filename to enable).
More r_speeds info (now a transparent overlay instead of spewing to console).
Supports rotating bmodels (use avelocity, and keep in mind the bmodel needs the "origin" key set to rotate (read up on hipnotic rotation support in your qbsp docs, or choose another qbsp if yours does not support this feature), or in q3 maps an origin brush works).
More sound channels.
More dynamic lights (32 changed to 256).
More precached models and sounds (256 changed to 4096).
Many more features documented in dpextensions.qc. (bullet tracing on models, qc player input, etc)



Replacement Content:
Formats supported: tga, png, jpg, pcx, lmp

All texture layers are optional except diffuse (the others are NOT loaded without it):
skins:
progs/player.mdl_0.tga - diffuse
progs/player.mdl_0_norm.tga - normalmap (can have alpha channel with bumpmap height for offsetmapping/reliefmapping)
progs/player.mdl_0_bump.tga - bumpmap (not loaded if normalmap is present)
progs/player.mdl_0_glow.tga - glow map (use _luma if tenebrae compatibility is a concern)
progs/player.mdl_0_luma.tga - alternate tenebrae-compatible name for glow map (use one or the other)
progs/player.mdl_0_pants.tga - pants image, greyscale and does not cover the same pixels as the diffuse texture (this is additive blended ('Screen' mode in photoshop) ontop of the diffuse texture with a color tint according to your pants color)
progs/player.mdl_0_shirt.tga - shirt image, same type as pants

map-specific textures:  (overrides textures for a specific map)
textures/e1m1/ecop1_6.tga
textures/e1m1/ecop1_6_norm.tga
textures/e1m1/ecop1_6_bump.tga
textures/e1m1/ecop1_6_glow.tga
textures/e1m1/ecop1_6_luma.tga
textures/e1m1/ecop1_6_pants.tga - pants and shirt layers are possible on bmodel entities with quakec modifications to set their .colormap field
textures/e1m1/ecop1_6_shirt.tga

map textures:
textures/quake.tga
textures/quake_norm.tga
textures/quake_bump.tga
textures/quake_glow.tga
textures/quake_luma.tga
textures/quake_pants.tga
textures/quake_shirt.tga

hud and menu pictures:
gfx/conchars.tga

replacement models:
same as in Quake, you can replace a model with exactly the same file name (including file extension), so for example an md3 player model has to be renamed progs/player.mdl, and a small box of shells in md3 format has to be renamed maps/b_shell0.bsp



Commandline options as of 2004-10-05:
BSD GLX: -gl_driver <drivername> selects a GL driver library, default is libGL.so.1, useful only for using fxmesa or similar, if you don't know what this is for, you don't need it
BSD GLX: -nogetprocaddress disables GLX_ARB_get_proc_address (not required, more formal method of getting extension functions)
BSD GLX: -novideosync disables GLX_SGI_swap_control
BSD Sound: -cddev <devicepath> chooses which CD drive to use
Client: -benchmark <demoname> runs a timedemo and quits, results of any timedemo can be found in gamedir/benchmark.log (for example id1/benchmark.log)
Client: -forceqmenu disables menu.dat (same as +forceqmenu 1)
Client: -particles <number> changes maximum number of particles at once, default 32768
Client: -texbrightness <number> sets the quake palette brightness (brightness of black), allowing you to make quake textures brighter/darker, not recommended
Client: -texcontrast <number> sets the quake palette contrast, allowing you to make quake textures brighter/darker, not recommended
Client: -texgamma <number> sets the quake palette gamma, allowing you to make quake textures brighter/darker, not recommended
Client: -useqmenu causes the first time you open the menu to use the quake menu, then reverts to menu.dat (if forceqmenu is 0)
Console: -condebug logs console messages to qconsole.log with sync on (so it keeps every message up to a crash), see also log_file and log_sync
Console: -developer enables warnings and other notices (RECOMMENDED for mod developers)
Console: -nostdout disables text output to the terminal the game was launched from
Filesystem: -basedir <path> chooses what base directory the game data is in, inside this there should be a data directory for the game (for example id1)
Filesystem: -path <path ..> specifies the full search path manually, overriding the generated one, example: -path c:\quake\id1 c:\quake\pak0.pak c:\quake\pak1.pak (not recommended)
GL: -noanisotropy disables GL_EXT_texture_filter_anisotropic (allows higher quality texturing)
GL: -nocombine disables GL_ARB_texture_env_combine or GL_EXT_texture_env_combine (required for bumpmapping and faster map rendering)
GL: -nocubemap disables GL_ARB_texture_cube_map (required for bumpmapping)
GL: -nocva disables GL_EXT_compiled_vertex_array (renders faster)
GL: -nodot3 disables GL_ARB_texture_env_dot3 (required for bumpmapping)
GL: -nodrawrangeelements disables GL_EXT_draw_range_elements (renders faster)
GL: -noedgeclamp disables GL_EXT_texture_edge_clamp or GL_SGIS_texture_edge_clamp (recommended, some cards do not support the other texture clamp method)
GL: -nofragmentshader disables GL_ARB_fragment_shader (currently unused, allows pixel shader effects)
GL: -nomtex disables GL_ARB_multitexture (required for faster map rendering)
GL: -noshaderobjects disables GL_ARB_shader_objects (required for vertex shader and fragment shader)
GL: -noshadinglanguage100 disables GL_ARB_shading_language_100 (required for vertex shader and fragment shader)
GL: -nostenciltwoside disables GL_EXT_stencil_two_side (accelerates shadow rendering)
GL: -notexture3d disables GL_EXT_texture3D (required for spherical lights, otherwise they render as a column)
GL: -notextureshader disables GL_NV_texture_shader (required for the Geforce3 water shader, NVIDIA only)
GL: -novertexshader disables GL_ARB_vertex_shader (currently unused, allows vertex shader effects)
Game: -battlemech runs the multiplayer topdown deathmatch game BattleMech
Game: -fniggium runs the post apocalyptic melee RPG Fniggium
Game: -goodvsbad2 runs the psychadelic RTS FPS game Good Vs Bad 2
Game: -hipnotic runs Quake mission pack 1: The Scourge of Armagon
Game: -nehahra runs The Seal of Nehahra movie and game
Game: -neoteric runs the game Neoteric
Game: -netherworld runs the game Netherworld: Dark Masters
Game: -nexuiz runs the multiplayer game Nexuiz
Game: -openquartz runs the game OpenQuartz, a standalone GPL replacement of the quake content
Game: -prydon runs the topdown point and click action-RPG Prydon Gate
Game: -quake runs the game Quake (default)
Game: -rogue runs Quake mission pack 2: The Dissolution of Eternity
Game: -setheral runs the multiplayer game Setheral
Game: -som runs the multiplayer game Son Of Man
Game: -tenebrae runs the graphics test mod known as Tenebrae (some features not implemented)
Game: -teu runs The Evil Unleashed (this option is obsolete as they are not using darkplaces)
Game: -transfusion runs Transfusion (the recreation of Blood in Quake)
Game: -zymotic runs the singleplayer game Zymotic
Input: -nomouse disables mouse support (see also vid_mouse cvar)
Linux ALSA Sound: -sndbits <number> sets sound precision to 8 or 16 bit (email me if you want others added)
Linux ALSA Sound: -sndmono sets sound output to mono
Linux ALSA Sound: -sndpcm <devicename> selects which pcm device to us, default is "default"
Linux ALSA Sound: -sndspeed <hz> chooses 44100 hz, 22100 hz, or 11025 hz sound output rate
Linux ALSA Sound: -sndstereo sets sound output to stereo
Linux GLX: -gl_driver <drivername> selects a GL driver library, default is libGL.so.1, useful only for using fxmesa or similar, if you don't know what this is for, you don't need it
Linux GLX: -nogetprocaddress disables GLX_ARB_get_proc_address (not required, more formal method of getting extension functions)
Linux GLX: -novideosync disables GLX_SGI_swap_control
Linux OSS Sound: -sndbits <bits> chooses 8 bit or 16 bit sound output
Linux OSS Sound: -sndmono sets sound output to mono
Linux OSS Sound: -sndspeed <hz> chooses 44100 hz, 22100 hz, or 11025 hz sound output rate
Linux OSS Sound: -sndstereo sets sound output to stereo
Linux Sound: -cddev <devicepath> chooses which CD drive to use
MacOSX GLX: -nogetprocaddress disables GLX_ARB_get_proc_address (not required, more formal method of getting extension functions)
MacOSX GLX: -novideosync disables GLX_SGI_swap_control
SDL GL: -gl_driver <drivername> selects a GL driver library, default is libGL.so.1 (Linux/BSD) or opengl32.dll (windows) or OpenGL.framework (MacOSX), useful only for 3dfxogl.dll/3dfxvgl.dll or fxmesa or similar, if you don't know what this is for, you don't need it
SDL Sound: -sndspeed <hz> chooses 44100 hz, 22100 hz, or 11025 hz sound output rate
Server: -dedicated [playerlimit] starts a dedicated server (with a command console), default playerlimit is 8
Server: -ip <ipaddress> sets the ip address of this machine for purposes of networking (default 0.0.0.0 also known as INADDR_ANY), use only if you have multiple network adapters and need to choose one specifically.
Server: -listen [playerlimit] starts a multiplayer server with graphical client, like singleplayer but other players can connect, default playerlimit is 8
Server: -port <portnumber> sets the port to use for a server (default 26000, the same port as QUAKE itself), useful if you host multiple servers on your machine
Sound: -nocdaudio disables CD audio support
Sound: -nosound disables sound (including CD audio)
Sound: -novorbis disables ogg vorbis sound support
Sound: -simsound runs sound mixing but with no output
Video: -bpp <bits> performs +vid_bitsperpixel <bits> (example -bpp 32 or -bpp 16)
Video: -fullscreen performs +vid_fullscreen 1
Video: -height <pixels> performs +vid_height <pixels> and also +vid_width <pixels*4/3> if only -height is specified (example: -height 768 sets 1024x768 mode)
Video: -width <pixels> performs +vid_width <pixels> and also +vid_height <pixels*3/4> if only -width is specified (example: -width 1024 sets 1024x768 mode)
Video: -window performs +vid_fullscreen 0
Windows DirectSound: -primarysound locks the sound hardware for exclusive use
Windows DirectSound: -snoforceformat uses the format that DirectSound returns, rather than forcing it
Windows GDI Input: -noforcemaccel disables setting of mouse acceleration (not used with -dinput, windows only)
Windows GDI Input: -noforcemparms disables setting of mouse parameters (not used with -dinput, windows only)
Windows GDI Input: -noforcemspd disables setting of mouse speed (not used with -dinput, windows only)
Windows Input: -dinput enables DirectInput for mouse/joystick input
Windows Input: -nojoy disables joystick support, may be a small speed increase
Windows Sound: -sndspeed <hz> chooses 44100 hz, 22100 hz, or 11025 hz sound output rate
Windows Sound: -wavonly uses wave sound instead of DirectSound
Windows WGL: -gl_driver <drivername> selects a GL driver library, default is opengl32.dll, useful only for 3dfxogl.dll or 3dfxvgl.dll, if you don't know what this is for, you don't need it
Windows WGL: -novideosync disables WGL_EXT_swap_control

How to install Quake on each operating system:
All that DarkPlaces needs from the Quake CD is pak files (be sure not to copy
opengl32.dll from the Quake CD, it will not work with DarkPlaces!), with this
in mind, all you need to do is make a Quake directory, extract the darkplaces
engine zip to that directory, then make a quake/id1 directory, and put the
pak0.pak and pak1.pak from your Quake CD into the quake/id1 directory, then
all should be well.

How to deal with a DOS Quake CD on Windows:
Try to use the DOS Quake installer if you can, use DOSBox if necessary to run
the installer, then copy the pak0.pak and pak1.pak to your id1 directory in
the darkplaces installation.  ( http://dosbox.sourceforge.net )

How to deal with a DOS Quake CD on Linux:
cat /media/cdrom/resource.001 /media/cdrom/resource.002 >quake.lha
unlha x quake.lha
If you can't get unlha or lha for your distribution, try using DOSBox to run
the Quake installer.

How to deal with a DOS Quake CD on Mac OSX:
Unknown.  Linux solution may work if you can get hold of lha, otherwise use
DOSBox to run the Quake installer.

How to deal with a WinQuake CD on Windows:
Copy the D:\Data\id1\pak0.pak and pak1.pak to your id1 directory.

How to deal with a WinQuake CD on Linux:
Copy the /media/cdrom/data/id1/pak*.pak to your id1 directory.

How to deal with a WinQuake CD on Mac OSX:
Find the data directory on the cdrom and copy the data/id1/pak*.pak files to
your id1 directory.

How to deal with a Linux Quake CD on Windows:
Find an archiver (perhaps 7zip or winrar) that can extract files from rpm
archives, locate the pak files and copy them to your id1 directory.

How to deal with a Linux Quake CD on Linux:
mkdir temp
cd temp
# in the following line replace quake.rpm with a correct rpm filename
cat /media/cdrom/quake.rpm | rpm2cpio | cpio -i
Now you should have a mess of subdirectories, locate the pak files and copy to
your id1 directory.

How to deal with a Linux Quake CD on Mac OSX:
Unknown.  If you can get hold of rpm2cpio and cpio you should be able to
follow the Linux method.

For more information on Quake installation on Linux see the Linux Quake Howto http://www.tldp.org/HOWTO/Quake-HOWTO.html


