Difference between revisions of "TES5Edit Scripting Functions"
imported>DavidJCobb (→Unsupported class methods: created) |
imported>DavidJCobb (→Pascal implementation: major and important updates: figured out the interpreter version deductively AND and checked xEdit's source code; specific interpreter details added) |
||
Line 443: | Line 443: | ||
=== Pascal implementation === | === Pascal implementation === | ||
TES5Edit | TES5Edit uses JvInterpreter from [http://jvcl.delphi-jedi.org/ JVCL] to execute Delphi as a scripting language; the interpreter version used is no older than 1.51.2 and no newer than 1.54. According to its own source code JvInterpreter has incomplete support for Delphi 5, and nothing newer; whether this refers to Borland Delphi 5 (released in 1999) or Delphi XE5 is unknown. No online documentation or language reference is available for the former. Modern reference documentation for Delphi (e.g. [http://docwiki.embarcadero.com/Libraries/XE8/en/System.RegularExpressionsCore.TPerlRegEx TPerlRegex docs]) will generally have accurate class descriptions, but large swaths of functionality will be missing from whatever JvInterpreter supports. | ||
An examination of [https://github.com/TES5Edit/TES5Edit/blob/sharlikran-fo4dump/wbScriptAdapter.pas xEdit's own source code] indicates that it provides (JvInterpreter's versions of) the following standard libraries to scripts, even if those scripts do not include the libraries via the <code>uses</code> command: | |||
* Buttons | |||
* Classes | |||
* Comctrls | |||
* Contnrs | |||
* Controls | |||
* Dialogs | |||
* ExtCtrls | |||
* Forms | |||
* Graphics | |||
* Menus | |||
* StdCtrls | |||
* System | |||
* SysUtils | |||
* Windows | |||
Misc notes: | |||
* In TES5Edit's Pascal implementation, values are returned by assigning to <code>Result</code>, rather than by assigning to the function name. | * In TES5Edit's Pascal implementation, values are returned by assigning to <code>Result</code>, rather than by assigning to the function name. | ||
* TES5Edit's Pascal implementation does not appear to support constructions such as <code>TList<Integer></code>. | * TES5Edit's Pascal implementation does not appear to support constructions such as <code>TList<Integer></code>. | ||
* If you try to store a Variant (e.g. the return value of GetElementNativeValues) in a Float variable and that variant has returned <code>nil</code>, then that Float will also contain <code>nil</code> and will throw errors when used. | * If you try to store a Variant (e.g. the return value of GetElementNativeValues) in a Float variable and that variant has returned <code>nil</code>, then that Float will also contain <code>nil</code> and will throw errors when used. | ||
==== xEdit extensions to JvInterpreter ==== | |||
xEdit extends units (standard libraries) provided by JvInterpreter with the following keywords. Note that since these are automatically included in your script, you can reference them directly and unprefixed (i.e. <code>Max</code> instead of <code>Math.Max</code>). | |||
<div style="max-height:20em;overflow-y:auto;border:1px solid #AAA"> | |||
* Controls | |||
** akLeft | |||
** akRight | |||
** akTop | |||
** akBottom | |||
* FileCtrl | |||
** ''function'' SelectDirectory | |||
* Forms | |||
** pmAuto | |||
** pmExplicit | |||
** pmNone | |||
** poMainFormCenter | |||
* Math | |||
** ''function'' Ceil | |||
** ''function'' Floor | |||
** ''function'' IntPower | |||
** ''function'' Max | |||
** ''function'' Min | |||
** ''function'' Power | |||
* Menus | |||
** maAutomatic | |||
** maManual | |||
* ShellApi | |||
** ''function'' ShellExecute | |||
** ''function'' ShellExecuteWait | |||
* System | |||
** ''function'' StringOfChar | |||
** MaxInt | |||
** MinInt | |||
* SysUtils | |||
** ''function'' Dec | |||
** ''function'' DirectoryExists | |||
** ''function'' ExcludeTrailingBackslash | |||
** ''function'' FileExists | |||
** ''function'' ForceDirectories | |||
** ''function'' Frac | |||
** ''function'' Inc | |||
** ''function'' IncludeTrailingBackslash | |||
** ''function'' Int | |||
** ''function'' IntToHex64 | |||
** ''function'' Pred | |||
** ''function'' SameText | |||
** ''function'' StringReplace | |||
** ''function'' StrToInt64 | |||
** ''function'' StrToInt64Def | |||
** ''function'' StrToFloatDef | |||
** ''function'' Succ | |||
** LowInteger | |||
** HighInteger | |||
** cbChecked | |||
** cbGrayed | |||
** cbUnchecked | |||
** fmCreate | |||
** lpAbove | |||
** lpBelow | |||
** lpLeft | |||
** lpRight | |||
** rfReplaceAll | |||
** rfIgnoreCase | |||
* Windows | |||
** ''function'' CopyFile | |||
** ''function'' CreateProcessWait | |||
** ''function'' Sleep | |||
** SW_HIDE | |||
** SW_MAXIMIZE | |||
** SW_MINIMIZE | |||
** SW_RESTORE | |||
** SW_SHOW | |||
** SW_SHOWDEFAULT | |||
** SW_SHOWMAXIMIZED | |||
** SW_SHOWMINIMIZED | |||
** SW_SHOWMINNOACTIVE | |||
** SW_SHOWNA | |||
** SW_SHOWNOACTIVATE | |||
** SW_SHOWNORMAL | |||
</div> | |||
The following classes are also extended (or simply offered, if JvInterpreter didn't already offer them): | |||
* | <div style="max-height:20em;overflow-y:auto;border:1px solid #AAA"> | ||
* TBinaryReader | |||
** ''get'' Create | |||
** ''get'' Read | |||
** ''get'' ReadBoolean | |||
** ''get'' ReadByte | |||
** ''get'' ReadBytes | |||
** ''get'' ReadChar | |||
** ''get'' ReadDouble | |||
** ''get'' ReadShortInt | |||
** ''get'' ReadSmallInt | |||
** ''get'' ReadUInt16 | |||
** ''get'' ReadUInt32 | |||
** ''get'' ReadInteger | |||
** ''get'' ReadSingle | |||
** ''get'' ReadString | |||
* TBinaryWriter | |||
** ''get'' Create | |||
** ''get'' Write | |||
** ''get'' WriteSingle | |||
* TBitmap | |||
** ''get'' SetSize | |||
* TBoundLabel | |||
* TBytesStream | |||
** ''get'' Create | |||
* TCheckListBox | |||
** ''get'' Create | |||
** ''get'' CheckAll | |||
** ''get/set'' AllowGrayed | |||
** ''get/set'' Checked | |||
** ''get/set'' Header | |||
** ''get/set'' ItemEnabled | |||
** ''get/set'' State | |||
** ''event'' TNotifyEvent | |||
* TComboBox | |||
** ''get/set'' DropDownCount | |||
* TCustomForm | |||
** ''get/set'' PopupMode | |||
** ''get/set'' PopupParent | |||
* TCustomIniFile | |||
** ''get'' DeleteKey | |||
** ''get'' EraseSection | |||
** ''get'' ReadBool | |||
** ''get'' ReadFloat | |||
** ''get'' ReadInteger | |||
** ''get'' ReadSection | |||
** ''get'' ReadSections | |||
** ''get'' ReadSectionValues | |||
** ''get'' ReadString | |||
** ''get'' SectionExists | |||
** ''get'' UpdateFile | |||
** ''get'' ValueExists | |||
** ''get'' WriteBool | |||
** ''get'' WriteFloat | |||
** ''get'' WriteInteger | |||
** ''get'' WriteString | |||
* TCustomLabeledEdit | |||
** ''get'' Create | |||
** ''get'' EditLabel | |||
** ''get/set'' LabelPosition | |||
** ''get/set'' LabelSpacing | |||
* THashedStringList | |||
** ''get'' Create | |||
* TLabeledEdit | |||
** ''get'' Create | |||
* TListItem | |||
** ''get/set'' SubItems | |||
* TListItems | |||
** ''set'' Count | |||
* TListView | |||
** ''event'' TLVOwnerDataEvent | |||
** ''event'' TLVSelectItemEvent | |||
* TIniFile | |||
** ''get'' Create | |||
* TMemIniFile | |||
** ''get'' Create | |||
** ''get'' GetStrings | |||
** ''get'' SetStrings | |||
* TMenu | |||
** ''get/set'' AutoHotKeys | |||
* TMenuItem | |||
** ''get'' Clear | |||
* TPerlRegex | |||
** ''get'' Compile | |||
** ''get'' Compiled | |||
** ''get'' ComputeReplacement | |||
** ''get'' Create | |||
** ''get'' EscapeRegexChars | |||
** ''get'' FoundMatch | |||
** ''get'' GroupCount | |||
** ''get'' GroupLengths | |||
** ''get'' GroupOffsets | |||
** ''get'' Match | |||
** ''get'' MatchAgain | |||
** ''get'' MatchedLength | |||
** ''get'' MatchedOffset | |||
** ''get'' MatchedText | |||
** ''get'' NamedGroup | |||
** ''get/set'' Options | |||
** ''get/set'' Regex | |||
** ''get'' Replace | |||
** ''get'' ReplaceAll | |||
** ''get/set'' Replacement | |||
** ''get'' Split | |||
** ''get'' SplitCapture | |||
** ''get/set'' Start | |||
** ''get/set'' Stop | |||
** ''get'' StoreGroups | |||
** ''get'' Studied | |||
** ''get'' Study | |||
** ''get/set'' Subject | |||
** ''get'' SubjectLeft | |||
** ''get'' SubjectRight | |||
* TPerlRegexOptions | |||
** ''const'' preAnchored | |||
** ''const'' preCaseLess | |||
** ''const'' preExtended | |||
** ''const'' preMultiLine | |||
** ''const'' preNoAutoCapture | |||
** ''const'' preNotBOL | |||
** ''const'' preNotEmpty | |||
** ''const'' preNotEOL | |||
** ''const'' preSingleLine | |||
** ''const'' preUnGreedy | |||
* TRegistryIniFile | |||
** ''get'' Create | |||
* TStrings | |||
** ''get/set'' DelimitedText | |||
** ''get/set'' Delimiter | |||
** ''set'' NameValueSeparator | |||
** ''set'' StrictDelimiter | |||
** ''get/set'' ValueFromIndex | |||
* TStringList | |||
** ''get/set'' CaseSensitive | |||
* TWinControl | |||
** ''get/set'' DoubleBuffered | |||
</div> | |||
==== | ==== Unsupported language features ==== | ||
{|class="wikitable" width =100% | {|class="wikitable" width =100% | ||
!style="text-align:left;"|Feature | !style="text-align:left;"|Feature | ||
Line 543: | Line 777: | ||
!style="text-align:left;"|Feature | !style="text-align:left;"|Feature | ||
!style="text-align:left;"|Description | !style="text-align:left;"|Description | ||
|- | |- | ||
|[http://docwiki.embarcadero.com/RADStudio/XE2/en/Variant_Support_Routines Variant support routines] | |[http://docwiki.embarcadero.com/RADStudio/XE2/en/Variant_Support_Routines Variant support routines] | ||
Line 554: | Line 785: | ||
|- | |- | ||
|} | |} | ||
Revision as of 13:57, 5 May 2017
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
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. |
wbGridCell | TwbGridCell | x : Integer, y : Integer | Returns an object belonging to an undocumented xEdit class, with x and y fields. Apparently related to worldspaces.
|
wbSubBlockFromGridCell | TwbGridCell | cellCoordinates : TwbGridCell | Apparently related to worldspaces. |
wbBlockFromSubBlock | TwbGridCell | subBlock : TwbGridCell | Apparently related to worldspaces. |
wbGridCellToGroupLabel | Cardinal | TwbGridCell | Apparently related to worldspaces. |
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 uses JvInterpreter from JVCL to execute Delphi as a scripting language; the interpreter version used is no older than 1.51.2 and no newer than 1.54. According to its own source code JvInterpreter has incomplete support for Delphi 5, and nothing newer; whether this refers to Borland Delphi 5 (released in 1999) or Delphi XE5 is unknown. No online documentation or language reference is available for the former. Modern reference documentation for Delphi (e.g. TPerlRegex docs) will generally have accurate class descriptions, but large swaths of functionality will be missing from whatever JvInterpreter supports.
An examination of xEdit's own source code indicates that it provides (JvInterpreter's versions of) the following standard libraries to scripts, even if those scripts do not include the libraries via the uses
command:
- Buttons
- Classes
- Comctrls
- Contnrs
- Controls
- Dialogs
- ExtCtrls
- Forms
- Graphics
- Menus
- StdCtrls
- System
- SysUtils
- Windows
Misc notes:
- In TES5Edit's Pascal implementation, values are returned by assigning to
Result
, rather than by assigning to the function name. - TES5Edit's Pascal implementation does not appear to support constructions such as
TList<Integer>
. - If you try to store a Variant (e.g. the return value of GetElementNativeValues) in a Float variable and that variant has returned
nil
, then that Float will also containnil
and will throw errors when used.
xEdit extensions to JvInterpreter
xEdit extends units (standard libraries) provided by JvInterpreter with the following keywords. Note that since these are automatically included in your script, you can reference them directly and unprefixed (i.e. Max
instead of Math.Max
).
- Controls
- akLeft
- akRight
- akTop
- akBottom
- FileCtrl
- function SelectDirectory
- Forms
- pmAuto
- pmExplicit
- pmNone
- poMainFormCenter
- Math
- function Ceil
- function Floor
- function IntPower
- function Max
- function Min
- function Power
- Menus
- maAutomatic
- maManual
- ShellApi
- function ShellExecute
- function ShellExecuteWait
- System
- function StringOfChar
- MaxInt
- MinInt
- SysUtils
- function Dec
- function DirectoryExists
- function ExcludeTrailingBackslash
- function FileExists
- function ForceDirectories
- function Frac
- function Inc
- function IncludeTrailingBackslash
- function Int
- function IntToHex64
- function Pred
- function SameText
- function StringReplace
- function StrToInt64
- function StrToInt64Def
- function StrToFloatDef
- function Succ
- LowInteger
- HighInteger
- cbChecked
- cbGrayed
- cbUnchecked
- fmCreate
- lpAbove
- lpBelow
- lpLeft
- lpRight
- rfReplaceAll
- rfIgnoreCase
- Windows
- function CopyFile
- function CreateProcessWait
- function Sleep
- SW_HIDE
- SW_MAXIMIZE
- SW_MINIMIZE
- SW_RESTORE
- SW_SHOW
- SW_SHOWDEFAULT
- SW_SHOWMAXIMIZED
- SW_SHOWMINIMIZED
- SW_SHOWMINNOACTIVE
- SW_SHOWNA
- SW_SHOWNOACTIVATE
- SW_SHOWNORMAL
The following classes are also extended (or simply offered, if JvInterpreter didn't already offer them):
- TBinaryReader
- get Create
- get Read
- get ReadBoolean
- get ReadByte
- get ReadBytes
- get ReadChar
- get ReadDouble
- get ReadShortInt
- get ReadSmallInt
- get ReadUInt16
- get ReadUInt32
- get ReadInteger
- get ReadSingle
- get ReadString
- TBinaryWriter
- get Create
- get Write
- get WriteSingle
- TBitmap
- get SetSize
- TBoundLabel
- TBytesStream
- get Create
- TCheckListBox
- get Create
- get CheckAll
- get/set AllowGrayed
- get/set Checked
- get/set Header
- get/set ItemEnabled
- get/set State
- event TNotifyEvent
- TComboBox
- get/set DropDownCount
- TCustomForm
- get/set PopupMode
- get/set PopupParent
- TCustomIniFile
- get DeleteKey
- get EraseSection
- get ReadBool
- get ReadFloat
- get ReadInteger
- get ReadSection
- get ReadSections
- get ReadSectionValues
- get ReadString
- get SectionExists
- get UpdateFile
- get ValueExists
- get WriteBool
- get WriteFloat
- get WriteInteger
- get WriteString
- TCustomLabeledEdit
- get Create
- get EditLabel
- get/set LabelPosition
- get/set LabelSpacing
- THashedStringList
- get Create
- TLabeledEdit
- get Create
- TListItem
- get/set SubItems
- TListItems
- set Count
- TListView
- event TLVOwnerDataEvent
- event TLVSelectItemEvent
- TIniFile
- get Create
- TMemIniFile
- get Create
- get GetStrings
- get SetStrings
- TMenu
- get/set AutoHotKeys
- TMenuItem
- get Clear
- TPerlRegex
- get Compile
- get Compiled
- get ComputeReplacement
- get Create
- get EscapeRegexChars
- get FoundMatch
- get GroupCount
- get GroupLengths
- get GroupOffsets
- get Match
- get MatchAgain
- get MatchedLength
- get MatchedOffset
- get MatchedText
- get NamedGroup
- get/set Options
- get/set Regex
- get Replace
- get ReplaceAll
- get/set Replacement
- get Split
- get SplitCapture
- get/set Start
- get/set Stop
- get StoreGroups
- get Studied
- get Study
- get/set Subject
- get SubjectLeft
- get SubjectRight
- TPerlRegexOptions
- const preAnchored
- const preCaseLess
- const preExtended
- const preMultiLine
- const preNoAutoCapture
- const preNotBOL
- const preNotEmpty
- const preNotEOL
- const preSingleLine
- const preUnGreedy
- TRegistryIniFile
- get Create
- TStrings
- get/set DelimitedText
- get/set Delimiter
- set NameValueSeparator
- set StrictDelimiter
- get/set ValueFromIndex
- TStringList
- get/set CaseSensitive
- TWinControl
- get/set DoubleBuffered
Unsupported language features
Feature | Details |
---|---|
anonymous methods | Refer to the Embarcadero documentation. |
array arguments | A function cannot accept an argument with a type like array of integer .
|
function overloading | Allows the same function to have multiple sets of arguments. |
object types | The object keyword isn't implemented.
|
out parameters | Out parameters always receive default values, such as false for a boolean. Use var parameters instead. |
procedural types | Refer to the Embarcadero documentation. |
structured types | Refer to the Embarcadero documentation. |
subclasses | The constructor keyword isn't implemented. Subclasses without a constructor can be defined, but attempts to instantiate them (MyClass.Create ) will always break.
|
try | Doesn't catch all runtime errors. |
Unsupported operators
Operator | Description |
---|---|
& | Prefix; suppresses parsing of a keyword (e.g. &For is a variable named "For").
|
@ | Prefix; retrieves the address of a variable for use as a pointer; compare to & in C++.
|
^ | Dereferences a pointer; compare to * in C++.
|
<< | Used for bit shifting, but returns a junk result in xEdit. Use Shl instead.
|
>> | Used for bit shifting, but returns a junk result in xEdit. Use Shr instead.
|
Unsupported keywords
Keyword | Description |
---|---|
absolute | Allows two or more variables to occupy the same location in memory. |
as | Used to cast a variable to a given class. |
constructor | Used to declare a constructor function for subclasses; absence of this keyword makes subclasses impossible to use. |
is | Used to test whether a variable is an instance of a given class; for anything derived from TObject , you can use the ClassName method instead.
|
object | Used to create object types. |
type | Partial implementation. You can use it to alias a class name, but it's broken for every single other use and its existence is therefore pointless. |
with | Statement. |
Unsupported classes and tools
Feature | Description |
---|---|
Variant support routines | Makes it easier to identify a variant's current type, and cast variants. Relevant type keywords like varInteger are also missing.
|
Move | This function is supposed to copy data from one memory location to another. Instead, it either throws an error, or fails silently and nulls out the target location. |