Esp-QuickEditor

[This page is outdated! See instead the wiki page: https://wiki.project-tamriel.com/wiki/Esp-QuickEditor]

DOWNLOAD LINK

 

Introduction

The Esp-QuickEditor is an SQL-based ESP editor/utility made by Worsas, a Lead Developer for Project Tamriel.

Because the program is written in Java, it requires the Java Runtime Environment to be installed, version 8 or later. Having the Java Development Kit (JDK) installed works too.

To open Esp-QuickEditor.jar, double-click the JAR file to have Java automatically execute the file. If that does not work, right-click the JAR file and select "Java(TM) Platform SE binary" from the "Open with..." menu.

When using the editor, make sure to back up any file you want to edit. Unlike TESAME and tes3cmd, changes overwrite the original file without warning.

 

Tables

You can edit ESM, ESP, and ESS files by issuing SQL commands in the upper text area. SQL is a programming language used for handling databases, which consist of one or more tables. Esp-QuickEditor treats an ESP/ESM/ESS file like a database with tables. The following tables are currently available:

  • idObjects — A table containing all objects with an ID that are declared within the file. The only exceptions are cells and dialogue entries.
  • cellObjects — A table containing all instances of objects that are physically placed within the game world
  • dialogueResponses — A table containing all dialogue responses declared in the current file
  • scripts — A table containing all scripts declared in the current file
  • exteriorCells — A table containing all exterior cells declared in the current file
  • interiorCells — A table containing all interior cells declared in the current file
  • masterFiles — A table containing all master files the current file depends on

Below are further convenience/shortcut tables, useful for updating references to certain objects.

  • bodypartReferences — A table containing all references to body parts within armors, clothing, and NPCs
  • classReferences — A table containing all references to classes within NPCs
  • creatureReferences — A table containing all references to NPCs/creatures within leveled lists, soul data, owner data, and sound generators
  • enchantmentReferences — A table containing all references to enchantments within weapons, armor, clothing, and books
  • factionReferences — A table containing all references to factions within NPCs
  • fileReferences — A table containing all filepaths referenced in items, statics, land textures, etc.
  • itemReferences — A table containing all references to items in containers, NPCs, creatures, leveled items, or key data
  • scriptReferences — A table containing all references to scripts in items, activators, etc.
  • soundReferences — A table containing all references to sound entries in regions, doors, lights, and sound generators
  • spellReferences — A table containing all references to spells in NPCs, creatures, or traps

 

Examples

SELECT Tables and Filter by Type or ID

It's always a good idea to issue a SELECT command on a table first to see what it contains and what fields it has:
    SELECT * FROM idObjects;

This can be done likewise with any of the other tables listed above and will show all entries of the selected table within the file.

Now I'd like to only see the NPCs declared in my current file:
    SELECT * FROM idObjects WHERE type = 'npc';

Or I want to see all objects whose IDs starts with _:
    SELECT * FROM idObjects WHERE id = '_%';

 

UPDATE IDs and References

If you want to change the ID of a custom activator in your file from myActivator to myNewActivator, issue the following commands:
    UPDATE idObjects SET id = 'myNewActivator' WHERE id = 'myActivator';
    UPDATE cellObjects SET id = 'myNewActivator' WHERE id = 'myActivator';

The first command updates the ID of the base activator. The second command makes all instances of the activator point to the new activator name.

To change the ID of an NPC from myNpc to myNewNpc in your file, an additional step is required:
    UPDATE idObjects SET id = 'myNewNpc' WHERE id = 'myNpc';
    UPDATE cellObjects SET id = 'myNewNpc' WHERE id = 'myNpc';
    UPDATE creatureReferences SET creature = 'myNewNpc' WHERE creature = 'myNpc';

This third command ensures that any objects owned by this NPC will still belong to them after the update (the creatureReferences table keeps track of these additional references to NPCs or creatures). Likewise, if you have a script, item, sound, or whatever else whose ID you want to change, make sure to make a call that type's respective references table to ensure that these are updated to the new ID.

Another example, this time for misc. items:
    UPDATE idObjects SET id = 'myNewMiscItem' WHERE id = 'myMiscItem';
    UPDATE cellObjects SET id = 'myNewMiscItem' WHERE id = 'myMiscItem';
    UPDATE itemReferences SET item = 'myNewMiscItem' WHERE item = 'myMiscItem';

The last line will update the references in inventories, containers, leveled lists, etc.

 

Dirty Object Cleaning

Sometimes you have an unclean file with accidental changes to vanilla or Tamriel_Data objects. You can remove these dirty edits with Esp-QuickEditor, although it is more common to use TESAME.
    DELETE FROM idObjects WHERE id='furn_bone_01';

This will delete your accidental object entry but will leave the instances of furn_bone_01 within your file unharmed (they are in the cellObjects table).

 

Flora Changes

Assets such as flora may receieve model changes that mess up existing placements. If the repositioning needed to fix each reference is predictable, the process can be automated. For a certain plant flora_floating in your file that's 50 units too high above the ground, use the following command to lower all of its instances:
    UPDATE cellObjects SET zPos = zPos-50 WHERE id = 'flora_floating';

A more complex task is to change the flora composition within a region examplecoast by swapping all of plant1 for plant2. Assume also that each instance of the new plant must be raised 15 units and scaled to 90% in order for the model to fit.
    UPDATE cellObjects SET id = 'plant2', zPos = zPos+15, scale = scale*0.9 WHERE id = 'plant1' AND cellRegion = 'examplecoast';

 

Grass ESPs

Project Tamriel usually keeps its grass objects in a separate ESP. To remove all placed objects in your file except for a certain grass plant grass_01, do the following:
    DELETE FROM cellObjects WHERE
    id <> 'grass_01';

The grass-free file is made with a similar command:
    DELETE FROM cellObjects WHERE
    id = 'grass_01';

You can replace 'grass_01' with 'grass_%' to include any ID beginning with grass_.

 

Region Edits and Dirty Cell Cleaning

Assigning and changing regions in the CS can be a difficult business, particularly when far away from grid coordinates [0,0]. The process is much simpler with this command that uses the exteriorCells table to set the region of [-120,-33] to my region:
    UPDATE exteriorCells SET region = 'my region' WHERE gridX = -120 AND gridY = -33;

In an exterior cell, you are bound to make dirty edits to adjacent cells. For example, if the adjacent cell to the west [-121,-33] is edited but outside the claim borders, you can delete it with the command:
    DELETE FROM exteriorCells WHERE gridX = -121 AND gridY = -33;

This will delete both the objects and the landscape of this cell from your file. (A future version of Esp-QuickEditor may feature a landscape table in case you only want to remove landscape and keep the cell objects.)

You can even use the functions <, >, <=, >=, and <>, instead of = to delete ranges of cells. For example, to delete all cells except for the ones in the exterior claim Thirr Valley 02, run the command:
    DELETE FROM exteriorCells WHERE
    (gridX <1 OR gridX >4 OR gridY >-40 OR gridY <-43) OR
    (gridX =1 AND gridY =-43) OR
    (gridX >=4 AND gridY >=-41);

Claims and sections are typically created with a formula for their particular cells. To make these yourself, think about how an area can be split into rectangles.

Alternatively, you can delete cells by region. The following command deletes cells that aren't in the specified western Cyrodiil regions:
    DELETE from exteriorCells WHERE
    region<>'Gilded Hills Region' AND
    region<>'Gold Coast Region' AND
    region<>'Abecean Sea Region';

Furthermore, you can target cells based on the number of references:
    DELETE FROM exteriorCells WHERE objectCount = 0;

 

Removing ESM Dependencies

To remove a dependency your file has on a master file called unwanted.esm:
    DELETE FROM masterFiles WHERE name = 'unwanted.esm';

Here is a more general command to delete multiple unwanted masters:
    DELETE from masterFiles WHERE
    name<>'Morrowind.esm' AND
    name<>'Tribunal.esm' AND
    name<>'Bloodmoon.esm' AND
    name<>'Tamriel_Data.esm';

 

Miscellaneous Uses

You can use RAND() to target a random portion of objects:
    DELETE FROM cellObjects WHERE cell='ExampleCell' AND RAND() < 0.5

To remove the spell Almsivi Intervention from all of your NPCs:
    DELETE FROM spellReferences WHERE spell = 'almsivi intervention'

To make all interior cells in your file where sleeping is legal (dungeons and caves) 40% darker:
    UPDATE interiorCells SET ambientRed=ambientRed*0.6, ambientGreen=ambientGreen*0.6, ambientBlue=ambientBlue*0.6, sunlightRed=sunlightRed*0.6, sunlightGreen=sunlightGreen*0.6, sunlightBlue=sunlightBlue*0.6 WHERE illegalToSleepHere=0;

 

End Note

It is up to you to figure out the other possible uses of the various references tables.

Note to SQL programmers: You will notice that support for different expressions is quite limited at this point. There are no functions, aliases, subselects, or any other advanced functions available. Only very basic SELECTs, UPDATEs, and DELETEs work. Many tables don't allow deletions on them and there are many columns that cannot be updated. INSERTs are only possible with the cellObjects and masterFiles table at the moment.

This tutorial is edited from Worsas' original post and may receive updates in the future.