==============================================================================
   Table of Contents
==============================================================================
Table of Contents
What is this?
I just want to play.
What was fixed?
What about features?
Debug "cheats".
Compiling source code.
Known issues.
Technical stuff: Why were these games so buggy?
A note on porting and added features.
A note on legalities.
Thanks & shoutouts
Final words.


==============================================================================
   What is this?
==============================================================================
EGwhaven is a bugfixed and enhanced rebuild of the Witchaven II source code
that was uploaded by former Capstone employee Les Bird.  It is not technically
a port as it is still a DOS EXE, though it may be regarded as a "port" in the
sense that Doom players often use the term.


==============================================================================
   I just want to play.
==============================================================================
As a bare minimum, you need a copy of Witchaven II, a DOS system (either real
or more likely emulated via DOSBox, see http://www.dosbox.com/) and a copy of
EGwhaven (should have been included with this file.)

To play:
- Install and set up Witchaven II, if you haven't already.
- Unpack the EGwhaven files into your Witchaven II directory.
- In DOSBox (or DOS mode), run EGWHAVEN.EXE
- Enjoy your bugfixed Witchaven experience.


==============================================================================
   What was fixed?
==============================================================================
For detailed information, see the file CHANGELOG.  Here's the quick version:

- Jump/fall speeds - No more slamming up and down uselessly.
- Control physics - Tighter movement and better mouse control.
- Projectile movement - Monsters and spells can now reliably aim at targets.
- Projectile collision - No more arrows stuck in midair because they crossed
                           another projectile's path.
- Shields - They are no longer indestructible. (Shield hits formerly "healed"
              the shield instead of damaging it.)
- Onyx Ring - Now it protects you from projectiles as stated in manual.
                (Formerly did nothing.)
- Glass Skull - Now levels you up correctly (was using Witchaven I values)
- Hero Time - Weapon speed no longer dependant on CPU.
- Dual wield - Success rate is no longer dependant on CPU.
- Skeleton - It animates correctly now.
- Enemy's ghost - Now he rises from the dead correctly.
- Pentagrams - Map loading no longer unsets map's translucency setting.
             - No longer count towards treasure score (could have made
                 full score unattainable.)
- Treasure chests - All intended random outcomes are now possible.
- Willow Wisp attack - Now does something.
- Enchanted weapons - You will no longer throw them away in favor of the
                        mundane version.  Also, some fixes to the enchanted
                        droning sounds (not completely polished yet)
- SVGA mode - It no longer wigs out as badly when the player is killed.
            - Exiting to menu no longer turns off the status bar.
- Hard disk install - Copy the SMK folder from the CD to your Witchaven II
                      install directory and it will play cinematics without
                      the CD in drive.  WARNING: If you don't have the SMK
                      files present in a valid location, the game may have
                      errors when completing a map (black screen).  This will
                      hopefully be fixed later down the line.


==============================================================================
   What about features?
==============================================================================
One major feature has been added so far, the GAME parameter.  Inspired by
the -game parameter from Quake, this will make the game load files from a
subdirectory, but fall back on the original data for things that aren't found.

If you have, for instance, put your levels in a subdirectory called NEWMAPS,
you would type:

EGWHAVEN GAME NEWMAPS

In keeping with the existing parameters, there is no - or / mark preceeding
the parameter.

This feature is in development; it can currently load custom maps as long as
they follow the game's naming convention (LEVEL*.MAP where * is the level
numbler with no prepended zeroes.)  It can also load a custom STUFF.DAT (same
format as Duke 3D GRP files) which may contain an alternate .ART set, but it
cannot load loose .ART files at the moment.


==============================================================================
   Debug "cheats".
==============================================================================
I've added several informational commands to the game's cheat code system.
To access them, hit BACKSPACE and then type in the command.  When you are done
looking at the info, hit ESC to go back to play.

------------------------------------------------------------------------------
Code       |  Displays
------------------------------------------------------------------------------
DBGARMOR   |  Armor points and type.
DBGSHIELD  |  Shield points, type, and if the shield is put away.
DBGRINGS   |  Whether the player has any of the four rings.
DBGPOWERS  |  Powerups and their time remaining.
------------------------------------------------------------------------------

Warning: Your powerups will still run down while you are looking at the info
displayed.  I'll probably fix that some time, but be aware that the commands
are meant to be used for debugging, not regular play.


==============================================================================
   Compiling source code.
==============================================================================
If you downloaded the source code release, be aware that it's currently only
set up to work with a Watcom compiler.  The file MAKE.BAT will call the
commands you need.  WHAVEN.MAK and WHAVEN.LNK contain the actual build
instructions.  The finished EGWHAVEN.EXE gets placed in the RUN directory.
CLEANUP.BAT will wipe out the files created during the build process (mainly
to prepare for a clean source release.)


==============================================================================
   Known issues.
==============================================================================
Although I have done my best to provide a debugged Witchaven II experience,
there are a few issues that, though I am aware of them, I have left unfixed.

Fire resistance blocking non fire attacks has to be regarded in the "not a bug
but a feature" category as the Witchaven II level designers counted on it
when designing some of the game's deathtraps.  The EGwhaven code does have a
"fixed" version that I might make selectable by mod definitions later.

Cinematic playback is handled by a blob, the replacement of which would
in all likelihood require full porting to a modern OS for the replacement
library to work.  I'm not ready to tackle that task yet and I'm not sure
about fixing it by other methods.  Apparently it's an issue related to
sound playback.

CapsLock is supposed to toggle autorun mode.  It's not currently working
correctly and I need to research DOS programming more deeply before I can
go on with fix attempts.

The TODO list contains a further list of issues that I know about, but have
yet to repair.


