MHQuake Readme
==============

===========================================================================================================
UPDATE:
Well, not quite.  This is pretty out of date now, things have moved on a bit since I originally wrote it a
few months back.  If something doesn't work as described here, it's either been changed or removed since.
There's some stuff added since too that isn't in here.  I'll write a more up to date readme before the next
major release.
===========================================================================================================

It's been a long time since I've provided a readme, so here goes.  The first and most important thing to
remember is that MHQuake is *not* a new game and it is *not* a mod.  Instead, it is a replacement for the
standard GLQuake engine primarily intended to give a more modern look to the old classics, while at the same
time retaining much of the *feel* of the original game.

You won't find anything in the maps that wasn't there before, and you won't see monsters behaving in exciting
new ways.  The weapons remain the very same, the traps and pickups will be the same, but the whole thing will
(hopefully) *look* a lot better than it did before.  Also, and hopefully again, it should not run that much
slower than regular GLQuake.  I've put a lot of work into speed optimisations (where they count), so a lot of
the extra prettiness comes at no cost.  Unfortunately, there are things like RGBA lightmaps, alias model
interpolation, etc which do incur a speed penalty.  Generally, I try to keep MHQuake running at above 90FPS
on my test machine.

A primary consideration is that when Quake was originally written the hardware to do a lot of stuff just
didn't exist.  2 TMU cards were only starting to appear, GL_LINEAR_MIPMAP_LINEAR was only supported on high
end professional workstation cards (more suitable for CAD work), OpenGL itself was a few versions down from
what it is now, with a lot of stuff implemented as extensions that varied from manufacturer to manufacturer.
MHQuake was just not possible before OpenGL 1.4.  Sound was an even bigger mess, with loads of software
fallbacks causing lag and choppiness.  The whole engine code is - quite frankly - full of deeply nasty
workarounds and hacks: I'm sure Carmack himself would be first to admit this.  The best approach would be "rip
it up and start again", but cos I wanted to release something (that worked) on a semi-regular basis I've taken
a more modular approach.

You won't need anything to run MHQuake beyond the engine itself.  There is no additional PAK file containing
new graphics, there is no extra DLL to be put in your Quake directory.  You *can* if you wish use LIT files to
add coloured lighting, and MP3s for music, but these are optional, not necessary.

Anyway, here's a brief overview of some of the main points: features as well as a few troubleshooting tips.


-hwsound
--------
Attempts sound mixing in hardware.  This will cause serious problems on sound hardware that does not fully
support it, so if MHQuake is slow and/or unstable after adding this parameter, remove it.


2D graphics locked at 640 x 480
-------------------------------
This is deliberate, and is primarily because of the new HUD.  If enough people demand, I may provide an
option to unlock them at some time.


3D Card Support
---------------
MHQuake absolutely requires 2 TMUs as a *minimum* to run.  If you have 3 or more TMUs, MHQuake will enable the
third TMU for any extra effects that require it.  Your card should support OpenGL 1.4, but no extensions beyond
core OpenGL 1.4 are required.  Update: I've noticed that my work PC (containing an ATI Radeon card) does not
properly support OpenGL 1.2 or above.  This may be ATI's drivers, or it may be a botched installation.  As
soon as I get to test it properly I'll modify this accordingly.  Update: MHQuake depends more on your 3D card
than it does on your CPU.  If you have an older PC you'll certainly benefit from something like a budget
GeForce.  I saw my FPS go from < 30 to > 90 at 1024 x 768 when I put a cheap FX5200 into a PII 350: faster
than a 1.4GHz Athlon with a GeForce 2!!!  If you don't have a hardware GPU you'll most likely suffer...


Automatic Water Translucency
----------------------------
If your map has not been vised for translucent water, MHQuake will make a very good stab at guessing the
necessary extra leafs and surfs that should be visible.  If your map has been so vised, MHQuake will detect it
and not apply Automatic Water Translucency (100% reliable so far in tests).  This is very fast to load, so it
is always on.  The old "r_wateralpha" cvar has been removed.


Coloured Light and LIT Files
----------------------------
MHQuake supports LIT files for adding coloured light to maps: just place them in a "maps" folder under "ID1"
(or whatever).  Most people have LIT files built using the MHColour tool I made years ago.  Unfortunately,
these files contain a few bugs, so MHQuake will ignore the LIT data and use the original BSP data for any
surfaces in the map containing such a bug.  MHQuake also saves stainmaps as a LIT file, so you should be able
to use it to make bloodstained versions of the levels for porting between different engines.


