TES3cmd

From Morrowind Modding Wiki
Jump to: navigation, search

tes3cmd is a command-line tool written by john.moonsugar. tes3cmd is used for examining and modifying TES3 plugins in various ways. It can also create a patch for various problems and merge leveled lists. It is written in Perl and runs natively on Windows or Linux.

Download tes3cmd

You can download tes3cmd from its Github page. Old versions can be found in the Google code's mlox project download page.

As of version 0.37, tes3cmd comes in standalone executable (.exe) form. But you can also use the plain script form, which requires you to install Perl.

Installing and running tes3cmd

The easiest way to install tes3cmd is just to put tes3cmd.exe into your "Data Files" folder.

You can install it elsewhere and then modify your computer's environment variables for this new location but other tools which rely on tes3cmd, such as abot's MMOG, expect tes3cmd to be located in your "Data Files" folder.

Features

tes3cmd's full feature list is detailed on the mlox wiki, in summary:

  • Add/Remove/List Plugins in your load order
  • Clean plugins of Evil GMSTs, junk cells, and more
  • Find record IDs common between two plugins
  • Delete records/subrecords/object instances from plugin
  • Report differences between two plugins
  • Dump records as text for easy study
  • Convert plugin (esp) to master (esm)
  • Convert master (esm) to plugin (esp)
  • Read/Write plugin Author/Description, update plugin masters
  • Powerful batch record modification via user code extensions
  • Patches problems, merges leveled lists, etc.
  • Identify overlapping dialog (a source of missing topic bugs)
  • Recover usable records from plugin with 'bad form' errors
  • Reset dates of Bethesda Data Files to original settings

The following are those features most of interest to mod users:

Clean plugins

The clean command removes various junk entries from plugins:

  • The clean command will clean objects in the plugin that match objects in any of its masters.
  • The subrecords for AMBI (ambient lighting) and WHGT (water height) for interior cells are often duplicated from the master of a plugin when the plugin is saved in the Construction Set.
  • Object definitions for various record types defined in a master are sometimes unnecessarily duplicated in dependent plugins.
  • Evil GMSTs, that is GMSTs (Game Settings) from the list of 11 Tribunal GMSTs or 61 Bloodmoon GMSTs that are inadvertently introduced to a plugin by the Construction Set with specific values.
  • Junk cells are bogus external CELL records that crop up in many plugins due to a Construction Set bug.

The goal of the "clean" command is that it should always be safe to use it with no options to get the default cleaning behavior.

Using a batch file to clean plugins

If you are uncomfortable using command-line utilities like tes3cmd you can create create a batch file for cleaning.

Copy and paste this text into Notepad:

@ECHO OFF
:START
CLS
REM ***************************************************************************************
REM *****       "Drag-and-Droppable" TES3CMD Cleaning Batch / CMD File                *****
REM *****        by: RMWChaos                                                         *****
REM *****        original concept by: Pinkertonius                                    *****
REM *****        modified by Spirithawke ver. 2013.03.29                              *****
REM ***************************************************************************************
REM *
REM *   TO SETUP ...
REM *
REM *           1. Download TES3CMD v0.37u from:
REM *                   http://mlox.googlecode.com/files/tes3cmd-0.37u-2012.12.10.7z
REM *
REM *           2. Unzip TES3CMD to your "\Morrowind\Data Files" directory
REM *
REM *           3. Create a new "Tes3cmd clean fancy2.txt" file in the same directory
REM *
REM *           4. Copy the entire contents of this code into the text file and save it
REM *
REM *           5. Rename the text file with a ".bat" or ".cmd" extension (either works)
REM *
REM *           6. *OPTIONAL* Create a SHORTCUT to the batch file on your desktop
REM *
REM *********************************************************************************
REM *
REM *   The cleaned plugin will take the place of the old 'dirty' plugin and the old
REM *           plugin will be backed up to "\Data Files\tes3cmd\backups" by default.
REM *
REM *   A log file called "<plugin.name>-cleaned.log" will also be created in Data Files
REM *
REM *********************************************************************************
REM *
REM *   Tribunal.esm and Bloodmoon.esm will use a different cleaning method so as not
REM *           to remove required GMSTs, and tes3cmd may ignore (not clean) other mods
REM *            based on its own internal code.
REM *
REM *********************************************************************************
REM *
REM *********************************************************************************
REM *****                       MOD CLEANING STEPS                              *****
REM *********************************************************************************
REM *
REM *   First, make sure the mod master dependencies are already located in the
REM *           "\Data Files" folder, or THE MOD WILL NOT BE CLEANED !!
REM *
REM *   TO RUN ...
REM *           Drag ESP/M files onto the shortcut, .bat, or .cmd file to clean mods.
REM *
REM *   CLEANING ORDER ...
REM *           1. Official masters (i.e. Tribunal.esm and Bloodmoon.esm)
REM *           2. Mod masters (e.g. GIANTS.esm, etc.)
REM *           3. Mod plugins that are a Master to another Plugin
REM *           4. Mod plugins relying on Official Masters, Mod Masters, or Plugin Masters
REM *           5. All other plugins without master dependencies
REM *
REM *   DO NOT CLEAN MOD "CONTROL FILES" ...
REM *           Files such as "GIANTS Ultimate Control File.esp" intentionally contain
REM *           records duplicated from their mod master, and should not be cleaned.
REM *
REM *********************************************************************************
REM *
REM *********************************************************************************
REM *****       CHECK for OFFICIAL ESMs, INITIATE LOG, CLEAN, and SYNC          *****
REM *********************************************************************************
REM *
REM *   Set initial environment variables ...
SET MOD="%~nx1"
SET TMP=".%~nx1"
SET BAK="%cd%\tes3cmd\backups\.%~nx1"
SET DBL="%cd%\tes3cmd\backups\%~n1~*%~x1"
SET LOG="%cd%\%~nx1-cleaned.log"

