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

To play:
- Install and set up Witchaven (2), if you haven't already.
- Put the EXE files into your Witchaven directories. EGWH1 is for the
     original game and EGWH2 is for Witchaven II.  For Witchaven II, place the
	 MAPNAMES.CFG in your game directory as well.
- In a DOS session (DOSBox, old PC, etc.), use EGSETUP.EXE to configure the
     games.  The same utility produces configurations suitable for both
	 versions.  (The original Witchave (2) setup utilities are still
         required for sound setup.)
- In the DOS session, run EGWH1 for Witchaven or EGWH2 for Witchaven II.
- Enjoy your bugfixed Witchaven experience.

==============================================================================
   What's new in EGWH1 v1.0
==============================================================================

- RULES.CFG customizable behaviors
- GAME parameter correctly maintains separate savegame sets for each game dir.
- Mouse movement and mouselook fixes/improvements.
- Monsters no longer get locked in insane repeat-teleporting loops.
- Keys to cycle through potions can be remapped.
- Better framerate fixes.
- Witchaven II autorun feature backported.
- Witchaven II shield toggle feature backported.
- 3-button mouse functionality restored.
- Loose daggers placed in the map are properly collectable now.

==============================================================================
   What's new in EGWH2 v1.0
==============================================================================

- RULES.CFG customizable behaviors
- GAME parameter correctly maintains separate savegame sets for each game dir.
- Mouse movement and mouselook fixes/improvements.
- Monsters no longer get locked in insane repeat-teleporting loops.
- Keys to cycle through potions can be remapped.
- Better framerate fixes.
- Level titles were made external and customizable.
- Fix to an error which caused intermission screen issues if WARP was used.
- Fixed a regression in EGWH2 versions 0.5 through 0.7 that crashed the game
   if too many sounds played at once.
- Level numbers greater than 15 can play background music.
- Fixes to end-of-level scoring to make it more accurate, especially on small
   levels with few items/enemies.
- Argothonian Clansman hit detection fix.  No more missing them when they're
   in mid-swing of the sword.

==============================================================================
   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 like with # and
whitespace can be included between keys as desired.  Any settings not adjusted
will 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_lev1 666

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)
chest_armor          : 1 if armor suits can be found in chests, 0 allows Hero
                       Time only.
				       (default 0)
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)
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)
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.
eg_xp_max            : Maximum XP level attainable, up to 9.
 

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


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

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