Welcome to the documentation for ESPER, a command line utility to merge plugins
and records for Bethesda Softworks' Morrowind.

The latest version is available at:


A discussion thread is at:


It is best to discuss bugs and glitches there.

Esper successfully parses Morrowind.esm and the two addon esm's, and all the
plugin files I've tried. It also writes Morrowind.esm to, and reads it from,
ESTXT format. I have started a new game using the plugin produced by merging
250 mods, and it appears to work.

Esper can also read and write files in a format called "ESTXT". This is a
plain-text file containing lisp expressions, one for each record, slightly
simplified to be more readable. If you specify an output file whose name ends
in ".estxt" output will be in this format rather than binary.  Similarly if any
of the input filenames end in .estxt, they will be treated as these text files.


Esper can be used from any directory, but it's easiest to put it in your "Data
Files" directory.

It is a COMMAND LINE utility -- you need to open a command prompt (C:\>
prompt), use "cd" to change to the directory where esper.exe is located,
then type the name of the program followed by any options you want to use.



Options that specify an ACTION
(only one allowed at a time)

--help, -h
	Show help
--merge-plugins, -p
	Mode = merge plugins
--merge-records, -r
	Mode = merge records from plugins
--list-active, -l
	Mode = list active plugins and masters in Morrowind.ini

	Scans plugins/masters and looks for all resource files that they depend
        on (icons, textures, meshes etc). Then checks to see if those resource
        files exist, either on HD or in any of the active BSA files.
        After scanning has finished, prints a list of all files that could
        not be found.
        Follows similar logic to merge-records, but instead of actually
        merging anything, prints a list naming all records which are modified
        by > 1 plugin in the file list, along with details about which
        files are implicated.

	Scan the three Bethesda master files, Morrowind.esm, Tribunal.esm and
        Bloodmoon.esm, and write information about the records they contain to
        the file "esper.cache" in the current directory.
        (this file is used by the --use-cache option; see below)
Options that modify esper's behaviour
(any combination of these can be used)

--output <file>, -o <file>
	Save output to <filename>. By default this is named according to the
        action you are performing:

          Merge plugins:      esper_merged_plugins.esp
          Merge records:      esper_merged_records.esp
          Anything else:      esper_output.esp

--mwdir <dir>, -d <dir>
	"Base" Morrowind directory (where Morrowind.ini and Morrowind.exe
        live) is <dir> (default is the *parent* directory of the current
--all, -a
	Use *ALL* active plugins when merging (!)

--batchfile <file>, -B <file>
        <File> is a text file containing one filename per line. Esper will use
        all the files named in <file> as if they were specified on the command line.

	(only affects the --merge-records action)
        Instead of scanning the three main Bethesda master files, uses the file
        "esper.cache" (which must be created using the --build-cache option)
        to quickly locate records within those files. This should speed up
        record merging.
	By default, if a record is marked as 'deleted' by any plugin
        (i.e. contains a subrecord called "DELE"), then the record will still
	be included in esper's output, with the DELE subrecord still in place.
        Morrowind should ignore records containing the DELE subrecord.
        However, if you want to scrub deleted records from output, specify the
        '--nuke' option, and esper will omit any such records when writing

        A problem that seems to occur with several 'record-merging' programs
        (principally TESTool, but also reported with esper) is that merging
        makes a few NPCs have zero hit points. Those NPCs drop dead as soon as
        you enter their cell. The cause is uncertain but one hypothesis is that
        the problem is caused by the fact that NPC hit points are *not stored*
        for some NPCs. Presumably Morrowind 'autocalculates' their HP somehow
        if they enter combat. However the merging process seems to break these

        The =zero-hp-fix= option detects NPCs who have no stored hit points,
        and assigns them a 'standard' set of hit points and other
        attributes. It is experimental; don't use it unless you have the

--verbose, -v
        Prints out lots of messages about what is going on as esper goes
        through its motions.
        By default, esper exits to the operating system when an error occurs.
        If you specify this option, esper will instead enter the lisp

Examples of usage:

(with esper.exe in your "Morrowind/Data Files" directory)

See usage information with:


List all active plugins in order of loading with:

	esper -l 

Merge plugin1 and plugin2.esp into `output.esp': (this works like the TES
construction set facility of the same name). Produce lots of messages telling
the user what esper is doing.

	esper -p plugin1.esp plugin2.esp --verbose

Merge RECORDS (objects, NPCS, etc) from plugin1 and plugin2 into merged-objects.esp:

	esper -r plugin1.esp plugin2.esp -o merged-objects.esp

Merge records from all the plugins named in "tomerge.txt" (one per line):

	esper -b tomerge.txt -r
Merge records from ALL active plugins into an ESTXT file:

	esper -a -r -o bigmerge.estxt

Check to see if any resources needed by Bloodmoon.esm are missing:

	esper -c Bloodmoon.esm

Check to see whether plugin1.esp and plugin2.esp modify any of the same

        esper --find-conflicts plugin1.esp plugin2.esp

Using the file description to communicate with Esper

Each ESP and ESM file has a description string up to 255 characters long.
You can view and modify this in Wrye Mash, or in the Construction Set.

Esper understands the special code {{ESPER:<tags>}} in file descriptions,
where <tags> is one or more record types. The whole thing is case-
insensitive. For example:


Currently this only has meaning when you are running 'merge records', where
it tells esper which record types to merge in the given file (in the above
example, only clothing and armour).

Esper also understands the special word:


When esper is merging records and encounters a file whose description
contains this, it will skip to the next file without merging any records.


Plugin/master filenames must be listed AFTER any command line options.
For example:

	esper plugin1.esp plugin2.esp -r -o foo.esp      (wrong)
        esper -r -o foo.esp plugin1.esp plugin2.esp      (right)

As with all command-line applications, any filenames that have spaces
or unusual characters in their name, need to be surrounded in quotes:

	esper -p "Clean Glass.esp" "Cloak Collection.esp"

Wildcards do *NOT* currently work.

"PGRD" records are not parsed at all, simply treated as binary "blobs".

Note that the utility does not currently merge levelled lists.

Esper has problems finding files in strictly case-sensitive file systems.
For this reason, 'check resources' does not work properly in Unix/Linux.

When merging RECORDS, if any plugin deletes a particular record, there is no
way for plugins later in the merge to undelete it. However the 'deleted' record
will still be merged correctly and included in the output plugin (unless you
specify the --nuke option). If you want to clear the merged record's deleted
status you will need to do this one of 2 ways:

1. manually in the Construction Set.
2. manually at the lisp command prompt eg:
      (read-records-from-plugin "foo.esp")
      (setf deleted (find-records-with-subrecord "DELE"))
      (undelete-record (nth 5 deleted))   ; numbering starts at 0
      (write-records-to-plugin "foo.esp")


    Esper is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    Esper is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with Esper.  If not, see <http://www.gnu.org/licenses/>.