TES5Edit Scripting Functions

TES5Edit Scripting

Description

Work in progress: To become the future home of scripting functions for TES5Edit. If you make scripts for TES5Edit please contribute to this page.

TES5Edit implements a script engine based on pascal syntax. The following table enumerates the functions exported by TES5Edit to the script engine that allows interacting with the editor's elements to perform various tasks such as finding records, fixing record conflicts, etc.

The information in the table is not complete so please contribute by explaining these functions, their uses and by fixing mistakes in this information.

TES5Edit Scripting Functions

The types described by this table such as IwbElement, IwbFile, etc.. are internal and not directly accessible but instead the script engine receives a generic type named IInterface which is common to every object type returned by TES5Edit. The reason the internal types are shown in this table is because some functions expect references to specific types even if the object reference is being hold by the generic IInterface variable.

Function	Returns	Arguments	Description
Add	IwbElement	container : IwbContainer, name : string, silent = true : boolean	Implemented for main records etc.
AddElement		container : IwbContainer , element : IwbElement
AdditionalElementCount	integer	container : IwbContainer
AddMasterIfMissing		file : IwbFile , mastername : string	Adds a master to a file by its filename if it isn't already a master for that file
AddMessage		message : string	Adds a message line into the TES5Edit output panel
AddNewFile	IwbFile		Adds a new file and returns its reference
AddRequiredElementMasters	IwbFile	aSourceElement : IwbElement , aTargetFile : IwbFile , aAsNew : boolean	Add the elements master into the target file.
Assigned	boolean	element : IwbElement	Returns true if the element is not nil. Else returns false.
CanContainFormIDs	boolean	element : IwbElement
CanMoveDown	boolean	element : IwbElement	Checks if an element can by moved down a list to a higher index
CanMoveUp	boolean	element : IwbElement	Checks if an element can be moved up a list to a lower index
ChangeFormSignature		record : IwbMainRecord , signature : TwbSignature
Check	boolean	element : IwbElement
ChildGroup	IwbGroupRecord	record : IwbMainRecord
ChildrenOf	IwbMainRecord	group : IwbGroupRecord
CleanMasters		file : IwbFile
CompareExchangeFormID	boolean	mainrecord : IwbMainRecord , oldFormID : Cardinal , aNewFormID : Cardinal
ConflictAllForMainRecord	TConflictThis	record : IwbMainRecord	Gets the ConflictThis argument of the record by calling ConflictLevelForMainRecord (see ctXxxxx enums)
ConflictAllForNode	TConflictThis	node : IwbElement	Gets the ConflictAll argument of the record by calling ConflictLevelForMainRecord (see ctXxxxx enums)
ConflictThisForMainRecord	TConflictThis	record : IwbMainRecord	Gets the ConflictThis argument of the record by calling ConflictLevelForMainRecord (see ctXxxxx enums)
ConflictThisForNode	TConflictThis	node : IwbElement	Gets the ConflictAll argument of the record by calling ConflictLevelForMainRecord (see ctXxxxx enums)
ContainingMainRecord	IwbMainRecord	element : IwbElement
DefType	TwbDefType	element : IInterface	returns the IwbElement::DefType (see dtXxxx enums)
ElementAssign	IwbElement	container : IwbContainer , aInder : integer, [element : IwbElement], aOnlySK : boolean	Adds a new element to the container
ElementByIndex	IwbElement	container : IwbContainer , index : integer	Gets an element in the container by index
ElementByName	IwbElement	container : IwbContainer , name : string	Gets an element in the container by name
ElementByPath	IwbElement	container : IwbContainer , path : string	Gets an element in the container by path
ElementBySignature	IwbElement	container : IwbContainer , signature : string	Gets an element in the container by its signature
ElementCount	integer	container : IwbContainer	Returns the number of elements in a container
ElementExists	boolean	container : IwbContainer , name : string	Checks if the name of the element already exist in the container
ElementType	TwbElementType	element : IwbElement	Returns the ElementType of the element
Equals	boolean	element1 : IwbElement , element2 : IwbElement	Compares both elements by their ElementID
FileByIndex	IwbFile	index : integer	Gets the file at the specified index
FileByLoadOrder	IwbFile	loadorder : integer	Gets the file at the specified load order
FileFormIDtoLoadOrderFormID	cardinal	file : IwbFile , formid : string/cardinal
FindChildGroup	IwbGroupRecord	group : IwbGroupRecord , aType : integer , aMainRecord : IwbMainRecord
FixedFormID	cardinal	aMainRecord : IwbMainRecord
FormID	cardinal	aMainRecord : IwbMainRecord	Obtains the FormID of the record
FullPath	string	element : IwbElement	Gives the full path, all the way down to file, of the input element
GetContainer	IwbContainer	element : IwbElement	Gets the container of the element
GetEditValue	string	element : IwbElement	Gets the element's value represented as text
GetElementEditValues	string	element : IwbElement , name : string	Gets the element's value represented as text
GetElementNativeValues	variant	element : IwbElement , name : string	Gets the element's native value
GetFile	IwbFile	element : IwbElement	Gets the file that defines the element
GetFileName	string	file : IwbFile	Obtains the filename of the plugin file
GetFormVersion	cardinal	mainrecord : IwbMainRecord
GetIsDeleted	boolean	mainrecord : IwbMainRecord	Indicates if the record has been deleted
GetIsESM	boolean	file : IwbFile	Indicates if the plugin is an ESM file
GetIsInitiallyDisabled	boolean	mainrecord : IwbMainRecord
GetIsPersistent	boolean	mainrecord : IwbMainRecord
GetIsVisibleWhenDistant	boolean	mainrecord : IwbMainRecord
GetLoadOrder	cardinal	file : IwbFile	Gets the global load order of the file
GetLoadOrderFormID	cardinal	mainrecord : IwbMainRecord	Obtains the FormID with the current load order applied
GetNativeValue	variant	element : IwbElement	Gets the element's native value
GroupBySignature		file : IwbFile , signature : string	Selects a group in a file by its signature
GroupLabel	cardinal	group : IwbGroupRecord
GroupType	integer	group : IwbGroupRecord
HasGroup	boolean	file : IwbFile , signature : string	Checks if a file has a group by the group's signature
HasMaster	boolean	file : IwbFile , signature : string	Returns true if the file has a master file defined
IndexOf	integer	container : IwbContainer , element : IwbElement	Gets the index of the element inside the collection
InsertElement		container : IwbContainer , position : integer , element : IwbElement	Inserts an existing element inside a collection by position
IsEditable	boolean	element : IwbElement
IsInjected	boolean	element : IwbElement
IsMaster	boolean	record : IwbMainRecord
IsWinningOverride	boolean	record : IwbMainRecord	Checks whether or not the record is the highest override loaded
JumpTo	TConflictThis	record : IwbMainRecord , backward : boolean	Selects the specified record
LastElement	IwbElement	container : IwbContainer	Obtains the last element in the collection
LinksTo	IwbElement	element : IwbElement	Obtains the referenced element
LoadOrderFormIDtoFileFormID	cardinal	file : IwbFile , aFormID : cardinal
MainRecordByEditorID	IwbMainRecord	group : IwbGroupRecord	Does not work for every case because it's inefficient
Master	IInterface	record : IwbMainRecord
MasterByIndex	IInterface	file : IwbFile , index : integer
MasterCount	cardinal	file : IwbFile
MasterOrSelf	IwbMainRecord	record : IwbMainRecord
MoveDown		element : IwbElement	Moves the element down
MoveUp		element : IwbElement	Moves the element up
Name		element : IwbElement	Obtains the name of the element
OverrideByIndex	IwbMainRecord	record : IwbMainRecord , index : integer	Gives the overriding record associated with the provided index
OverrideCount	cardinal	record : IwbMainRecord	Provides a value for the number of overrides there are for a given record
Path	string	element : IwbElement
RecordByEditorID	IwbMainRecord	file : IwbFile , editorid : string
RecordByFormID	IwbMainRecord	file : IwbFile , formid : integer , aAllowInjected : boolean
RecordByIndex	IwbMainRecord	file : IwbFile , index : integer
RecordCount	cardinal	file : IwbFile	Returns a value corresponding to the number of records in a file
ReferencedByCount	cardinal	record : IwbMainRecord
ReferencedByIndex	IwbMainRecord	record : IwbMainRecord , index : integer
Remove		element : IwbElement	Removes an element
RemoveByIndex	IwbElement	container : IwbContainer , index : integer , aMarkModified : boolean
RemoveElement	IwbElement	container : IwbContainer , element : IwbElement
RemoveNode	boolean	node : IwbElement	Removes the node from the file
ResourceCopy		container : IwbContainer , fileName : string , pathOut : string , containerIndex : integer
ResourceCount	cardinal	container : IwbContainer , aFileName : string , containers : TStrings
ResourceExists	boolean	container : IwbContainer , aFileName : string
ResourceList		container : IwbContainer , aContainerName : string , containers : TStrings
ReverseElements		container : IwbContainer	Reverses the order of a list of elements in a container
SetEditValue		element : IwbElement , value : string	Sets the value of the element as string
SetElementEditValues		container : IwbContainer , path : string , value : string	Sets the value as a string of the element by its path
SetElementNativeValues		container : IwbContainer , path : string , value : variant	Sets the native value of the element by its path
SetFormVersion		record : IwbMainRecord , version : integer
SetIsDeleted		record : IwbMainRecord , value : boolean	Enables/disables deleted flag for a record
SetIsESM		file : IwbFile , value : boolean	Enables/disbles ESM flag for a file
SetIsInitiallyDisabled		record : IwbMainRecord , value : boolean
SetIsPersistent		record : IwbMainRecord , value : boolean
SetIsVisibleWhenDistant		record : IwbMainRecord , value : boolean
SetLoadOrderFormID		record : IwbMainRecord , loadOrderFormId : cardinal	Changes the 8-digit hexadecimal Form ID for a record
SetNativeValue		element : IwbElement , value : variant	Sets the native value of the element
ShortName	string	element : IwbElement	Gets the short name of the element
Signature	string	record : IwbMainRecord	Gets the signature of a record
SortKey	string	element : IwbElement, aExtended: boolean
SortMasters		file : IwbFile	Attempts to sort the masters for a file by their load order
wbCopyElementToFile	IwbElement	element : IwbElement , file : IwbFile , aAsNew : boolean , aDeepCopy : boolean
wbCopyElementToRecord	IwbElement	element : IwbElement , aMainRecord : IwbMainRecord , aAsNew : boolean , aDeepCopy : boolean
WinningOverride	IwbMainRecord	record : IwbMainRecord	Will return the winning override record

