Difference between revisions of "TES5Edit Scripting Functions"

From the CreationKit Wiki
Jump to navigation Jump to search
imported>DavidJCobb
 
(97 intermediate revisions by 10 users not shown)
Line 1: Line 1:
[[Category:Tools]]
Do not add to this page please. All documentation has been moved to GitHub:
[[Category:Data File Editors]]


== TES5Edit Scripting ==
* [https://tes5edit.github.io/docs/13-Scripting-Functions.html Scripting Functions]
=== 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.
If you would like to contribute feel free to edit the files and submit your changes:


The information in the table is not complete so please contribute by explaining these functions, their uses and by fixing mistakes in this information.
https://github.com/TES5Edit/docs


=== TES5Edit Global Variables ===
= Additional TES5Edit Resources =
These are predefined read-only variables that can be called at any time.
{| class="wikitable" style="background-color: #AAAAAA; cellpadding: 0"
|- align="left"
! scope="col" style="background-color: #DDDDDD" | Name
! scope="col" style="background-color: #DDDDDD" | Type
! scope="col" style="background-color: #DDDDDD" | Description
! scope="col" style="background-color: #DDDDDD" | Note
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>DataPath</b> || String || Provides the file path to Skyrim's data folder as a String ||
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>ScriptsPath</b> || String || Provides the file path to Tes5Edit's 'Edit Scripts' folder as a String ||
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>FileCount</b> || Integer || Provides the number of loaded files in your current TES5Edit session || "Skyrim.Hardcoded.keep.this..." is considered a file and is reflected in this variable.
|}


=== TES5Edit Scripting Functions ===
* [[TES5Edit|TES5Edit]]
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 <b>IInterface</b> which is common to every object type returned by TES5Edit.
* [[TES5Edit_Cleaning_Guide_-_TES5Edit|TES5Edit Cleaning Guide]]
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.
* [[TES5Edit_Mod_Cleaning_Tutorial|TES5Edit Mod Cleaning Tutorial]]
 
* [[Fixing_Navmesh_Deletion_Tutorial|Fixing Navmesh Deletion Tutorial]]
{| class="wikitable" style="background-color: #AAAAAA; cellpadding: 0"
* [[Skyrim_Dirty_Plugins_List|Skyrim Dirty Plugins List]]
|- align="left"
* [[TES5Edit_Scripting_Functions|TES5Edit Scripting Functions]]
! scope="col" style="background-color: #DDDDDD" | Function
* [https://bethesda.net/community/topic/57570/relz-sseedit/ Official Elderscrolls TES5Edit forum topic] (offline)
! scope="col" style="background-color: #DDDDDD" | Returns
! scope="col" style="background-color: #DDDDDD" | Arguments
! scope="col" style="background-color: #DDDDDD" | Description
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>Add</b> || IwbElement || container : IwbContainer, name : string, silent = true : boolean || Implemented for main records etc.
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>AddElement</b> ||  || container : IwbContainer , element : IwbElement  ||
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>AdditionalElementCount</b> || integer || container : IwbContainer ||
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>AddMasterIfMissing</b> ||  || file : IwbFile , mastername : string  || Adds a master to a file by its filename if it isn't already a master for that file
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>AddMessage</b> ||  || message : string  || Adds a message line into the TES5Edit output panel
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>AddNewFile</b> || IwbFile ||  || Adds a new file and returns its reference
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>AddRequiredElementMasters</b> || IwbFile || aSourceElement : IwbElement , aTargetFile : IwbFile , aAsNew : boolean  || Add the element''s master into the target file.
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>Assigned</b> || boolean || element : IwbElement  || Returns true if the element is not nil.  Else returns false.
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>CanContainFormIDs</b> || boolean || element : IwbElement  ||
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>CanMoveDown</b> || boolean || element : IwbElement  || Checks if an element can by moved down a list to a higher index
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>CanMoveUp</b> || boolean || element : IwbElement  || Checks if an element can be moved up a list to a lower index
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>ChangeFormSignature</b> ||  || record : IwbMainRecord , signature : TwbSignature  ||
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>Check</b> || string || element : IwbElement  || Used in the "Check For Errors" script.
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>ChildGroup</b> || IwbGroupRecord || record : IwbMainRecord  || Use on a record like CELL or WRLD to return the group of records stored within it.
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>ChildrenOf</b> || IwbMainRecord || group : IwbGroupRecord  ||
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>CleanMasters</b> ||  || file : IwbFile  ||
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>CompareExchangeFormID</b> || boolean || mainrecord : IwbMainRecord , oldFormID : Cardinal , aNewFormID : Cardinal  || Switches FormID references on mainrecord from oldFormID to aNewFormID.
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>ConflictAllForMainRecord</b> || TConflictThis || record : IwbMainRecord  || Gets the ConflictThis argument of the record by calling ConflictLevelForMainRecord (see ctXxxxx enums)
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>ConflictAllForNode</b> || TConflictThis || node : IwbElement  || Gets the ConflictAll argument of the record by calling ConflictLevelForMainRecord (see ctXxxxx enums)
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>ConflictThisForMainRecord</b> || TConflictThis || record : IwbMainRecord  || Gets the ConflictThis argument of the record by calling ConflictLevelForMainRecord (see ctXxxxx enums)
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>ConflictThisForNode</b> || TConflictThis || node : IwbElement  || Gets the ConflictAll argument of the record by calling ConflictLevelForMainRecord (see ctXxxxx enums)
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>ContainingMainRecord</b> || IwbMainRecord || element : IwbElement  ||
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>DefType</b> || TwbDefType || element : IInterface  || returns the IwbElement::DefType (see dtXxxx enums)
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>ElementAssign</b> || 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"
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>ElementByIndex</b> || IwbElement || container : IwbContainer , index : integer  || Gets an element in the container by index
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>ElementByName</b> || IwbElement || container : IwbContainer , name : string  || Gets an element in the container by name
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>ElementByPath</b> || IwbElement || container : IwbContainer , path : string  || Gets an element in the container by path
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>ElementBySignature</b> || IwbElement || container : IwbContainer , signature : string  || Gets an element in the container by its signature
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>ElementCount</b> || integer || container : IwbContainer  || Returns the number of elements in a container
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>ElementExists</b> || boolean || container : IwbContainer , name : string  || Checks if the name of the element already exist in the container
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>ElementType</b> || TwbElementType || element : IwbElement  || Returns the ElementType of the element
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>Equals</b> || boolean || element1 : IwbElement , element2 : IwbElement  || Compares both elements by their ElementID
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>FileByIndex</b> || IwbFile || index : integer  || Gets the file at the specified index
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>FileByLoadOrder</b> || IwbFile || loadorder : integer  || Gets the file at the specified load order
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>FileFormIDtoLoadOrderFormID</b> || cardinal || file : IwbFile , formid : string/cardinal  ||
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>FindChildGroup</b> || IwbGroupRecord || group : IwbGroupRecord , aType : integer , aMainRecord : IwbMainRecord  ||
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>FixedFormID</b> || cardinal || aMainRecord : IwbMainRecord  || Returns the local FormID of the record (so local records will not have a load-order prefix e.g. 08FFFFFF -> 00FFFFFF)
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>FormID</b> || cardinal || aMainRecord : IwbMainRecord  || Obtains the FormID of the record
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>FullPath</b> || string || element : IwbElement  || Gives the full path, all the way down to file, of the input element
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>GetContainer</b> || IwbContainer || element : IwbElement  || Gets the container of the element
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>GetEditValue</b> || string || element : IwbElement  || Gets the element's value represented as text
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>GetElementEditValues</b> || string || element : IwbElement , name : string  || Gets the element's value represented as text
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>GetElementNativeValues</b> || variant || element : IwbElement , name : string  || Gets the element's native value
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>GetFile</b> || IwbFile || element : IwbElement  || Gets the file that defines the element
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>GetFileName</b> || string || file : IwbFile  || Obtains the filename of the plugin file
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>GetFormVersion</b> || cardinal || mainrecord : IwbMainRecord  ||
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>GetIsDeleted</b> || boolean || mainrecord : IwbMainRecord  || Indicates if the record has been deleted
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>GetIsESM</b> || boolean || file : IwbFile  || Indicates if the plugin is an ESM file
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>GetIsInitiallyDisabled</b> || boolean || mainrecord : IwbMainRecord  || Returns the value of the initially disabled flag on the specified record as a boolean
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>GetIsPersistent</b> || boolean || mainrecord : IwbMainRecord  || Returns the value of the persistent flag on the specified record as a boolean
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>GetIsVisibleWhenDistant</b> || boolean || mainrecord : IwbMainRecord  || Returns the value of the visible when distant flag on the specified record as a boolean
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>GetLoadOrder</b> || cardinal || file : IwbFile  || Gets the global load order of the file
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>GetLoadOrderFormID</b> || cardinal || mainrecord : IwbMainRecord  || Obtains the FormID with the current load order applied
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>GetNativeValue</b> || variant || element : IwbElement  || Gets the element's native value
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>GroupBySignature</b> ||  || file : IwbFile , signature : string  || Selects a group in a file by its signature
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>GroupLabel</b> || cardinal || group : IwbGroupRecord  ||
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>GroupType</b> || integer || group : IwbGroupRecord  ||
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>HasGroup</b> || boolean || file : IwbFile , signature : string  || Checks if a file has a group by the group's signature
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>HasMaster</b> || boolean || file : IwbFile , signature : string  || Returns true if the file has a master file defined
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>IndexOf</b> || integer || container : IwbContainer , element : IwbElement  || Gets the index of the element inside the collection
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>InsertElement</b> ||  || container : IwbContainer , position : integer , element : IwbElement  || Inserts an existing element inside a collection by position
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>IsEditable</b> || boolean || element : IwbElement  || Returns true if the record can be edited by TES5Edit (false for Bethesda master files)
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>IsInjected</b> || boolean || element : IwbElement  || Returns true if the record has been injected into another file
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>IsMaster</b> || boolean || record : IwbMainRecord  || Returns true if the record is not an override for an already existing record
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>IsWinningOverride</b> || boolean || record : IwbMainRecord  || Checks whether or not the record is the highest override loaded
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>JumpTo</b> || TConflictThis || record : IwbMainRecord , backward : boolean  || Selects the specified record
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>LastElement</b> || IwbElement || container : IwbContainer  || Obtains the last element in the collection
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>LinksTo</b> || IwbElement || element : IwbElement  || Obtains the referenced element
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>LoadOrderFormIDtoFileFormID</b> || cardinal || file : IwbFile , aFormID : cardinal  || Converts a FormID from the LoadOrder to the File Format.  This means removing the formID prefix from local formIDs.
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>MainRecordByEditorID</b> || IwbMainRecord || group : IwbGroupRecord  || Does not work for every case because it's inefficient
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>Master</b> || IInterface || record : IwbMainRecord  ||
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>MasterByIndex</b> || IInterface || file : IwbFile , index : integer  || Returns the master file at the specified index from the specified file
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>MasterCount</b> || cardinal || file : IwbFile  || Returns the number of master files the specified file requires
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>MasterOrSelf</b> || IwbMainRecord || record : IwbMainRecord  || Returns the master record for the given record when used on override records
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>MoveDown</b> ||  || element : IwbElement  || Moves the element down (if the element is in a dtSubRecordArray or dtArray)
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>MoveUp</b> ||  || element : IwbElement  || Moves the element up (if the element is in a dtSubRecordArray or dtArray)
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>Name</b> ||  || element : IwbElement  || Obtains the name of the element
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>OverrideByIndex</b> || IwbMainRecord || record : IwbMainRecord , index : integer  || Gives the overriding record associated with the provided index
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>OverrideCount</b> || cardinal || record : IwbMainRecord  || Provides a value for the number of overrides there are for a given record
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>Path</b> || string || element : IwbElement  || Returns the path of the specified element.
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>RecordByEditorID</b> || IwbMainRecord || file : IwbFile , editorid : string  ||
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>RecordByFormID</b> || IwbMainRecord || file : IwbFile , formid : integer , aAllowInjected : boolean  || Will return the record with the specified FormID in the specified file, if it exists.
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>RecordByIndex</b> || IwbMainRecord || file : IwbFile , index : integer  || Returns the reocrd at the specified index in the specified file.
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>RecordCount</b> || cardinal || file : IwbFile  || Returns a value corresponding to the number of records in a file
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>ReferencedByCount</b> || cardinal || record : IwbMainRecord  || Returns the number of records that reference the input record.
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>ReferencedByIndex</b> || IwbMainRecord || record : IwbMainRecord , index : integer  || Returns the IwbMainRecord reference to the given record at the entered index.
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>Remove</b> ||  || element : IwbElement  || Removes an element.
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>RemoveByIndex</b> || IwbElement || container : IwbContainer , index : integer , aMarkModified : boolean  ||
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>RemoveElement</b> || IwbElement || container : IwbContainer , element : IwbElement  ||
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>RemoveNode</b> || 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.
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>RemoveFilter</b> ||  ||  || Removes all Mod filters.  Useful for visually correcting the contents of a file that has had records/GRUPs removed via RemoveNode.
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>ResourceCopy</b> ||  || container : IwbContainer , fileName : string , pathOut : string , containerIndex : integer  ||
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>ResourceCount</b> || cardinal || container : IwbContainer , aFileName : string , containers : TStrings  ||
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>ResourceExists</b> || boolean || container : IwbContainer , aFileName : string  ||
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>ResourceList</b> ||  || container : IwbContainer , aContainerName : string , containers : TStrings  ||
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>ReverseElements</b> ||  || container : IwbContainer  || Reverses the order of a list of elements in a container
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>SetEditValue</b> ||  || 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')
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>SetElementEditValues</b> ||  || container : IwbContainer , path : string , value : string  || Sets the value as a string of the element by its path
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>SetElementNativeValues</b> ||  || container : IwbContainer , path : string , value : variant  || Sets the native value of the element by its path
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>SetFormVersion</b> ||  || record : IwbMainRecord , version : integer  ||
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>SetIsDeleted</b> ||  || record : IwbMainRecord , value : boolean  || Enables/disables deleted flag for a record
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>SetIsESM</b> ||  || file : IwbFile , value : boolean  || Enables/disbles ESM flag for a file
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>SetIsInitiallyDisabled</b> ||  || record : IwbMainRecord , value : boolean  || Enables/disables the initially disabled flag for a record.
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>SetIsPersistent</b> ||  || record : IwbMainRecord , value : boolean  || Enables/disables the persistent flag for a record.
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>SetIsVisibleWhenDistant</b> ||  || record : IwbMainRecord , value : boolean  || Enables/disables the visible when distant flag for a record.
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>SetLoadOrderFormID</b> ||  || record : IwbMainRecord , loadOrderFormId : cardinal  || Changes the 8-digit hexadecimal Form ID for a record
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>SetNativeValue</b> ||  || element : IwbElement , value : variant  || Sets the native value of the element
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>ShortName</b> || string || element : IwbElement  || Gets the short name of the element
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>Signature</b> || string || record : IwbMainRecord  || Gets the signature of a record
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>SortKey</b> || 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.
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>SortMasters</b> ||  || file : IwbFile  || Attempts to sort the masters for a file by their load order
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>wbCopyElementToFile</b> || 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.
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>wbCopyElementToRecord</b> || 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.
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>WinningOverride</b> || 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:
 
<pre>
{
Script description.
------------------------
Hotkey: Ctrl+Alt+Shift+E
}
</pre>
 
==== 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)
 
<pre>
uses 'MyTools';
</pre>
 
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.
 
''(Ed. note: Since nobody has actually gotten around to doing the above, let me at least start us off with some functions spotted in the built-in scripts. Most of them seem to be standard and can probably be looked up on the Internet, by anyone who has the time.)''
 
*''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, asUnknown1, asUnknown2, nil)'' returns a path as a string; used in "Assets browser.pas"
*''ShellExecute'' seen in "Execute external applications.pas", used to call another program
*''TButton'' used in "Assets browser.pas"
*''TCheckListBox'' used in "Copy as override.pas"
*''TComboBox'' used in "Assets browser.pas"
*''TForm'' used in "Assets browser.pas" and "Copy as override.pas"
*''TListView'' used in "Assets browser.pas"
*''TMemo'' used in "Assets browser.pas"
*''TMenuItem'' used in "Assets browser.pas"
*''TPanel' used in "ExportImportTexts.pas"
*''TPopupMenu'' used in "Assets browser.pas"
*''TSaveDialog'' used in "Assets browser.pas"
*''TScrollBox' used in "ExportImportTexts.pas"
 
{| class="wikitable" style="background-color: #AAAAAA; cellpadding: 0"
|- align="left"
! scope="col" style="background-color: #DDDDDD" | Class
! scope="col" style="background-color: #DDDDDD" | Reference
! scope="col" style="background-color: #DDDDDD" | Description
! scope="col" style="background-color: #DDDDDD" | Use example
! scope="col" style="background-color: #DDDDDD" | Note
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>TComboBox</b> || [http://docs.embarcadero.com/products/rad_studio/delphiAndcpp2009/HelpUpdate2/EN/html/delphivclwin32/StdCtrls_TComboBox.html TComboBox] || Combobox (a drop-down you can type into) || none || Set the <code>Style</code> property to <code>csDropDownList</code> to disallow custom text entry, mimicking the function of a typical drop-down menu
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>TForm</b> || [http://lazarus-ccr.sourceforge.net/docs/lcl/forms/tform.html TForm] || A dialog? || ExportImportTexts.pas ||
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>TLabel</b> || [http://docs.embarcadero.com/products/rad_studio/delphiAndcpp2009/HelpUpdate2/EN/html/delphivclwin32/StdCtrls_TLabel.html TLabel] || Apparently used to display ordinary text. || none || Set the [http://docs.embarcadero.com/products/rad_studio/delphiAndcpp2009/HelpUpdate2/EN/html/delphivclwin32/StdCtrls_TStaticText_Caption.html <code>Caption</code>] property to your text. To show line breaks, concatenate <code>#13#10</code> into your string (e.g. <code>'Line 1' + #13#10 + 'Line 2'</code>).
|- align="left" style="background-color: #EEEEEE"
| scope="row" | <b>TPanel</b> || [http://docs.embarcadero.com/products/rad_studio/delphiAndcpp2009/HelpUpdate2/EN/html/delphivclwin32/ExtCtrls_TPanel.html TPanel] || General-purpose container for UI widgets || ExportImportTexts.pas ||
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>TStaticText</b> || [http://docs.embarcadero.com/products/rad_studio/delphiAndcpp2009/HelpUpdate2/EN/html/delphivclwin32/StdCtrls_TStaticText.html 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. So pretty much worthless, in other words.
|}
 
 
TES5Edit appears to provide the following variables:
 
{| class="wikitable" style="background-color: #AAAAAA; cellpadding: 0"
|- align="left"
! scope="col" style="background-color: #DDDDDD" | Name
! scope="col" style="background-color: #DDDDDD" | Type
! scope="col" style="background-color: #DDDDDD" | Description
! scope="col" style="background-color: #DDDDDD" | Note
|- align="left" style="background-color: #F8F8F8"
| scope="row" | <b>frmFileSelect</b> || TForm || Returns a copy of the plug-in select dialog, which can be shown by calling <code>fMyDialogVariable.ShowModal</code> || You can get a reference to the checkbox list (as a TCheckListBox) by calling <code>TCheckListBox(fMyDialogVariable.FindComponent('CheckListBox1'))</code>
|}
 
=== Simple Script Sample ===
 
This is a sample script which will only export every selected NPC to a CSV file:
 
<pre>
{
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.
</pre>
 
=== Pascal implementation ===
TES5Edit appears to use [http://jvcl.delphi-jedi.org/JvInterpreter.htm 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. <code>array of integer</code>).
* TES5Edit's Pascal implementation either does not support classes, or does not support the "constructor" keyword.
** 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.
* In TES5Edit's Pascal implementation, values are returned by assigning to <code>Result</code>, rather than by assigning to the function name.

Latest revision as of 04:25, 10 April 2024

Do not add to this page please. All documentation has been moved to GitHub:

If you would like to contribute feel free to edit the files and submit your changes:

https://github.com/TES5Edit/docs

Additional TES5Edit Resources[edit | edit source]

Retrieved from "https://ck.uesp.net/w/index.php?title=TES5Edit_Scripting_Functions&oldid=23419"