Crashes at certain times in certain mods
----------------------------------------
Most likely caused by QuakeC being used in an unintended manner.  For example, Zerstorer cutscenes set the
viewsize to 120 to avoid drawing the old status bar.  Any attempt to draw the MHQuake HUD during a cutscene
will cause the engine to crash (this is because a lot of the client data required for the HUD or status bar
simply isn't present in cutscenes).  Update: I've hacked in a fix for this, but it's far from perfect.  I'll
do it properly sometime soon.


Direct X Problems
-----------------
MHQuake was compiled using the Direct X 8.1 SDK - you should have at least Direct X 8.1 installed for MHQuake
to work.  MHQuake only uses Direct X for sound (no "crappy Windows multimedia base").  I think that given the
high number of games that use Direct 3D these days most people would be at least at 8.1.


Dynamic lighting
----------------
Dynamic lights (and lightstyle changes) are only applied at 10FPS.  I have never noticed any difference.


External Textures
-----------------
These are back.  TGA, BMP (4, 8, 8 RLE and 24 bpp) and PCX are all supported.  Naming conventions are standard,
so any such textures you have should load OK.  The BMP loader is all my own, but it seems pretty stable :-)
I don't support 16 bit cos my paint program can't make them (so I can't test them properly...)


Font Support
------------
Set gl_windowsfont to 1 to enable use of the Courier New font instead of the Quake charset.  This causes a bit
of a speed hit, and is only really suitable for 1024 * 768 resolution so it's off by default.


gl_stainmaps 0|1
----------------
Used to toggle stainmaps off and on.  Stainmaps used include goo from scrags, explosion burns, bullet and nail
marks, and lots of blood.  These have been fairly tightly optimised, so there should be minimal slowdown from
enabling them.  Stainmaps are loaded and saved with your game save.


HUD
---
MHQuake features a more modern looking HUD than the old Quake status bar.  All of the information on the
status bar is present without intruding on your screen real estate as much.  The HUD features animating 3D
models (there's also one in the Multiplayer setup menu) and powerup countdowns.  This may not be fully
compatible with your favourite mods.  The viewsize cvar is used to control how much of the HUD is visible:
100 = full HUD, 110 = vital stats (health/ammo/armour) only, 120 = no HUD.


MP3 Support
-----------
I've removed the old CD Audio code and replaced it with MP3 code.  It's currently fairly hacky, but it's on
my to do list.  The important thing for now is that it works.  Just rip your Quake CD and save the files to a
new directory called "music" under "ID1" (or wherever).  The files themselves should be called "01.mp3",
"02.mp3", "03.mp3" etc.


Point Particles are too big!
----------------------------
Likely caused by old(er) drivers.  I saw this myself on a machine where I had rolled back my NVidia drivers
from version 6 to version 5.  Reinstalling the version 6 drivers fixed it.  It also worked perfectly fine on
a machine that had a clean install of the version 5 drivers - rolling back seemed to be the primary cause.
Update: also reported on hacked NVidia drivers - again, updating to the latest official drivers fixed it.
Oddly enough, in this case they worked fine in demos but were superlarge in play.  I dunno...


Texture upsizing
----------------
All map textures are upsized to twice their standard size, then filtered by a pixel interpolation algorithm
to remove blockiness.  This should improve the view at a distance as well as provide more detail close up.  It
does not look absolutely perfect on some textures.  Update: new algorithm in place, looks much better.


Underwater Gof and Caustics
---------------------------
"Gof" is a typo, but I left it in cos "fog" doesn't work at the moment!  Hopefully fixed soon.  Caustics use
the same texture as the liquid they are under, but may be a bit dark in some scenes.  I'm working on it.


The To Do List
==============

This engine is not complete.  I have a To Do List of over 4 pages of tightly spaced handwritten bullet points.
If something doesn't work, looks bad, or just plain sucks, chances are that either (a) it's deliberate cos *I*
like it, or (b) it's on the list.


Big Yowsa
=========

Reckless for encouragement, some coding work, and keeping the flame while I was away.
Kempie for encouragement and playtesting.





