==============================================================================
   Table of Contents
==============================================================================
* Table of Contents
* What is this?
* I just want to play.
* What's new in this version?
* Other major fixes?
* What about features?
* RULES.CFG reference.
* Compiling / editing 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 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 and/or 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.)  All included EXEs are to be run under DOS.

To play:
- Install and set up Witchaven (II), if you haven't already.  You MUST set
     sound up correctly as per the vanilla game.  Check your sound setup
     before reporting crashes!
- Put the EGwhaven files in the directories of their respective games.
     EGWH1 is for the original game and EGWH2 is for Witchaven II.
- Configure EGwhaven enhanced preferences using EGSETUP.EXE.  This config is
     interchangeable for both games so if you set up one, you can copy
     EGPREF.CFG over to the other.
- Run EGWH1 for Witchaven or EGWH2 for Witchaven II.  Enjoy!

==============================================================================
   What's new in EGwhaven v1.3
==============================================================================

v1.3 aims to fix a number of issues introduced in the rushed and rather
disastrously buggy v1.2.  This version should be much more thoroughly tested.
A few other fixes and additions have also been made.

- Regressions to save games which could heavily break reloaded sessions
     in v1.2 have been cleaned up.
- Jumping and gravity strength have been re-corrected mathematically and
     should now be finally finalized (I am very confident that WH1 at least
     is as close to original intent as possible without being able to check
     against the original dev machine.)
- Stricter checks to prevent monsters from stepping off the edges of cliffs.
- Stricter checks to the player's vertical movement to work around an
     occasional bug where Grondoval would be erroneously pulled up into the
     ceiling.
- A bug which doubled health potion / ankh health values and potentially
     exceeded the player's max health was fixed in Witchaven II.
- New RULES.CFG options for spell level requirements and maximum ammo for
     bow & arrows and pike axes.


==============================================================================
   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

There is also a WARP parameter, analogous to -warp in Doom.  Use it just
like you would the MAP parameter, but it will additionally bypass the main
menu to drop you immediately into the game.  Example:

EGWHAVEN WARP 11

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

The GAME feature allows map sets to be placed in their own subdirectories,
and can maintain a separate set of save games for each.  It can load most
forms of game data, although it cannot load loose .ART files at the moment
 (put them in a STUFF.DAT), nor SMK files or a few rarely-modded BUILD files
like PALETTE.DAT.

RULES.CFG contains variables which define game behaviors.  These can
enable/disable certain behavior fixes and offer a few tweaks for map set
designers.  See below for further details.

MAPNAMES.CFG (WH2 only) allows the intermission map titles to be customized,
so that map set designers can have their own titles displayed instead of
the defaults.  It also allows an arbitrary number of levels to be defined.
Format is one line for each map, consisting of <map number> <map name>.
Map names are case insensitive but display as ALL CAPS in-game.
Example:
666  COOL NEW LEVEL
A MAPNAMES.CFG is included and required to place in your Witchaven II
directory if you want EGwhaven to display the original map names, otherwise
it will use the generic fallbacks.

You can toggle autorun mode in-game by hitting backspace and entering
 "AUTORUN".

==============================================================================
   RULES.CFG Reference.
==============================================================================

The format of RULES.CFG is plain text, one setting per line in the form
 <key name> <value>.  Comments are possible by beginning a line with # and
whitespace can be included between keys as desired.  Any settings not adjusted
will typically default to the game's vanilla behavior or something close to it,
even if this means some intended outcomes will continue not to trigger.  The
keys are case-insensitive.
Example:
xp_lev2 666

Valid skill levels are 1 to 4 so if you want to disable an "at or below"
skill setting, set it to 0, and to disable an "at or above" one set it to 5.

Valid experience levels are 1 to 9.


Here is the complete listing of settings that are currently possible:

chest_poison         : 1 if poison traps in chests are allowed, 0 otherwise
                       (default 0)
                       (Devs seem to have intended 1 but it was bugged)
chest_armor          : 1 if armor suits can be found in chests, 0 allows Hero
                       Time only.
                       (default 0)
                       (Devs seem to have intended 1 but it was bugged)
chest_explode        : 1 if explosive traps in chests are allowed, 0 otherwise
                       (default 1)
resist_blocks_traps  : 1 if fire resistance protects against standard
                       projectiles, 0 otherwise.
                       (default 1)
invis_stops_traps    : 1 if invisibility stops wall traps from firing,
                       0 otherwise.
                       (default 0)