REM *   Check for Morrowind.esm (cannot clean) ...
IF %MOD%=="Morrowind.esm" (
       ECHO You cannot clean %MOD%.
       PAUSE
       GOTO END
)

REM *   Initiate log file ...
ECHO Cleaning of %MOD% initiated on %DATE% at %TIME% > %LOG%
@ECHO: >> %LOG%

REM *   Append original mod header contents to log file ...
ECHO Pre-clean / pre-sync mod header contents . . . >> %LOG%
tes3cmd dump --type TES3 %MOD% >> %LOG%
@ECHO: >> %LOG%

REM *   Notify user that cleaning has begun ...
ECHO Cleaning of %MOD% has begun . . .
@ECHO:
ECHO You may not see activity for some
ECHO  time, especially on larger mods . . .
@ECHO:
@ECHO:

REM *   If file is NOT Tribunal or Bloodmoon ...
IF NOT %MOD%=="Tribunal.esm" (
       IF NOT %MOD%=="Bloodmoon.esm" (
               tes3cmd clean --hide-backups --replace %MOD% >> %LOG% 2>&1
               GOTO SYNC
       )
)

REM *   If mod IS Tribunal or Bloodmoon ...
ECHO "EVIL GMSTs" will not be cleaned . . . >> %LOG%
@ECHO: >> %LOG%

REM *   Temporarily rename mod to bypass tes3cmd no-clean behavior ...
REN %MOD% %TMP%
tes3cmd clean --hide-backups --replace --instances --cell-params --dups --junk-cells %TMP% >> %LOG% 2>&1

REM *   Rename mod and backup back to original name ...
REN %TMP% %MOD%
REN %BAK% %MOD%

:SYNC
@ECHO: >> %LOG%
@ECHO: >> %LOG%

REM *   Synchronize mod header ...
ECHO Syncrhonizing mod - update masters and header . . . >> %LOG%
@ECHO: >> %LOG%
tes3cmd header --hide-backups --synchronize %MOD% >> %LOG% 2>&1
@ECHO: >> %LOG%
ECHO Synchronizing complete. >> %LOG%
@ECHO: >> %LOG%

REM *   Append mod header description ...
rem ECHO Update header description . . . >> %LOG%
rem tes3cmd header --hide-backups --description "+ Cleaned by tes3cmd on %DATE% at %TIME%." %MOD% >> %LOG% 2>&1
rem @ECHO: >> %LOG%

REM *   Delete extra backups created during synchronization ...
IF EXIST %DBL% DEL %DBL%

REM *********************************************************************************
REM *****       TIMESTAMP LOG, OUTPUT LOG, and DISPLAY LOG LOCATION             *****
REM *********************************************************************************
:DISP

REM *   Append cleaned & updated mod header contents to end of log ...
rem ECHO Post-clean / post-sync mod header contents . . . >> %LOG%
rem tes3cmd dump --type TES3 %MOD% >> %LOG% 2>&1
rem @ECHO: >> %LOG%

REM *   Timestamp the log file with completeion date and time ...
ECHO Cleaning finished %MOD% on %DATE% at %TIME% >> %LOG%

REM *   Output log file to console ...
TYPE %LOG%
@ECHO:

REM *   Display location of log file and wait for user input to close CMD window ...
ECHO The log file for this cleaning process was stored here:
@ECHO:
ECHO %LOG%
PAUSE

REM *********************************************************************************
REM *****               End of batch commands, exit CMD window.                 *****
REM *********************************************************************************
:END

Save as tes3cmd_clean.bat where ever you installed tes3cmd.exe. Next find tes3cmd_clean.bat, right click it and select Send To > Desktop (create shortcut).

Now you can drag an esp from any folder onto your desktop shortcut and tes3cmd will clean the plugin and replace the original. tes3cmd will create a log file showing what the cleaning command did, the log file's named after the plugin that's been cleaned. So if you dragged and dropped foo.esp onto the shortcut then the log file will be called "foo-cleaned.log". The log file is stored in the same folder as the plugin.

Multipatch

The multipatch command produces a patch file based on your current load order to solve various problems. The tes3cmd created multipatch plugin:

  • Ensures renamed cells are not accidentally reverted to their original name.
  • Fixes all fogbugged cells in your active plugins by setting the fog density of those cells to a non-zero value.
  • Ensures that known summoned creatures are flagged as persistent. There is a bug in Morrowind that can cause the game to crash if you leave a cell where an NPC has summoned a creature.
  • Merges leveled lists used in your active plugins.

Using a batch file to create a multipatch plugin

If you are uncomfortable using command-line utilities like tes3cmd you can create a batch file to generate a multipatch plugin.

Copy and paste this text into Notepad:

@echo off
REM batch file to create a multipatch plugin using tes3cmd
REM put shortcut on desktop and double-click it to create multipatch

tes3cmd multipatch > multipatch.log
TYPE multipatch.log
PAUSE

Save as tes3cmd_multipatch.bat where ever you installed tes3cmd.exe. Next find tes3cmd_multipatch.bat, right click it and select Send To > Desktop (create shortcut).

Now simply double-click the shortcut on your desktop to create a multipatch plugin.

Reset dates

Resets the dates of the Bethesda masters (.esm) and archives (.bsa) to their original settings.

This may help those people who have problems with textures and meshes being overridden by the vanilla resources, as can happen with the Steam version of Morrowind.