Script Structure

Base Script Functions

The are three special functions that TES5Edit will call when a script is run:

• Initialize: This function is called when the script starts. It's useful to initialize variables.
• Process: This function is called for every record selected in the TES5Edit tree. If a plugin is selected then it will be called for each record defined in the plugin. The same happens if a record type is selected in the tree.
• Finalize: This function is called when the script has finished processing every record. Generally useful for saving files and freeing the allocated resources.

All these functions are optional, so if they are not needed they can be omitted.

Hotkeys

TES5Edit can assign hotkeys to scripts. The script hotkey is defined in the description like this:

{
	Script description.
	------------------------
	Hotkey: Ctrl+Alt+Shift+E
}

Script References

Scripts can use functions defined in other scripts. That allows creating toolkits to avoid duplicating code. To make use of this feature the following instruction is used: (use below the unit name)

uses 'MyTools';

With that command we instruct the script to load another script named "MyTools.pas" and the functions in that script will be available. Note that any conflict in names can be resolved by the unit name. So it's suggested to change the toolkit script unit name appropriately.

Script User Interface

TO DO: Explain user interface and provide some examples.

Simple Script Sample

This is a sample script which will only export every selected NPC to a CSV file:

{
	Script description: Exports the FormID and EditorID of the selected NPCs
}

// This is the unit name that will contain all the script functions
unit ExportScripts;

// Global variables
var NPCList : TStringList;

// Called when the script starts
function Initialize : integer;
begin
	NPCList := TStringList.Create;
	NPCList.Add('FormID;EditorID');
end;

// Called for each selected record in the TES5Edit tree
// If an entire plugin is selected then all records in the plugin will be processed
function Process(e : IInterface) : integer;
begin
	if Signature(e) <> 'NPC_' then exit;
	NPCList.Add(IntToHex(FixedFormID(e), 8) + ';' + GetElementEditValues(e, 'EDID'));
end;

// Called after the script has finished processing every record
function Finalize : integer;
var filename : string;
begin
	filename := ProgramPath + 'Edit Scripts\NPCs.csv';
	AddMessage('Saving NPC list to ' + filename);
	NPCList.SaveToFile(filename);
	NPCList.Free;
end;

end.