Difference between revisions of "TES5Edit Scripting Functions"

From the CreationKit Wiki
Jump to navigation Jump to search
imported>DavidJCobb
imported>DavidJCobb
(→‎Pascal implementation: more information on the class "support")
Line 442: Line 442:
* TES5Edit's Pascal implementation does not support <code>&</code> as a prefix for suppressing keyword parsing (e.g. <code>&For</code> to refer to a variable named "For").
* TES5Edit's Pascal implementation does not support <code>&</code> as a prefix for suppressing keyword parsing (e.g. <code>&For</code> to refer to a variable named "For").
* TES5Edit's Pascal implementation does not appear to support the <code>^</code> operator.
* TES5Edit's Pascal implementation does not appear to support the <code>^</code> operator.
* TES5Edit's Pascal implementation either does not support classes, or does not support the "constructor" keyword.
* TES5Edit's Pascal implementation has exceptionally poor support for defined classes and subclasses:
** The <code>constructor</code> keyword is not supported.
** Subclasses without a constructor don't trip up the parser, but attempting to instantiate them (e.g. <code>MyClass.Create</code>) causes TES5Edit to choke on the classname, which it sees as an undefined identifier. At this time, it's not known whether custom classes can actually be ''used'' in an xEdit script.
** One can safely assume, then, that the classes and functionality available to one is limited by both the Delphi version (presently unknown) and the JVCL version (presently unknown) that TES5Edit uses.
** One can safely assume, then, that the classes and functionality available to one is limited by both the Delphi version (presently unknown) and the JVCL version (presently unknown) that TES5Edit uses.
* TES5Edit's Pascal implementation does not appear to support the <code>is</code> or <code>as</code> keywords. However, <code>TObject</code> and its subclasses offer a <code>ClassName</code> method.
* TES5Edit's Pascal implementation does not appear to support the <code>is</code> or <code>as</code> keywords. However, <code>TObject</code> and its subclasses offer a <code>ClassName</code> method.

Revision as of 19:34, 10 July 2016


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 Global Variables

These are predefined read-only variables that can be called at any time.

Name Type Description Note
DataPath String Provides the file path to Skyrim's data folder as a String
ProgramPath String Provides the file path to Tes5edit's installation folder as a String
ScriptsPath String Provides the file path to Tes5Edit's 'Edit Scripts' folder as a String. If launching TES5Edit via a .tes5pas file, ScriptsPath will change to the directory where the .te5pas file is located. (therefore if your script has any .pas file it is grabbing functions from, they also need to be in the that same directory.)
FileCount Integer Provides the number of loaded files in your current TES5Edit session "Skyrim.Hardcoded.keep.this..." (aka. Skyrim.exe) is considered a file and is reflected in this variable.
wbAppName String Returns 'TES5','TES4','FNV','FO3'
wbVersionNumber Integer Returns xEdit version number.

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 held 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.
BaseRecord IwbMainRecord element : IwbMainRecord Used on REFR records to to grab the Base Form they are referencing, otherwise returns nil.
BuildRef file : IwbFile Will build and update ReferencedBy() data for IwbMainRecord's housed inside of files created via AddNewFile().
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 string element : IwbElement Used in the "Check For Errors" script.
ChildGroup IwbGroupRecord record : IwbMainRecord Use on a record like CELL or WRLD to return the group of records stored within it.
ChildrenOf IwbMainRecord group : IwbGroupRecord
CleanMasters file : IwbFile
CompareExchangeFormID boolean mainrecord : IwbMainRecord , oldFormID : Cardinal , aNewFormID : Cardinal Switches FormID references on mainrecord from oldFormID to aNewFormID.
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)
EditorID string element : IwbElement grabs the EditorID of element
ElementAssign IwbElement container : IwbContainer , aInder : integer, [element : IwbElement], aOnlySK : boolean Copy the contents of one element into a container element
container
Destination element
aInder
Index of element to copy to in case if destination is array, (use HighInteger to append); LowInteger or other negative value for non arrays.
element
Element to copy from. Use nil to create a blank element of the appropriate type
aOnlySK
Unknown - false appears to work

