Dark Engine Motion Database Patcher (MDBReplace) Version 1.0
Sunday, January 11, 2004 - Tuesday 15th June, 2004
by Philip M. Anderson (Weyoun)

----------------------------------------------
Licence Agreement:
----------------------------------------------

'MDBReplace' is released as freeware, under the following conditions:

  1. Neither this software, nor its output, is to be used in any way to illegally modify
     software.

  2. Neither this software, nor its output, is to be used in any way, in whole, or in part, for
     profit or financial gain.

  3. Neither this software, nor its output, is to be used in any commercial way whatsoever.

  4. Any output created with this program which is only a modification of existing copyright
     material (as opposed to purely original output), is still copyrighted to the originator
     of the modified material.

Anyone using this software is considered to have accepted this agreement.

----------------------------------------------
Disclaimer:
----------------------------------------------

Any user of this software acknowledges that this software is distributed on an "as is" basis.  No
guarantee or warranty, either express or implied, is given in respect of this software's
stability, reliability, or safety of use.  Although the author is confident that there is no
harmful code present in the software, the author takes no responsibility for any damage or loss
of any kind arising as a direct or indirect result of the use of this software.  Use of this
software is entirely at the risk of the user.

All downloaded software should always be checked using a virus checker before use.  The author
has made every possible effort to ensure that this software is free of viruses, but takes no
responsibility for any harm caused by viruses which may still be present within.

----------------------------------------------
Introduction:
----------------------------------------------

OK.  Now that the nasty stuff is out of the way, let's get down to business!

The Dark Engine, as designed by Looking Glass Studios, animates AI characters using motion data
stored in three types of file.  The most complex of these files is the motion database, which
acts as a sophisticated index of all motions available to the game in question.  This software is
intended as a complement to Shadowspawn's impressive Motion Database Editor.  Shadowspawn's
creation is ideal for the creation of whole new motion database files (as required when new
creatures are designed.  MDBReplace is intended for much smaller-scale modifications to the
motion database, and is most useful when partnered with the Motion Editor.

----------------------------------------------
Motions, and the Dark Engine:
----------------------------------------------

As previously mentioned, the Dark Engine uses three types of file for motions:

- '.mc' (motion control) files:
     contain the actual motion data (angles for rotations of joints in an AI mesh).  These .mc
     files can be modified with the Motion Editor.

- '.mi' (motion information) files:
     contain additional information about the motion, for example capture/playback frame rate,
     number of frames etc.  .mi files can be partially edited with the motion editor integrated
     into DromEd, or more fully using the Motion Editor.

- 'motiondb.bin' (motion database) files:
     contain an index of all available motions.  Motions cannot be used by the Dark Engine if
     they are not listed in the motion database.  Motion database files can be created/edited
     using Shadowspawn's Motion Database Editor.

Unusually, '.mi' files are generally ignored by the Dark Engine.  The data contained in these
files is actually mirrored within the motion database, and this is where the engine looks to
obtain the required information.  So placing a motion control ('.mc') file in the MOTIONS/ folder
will override its namesake in MOTIONS.CRF.  However, even if present, the corresponding motion
information ('.mi') file will be totally ignored.  This will of course cause problems if there
has been a change to the data in the '.mi' file (for example the addition of extra frames in the
motion).  In this case, Thief or System Shock II will still look to the (unmodified) motion
database for the frame count, and upon playback the motion will be cut short.

This program is designed to get around this problem by patching the motion database to update the
'.mi' entry within to match the user's edited version.

----------------------------------------------
Using MDBReplace:
----------------------------------------------

In order to use MDBReplace, the user must have the '.mi' file(s) for any motion he/she has
edited/downloaded.

Upon running MDBReplace, only the FILE menu will be accessible.  The first thing to do is to
select the motion database file that needs to be patched, by using 'FILE/OPEN MOTION DATABASE'.
Once the program reads the motion database file, the other two main controls will become active.
The next stage is to select the motion you wish to modify, using the drop-down menu bar.  Once
done, the final stage is to click on the 'Replace!' button.  The user will then be prompted to
select the modified '.mi' file, which will be patched into the motion database.  The patched
database will be written to a file called 'motiondb.bin_new' to preserve your original motion
database, BUT DON'T RELY ON THIS!  ALWAYS MAKE BACKUPS OF ANY FILES YOU FEEL MAY BE AT RISK!
Once the patch is completed the program will automatically quit.  The new file should obviously
be renamed to 'motiondb.bin' and placed in your Thief/SS2 folder, overwriting the original (you
did make a backup, didn't you?)

Now the restriction on motion parameters (most notably length) has been lifted.  You can now
replace a three-frame motion with a three thousand-frame one successfully using MDBReplace!

----------------------------------------------
Acknowledgements:
----------------------------------------------

Thanks to the following people who have contributed to this project:

Shadowspawn:
   Master (1) of the motion database, Shadowspawn figured out how to read the data contained in
   .mi files (which are identical in format to the fourth data block stored in 'motiondb.bin',
   the key to this program), as well as relentlessly (and successfully) working towards a
   complete file-format specification for the motion database.

Zygoptera:
   Master (2) of the motion database, Zygoptera discovered which section of the .mi file relates
   to the number of frames in a motion, as well as making some important breakthroughs on the
   motion database.

Everyone at www.ttlg.com/forums:
   Thanks for being such an enthusiastic fan-community for Thief/System Shock.  I would never
   have gotten this far without you!

----------------------------------------------
Version History:
----------------------------------------------

Version 1.0 - Completed 16/6/2004.
   First functional version.  Initial release.

----------------------------------------------
Contacting the Author:
----------------------------------------------

You can contact me to report bugs / make enquiries / tell jokes / whatever in the following ways:

email               - p.m.anderson@durham.ac.uk (but not for much longer!)
www.ttlg.com/forums - I am a member of TTLG's Editors' Guild, and I post under the name 'Weyoun'.
