Tes3cmd

From Project Tamriel Wiki
Jump to navigation Jump to search

tes3cmd is a command-line tool written in Perl that is used for editing, inspecting and cleaning mods.

You can download the latest version 0.40 (pre-release alpha) on GitHub.

The below page is a quick guide and overview of common use-cases in Project Tamriel and Tamriel Rebuilt. For a much more detailed guide, check the official documentation or the inbuilt help (the command tes3cmd help).

Note: If you specifically wish to use the tes3cmd modify command (see below), you will want to download the older version 0.37v from SourceForge. See also the documentation for 0.37v and the changelog for differences with 0.40.

General Guidelines

Getting Started on Windows

Put the file tes3cmd.exe into your Data Files folder.

  • To use the command line, Shift + right click on empty space in the folder and select "Open command window here". Type the line you want to use in the command window and enter.
  • To use with batch files (so you don't have to type each line by hand), create an empty .txt file (right click, click New > Text document), then copy or type the command lines into the file. Save and rename the file extension to .bat instead of .txt. Double click the .bat file in the folder to run the command. It is a good idea to add "pause" on the last line of the .bat file so the command window won't close itself and you can read output messages.
    • Note: There is a 8191 characters limit for the command in modern Windows, and the same limit applies to batch files.

Getting Started on Linux or MacOS

  1. Extract the tes3cmd executable file somewhere that is accessible from the command line – i.e., somewhere on your PATH.
  2. Open the terminal and change the working directory to your Morrowind Data Files folder (use the cd command).
  3. Use whichever tes3cmd command you wish by entering it in the prompt and pressing Enter. For example, enter tes3cmd help to see the possibilities.
  4. To make batch commands, you can write a simple shell script.

A Note on Special Characters

The characters [\^$.|?*+() are special characters for regular expressions, used by many of tes3cmd's optional parameters like --match. You can use regular expressions to your advantage for powerful filtering, but you also need to escape special characters with a backslash (\) when you're looking for the character itself: for example a period stands for any character unless you write it as "\.". Parentheses also need to be escaped with backslash: "\(".

In Windows there are also special characters in command line or .bat files. This shouldn't usually be a problem, but for example you will need to double the percentage sign (%) if you use the --format option for dumps.

Common Use Cases

Below are examples of are commands used for a few common tasks.

The code blocks show you what you need to enter on the command line. In all cases below, you need to replace the MyPlugin.esp or equivalent with the name of your own file.

Cleaning

tes3cmd clean MyPlugin.esp

Safe to use for Tamriel Rebuilt and Project Tamriel claims (and most mods). The original file is not modified. The clean file has the same filename with "Clean" in front of it.

This line will remove all dirty objects that are in your plugin but aren't different from objects in its masters. Will clean dirty objects from Morrowind.ESM, Tribunal.ESM, Bloodmoon.ESM. Will clean objects dirtied from Tamriel Rebuilt or Project Tamriel if your plugin has a main project .ESM file (e.g., TR_Mainland.ESM) as a master file.

Will NOT clean most dirty dialogue, because dialogue lines get different data when you add lines next to them. See the TESAME tutorial for more details.

Will NOT clean junk cells that are not from a master file (.ESM). To find empty cells, you can use tes3cmd dump --exterior --no-match "FRMR" MyPlugin.esp > MyPluginEmptyCells.txt

Dumping

See the official documentation for examples. For instance, to dump all dialogue from Tamriel Rebuilt into a text file:

tes3cmd dump --type DIAL --type INFO TR_Mainland.esm > TR_Mainland_DialogueDump.txt 

Exporting

You can use this command to export into a plugin (.ESP file) instead of a .txt file. Take care that the NEW file is the one in the argument --raw-with-header, it comes first in the line. If you put the file names in the wrong order, you will turn your plugin into an empty file with no backups!

tes3cmd dump --type DIAL --type INFO --raw-with-header "TR_Mainland_Dialogue.esp" TR_Mainland.esm

Most data types can be exported directly except dialogue and cells:

  • Dialogue always needs DIAL (topic or journal ID) and INFO (dialogue entries) to be exported together and in the original order. To export filtered dialogue in bulk, first export all dialogue without any filters, then "delete" the unwanted parts with filters. To export specific dialogue, filter for the exact IDs of both INFO and DIAL; the ID of a topic is the topic name.
  • Interior cells need both their CELL and PGRD (if there is a pathgrid). Exterior cells need their CELL, LAND, PGRD, and all LTEX records. To export filtered cells in bulk, first export all CELL, LAND, PGRD, LTEX types, then delete the CELL, LAND, PGRD (but not LTEX) records that you do not want.

Modifying

WARNING: Always back up your files before using this function or the delete function. Do not use it on the vanilla .ESM files. Do not use it on the main province .ESM files (e.g., TR_Mainland.ESM) or Tamriel_Data.ESM, if you don't know what you're doing. Always use proper filters. Any scripts modified with this function need to be recompiled in the CS.

The modify command does not work in the latest alpha version. To use modify, download 0.37v, rename its .exe file to "tes3cmd037.exe" and put it in your Data Files folder (on Windows; for Linux or MacOS, you can rename the tes3cmd executable file to tes3cmd037 and place it somewhere on your PATH). Then when you want to use a modify line, for instance to add spaces around all uses of "--" in dialogue in the file, use tes3cmd037 instead of tes3cmd:

tes3cmd037 modify --type INFO --replace "/--/ -- /" MyPlugin.esp 

Note that in this example any IDs for speakers or conditions in dialogue would be modified too if they included "--". To be perfectly safe you should add another filter: --sub-match "Response:" so that only the text field is modified. When increasing the character count of IDs or dialogue in bulk, use dumps and a text editor to make sure limits aren't exceeded: 512 characters for dialogue text, 24 characters for NPC, creature or container IDs, 31 characters for scripts, 32 characters for other IDs.

Batch Script Examples

WARNING: .bat files are as dangerous as .exe files! Do not double click on a .bat file from an unknown source unless you have opened it in a text editor and can verify its contents.