==============================================================================
   Technical stuff: Why were these games so buggy?
==============================================================================
A question that's often asked about the Witchaven games is, how could they
even release them when they're such a mess?  In the case of some of the worst
bugs, the rather interesting answer is that they lay dormant at the time of
release.

Some explanation: different computers run instructions at different speeds.
For consoles, programmers can count on standardized hardware; an NES runs at
the same speed as every other (official) NES.  That allows programmers to be
"lazy" and not worry about putting in any special code to regulate the game
to a particular speed; if it runs at the right speed on the developer's
system, it runs right on the player's system too.

PCs, on the other hand, are an entirely different beast in this regard.  There
is no one standard PC, and an increasing number of different CPUs that run at
varying speeds.  This means that to make a game that runs reliably across a
variety of CPUs, special code to regulate the game speed is required.  DOS
games from the 80s often didn't do that, which is why they run unplayably fast
without special settings to slow things down.

The Witchaven code is a bit of an oddity in this regard.  In most places, the
code corrects the game to system speed as it should.  Yet, there are a few
places where the programmers forgot to do this.  Hence, those functions ran
OK on the developers' machine(s), and usually ran OK on players' machines at
the time of release... but run it on a much faster machine, and suddenly those
functions are all messed up.  This is all the more insidious since for the
most part, the game is adjusted to the system speed, so you can't instantly
look at it and say "oh, it's running too fast".  You just see that some parts
are bugged up.  That is why you have problems jumping, and why autoaimed
projectiles go way off somewhere they shouldn't.

Some other bugs are of a more mundane variety, of course.  In some cases the
programmers simply forgot to finish something (Onyx Ring) or to update it to
Witchaven II when they made alterations (Glass Skull).  A few features,
especially in Witchaven II, appear to have been rushed, and not given the
polish they should have received.  And some bugs are just plain and simple
oversights or typos.


==============================================================================
   A note on porting and added features.
==============================================================================
My purpose with EGwhaven has always been providing bugfixes first and
foremost, then adding a a few modest enhancements.  I may consider porting the
code to a newer BUILD version / newer systems at some point, once all else is
done and if no one else comes forth to, but that would require making many
additional updates and alterations to the code, and as far as I'm concerned
I'm content to let DOSBox do the "porting" for me.  Aside from the cinematic
playback problems, the major issues preventing Witchaven II from being run
under DOSBox should be gone.

Most of the modding features added or planned are either logical extensions
from making Witchaven I run as a mod, or done for the convenience of running
new map sets (the original way Witchaven II worked supported designing new
levels in only the most basic way, and necessitated replacing the core files
to make a map set or adjust graphics.)  I will not be making EGwhaven into
a super-everything-scripted-and-moddable-all-in-one-FPS-creation-toolkit.  If
you're a modder looking for an engine that tries to play the part of a game
creation system on the side, you might look into eDuke32 (if you want to stick
with BUILD), ZDoom (Doom based) or maybe even Darkplaces (Quake based).

If you're interested in making your own Witchaven / Witchaven II port, you
are, as far as my part is concerned, welcome, encouraged even, to use the
EGwhaven code, and to contact me with questions regarding how things work in
the game (I might actually know!)


==============================================================================
   A note on legalities.
==============================================================================
EGwhaven is based on the Witchaven and Witchaven II source code generously
provided by Les Bird at: http://www.lesbird.com/CAPSTONE/

This was not an official release by Capstone / IntraCorp.  The statement
given by Les Bird on his site is as follows:

"These games were released by Capstone Software prior to them folding in
1996. As a former Capstone programmer I found these developer snapshots in my
archives and by popular demand I've decided to release it to the hobbyist
community in hopes that the games will be revived. I do not own the rights to
these games. I do not know who owns the rights to these games. To the best of
my knowledge these games are abandonware (or whatever you want to call it)."

As such, regard EGwhaven in the same way you might a ROM hack for an NES game;
an unlicensed modification but in practice "no one cares".  This code is not
GPL.  It is not "Open Source" nor "Free Software" as defined by the FSF.  You
cannot legally copy this code into a GPLed project or copy code from a GPLed
project into it.

Currently, ONLY code and blobs from Les Bird's Witchaven and Witchaven II
snapshots have been used.  The BUILD portions of the game may fall under Ken
Silverman's BUILD license, see BUILDLIC.TXT.  I have not, however, updated
the BUILD segment to its most current release, instead using the BUILD .OBJs
originally used in the making of Witchaven II.  That may change in the future.

The full Witchaven and Witchaven II game data are not included with releases
of EGwhaven.  Please do not package EGwhaven into warez/abandonware downloads
(but feel free to include a link, if you want).  If you do not have a copy of
the game, you are encouraged to buy a disc copy, which are commonly available.

I, ETTiNGRiNDER, do not claim any copyright ownership of the Witchaven source
code, nor the Witchaven games themselves.


==============================================================================
   Thanks & shoutouts
==============================================================================

To Les Bird, for getting the source code out there.
And to Corvin of R.T.C.M., for encouragement and testing.


==============================================================================
   Final words.
==============================================================================
I hope that EGwhaven will provide a greater enjoyment of the game for
Witchaven fans and perhaps even win over some of the people who were put off
by the game's bugginess as originally released.  Please let me know if you
find any additional bugs that aren't mentioned in the documentation.

Also, if you make any custom Witchaven adventures with the map editor, for
EGwhaven or for the vanilla game, I would love to play them and perhaps host
them on my web site.

      - Your brother in battle,
         ETTiNGRiNDER
         ettingrinder@hush.com
         http://ettingrinder.jimdo.com

==============================================================================