onyx_effect          : Effect of Onyx Ring. 0 is no effect, treasure points
                       only. 1 gives immunity to all non-magic projectiles.
                       2 means non-magic projectiles are blocked half the time.
                       (default 0)
                       (Devs' true intent is unclear)
onyx_temporary       : 1 if you lose the Onyx Ring at the end of a level.
                       0 lets you keep it.
                       (default 0)
adamantine_temporary : 1 if you lose the Adamantine Ring at the end of a level.
                       0 lets you keep it.
                       (default 0)
willow_melee         : 1 gives the Willow Wisp a level drain melee attack.
                       0 is no melee.
                       (default WH1 1, WH2 0)
skill_extraweaps     : At or below this skill setting, you start with more
                       weapons (1 through 5).  Otherwise you start with
                       fist/dagger only.
                       (default WH1 1, WH2 4)
skill_noweaponloss   : At or below this skill setting, you will not lose
                       weapons you had when dying.
                       (default WH1 1, WH2 0)
skill_autohealth     : At or below this skill setting, you will automatically
                       drink health potions when about to die.
                       (default WH1 0, WH2 4)
skill_respawn        : At or above this skill setting, monsters respawn.
                       (default 4)
scroll_charges       : Picking up a scroll gives you this many spell charges.
                       (default WH1 1, WH2 5)
boss_level           : (WH1 only) At this level or above, Illwhyrin will act
                       in final boss mode, otherwise she is the retreating
                       Illwhyrin.
                       (default 25)
battle_music         : (WH2 only) 1 allows battle music to play.  0 keeps the
                       level music even during combat.
                       (default 1)
pike_max             : Maximum pike axe ammo for throwing
                       (default 32767, nearly unlimited)
arrow_max            : Maximum bow & arrows ammo
                       (default 100)
xp_lev2              : How much XP is required for XP level 2.
xp_lev3              : How much XP is required for XP level 3.
xp_lev4              : How much XP is required for XP level 4.
xp_lev5              : How much XP is required for XP level 5.
xp_lev6              : How much XP is required for XP level 6.
xp_lev7              : How much XP is required for XP level 7.
xp_lev8              : How much XP is required for XP level 8.
xp_lev9              : How much XP is required for XP level 9.
xp_max               : Maximum XP level attainable, up to 9.
scroll_scare_lev     : Level at which Scare spell becomes usable
scroll_vision_lev    : Level at which Night Vision spell becomes usable
scroll_freeze_lev    : Level at which Freeze spell becomes usable
scroll_arrow_lev     : Level at which Magic Arrow spell becomes usable
scroll_open_lev      : Level at which Open Doors spell becomes usable
scroll_fly_lev       : Level at which Fly spell becomes usable
scroll_fireball_lev  : Level at which Fireball spell becomes usable
scroll_nuke_lev      : Level at which Nuke spell becomes usable
 

==============================================================================
   Compiling / editing 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.)

Open Watcom was once tested as NOT working currently.  Try using Watcom 11
which is available from the same places as Open Watcom.  From what I can
gather, the problem has to do with the precompiled BUILD .OBJ files not being
compatible (they would have to be rebuilt, which will require other changes to
the code.)  Until integration with a rebuilt BUILD can be done, this means
that getting a working compilation system is a bit obtuse: you will need the
old watcom-c-11.0c.exe install from the Open Watcom FTP, plus the missing
DOS4GW files which you can get from a newer Open Watcom install (or use
DOS32A).

Starting with EGWH2 v0.5, I have included a CODE_REFERENCE.TXT document
explaining some of what is going on in the source code and where different
functions can be found.


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

CapsLock was supposed to toggle autorun mode in WH2.  I have never got it to
work reliably so I have removed it in favor of setting autorun via EGSETUP
when configuring the game.  If you MUST adjust it during the game, an option
to toggle it via a backspace cheat "AUTORUN" has been implemented.

Some wall decorations / traps in WH1 maps appear sliced off along line
boundaries.  This appears to be due to a BUILD engine change and occured even
in later official patches of the game.  It may be better to pursue a data fix
than a code fix for these instances.

Hard crashes may happen if the game is not set up correctly before running.
As it appears to be due to incorrect settings I am considering crashes of
this nature to be "not a bug" but I have made an effort to prevent this
from happening by making the game refuse to run if the configs are not
detected.

On slow systems you may notice gameplay issues, particularly in Witchaven 2.
If this becomes an issue, try using 320x200 graphics mode or taking any
possible steps to improve system performance.


==============================================================================
   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.

If you want a more in-depth rundown of some of the bugs and issues that the
games suffered from, check this subpage of my site:
http://ettingrinder.youfailit.net/wh-bugs.html


==============================================================================
   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 / Linux 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 (and even those are improved), the major issues preventing
Witchaven II from being run under DOSBox should be gone.

Most of the modding features added or planned are either things that could be
done with an EXE patch, 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, mostly code and blobs from Les Bird's Witchaven and Witchaven II
snapshots have been used, with a small amount of code from Kenbuild worked in.
The BUILD portions of the game 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 and Witchaven II.  That may change in the future.

The full Witchaven and Witchaven II game data are not included with releases
of EGwhaven.  If you do not have a copy of the game, you are encouraged to
buy disc copies, which are commonly available.  There is a version which
includes both games on one disc, although it is rarer than the separate
releases.

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.
To Adam Biser, for some excellent help in fixing the code.  You rock!
To Corvin of R.T.C.M., for encouragement and testing.
To Corak, for intensive bug hunting.
To BME/ILMBH, for adding EGwhaven support to his frontend, testing and ideas.
To Bloodshedder, for helping to keep my site online, including the EGwhaven
   pages.
And all other Witchaven fans who have sent in their info and encouragement.


==============================================================================
   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 so please send them my way.

      - Play on and slay on,
         ETTiNGRiNDER
         ettingrinder@tutamail.com
         http://ettingrinder.youfailit.net

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