Sample: there is a script to copy VMAD subrecords "Skyrim - Copy VMAD subrecord.pas"

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 Returns the local FormID of the record (so local records will not have a load-order prefix e.g. 08FFFFFF -> 00FFFFFF)
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 Returns the value of the initially disabled flag on the specified record as a boolean
GetIsPersistent boolean mainrecord : IwbMainRecord Returns the value of the persistent flag on the specified record as a boolean
GetIsVisibleWhenDistant boolean mainrecord : IwbMainRecord Returns the value of the visible when distant flag on the specified record as a boolean
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 Returns true if the record can be edited by TES5Edit (false for Bethesda master files)
IsInjected boolean element : IwbElement Returns true if the record has been injected into another file
IsMaster boolean record : IwbMainRecord Returns true if the record is not an override for an already existing record
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. Not to be confused with ReferencedBy Elements. Call this function on any container element (etSubRecord) to get the iwbMainRecord of that form. (Ex: Calling LinksTo() on any 'LNAM - FormID' subRecord found in a FormID List will return the IwbMainRecord of that record).
LoadOrderFormIDtoFileFormID cardinal file : IwbFile , aFormID : cardinal Converts a FormID from the LoadOrder to the File Format. This means removing the formID prefix from local formIDs.
MainRecordByEditorID IwbMainRecord group : IwbGroupRecord Does not work for every case because it's inefficient
Master IInterface record : IwbMainRecord
MasterByIndex IInterface file : IwbFile , index : integer Returns the master file at the specified index from the specified file
MasterCount cardinal file : IwbFile Returns the number of master files the specified file requires
MasterOrSelf IwbMainRecord record : IwbMainRecord Returns the master record for the given record when used on override records
MoveDown element : IwbElement Moves the element down (if the element is in a dtSubRecordArray or dtArray)
MoveUp element : IwbElement Moves the element up (if the element is in a dtSubRecordArray or dtArray)
Name element : IwbElement Obtains the name of the element
NifTextureList tbsOpenResource : TBytesStream, slTextures : TStrings Used to grab the file names of all related textures belonging to a nif file and adds it to slTextures. (Ex. NifTextureList(ResourceOpendata(DataPath,'meshes\effects\plants\floradeathbell01.nif'), slTextures); will try and find floradeathbell01.nif as a loose file inside of your data folder (or winning loose file for Mod Organizer users) and add all related textures to slTextures. slTextures is formatted so it can be used as aFileName for any other Resource-Related Tes5Edit functions.
ObjectToElement IwbElement slObject : TObject IInterface's added to TLists (or TStringLists via sl.AddObject('string', iielement)) will need to be changed back with this function. (ex. iinterfaceVar := ObjectToElement(sl.Objects[i])).
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 Returns the path of the specified element.
RecordByEditorID IwbMainRecord file : IwbFile , editorid : string This only works for MGEF and GMST records. For all other records, use something like MainRecordByEditorID(GroupBySignature(f, 'ECZN'), 'RandomEncounterZone1')
RecordByFormID IwbMainRecord file : IwbFile , formid : integer , aAllowInjected : boolean Will return the record with the specified FormID in the specified file, if it exists. Since formid needs to be in local format (rather than load order format that you see in TES5Edit) it is extremely difficult to grab Override records with this function.
RecordByIndex IwbMainRecord file : IwbFile , index : integer Returns the reocrd at the specified index in the specified file.
RecordCount cardinal file : IwbFile Returns a value corresponding to the number of records in a file
ReferencedByCount cardinal record : IwbMainRecord Returns the number of records that reference the input record.
ReferencedByIndex IwbMainRecord record : IwbMainRecord , index : integer Returns the IwbMainRecord reference to the given record at the entered index.
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. Use this instead of Remove/RemoveElement to avoid errors when removing elements selected by and visible to the user.
RemoveFilter Removes all Mod filters. Useful for visually correcting the contents of a file that has had records/GRUPs removed via RemoveNode.
ResourceContainerList slContainers : TwbFastStringList Will fill slContainers with the full filename (directory+name) of all loaded BSA files. (note: tes5edit scripts use TwbFastStringList, but TStringList will work as well)
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
ResourceOpenData TBytesStream aContainerName: String : String, aFileName : String aFileName should be formatted similar to the other Resource-oriented Tes5edit scripts. aContainerName should be filled with a string generated by the function ResourceContainerList. Should only be used in conjunction with NifTextureList as ResourceCopy removes any other need for this function
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 (you can set Form members by using their formID string as the second parameter of this function, e.g. '01A32FF8')
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 Enables/disables the initially disabled flag for a record.
SetIsPersistent record : IwbMainRecord , value : boolean Enables/disables the persistent flag for a record.
SetIsVisibleWhenDistant record : IwbMainRecord , value : boolean Enables/disables the visible when distant flag for a record.
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 Outputs a string unique to the element entered. This can be used for sorting elements or for comparing them. E.g. You could compare the SortKey for two elements in records which override each other to see if they are different from each other.
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 Copies an IwbMainRecord, IwbGroupRecord, or IwbContainer to the specified file. The aAsNew boolean controls whether or not you're copying the record as an override record.
wbCopyElementToRecord IwbElement element : IwbElement , aMainRecord : IwbMainRecord , aAsNew : boolean , aDeepCopy : boolean Copies an element to a record. E.g. the "conditions" element on a COBJ record, or a faction from an NPC_ record.
wbCRC32Data Cardinal aData: TBytes
wbCRC32File Cardinal aFileName: string Recommended for most scenarios, it is also the fastest option.
wbSHA1Data string aData: TBytes
wbSHA1File string aFileName: string Calculation time is ~2 times longer than CRC32.
wbMD5Data string aData: TBytes
wbMD5File string aFileName: string Calculation time is ~2.5 times longer than CRC32.
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.

  • AddMessage(asMessage) pushes a line to TES5Edit's Information tab.
  • InputQuery(asWindowTitle, asWindowText, out sVariableToSet) displays a prompt dialog; it returns False if the user clicked Cancel or X, or True otherwise, and sets the output variable to whatever the user types if the user hits "OK."
  • SelectDirectory(asPromptStringOfSomeKind, asInitialDirectory, asRootDirectory, nil) returns a path as a string; used in "Assets browser.pas"
  • ShellExecute seen in "Execute external applications.pas", used to call another program
  • TCheckListBox used in "Copy as override.pas"
  • TListView used in "Assets browser.pas"
  • TMemo used in "Assets browser.pas"
  • TMenuItem used in "Assets browser.pas"
  • TPopupMenu used in "Assets browser.pas"
  • TSaveDialog used in "Assets browser.pas"
  • TScrollBox' used in "ExportImportTexts.pas"
  • I highly recommend viewing/using MatorTheEternal's mtefunctions.pas for examples as well.
Class Reference Description Use example Note
TButton TButton Button Assets browser.pas The button doesn't automatically expand its width to accommodate its contents.
TCheckBox TCheckBox Checkbox none You can apply a label using the Caption property; you don't need to make your own TLabel. Note, for more advanced scripts, that OnChange is not supported; use OnClick (which listens for more than just clicks) instead. Manually changing the Checked property will also fire an OnClick event; to avoid recursion where needed, you can set OnClick to nil, change Checked, and then restore OnClick's value.
TComboBox TComboBox Combobox none Set the Style property to csDropDownList to disallow custom text entry, mimicking the function of a typical drop-down menu
TForm TForm A dialog? ExportImportTexts.pas
TLabel TLabel Used to display ordinary text. none Set the Caption property to your text. To show line breaks, concatenate #13#10 into your string (e.g. 'Line 1' + #13#10 + 'Line 2').
TPanel TPanel General-purpose container for UI widgets ExportImportTexts.pas
TStaticText TStaticText Apparently used to display ordinary text. none Pretty much the same as a TLabel, but it cuts off any text that has line breaks. Not particularly useful.


TES5Edit appears to provide the following variables:

Name Type Description Note
frmFileSelect TForm Returns a copy of the plug-in select dialog, which can be shown by calling fMyDialogVariable.ShowModal You can get a reference to the checkbox list (as a TCheckListBox) by calling TCheckListBox(fMyDialogVariable.FindComponent('CheckListBox1'))

Simple Script Sample

This is a sample script which will only export every selected NPC to a TXT 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.txt';
	AddMessage('Saving NPC list to ' + filename);
	NPCList.SaveToFile(filename);
	NPCList.Free;
end;

end.

Pascal implementation

TES5Edit appears to use JVCL to interpret Delphi, a variant of Pascal. A few details can be found below.

  • TES5Edit's Pascal implementation does not appear to support function overloading.
  • TES5Edit's Pascal implementation does not appear to support open array parameters (e.g. array of integer).
  • TES5Edit's Pascal implementation does not appear to support the With statement.
  • TES5Edit's Pascal implementation does not support & as a prefix for suppressing keyword parsing (e.g. &For to refer to a variable named "For").
  • TES5Edit's Pascal implementation does not appear to support the ^ operator.
  • TES5Edit's Pascal implementation has exceptionally poor support for defined classes and subclasses:
    • The constructor keyword is not supported.
    • Subclasses without a constructor don't trip up the parser, but attempting to instantiate them (e.g. MyClass.Create) causes TES5Edit to choke on the classname, which it sees as an undefined identifier. At this time, it's not known whether custom classes can actually be used in an xEdit script.
    • One can safely assume, then, that the classes and functionality available to one is limited by both the Delphi version (presently unknown) and the JVCL version (presently unknown) that TES5Edit uses.
  • TES5Edit's Pascal implementation does not appear to support the is or as keywords. However, TObject and its subclasses offer a ClassName method.
  • TES5Edit's Pascal implementation does not appear to support constructions such as TList<Integer>.
  • TES5Edit's Pascal implementation does not appear to support procedural types or anonymous methods.
  • In TES5Edit's Pascal implementation, values are returned by assigning to Result, rather than by assigning to the function name.
  • Variant support routines don't appear to be implemented, making it tricky to work with variants.
  • Type keywords such as varInteger aren't implemented.
  • Structured types don't appear to be implemented.
  • Object classes such as TList and TStringList are very primitive; methods like AddRange are missing, and their Create constructors don't accept arguments.
  • TES5Edit's Pascal implementation does not support the definition of custom enum types using the type keyword. It basically only supports the "type" keyword as a means of aliasing classes.
  • TES5Edit's Pascal implementation supports out parameters but does not handle them properly. It appears as though they always receive default values (e.g. false booleans, empty strings). Var parameters properly receive values.
  • TES5Edit's Pascal implementation, while allowing you to use the << and >> operators for bitshifting, will result in values of FFFFFFFFFFFFFFFF or 0 instead an actual result. Use the shr and shl operators instead to perform working bitshifting. `FormID shr 24` for load order, etc.

The reference documentation below appears to match what TES5Edit provides.